Qué es DESIGN.md y cómo escribir uno que tu herramienta de IA respete
El formato, qué poner dentro y dónde se queda corto, desde un catálogo de 13 sistemas de diseño que lo incluyen.
En resumen
DESIGN.md es un archivo Markdown que describe una identidad visual a los agentes de código, para que construyan con tus colores, tipografías y reglas en vez de usar sus valores por defecto. Google Labs lo publica como formato abierto, todavía en alfa. Los valores exactos le dan el aspecto y las razones escritas le dicen cómo usarlos.
- El formato combina tokens legibles por máquina en YAML con razones escritas en Markdown.
- Copiar el archivo de una marca famosa enseña el formato, pero esa identidad sigue sin ser tuya.
- Las reglas sobre qué evitar y cómo se mueven las cosas suelen ser las líneas más útiles.
- Un DESIGN.md fija un sistema. No decide qué dice cada página ni cómo se desarrolla.
- Nuestros 13 archivos tienen entre 1.614 y 2.897 palabras, así que es un documento de verdad.
Qué es DESIGN.md
DESIGN.md es un archivo Markdown que le da a un agente de código una descripción duradera de tu identidad visual. Sin él, el agente recurre a lo que más ha visto, y por eso tantas webs hechas con IA se parecen.
La especificación (se abre en una pestaña nueva) es de Google Labs, con licencia Apache 2.0, y su estado es alfa. Un archivo tiene dos capas. Los tokens en YAML guardan los valores exactos, y la prosa en Markdown explica por qué existen esos valores y cómo aplicarlos.
Qué lleva un archivo DESIGN.md
Un DESIGN.md lleva tokens exactos arriba y orientación escrita por secciones debajo. El formato oficial usa esta estructura:
| Capa | Qué contiene | Ejemplo |
|---|---|---|
| Tokens | Colores, tipografía, espacios y radios con valores exactos | primary: "#1A1C1E" |
| Overview | El carácter de la identidad | «Un periódico de gama alta» |
| Colors | La función de cada color | «El único que indica interacción» |
| Typography, Layout, Shapes | Cómo aplicar tipografía, espacio y forma | Márgenes, retículas, reglas de esquinas |
| Components | Cómo se ven y se comportan las piezas | Botones y sus estados |
| Do’s and don’ts | Qué mantiene intacta la identidad | «Nunca dos colores de acento» |
Basado en la especificación DESIGN.md de Google Labs, versión alfa. Los ejemplos son ilustrativos.
El mismo proyecto publica una herramienta de línea de comandos que comprueba un archivo contra el formato, incluidas las referencias de tokens y el contraste. Úsala cuando tengas tu archivo.
Cómo es uno real
Un archivo útil describe una identidad con tanta precisión que dos personas tomarían la misma decisión. Este es el comienzo, abreviado, del DESIGN.md de nuestro sistema de diseño RUBRA, que está escrito en inglés:
1. Character
Editorial, warm, exact. A RUBRA page reads like a botanical plate in a good
book: cream paper, a fine serif, hairline rules, one red that means growth.
Nothing is decorative unless it carries information.
2. Colour
| Token | Value | Use |
| --rb-paper | #EEE6D8 | Page background |
| --rb-ink | #221613 | Text, control borders, the traced tree |
| --rb-vermilion | #E0321F | The bloom, focus rings, accent type |Fíjate en «one red that means growth», un solo rojo que significa crecimiento. Esa línea evita que el agente agregue un segundo color de acento, y un código hexadecimal solo no lo haría. Nuestros archivos también cubren tipografía, retícula, componentes, movimiento, imágenes, textos y un mínimo de accesibilidad, y terminan con una lista de qué hacer y qué evitar.
También se diferencian del formato oficial en una cosa. Los nuestros abren con prosa y guardan los valores en un archivo CSS junto al documento, porque cada uno viene dentro de un kit con componentes en vivo. Una herramienta que solo lea tokens en YAML no los encontraría ahí.
Por qué no basta con copiar el archivo de una marca famosa
Un archivo extraído de una marca famosa sirve para aprender el formato, pero describe la identidad de otro. Las colecciones de estos archivos son muy populares: awesome-design-md (se abre en una pestaña nueva) supera las 125.000 estrellas en GitHub.
Resuelven el primer problema, porque el agente deja de usar sus valores por defecto. Dejan otros tres:
- Te pareces a ellos. Tu web hereda un aspecto que pertenece a otra empresa, lo que es mal comienzo para una marca y un riesgo si la publicas como propia.
- La extracción muestra el qué, no el porqué. Leer una web te da sus colores y tamaños. Casi nunca te da la regla que hay detrás, y esa regla es la que aguanta en una página que la marca nunca diseñó.
- Casi no hay movimiento. Cómo se mueve una web no se puede leer solo de una hoja de estilos, y el movimiento pesa mucho en que una web se sienta diseñada.
DESIGN.md, capturas o un prompt terminado
Usa un DESIGN.md para mantener un sistema coherente, capturas para mostrar un ambiente y un prompt terminado para reconstruir una web concreta. Responden a preguntas distintas, así que muchos proyectos necesitan más de uno.
| Entrada | Sirve para | Dónde se queda corta |
|---|---|---|
| Capturas | Mostrar una sensación rápido | El agente adivina cada valor, y el movimiento no se ve |
| DESIGN.md | Mantener coherentes muchas páginas | No dice qué lleva una página ni cómo se desarrolla |
| Prompt terminado | Reconstruir una web completa | Es largo y solo sirve para esa web |
Nuestra opinión de trabajar con las tres. Todavía no las medimos una al lado de la otra.
Un DESIGN.md no convierte una página floja en una buena. Puede dejar cada tarjeta del color correcto y seguir dándote un hero con tres tarjetas. Para la página en sí, sigues necesitando un prompt que fije todo el recorrido.
Cómo escribir el tuyo
Empieza por las decisiones en las que el agente se sigue equivocando, y añade una regla cada vez que corrijas algo dos veces. Una primera versión lleva menos tiempo que las correcciones que ahorra:
- Describe el carácter en dos frases. Compáralo con algo físico, como un libro impreso o una máquina.
- Dale una función a cada color. Si dos colores hacen lo mismo, quita uno.
- Fija dos tipografías con tamaños, incluido lo que el titular no debe hacer nunca.
- Nombra un rasgo propio. Lo único que hace que una página sea reconociblemente tuya.
- Describe el movimiento. El disparador, el cambio, la duración y el estado final.
- Escribe qué evitar. Tarjetas redondeadas, degradados y heroes centrados son lo primero que elegirá el agente.
- Pruébalo. Reconstruye una página en una sesión limpia y arregla lo que salió mal.
Si usas Claude Code, guarda el archivo junto al proceso de nuestra guía cómo crear una página web con Claude Code.
Veredicto. Escribe un DESIGN.md en cuanto construyas más de una página. Empieza corto, añade una regla cada vez que corrijas algo dos veces y no esperes que diseñe la página por ti.
Preguntas
Respuestas cortas a lo que suele venir después.
¿Quién creó DESIGN.md?
Google Labs publica la especificación con licencia Apache 2.0, y su herramienta de diseño Stitch usa el formato. La especificación está marcada como alfa, así que puede cambiar. Como es Markdown plano, también puedes dárselo a otras herramientas.
¿Dónde se pone un archivo DESIGN.md?
En la raíz del proyecto, junto a la demás documentación y guardado en el repositorio. Después menciónalo en tu pedido o en tu CLAUDE.md, para que el agente lo lea antes de empezar. No des por hecho que todas las herramientas lo encuentran solas.
¿DESIGN.md funciona con Claude Code, Cursor y Lovable?
Cualquier herramienta que pueda leer un archivo puede usarlo, porque es texto plano. Lo que cambia es cuánto lo respeta cada una. Nosotros se lo damos a Claude con el pedido y reconstruimos para comprobarlo. Todavía no comparamos todas, así que prueba primero con una sección.
¿Qué diferencia hay entre DESIGN.md y CLAUDE.md?
CLAUDE.md dice cómo trabajar en un proyecto, con su proceso, comandos y reglas. DESIGN.md dice cómo se ve y se comporta el producto. Mantenlos separados y enlaza uno desde el otro, para que un cambio visual no toque tus instrucciones de trabajo.
¿Qué longitud debe tener un DESIGN.md?
La necesaria para resolver lo que el agente adivinaría. Los nuestros tienen entre 1.614 y 2.897 palabras, porque también cubren componentes, movimiento y accesibilidad. Un archivo corto con colores y tipografía ya sirve para un proyecto pequeño.
¿Hace falta un sistema de diseño antes de escribir un DESIGN.md?
Hacen falta decisiones, no un sistema terminado. Una paleta con una función para cada color, dos tipografías, una escala de espacios y unas pocas reglas bastan para empezar. Añade una línea cada vez que el agente se equivoque.
Olvídate de la página en blanco
Empieza desde una web terminada.
Cada plantilla es un prompt probado con su código, sus recursos y su movimiento.Sigue leyendo
Todos los artículos
Cómo escribir un prompt para crear una web completa
Las seis partes que necesita un prompt para crear una web completa, medidas en 62 prompts de nuestro catálogo.
Cómo hacer un vídeo de fondo en bucle sin corte para una web
Cinco pasos para un bucle de hero sin corte visible, desde el prompt de generación hasta la etiqueta de vídeo final.