≡En resumen
- DESIGN.md le dice a un agente de IA cómo debe verse tu producto, igual que CLAUDE.md le dice cómo trabajar.
- Combina valores exactos (tokens en YAML) con explicaciones de cuándo y cómo usarlos.
- Evita el aspecto genérico de las interfaces generadas por IA y mantiene la coherencia entre pantallas.
- Claude Code no lo lee solo: lo importas desde tu CLAUDE.md o se lo pides expresamente.
- Es una especificación en alfa de Google Labs; revisa el repositorio oficial antes de depender de detalles concretos.
01 ¿Qué es un archivo DESIGN.md?
Cuando pides a una IA que te haga una página, decide por su cuenta colores, tipografías, sombras y radios de borde. El resultado suele funcionar, pero se parece a todo lo demás y cambia de una pantalla a otra. DESIGN.md resuelve eso: es un archivo en la raíz del proyecto que describe tu sistema de diseño en un formato que un agente puede leer y aplicar.
El formato nació en Stitch, la herramienta de diseño con IA de Google Labs, y Google publicó su especificación como borrador abierto en abril de 2026, con licencia Apache 2.0. Desde entonces lo usan también desarrolladores que trabajan con Claude Code, Cursor u otros agentes.
02 Estructura de un DESIGN.md: tokens y secciones
Un DESIGN.md tiene dos capas. Arriba, entre líneas ---, un bloque YAML con los tokens de diseño: los valores exactos y normativos. Debajo, un cuerpo en Markdown con secciones que explican cómo y cuándo aplicarlos. La especificación propone estas secciones, todas opcionales pero en este orden:
| Sección | Qué describe |
|---|---|
| Overview (Brand & Style) | Personalidad de la marca, tono visual y público |
| Colors | Paleta, roles de cada color y contraste |
| Typography | Familias, tamaños, pesos y jerarquía de textos |
| Layout (Layout & Spacing) | Rejilla, márgenes, escala de espaciado y puntos de corte |
| Elevation & Depth | Sombras, capas y profundidad |
| Shapes | Radios de borde y formas recurrentes |
| Components | Botones, tarjetas, formularios y sus estados |
| Do's and Don'ts | Lo que siempre se hace y lo que nunca se hace |
---colors: primary: "#1F4FD8" surface: "#FFFFFF"typography: heading: { fontFamily: Inter, fontWeight: 700 }rounded: card: 8px---## Do's and Don'ts- Un solo botón primario por pantalla.- Nunca texto gris claro sobre fondo blanco.
Los nombres exactos de las claves YAML los define la especificación oficial; compruébalos en el repositorio antes de escribir el tuyo.
03 Por qué DESIGN.md mejora lo que diseña la IA
Coherencia
Todas las pantallas comparten colores, espacios y componentes, aunque las genere el agente en sesiones distintas.
Menos aspecto genérico
Sin instrucciones, los modelos tienden a los mismos degradados y tarjetas; con tokens claros siguen tu marca.
Portátil entre herramientas
Es texto plano: sirve igual para Claude Code, Cursor, Stitch u otro agente, y para las personas del equipo.
Versionable
Vive en Git con el código, así cada cambio de diseño queda revisado y registrado.
Comprobable
La CLI oficial detecta referencias rotas y problemas de contraste WCAG antes de que lleguen a la web.
04 Cómo usar DESIGN.md con Claude Code
-
1
Escribe o extrae tu sistema
Si ya tienes web o guía de marca, pide a Claude que la analice y redacte un primer DESIGN.md con tus colores, fuentes y componentes reales.
-
2
Colócalo en la raíz
Guarda el archivo como DESIGN.md junto a tu CLAUDE.md, en el repositorio del proyecto.
-
3
Impórtalo desde CLAUDE.md
Claude Code admite importar archivos con la sintaxis @ruta. Añade una línea con @DESIGN.md para que se cargue en cada sesión.
-
4
Valídalo
Con npx @google/design.md lint DESIGN.md compruebas la estructura, los tokens y el contraste.
-
5
Genera y compara
Pide una pantalla nueva y revisa si respeta las reglas; si no, ajusta el texto del DESIGN.md en lugar de corregir pantalla a pantalla.
-
6
Exporta los tokens
La CLI puede convertir los tokens a Tailwind o al formato DTCG del W3C para usarlos directamente en tu CSS.
05 Ejemplo práctico: de la guía de marca a una landing coherente
La clínica tiene un manual de marca en PDF y una web antigua. Primero se pide al agente que lea ambos y proponga un DESIGN.md: dos azules corporativos, una tipografía para titulares y otra para texto, botones redondeados y fotografías reales en lugar de ilustraciones. El equipo corrige el borrador (el verde que aparecía en la web antigua ya no forma parte de la marca) y lo valida con la CLI.
A partir de ahí, cada página nueva —servicios, equipo, contacto— se genera ya con esos valores. Cuando la clínica decide aumentar el tamaño del texto para pacientes mayores, cambia una línea del DESIGN.md y pide al agente que actualice las páginas, en lugar de revisarlas una a una.
06 DESIGN.md frente a otros archivos de instrucciones
| Archivo | Para qué sirve | Quién lo lee |
|---|---|---|
| CLAUDE.md | Instrucciones del proyecto: comandos, normas, arquitectura | Claude Code, automáticamente |
| AGENTS.md | Instrucciones del proyecto en un formato común a varios agentes | Varios agentes de código; Claude Code también puede leerlo |
| SKILL.md | Una habilidad reutilizable con instrucciones y recursos | Claude cuando la tarea encaja con la skill |
| DESIGN.md | La identidad visual y las reglas de interfaz | Stitch y cualquier agente al que se le indique |
| Tokens DTCG (JSON) | Valores de diseño para herramientas y código | Figma, librerías y pipelines de diseño |
07 Buenas prácticas y errores frecuentes
- ✓Usa valores exactos (hexadecimales, píxeles, nombres de fuente), no adjetivos como «moderno» o «limpio».
- ✓Explica el porqué de cada decisión: el agente aplica mejor una regla cuando entiende su intención.
- ✓Incluye los estados de los componentes: hover, foco, deshabilitado y error.
- ✓Mantén el archivo corto; lo que no cabe en una lectura rápida se aplica peor.
- ✓Actualízalo cuando cambie la marca, no solo el CSS.
- ✓Revisa la accesibilidad: contraste suficiente y tamaños de texto legibles.
Un buen DESIGN.md parte de un diseño UX/UI pensado para tus usuarios y de un manual de identidad corporativa claro; el archivo solo lo traduce a un lenguaje que entienden los agentes. Si quieres ver más archivos y utilidades de este tipo, revisa nuestra selección de recursos de IA para Claude.
Preguntas frecuentes sobre DESIGN.md
Es un archivo Markdown que describe el sistema de diseño de un producto (colores, tipografía, espaciado, formas y componentes) para que los agentes de IA lo apliquen al generar interfaces. Su especificación la publicó Google Labs.
No. Claude Code carga automáticamente CLAUDE.md, así que lo habitual es importar DESIGN.md desde CLAUDE.md con la línea @DESIGN.md o pedirle expresamente que lo siga.
Es una especificación abierta de Google Labs con licencia Apache 2.0, todavía en versión alfa. No es un estándar de un organismo como el W3C, aunque puede exportar sus tokens al formato DTCG.
CLAUDE.md da instrucciones de trabajo sobre el proyecto; DESIGN.md describe cómo debe verse. Se complementan y suelen convivir en la raíz del repositorio.
Parte de tu guía de marca o de tu web actual, pide a un agente un primer borrador con valores exactos, revísalo con tu equipo de diseño y valídalo con la CLI oficial.
Sí. Herramientas de diseño con IA como Stitch lo usan para generar pantallas coherentes, y también es una forma clara de documentar tu marca para personas.
La especificación propone Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components y Do's and Don'ts, todas opcionales, además de un bloque YAML inicial con los tokens de diseño.
Sí. La CLI oficial puede exportar los tokens del archivo a una configuración de Tailwind o al formato DTCG, de modo que el diseño descrito y el código compartan los mismos valores.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗