
guía en español
DESIGN.md
El archivo que le explica tu sistema de diseño a un agente de código: qué es, cómo se escribe y cómo lo resuelven tres marcas.
Qué es
Un agente que construye interfaces sin contexto elige colores, tipografías y espaciados genéricos. DESIGN.md resuelve eso con un archivo markdown que vive en el repositorio y describe la identidad visual del producto, para que el agente la lea antes de tocar una pantalla.
El formato nació en Stitch, la herramienta de diseño de Google Labs. El 21 de abril de 2026 Google abrió el borrador de la especificación con licencia Apache 2.0, en estado alpha. Se basa en el formato de tokens de la W3C (DTCG), así que convive con los tokens que ya usa tu equipo.
Anatomía
La especificación define dos capas. Los tokens, en YAML al inicio del archivo, son los valores normativos: colores, tipografía, radios, espaciado y componentes. La prosa, en secciones de markdown, explica para qué existe cada valor y cuándo no usarlo.
---
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
rounded:
md: 8px
spacing:
md: 16px
---
## Colors
- **Tertiary (#B8422E):** el único color de interacción.
- **Neutral (#F7F5F2):** fondo cálido, más suave que el blanco puro.
La especificación trae una CLI. lint revisa la estructura, que cada referencia a un token exista y el contraste WCAG de cada par de colores. diff compara dos versiones y falla si la nueva tiene más problemas, así que sirve en CI para que un cambio de tokens no rompa la accesibilidad.
npx @google/design.md lint DESIGN.mdnpx @google/design.md diff DESIGN.md DESIGN-v2.md
Cuatro formas de escribirlo
En la práctica, cada equipo lo resuelve distinto. La diferencia que más importa es dónde vive la verdad de los tokens y quién escribe el archivo.
| Forma | Ejemplo | Dónde viven los tokens | Fuerte en | Cuidado con |
|---|---|---|---|---|
| Formato de la especificación | El ejemplo de Google | En el YAML del archivo | Se valida con lint y diff | Poco criterio si la prosa es corta |
| Puente a un registry | Crafter | En un theme.json instalable | Los tokens se instalan, no se copian | Depende de su stack de componentes |
| Brief de marca | Vercel | En una API de CSS publicada | Proceso, prioridades y criterio | Largo y pensado para un tipo de página |
| Extraído por terceros | Supabase | Inferidos del CSS del sitio | Rápido para cualquier marca | No es oficial y envejece |

Caso Crafter: un DESIGN.md que instala su sistema
crafter.run/design.md es el de Crafter Station, el estudio detrás de Taste hacking, y conecta la prosa con su librería Crafter UI. Pesa unos 10 KB y no repite los tokens en YAML: manda al agente a instalar theme.json desde el registry y declara que, en una librería derivada, ese archivo manda sobre la paleta base.

Lo más útil son las reglas con números, que un agente puede cumplir o violar sin ambigüedad:
- Ningún texto por debajo de 14 px, ni siquiera en SVG o canvas: si no entra, se reacomoda el layout.
- Nunca blanco ni negro puros para fondo o texto.
- El amarillo de marca es superficie o detalle, nunca texto chico sobre papel; para texto hay un color de acento accesible.
- Espaciado desde un ritmo de 4 px: 4 a 8 dentro de un grupo, 12 a 16 entre campos, 24 a 32 entre secciones.
- Pares de “bien” y “evitar” en cada sección, y una lista final para revisar la pantalla terminada.
Para los componentes no describe cada uno: apunta a llms.txt y a /r/<componente>.json, así que el agente descubre e instala solo lo que falta.

Caso Vercel: un brief con criterio
vercel.com/design.md no sigue el YAML de la especificación. Empieza con un encabezado de nombre y descripción, como una skill de agente, y está pensado para un trabajo concreto: los sitios de reportes, propuestas y calculadoras que Vercel arma para sus clientes. Son unas 380 líneas, cerca de 40 KB.

- Un orden de prioridades para cuando los requisitos chocan: primero los datos y las restricciones, después el proyecto del cliente, recién después el estilo.
- Cuatro pasadas de trabajo: entender la tarea del lector, elegir la composición, aplicar el sistema visual y revisar en privado.
- Una lista de reflejos de diseño generado que prohíbe, como gradientes decorativos, tarjetas dentro de tarjetas o un hero centrado seguido de una grilla de tarjetas.
- Una API de CSS publicada, con clases como
vbg-statovbg-chart, y la orden de no inventar sinónimos.
Es el ejemplo más claro de que un DESIGN.md puede transmitir criterio, no solo valores.

Caso Supabase: lo que circula sin ser oficial
Supabase no publica un DESIGN.md: supabase.com/design.md responde 404 (lo comprobamos el 21 de noviembre de 2026). Aun así, aparece en todas las colecciones. awesome-design-md, de VoltAgent, con más de 128 mil estrellas en GitHub, incluye uno, y DesignMD Directory publica otro extraído del sitio a partir de 2,860 elementos.

Sirven para estudiar una marca en minutos, pero tienen límites claros. Infieren el rol de cada color por cuántas veces aparece en el CSS, no por la intención del equipo. Quedan viejos en cuanto el sitio cambia. Y no dan permiso para usar la identidad de otra marca en un producto propio.
Cómo escribir el tuyo
- Empieza por la tarea: qué tiene que entender o hacer quien usa la interfaz, antes que los colores.
- Nombra los tokens por su rol (fondo, texto secundario, acción principal), no por su valor.
- Escribe reglas con números: pisos de tamaño, rangos de espaciado, cuándo sí y cuándo no.
- Acompaña cada regla con un ejemplo de “bien” y uno de “evitar”.
- Cubre los estados (cargando, vacío, error, deshabilitado), la accesibilidad y los temas claro y oscuro.
- Deja la verdad en un solo lugar: el YAML del archivo, un theme.json o tu CSS, pero no tres copias.
- Valídalo con
linten CI y revisa el resultado en la pantalla, no solo en el build.
Conectarlo con Claude Code
Claude Code lee CLAUDE.md al inicio de cada sesión, y ese archivo puede importar otros con @ruta. Con una línea, tu DESIGN.md entra en todas las sesiones:
# CLAUDE.md
Sigue el sistema de diseño de @DESIGN.md en todo cambio de interfaz.
Si todavía no lo usas, la guía de Claude Code para diseño cubre la instalación y la primera sesión.
Preguntas frecuentes
¿Qué es DESIGN.md?
Es un archivo markdown que describe la identidad visual de un producto para que un agente de código la respete. Combina tokens con valores exactos y prosa que explica cuándo y por qué usarlos.
¿DESIGN.md es un estándar?
Es un borrador abierto. Google Labs publicó la especificación en abril de 2026 con licencia Apache 2.0 y la marca como alpha. Muchas empresas publican su propio DESIGN.md sin seguir el formato al pie de la letra.
¿Dónde va el archivo?
En la raíz del repositorio, para que el agente lo lea junto al código. Algunas marcas también lo sirven en su dominio, como crafter.run/design.md o vercel.com/design.md, para que cualquier agente lo descargue.
¿Sirve con Claude Code, Cursor o Codex?
Sí. Es texto plano: cualquier agente que lea archivos del proyecto puede usarlo. En Claude Code se importa desde CLAUDE.md con @DESIGN.md para que cargue en cada sesión.
¿Puedo usar el DESIGN.md de otra marca?
Para estudiar cómo está hecho, sí. Para lanzar un producto con la identidad de otra marca, no: los colores se pueden inspirar, pero logos, fuentes con licencia y la marca en sí no son tuyos.
Sigue leyendo
O vuelve a la guía de design engineering y al rol de agentic design systems engineer.
Un DESIGN.md dice cómo se ve; falta pedir lo que admiras
Taste hacking es un curso en vivo, en español, para construir con un agente las interfaces, animaciones y videos que admiras.
Anótate a la edición 02