Sistemas de diseño para agentes de código de IA

Pida a cualquier agente de código que "cree una landing page" y obtendrá lo mismo: un hero casi negro, un degradado violeta, Inter, tres tarjetas de características con esquinas redondeadas. Es competente y completamente genérico, porque el modelo no tiene memoria de su marca entre prompts. Si añade una segunda página, el estilo diverge: espaciados diferentes, un azul ligeramente distinto, una nueva forma de botón. No hay una fuente de verdad para la apariencia, por lo que no hay consistencia.

Vale la pena ser precisos sobre el porqué, ya que la razón determina la solución. El modelo no está fallando en el diseño; está haciendo exactamente lo que se le pidió: producir la interfaz más probable según la solicitud. A falta de una restricción, la interfaz más probable es el centro de todo lo que ha visto, y cualquier persona que use prompts sin restricciones llegará al mismo centro.

Esto redefine la solución. No se trata de intentar que el agente sea más creativo, sino de intentar desplazarlo del centro y mantenerlo en un lugar específico, lo cual requiere definir cuál es ese lugar y qué queda fuera de él.

Analizamos 299 archivos DESIGN.md publicados en repositorios y directorios públicos (archivos reales, escritos por equipos reales para dar pautas de diseño a los agentes) y medimos qué contenían en lugar de lo que pretendían contener. 72 eran específicamente archivos de diseño visual. El patrón es lo suficientemente consistente como para ser diagnóstico.

La última fila es la clave. La tipografía se menciona en el 83% de los archivos, y el 44% de esos mismos archivos no contiene ningún valor de tamaño concreto. "Use una jerarquía tipográfica clara" es una mención. No es una instrucción, y el modelo la satisface con cualquier jerarquía que sea más común en sus datos de entrenamiento.

Los dos números más importantes son la cifra de prohibiciones y la de roles semánticos, y ambos fallan de la misma manera. Un archivo que enumera #3b82f6 como "primary" sin prohibir nada le ha dicho al modelo que existe un azul específico, pero ha dejado abierta cualquier decisión sobre dónde usarlo. El agente lo utiliza entonces en encabezados, enlaces, rellenos de iconos, un borde y un degradado, porque todos esos son usos plausibles de un color primario.

Un sistema de diseño que sobreviva a ser leído por un modelo, aplicado en veinte archivos y retomado en la siguiente sesión necesita seis partes. Cada una de ellas soluciona un fallo específico.

La fila del modo oscuro es la que los equipos subestiman. Derivar el modo oscuro invirtiendo el modo claro es lo que hace un modelo cuando nada le indica lo contrario, y falla de formas predecibles: las sombras dejan de leerse contra superficies oscuras, los grises medios pierden contraste tanto con el texto como con el fondo, y un acento saturado que se veía seguro sobre blanco se vuelve deslumbrante sobre un color casi negro. Definirlo cuesta un segundo conjunto de tokens y elimina toda una categoría de retrabajo.

Un kit es un sistema completo, no una paleta. A continuación se muestra una vista previa en vivo del kit gratuito ambient-sage: los mismos tokens, fuentes y tratamientos que recibe un agente cuando lo aplica. Todo en esta página podría repintarse cambiando el kit.

Independientemente de cómo lo instale, la carga útil son las mismas tres cosas:

1. Un DESIGN.md: el brief escrito: la intención del diseño, el sistema tipográfico, las reglas de espaciado y maquetación, los tratamientos de componentes, los motivos distintivos y los aciertos y errores. Esto es lo que evita que el agente recurra a lo genérico. Qué es un DESIGN.md y cómo generar uno.
2. Design tokens semánticos de color: 28 roles (background, foreground, primary, muted, card, border, chart-1…5 y más) tanto en modo claro como oscuro. El agente aplica estilos basándose en los nombres de los roles, no en el hex puro, para que los temas mantengan la coherencia. Explicación de los design tokens semánticos de color.
3. Exportaciones de framework: el mismo sistema como variables CSS, @theme de Tailwind v3/v4, un elemento de registro de shadcn o JSON de DTCG/W3C. El agente conecta el que coincida con su stack.

Los nombres de los roles en el segundo punto hacen más trabajo de lo que parece. --color-muted-foreground le indica al modelo tanto cuál es el valor como dónde pertenece; --gray-400 solo le indica el valor, y el agente decide por sí mismo qué gris debe tener un pie de foto. En esa decisión es donde se filtra la consistencia, archivo por archivo.

La mecánica varía según la herramienta: los agentes de código ejecutan un servidor MCP local, los constructores web utilizan el registro de shadcn o el DESIGN.md exportado. Elija su herramienta:

• Dar un sistema de diseño a Claude Code: MCP a través de .mcp.json, o identityforge apply.
• Asigne un sistema de diseño a Cursor: MCP a través de .cursor/mcp.json, además de cómo estructurar los archivos de reglas.
• Asigne un sistema de diseño a Windsurf: configuración manual de MCP para Cascade y la ruta de la CLI.
• Asigne un sistema de diseño a v0: el registro de shadcn + DESIGN.md como brief.
• Asigne un sistema de diseño a Lovable: conocimiento del proyecto + shadcn add en el repositorio.
• Asigne un sistema de diseño a Bolt: ejecute shadcn add directamente en la terminal de Bolt.

Ambos, y por razones distintas. Vale la pena entender bien la distinción, ya que instalar un servidor MCP esperando que el resultado sea visualmente mejor es una decepción común.

Las prohibiciones son el caso más claro para el archivo. Un agente que está a punto de añadir una sombra paralela no tiene motivos para preguntar "¿están permitidas las sombras paralelas?", por lo que una restricción que reside tras una llamada a una herramienta es una restricción que nunca se ejecuta. Las restricciones deben estar presentes antes de la decisión. Más sobre dónde corresponde cada una.

Explore los kits por estilo visual para ver sistemas completos en contexto: tipografía, color, superficies y reglas de construcción. Cada kit tiene un id permanente y un slug legible; una vez que se conoce cualquiera de los dos, el agente puede omitir la búsqueda y aplicarlo directamente. Los slugs pueden renombrarse, pero el antiguo sigue resolviendo, por lo que un identificador almacenado no queda obsoleto. Si ya tiene colores de marca, la herramienta MCP match_palette encuentra los kits que mejor se adapten perceptualmente.

Instalar un sistema de diseño y asumir que ha funcionado es la razón por la que los equipos acaban sorprendidos tres semanas después. Cuatro comprobaciones, en orden creciente de esfuerzo:

1. 1

   Buscar valores de color literales con grep

   La señal más rápida posible. Si el agente sigue los design tokens semánticos, no debería haber ningún valor hex fuera de su archivo de tokens.

   Copy

   # any hex outside the token definitions
   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Comprobar los grosores de fuente (font weights)

   El grosor es donde la jerarquía vuelve silenciosamente al valor predeterminado. Si su sistema indica solo 400 y 600, cualquier otro valor es una desviación.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black|semibold)' src | head -30

3. 3

   Solicitar la misma pantalla dos veces, en sesiones separadas

   La consistencia entre sesiones es la prueba real. Si dos ejecuciones producen espaciados, radios o jerarquías significativamente diferentes, el sistema no está restringiendo lo que debería.

4. 4

   Construir primero una pantalla en modo oscuro

   Si el modo oscuro fue derivado en lugar de definido, aquí es donde se nota: sombras inertes, grises medios turbios, un color de acento deslumbrante. Es más barato detectarlo ahora que después de veinte pantallas.

Las dos primeras comprobaciones merece la pena ejecutarlas en CI. Una regla que detecte un valor hex bruto en un pull request aporta más a la consistencia a largo plazo que cualquier cantidad de documentación, que es la misma conclusión a la que llegó Salesforce con el linter de SLDS.