DESIGN.md comenzó en Google Labs como el formato detrás de Stitch, su herramienta de generación de UI. Google publicó la especificación como código abierto y la especificación ahora reside en GitHub. Se extendió rápidamente más allá de Google: Atlassian publicó un relato sobre las pruebas de contexto de diseño portátil en la práctica, y surgió un ecosistema de catálogos a su alrededor.

La extensión .md es simplemente markdown. El archivo no tiene una sintaxis especial, ni un esquema contra el cual validar, ni un paso de compilación. Esto es deliberado: un agente lo lee de la misma manera que lee cualquier otro archivo de su repositorio.

Un agente de código al que se le pide construir una UI debe obtener sus valores visuales de algún lugar. A falta de una fuente, utiliza los valores predeterminados de la librería, que es por qué los productos creados con IA convergen en una misma apariencia. Puede proporcionar valores en un prompt, pero los prompts viven en una conversación y las conversaciones se degradan a medida que crecen.

Un archivo no se degrada. Ese es el mecanismo fundamental, y todo lo demás sobre el formato se deriva de ello.

En lugar de suponer, hemos tomado una muestra. Extrajimos 299 archivos DESIGN.md de la raíz de repositorios mediante la búsqueda de código de GitHub y analizamos el contenido de cada uno. El primer resultado fue una sorpresa y redefine todo lo demás.

Dentro de esos 72 archivos genuinos de diseño visual, el panorama es consistente. El archivo mediano tiene 1,337 palabras en 263 líneas, por lo que no son borradores simples: la gente está dedicando un esfuerzo real. Lo están aplicando a las mismas tres secciones y omitiendo las mismas cuatro.

El color y la tipografía son casi universales. El radio, la elevación, la iconografía y la accesibilidad son poco comunes. Y hay una omisión más grave que todas estas, porque es invisible hasta que alguien pulsa un interruptor.

De los 72 archivos de diseño visual que analizamos, 50 no contienen ningún modo oscuro: sin bloques .dark, sin prefers-color-scheme, sin un segundo conjunto de valores. Eso es el 69%.

Este es el vacío más crítico en la forma en que se aplica el formato, y falla silenciosamente. Todo parece correcto en modo claro. Entonces, el usuario cambia el tema y el agente tiene que inventar cada valor oscuro sobre la marcha: un fondo que nunca fue elegido, un primer plano cuyo contraste nunca se comprobó, un color de acento que se desvanece porque nadie aumentó su croma para un fondo oscuro.

## Color

### Light
--background: oklch(0.98 0.006 85)
--foreground: oklch(0.22 0.014 85)
--card:       oklch(1 0 0)
--muted-foreground: oklch(0.48 0.012 85)
--primary:    oklch(0.52 0.13 152)
--border:     oklch(0.90 0.008 85)

### Dark
--background: oklch(0.17 0.010 85)   /* not pure black */
--foreground: oklch(0.95 0.006 85)   /* not pure white */
--card:       oklch(0.22 0.010 85)   /* raised, not shadowed */
--muted-foreground: oklch(0.70 0.010 85)
--primary:    oklch(0.68 0.16 152)   /* higher chroma to survive the dark ground */
--border:     oklch(0.30 0.010 85)

Solo el 6% de los archivos analizados utilizan OKLCH. Vale la pena hacer el cambio específicamente aquí porque su canal de luminosidad es perceptualmente uniforme, por lo que puede cambiar un tono sin tener que volver a comprobar cada par de contraste.

La decisión más trascendental del archivo es nombrar por *rol* en lugar de por tono. --primary le indica al agente dónde va el valor; --blue-600 no. Los roles le permiten aplicar su sistema correctamente en situaciones que nunca anticipó y sobreviven a un cambio de marca.

El 86% de los archivos analizados no utilizan nombres de roles semánticos. Enumeran códigos hex o nombran los colores por su tono. Esa es la diferencia entre un archivo que un agente puede aplicar a un componente que nunca describió y un archivo del que solo puede copiar. La capa de tokens semánticos es la que realiza el trabajo real aquí.

Defina las familias, los pesos, el tracking y los pasos de la escala. El error común es escribir *una serif para encabezados, una sans para el cuerpo*; una instrucción que el agente debe resolver, y la resolverá de forma distinta cada vez.

## Typography

Heading: "Fraunces", serif — 600, tracking -0.02em
Body:    "Inter", sans-serif — 400, line-height 1.6
Mono:    "JetBrains Mono" — 400, tabular figures in tables

Scale: 0.8125 / 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem
H1 uses 3rem at 1.05 line-height; body copy never exceeds 68ch.

Una escala de espaciado, un radio que varíe según el tamaño del elemento y dos o tres niveles de elevación que coincidan con una fuente de luz. El radio solo está cubierto en el 21% de los archivos y la elevación en el 26%, razón por la cual gran parte de la UI generada tiene una esquina de 0.5rem en cada elemento, independientemente de su tamaño.

## Spacing
Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96px
Section rhythm: 96px desktop, 64px mobile.

## Radius
sm 0.25rem (inputs) · md 0.5rem (buttons) · lg 0.875rem (cards) · xl 1.25rem (modals)

## Elevation
0 flush — use a border, no shadow
1 cards — 0 1px 2px rgb(0 0 0 / 0.06)
2 dropdowns — 0 4px 12px rgb(0 0 0 / 0.08)
Dark mode: raise the surface, do not deepen the shadow.

Los tokens indican al agente qué valores usar. No dicen nada sobre qué hacer cuando se encuentra con un componente que su archivo nunca mencionó. Los motivos y las prohibiciones cubren ese vacío, y son la diferencia entre un archivo que restringe el resultado y uno que simplemente le da color.

El 76% de los archivos no definen prohibiciones y el 57% no definen motivos. Estas son las dos secciones más sencillas de escribir y las dos que más a menudo faltan.

## Motifs
- Hairline rules separate sections; no boxed cards on marketing pages.
- Numerals are tabular everywhere they can be compared.
- One accent per screen. If two things compete, one becomes muted.

## Don't
- No gradient text, ever.
- No shadow on a flush surface — use --border.
- Never hardcode a hex. If a role is missing, add the role.

Cubra las primitivas que aportan más identidad: botones, inputs y tarjetas, con sus estados. No necesita incluir cada componente. La iconografía es la sección más sencilla del archivo y la más rara en la práctica, con un 10%: nombre la librería de iconos, el grosor del trazo, los pasos de tamaño y una línea sobre el tratamiento de imágenes.

Más allá de las secciones faltantes, un modo de fallo aparece en más de la mitad del corpus: escribir un adjetivo donde debería ir un valor.

El 54% de los archivos analizados contienen al menos un adjetivo vago que sustituye a una decisión. Los más comunes fueron *clean* (39% de los archivos), *modern* (36%) y *professional* (22%), seguidos de *generous whitespace*, *elegant* y *beautiful*. Además, el 44% no contiene ningún valor concreto de espaciado o tamaño en ningún lugar del archivo.

1. Adjetivos en lugar de valores. El defecto más común, presente en más de la mitad de los archivos.
2. Dark mode omitido. En el 69%, y falla silenciosamente.
3. Colores nombrados por tono en lugar de por rol. En el 86%, y se rompe en cuanto el agente se encuentra con un componente que usted no describió.
4. Sin prohibiciones. En el 76%. Las prohibiciones se siguen con más fiabilidad que las preferencias.
5. Una sección que dice 'use your judgment'. Peor que no tener sección, porque devuelve exactamente la discreción que el resto del archivo intentaba restringir.

Colóquelo en la raíz del repositorio, junto a AGENTS.md. La raíz es fundamental: un DESIGN.md anidado en docs/ es un documento para humanos, y los agentes que buscan la convención miran en la raíz.

A continuación, haga referencia a él desde las instrucciones de su agente en una sola línea, para que sea descubierto en lugar de hallado por azar. Es un elemento hermano de esos archivos en lugar de un competidor: los cuatro archivos realizan tareas distintas.

# AGENTS.md

## Design
Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

AGENTS.md es la convención más amplia para las instrucciones de los agentes y es leída por un conjunto creciente de herramientas. DESIGN.md contiene el contrato visual; AGENTS.md lo señala.

Esta es la parte que omiten todos los demás tutoriales. Un DESIGN.md es tan bueno como la interfaz que produce, y las secciones anteriores no son una ilustración: son la forma serializada del kit que se muestra a continuación.

Si lo escribe a mano, las dos secciones por las que debe obligarse a pasar son el dark mode y las prohibiciones. El corpus es inequívoco en que esas son las que la gente omite, y son las que determinan si el archivo restringe algo o no.