Sistema de diseno

Kodavio puede usar design.md como memoria de diseno. Esa memoria ayuda a mantener colores, tipografia, espaciados, radios, sombras y criterios visuales consistentes.

La ventaja de design.md es que Codex deja de improvisar pagina a pagina. Antes de crear o convertir, puede leer una fuente comun y decidir nombres de tokens, jerarquia tipografica, estilo de componentes y reglas de composicion.

Que guarda `design.md`

Un buen design.md no tiene que ser enorme. Tiene que ser claro.

Bloque	Que contiene	Para que lo usa Codex
Proyecto	Nombre, URL, builder principal y sistema activo.	Contexto antes de tocar paginas.
Tokens	Colores, tipografia, spacing, breakpoints, radios y sombras.	Mantener consistencia visual.
Componentes	Botones, cards, formularios, headers, footers o CTAs.	Reutilizar patrones en paginas nuevas.
Reglas visuales	Densidad, tono, jerarquia, responsive, accesibilidad.	Evitar resultados genericos.
Notas de conversion	Decisiones tomadas al importar o migrar frameworks.	Entender de donde viene cada token.

Detectar el sistema actual

Usa primero una lectura en seco:

Revisa el sitio y detecta si hay un builder o framework de diseno activo.

Despues ejecuta una importacion en dry_run del sistema de diseno:
- no escribas todavia en design.md;
- revisa tokens, colores, tipografias, spacing y breakpoints;
- detecta claves raras, genericas o ruidosas;
- proponme que se importaria y que limpiarias antes de guardar.

Importar design.md

Cuando el resultado sea correcto:

Con el resultado anterior, limpia los tokens ruidosos y escribe el design.md.

Condiciones:
- conserva solo tokens utiles y nombrados con sentido;
- incluye notas de conversion;
- no cambies paginas ni plantillas;
- resume lo que has escrito.

Curar tokens importados

No todo lo que se detecta debe guardarse. Algunos frameworks o builders generan claves genericas, internas o temporales. Antes de escribir, pide que Codex separe:

Tipo de token	Ejemplo	Decision
Semantico	`color-primary`, `font-display`, `space-section`	Mantener.
Utilitario claro	`radius-lg`, `shadow-card`, `container-xl`	Mantener si se usa.
Generico	`value`, `spacing`, `color`, `item`	Revisar o eliminar.
Ruido de plugin	Claves temporales o nombres sin relacion visual.	Eliminar salvo evidencia.
Conflicto	Dos tokens distintos con el mismo rol.	Resolver con alias o nota.

Cuando el sitio usa Tailwind o WindPress, pide especificamente buscar tokens en variables CSS y reglas @theme, ademas de opciones del builder. Esto mejora mucho la importacion.

WindPress

WindPress compila Tailwind en el navegador, cuando abres su editor. Por eso, cambiar su main.css no cambia lo que ve el visitante hasta que la caché se vuelve a generar.

A partir de la 0.3.2:

Kodavio ve WindPress aunque todavía no exista main.css, y puede crearlo.
Al parchear un fichero de diseño, la respuesta trae solo el cambio, no el fichero entero antes y después.
Tu agente puede subir la caché compilada sin abrir el editor de WindPress.

Para subir la caché, el agente sigue tres pasos:

kodavio/windpress-scan-classes le da las clases que usa el sitio y el main.css. Las busca con los mismos proveedores de contenido que usa WindPress.
Compila con Tailwind en su máquina. Necesita tener el CLI de Tailwind instalado.
kodavio/windpress-cache-write sube el resultado. Primero en ensayo; después pide confirmación doble, porque cambia el CSS de todo el sitio. Guarda copia de la caché anterior, y deshacerlo la devuelve tal cual.

Probado en un WordPress real con WindPress 3.3 y Tailwind 4.1: la página servida usa las clases nuevas, y tras deshacer vuelve la caché anterior.

Prompt recomendado:

He cambiado clases en varias páginas y no se ven en el sitio.
Escanea las clases de WindPress, compila la caché en tu máquina
y haz el ensayo de la subida. No la subas hasta que confirme.

La caché nunca se purga

Subir la caché la sustituye; nunca la purga. Tu agente no debe purgar la caché de WindPress salvo que se lo pidas expresamente.

Compilar fuera del sitio puede dejar fuera alguna clase que WindPress sí habría visto. Si falta un estilo después de subirla, deshaz la subida o regenera la caché desde el editor de WindPress.

Frameworks y builders

El plugin puede aprovechar informacion de:

Bricks global variables.
WindPress o Tailwind.
ACSS cuando esta disponible.
Core Framework cuando esta disponible.
Tokens propios de Kodavio.
Variables CSS del tema o child theme.
Configuracion de frameworks cuando hay adapter o senales suficientes.

Revision humana recomendada

Algunos frameworks generan claves muy genericas como value, spacing o nombres temporales. Antes de escribir design.md, revisa que los tokens tengan sentido para el proyecto.

Usarlo para crear paginas

Antes de pedir una pagina nueva:

Lee design.md y usalo como contrato visual.

No inventes colores, fuentes ni espaciados si ya hay tokens definidos.
Si falta algun token necesario, proponlo primero y explica por que.

Esto ayuda a que Bricks, Elementor y Gutenberg generen resultados consistentes entre si.

Como se aplica en cada builder

El mismo design.md no se aplica igual en todos los builders. Codex debe traducirlo al mecanismo natural de cada uno.

Destino	Como deberia usarlo	Ejemplo
Bricks	Variables globales, clases, estilos de elementos y componentes reutilizables.	Usar `color-primary`, `space-section` y radios globales en secciones nuevas.
Elementor	Settings de widgets/containers, estilos globales cuando existan y clases auxiliares.	Crear containers con gaps y tipografia coherente con el sistema.
Gutenberg	Clases, bloques core, patrones y atributos seguros.	Crear un CTA con clases semanticas y bloques core portables.
Framework externo	Adapter o equivalencias controladas.	Traducir tokens a WindPress/Tailwind, ACSS o Core Framework si esta soportado.

Cuando pidas una pagina, incluye siempre una condicion como:

Usa design.md como contrato visual.
Si necesitas un token que no existe, proponlo en vez de inventarlo silenciosamente.

Como se aplica en conversiones

En una conversion, design.md sirve para decidir que conservar y que normalizar:

Si el origen usa colores sueltos, Codex debe aproximarlos al token mas cercano.
Si el origen usa clases de un framework, debe buscar equivalentes en el sistema activo.
Si el destino no soporta un efecto, debe marcarlo como perdida o revision manual.
Si hay estilos duplicados, debe proponer limpiar despues, no durante la conversion.
Si un componente aparece varias veces, debe recomendar convertirlo en template, componente o patron.

Prompt recomendado:

Convierte esta pagina usando design.md como referencia.

Antes de crear nada:
- identifica tokens usados en origen;
- mapea colores, tipografias, spacing y radios al sistema actual;
- dime que estilos se perderian o cambiarian;
- prepara plan y dry_run;
- no limpies metadata antigua.

Cambiar de framework

Para mover el sistema de diseno de un framework a otro, pide un plan antes de escribir:

Quiero migrar el sistema de diseno de este sitio a otro framework.

Primero analiza el sistema actual, dime origen y destino posibles, y prepara un plan.
No escribas cambios todavia. Necesito ver:
- tokens que se pueden mapear directamente;
- tokens que necesitan decision manual;
- riesgos visuales;
- pasos recomendados.

Migracion entre frameworks de diseno

Cambiar de framework no debe ser un reemplazo ciego. El flujo recomendado es:

Detectar sistema actual y destino posible.
Exportar o leer tokens actuales.
Crear una tabla de equivalencias.
Marcar tokens sin equivalente.
Generar snapshot o backup.
Aplicar solo cuando el plan este revisado.
Probar paginas representativas.

Pide siempre que Codex distinga entre migrar tokens, migrar clases utilitarias y migrar estilos embebidos en paginas. Son problemas relacionados, pero no iguales.

Senales de que el sistema de diseno esta listo

Antes de usarlo como base de muchas paginas, revisa:

Los colores tienen nombres semanticos, no solo nombres tecnicos.
Hay escala de tipografia clara.
Spacing y containers tienen unidades consistentes.
Los breakpoints coinciden con el framework real.
No hay tokens ruidosos como value o item.
Hay notas de origen: Bricks, WindPress, Tailwind, ACSS, Core Framework o CSS variables.
Codex puede explicar como aplicaria los tokens en Bricks, Elementor y Gutenberg.