Cómo documentar un sistema de diseño para que una IA realmente lo siga

El instinto es dirigir al agente al sitio del sistema de diseño. Rara vez ayuda, por cuatro razones estructurales que no tienen nada que ver con la calidad del sitio.

La fila de organización es la que la gente pasa por alto. Un sitio organizado por componentes es perfecto para alguien que ya sabe que necesita un Botón. Un agente que está a punto de construir una pantalla aún no ha decidido qué componentes usar; sus primeras decisiones son sobre densidad, jerarquía y maquetación, y eso es exactamente lo que un sitio organizado por componentes nunca cubre.

La fila de integridad es la más trascendental. La documentación describe lo que existe porque para eso sirve la documentación. Pero la diferencia entre su interfaz y una genérica es, principalmente, un conjunto de cosas que usted nunca hace, y ninguna página de componentes las mencionará jamás.

Analizamos 299 archivos DESIGN.md publicados en repositorios y directorios públicos —archivos escritos deliberadamente para dar guías de diseño a agentes de IA— y medimos sus contenidos. 72 eran específicamente archivos de diseño visual. El patrón es lo suficientemente consistente como para usarlo como una lista de verificación de lo que se debe evitar.

Compare las dos últimas filas. La tipografía se menciona en el 83% de los archivos, pero el 44% no contiene ningún valor de tamaño concreto. Esa brecha resume todo el problema en una sola estadística: los archivos hablan de tipografía sin decir nunca qué tamaño tiene cada elemento.

La cifra de los adjetivos es la otra mitad. "Limpio" aparece en el 39% de estos archivos, "moderno" en el 36%. Ambas son palabras que un modelo satisface produciendo el centro de su distribución de entrenamiento, que es precisamente el aspecto genérico que el archivo pretendía evitar.

Cada uno de estos responde a un fallo medido anteriormente. Aplicados en conjunto, transforman una descripción en algo ejecutable.

1. 1

   Asigne un rol a cada color, no solo un valor

   #6b7280 es un valor que un modelo usará indistintamente para el texto del cuerpo, bordes, iconos, placeholders y estados desactivados. --text-muted, descrito únicamente como texto secundario y de apoyo, tiene una sola función. Cinco roles superan a un hex, y permiten cambiar los bordes más tarde sin alterar los subtítulos.

   Copy

   --text-muted: #6b7280   /* secondary and supporting text only */
   --border-subtle: #e5e7eb /* structural edges, dividers */
   --text-disabled: #9ca3af /* disabled controls only */

2. 2

   Sustituya cada adjetivo por un número o una regla

   "Espaciado generoso" se convierte en "gap de sección 64px, padding de tarjeta 24px". "Tipografía limpia" se convierte en una escala. Si una frase no puede contrastarse con una pantalla renderizada, es decoración.

3. 3

   Escriba las prohibiciones

   La sección con mayor impacto y la que el 76% de los archivos omite por completo. Cinco líneas son suficientes para empezar.

   Copy

   ## Never
   
   - No gradients
   - No drop shadows — elevation is a surface step plus a 1px border
   - No font-weight above 600
   - No colour value outside the token set
   - No border-radius above 12px

4. 4

   Defina el modo oscuro, no permita que sea derivado

   Si se deja sin definir, el modelo invierte el modo claro y el resultado falla de forma predecible: las sombras dejan de leerse, los grises medios pierden contraste en ambos extremos y un color de acento saturado que se veía bien sobre blanco deslumbra sobre un fondo casi negro. Un segundo set de tokens cuesta una hora de trabajo y elimina toda una categoría de correcciones.

5. 5

   Declare la decisión de densidad explícitamente

   Saber si se trata de una herramienta densa o de una superficie de marketing espaciosa cambia cada decisión posterior, y es la decisión que la mayoría de los archivos nunca toma. Si su producto tiene ambos tipos de superficie, eso requiere dos archivos, no un solo archivo ambiguo.

6. 6

   Nombre al menos dos motivos

   Los elementos específicos y recurrentes que hacen que el diseño sea suyo: una línea de acento de 2px a la izquierda de los encabezados de sección, columnas numéricas siempre tabulares y alineadas a la derecha, una forma particular de dibujar los estados vacíos. El 57% de los archivos no tienen ninguno, razón por la cual su resultado es correcto pero carece de personalidad.

7. 7

   Apunte al archivo de tokens; nunca lo repita

   En el momento en que un valor hex existe tanto en el archivo de diseño como en el de tokens, uno se actualizará y el otro no, y el modelo usará con seguridad el valor obsoleto. Referencie, no copie.

Lo que producen los siete cambios, al final, es un archivo cuyos valores un agente puede resolver sin inventar nada. Esta es la misma información renderizada en lugar de escrita; útil aquí como una lista de verificación de lo que su propio archivo debe ser capaz de responder:

No todas las prohibiciones funcionan igual. Tres propiedades separan aquellas que cambian el resultado de las que son ignoradas.

La tercera fila es la que se suele pasar por alto. Una prohibición sin alternativa crea un vacío que el modelo debe llenar, y lo hace basándose en la misma distribución de entrenamiento de la que usted intentaba escapar. Cada "nunca X" debe ir seguido de "en su lugar, Y".

El archivo debe caber en el contexto junto con la tarea real, lo que impone un límite real. Aproximadamente 400 líneas es un objetivo viable; a partir de ahí, las reglas individuales empiezan a perder prioridad frente a la tarea.

El orden también importa. Coloque la intención y las prohibiciones al principio. Un modelo que lee de arriba abajo encuentra la regla general antes que el caso especial, que es el mismo orden que Stripe utiliza en su Appearance API: primero el tema, luego las variables y después las reglas específicas.

# DESIGN.md

## Intent            <- who reads this product, and what it is for
## Never             <- the prohibitions, early and unmissable
## Colour            <- roles for light and dark, referencing tokens
## Type              <- scale with real numbers, weight band, tracking
## Spacing & density <- the scale, and which surface uses which step
## Elevation         <- the strategy, stated once
## Composition       <- how components sit together
## Motifs            <- what makes this design specifically ours

No todo debe estar en el archivo; intentar incluirlo todo es lo que hace que crezca hasta dejar de ser útil. La línea divisoria es si el agente lo necesita antes de decidir o solo bajo demanda.

El servidor MCP de Carbon de IBM es un buen modelo para la primera columna: expone la búsqueda de documentación, ejemplos de código de componentes, gráficos y componentes experimentales como herramientas. Notablemente, ninguna de estas son prohibiciones, porque una herramienta de recuperación solo muestra lo que el agente piensa consultar. Más sobre esta división.

Escribir el archivo y asumir que ha funcionado es la forma en que los equipos descubren el problema tres semanas después. Cuatro comprobaciones, en orden creciente de esfuerzo.

1. 1

   Busque valores de color literales mediante grep

   Si el agente sigue los roles semánticos, no debería haber ningún valor hex fuera de su archivo de tokens.

   Copy

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

2. 2

   Busque mediante grep los pesos prohibidos

   El peso es donde la jerarquía suele revertirse silenciosamente al valor predeterminado, y es la señal más rápida de que una prohibición no se está aplicando.

   Copy

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

3. 3

   Solicite la misma pantalla dos veces, en sesiones separadas

   La consistencia entre sesiones es la prueba real. Si dos ejecuciones difieren significativamente en espaciado, radio o jerarquía, el archivo no está restringiendo lo necesario, y el diff le indicará exactamente qué sección falta.

4. 4

   Construya primero una pantalla en modo oscuro

   Si el modo oscuro fue derivado en lugar de definido, aquí es donde saldrá a la luz. Es mucho más económico detectarlo en la pantalla uno que en la pantalla veinte.

Las dos primeras comprobaciones deben integrarse en CI. Un control que rechace un pull request que contenga un valor hex bruto aporta más a la consistencia a largo plazo que cualquier documentación; esta es la conclusión a la que llegó Salesforce con el linter de SLDS y Stripe al eliminar la capacidad por completo.