Cómo escribir un DESIGN.md
Un DESIGN.md solo funciona si la máquina nunca tiene que adivinar. Pon orientación antes que detalle, valores antes que adjetivos y cubre los componentes reales. Esta es la estructura que funciona y los errores que la rompen.
Empieza con orientación, no con detalle
Primero indica qué está viendo la máquina: nombre, esencia en una frase e indicadores que cambian lo posterior, como claro u oscuro.
Suele ir en un bloque estructurado al principio; YAML frontmatter es la convención de la especificación DESIGN.md abierta de Google. El agente lo lee antes de interpretar el resto. Abrir con cincuenta colores sin orientación obliga a reconstruir la intención.
Indica valores, no adjetivos
"Warm, minimal, editorial" means something different to every model on every run. "Background <hex>, ink <hex>, one accent <hex>, body type at <px> with a 1.5 line height, spacing on an <px> rhythm" means the same thing every time. Tokens are the contract; adjectives are decoration.
Nombra tokens por función —background, ink, accent, line—, no por aspecto. Los nombres de función sobreviven a cambios de tema e indican dónde va el valor.
Da una función a la prosa: explica por qué y cómo combinar. «El acento se reserva a una acción por pantalla» es obedecible; «la paleta se siente tranquila» no.
Cubre los componentes que construirá el agente
Los tokens no determinan toda la UI. Con la misma paleta cambia si los botones son rellenos o delineados, las esquinas rectas o redondas, las tarjetas llevan sombra o línea y el énfasis usa peso, tamaño o color.
Escribe reglas declarativas breves para botones, tarjetas, inputs y navegación, y añade límites de uso. Si el agente sabe que un estilo es editorial, no lo forzará sobre un dashboard denso.
Errores que rompen una especificación
Adjetivos sin valores: una descripción bonita sin números hace que el agente invente su paleta.
Volcar todo el manual: DESIGN.md es una especificación de trabajo, no un archivo. Si tarda más en leerse que la pantalla en construirse, el agente hojea y adivina. Conserva solo lo que cambia la salida.
Sin límites de uso: se aplicará mal en todas partes.
Dejar pudrirse DESIGN.md: trátalo como código y actualízalo en el mismo commit que el diseño, o aplicará el del trimestre anterior.
Referencias internas incoherentes: si tipografía y ejemplos implican escalas distintas, el agente elegirá una sin avisar.
O elige uno ya preparado
Vale la pena escribir DESIGN.md para un sistema propio. Pero si quieres Bauhaus, Swiss International o un estilo contemporáneo de marca, tendrías que reconstruir un movimiento entero y lo normal es equivocarse en matices.
Para eso sirve una biblioteca. Curio entrega cientos de estilos reales como DESIGN.md completos, investigados y listos para aplicar mediante MCP, enlace o descarga. Elige el estilo; el archivo ya está escrito.
FAQ
¿Qué longitud debe tener un DESIGN.md?
Tan corto como sea posible sin dejar preguntas visuales. Suele ocupar una o dos páginas: orientación, tokens, componentes recurrentes y límites. Si una sección no cambia lo que construye la AI, elimínala.
¿Dónde debe vivir el archivo?
En la raíz, junto a README.md. Es donde miran primero los agentes y sigue la convención del nombre. Algunas herramientas aceptan una ruta o MCP, pero la raíz funciona en todas.
¿Uno o varios archivos?
Uno. El objetivo es leer el sistema completo en una pasada. Repartirlo obliga al agente a encontrar y reconciliar archivos, reintroduciendo la adivinación.
¿Necesito YAML frontmatter?
Es la convención de Google y resulta fácil de analizar, así que es un buen valor predeterminado. La regla profunda es orientación antes que detalle: explica el estilo antes de listar valores.