Si has pedido a un agente de IA que cree una UI, probablemente te resulte familiar: ayer la pantalla tenía un botón azul con esquinas redondeadas; hoy, en una sesión nueva, aparece un degradado morado y botones angulares. El mismo proyecto acaba pareciendo una app de otra marca en cada pantalla, así que copias en cada prompt «el color de marca es #2563EB, el radio es 8px…».
DESIGN.md es una especificación de archivos pensada para este problema. Google Labs publicó como código abierto el 21 de abril de 2026 el formato que usaba en Stitch, su herramienta de diseño de UI con IA (Anuncio oficial de Google). En una frase, es «una especificación de formato para explicar la identidad visual a un agente de programación». Basta con guardar un archivo Markdown en el repositorio para que el agente lo lea cada vez que cree una UI.
Por qué un archivo y no un prompt
La debilidad de poner las reglas de marca en el prompt es su volatilidad. Desaparecen al terminar la sesión y cada miembro acaba usando una versión distinta. Un archivo confirmado en el repositorio es diferente.
- Permite control de versiones. Los cambios en las reglas de diseño quedan en el historial de Git y pasan a revisión en los PR.
- Vive junto al código. Como las reglas están donde el agente lee el código, entran en el contexto sin herramientas ni enlaces adicionales.
- Es independiente de la herramienta. Al ser texto plano, cualquier agente puede leerlo: Claude Code, Cursor, Copilot, etc.
La idea no es nueva. CLAUDE.md·AGENTS.md ya funcionan con el mismo principio para dar reglas de comportamiento a los agentes. DESIGN.md amplía esa convención al sistema de diseño. Si CLAUDE.md explica «cómo trabajar en este proyecto», DESIGN.md explica «cómo debe verse este producto». Por qué CLAUDE.md debe ser breveAnalizamos en detalle cómo diseñar el contexto cargado de forma permanente.
Hay una confusión frecuente. En un flujo de desarrollo guiado por especificaciones, el «documento de diseño técnico design.md» creado en el orden requirements.md → design.md → tasks.md solo comparte el nombre. El DESIGN.md de este artículo no es un documento de arquitectura, sino un archivo de sistema de diseño.
Estructura del archivo: tokens para máquinas + prosa para personas
Según Especificación oficial, DESIGN.md consta de dos partes: al principio, tokens de diseño legibles por máquinas en front matter YAML; después, la intención de diseño en prosa Markdown legible por personas.
---
name: My Product
version: alpha
colors:
primary: "#2563EB"
surface: "#FFFFFF"
onSurface: "#0F172A"
typography:
headline:
fontFamily: Pretendard
fontSize: 28px
fontWeight: 700
spacing:
sm: 8px
md: 16px
rounded:
card: 12px
components:
button:
backgroundColor: "{colors.primary}"
rounded: 8px
---
## Overview
Servicio financiero sobrio y confiable. Prioriza la claridad de la información sobre la decoración llamativa.
## Colors
primaryse usa con moderación solo en elementos de llamada a la acción. El 80%de la pantalla se mantiene en la familia surface .
...Aquí está la clave: los tokens son la norma y la prosa, el contexto. El valor colors.primary: "#2563EB" es la respuesta correcta que el agente debe seguir. La prosa «primary se usa con moderación solo en llamadas a la acción» ayuda a decidir cuándo y dónde usarlo. Si solo das códigos de color, el agente los aplicará en cualquier sitio; si solo describes el ambiente, elegirá colores arbitrarios. Por eso ambos viven en un mismo archivo.
Estas son algunas reglas de la especificación.
- En el front matter,
namees obligatorio y debe definirse al menos un colorprimary. - Los tokens se enlazan mediante referencias de ruta, como
{colors.primary}. Si el fondo del botón referencia primary, cambiar solo primary propaga el cambio. - El cuerpo define 8 secciones: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components y Do’s and Don’ts. Todas son opcionales, pero deben conservar este orden.
- Las áreas excluidas pueden indicarse con el campo
omittedjunto con el motivo. Así el agente distingue entre algo no escrito y algo omitido deliberadamente.
Por qué también incluye herramientas de validación
No solo se publicó la especificación del formato: también se publicó Herramienta CLI oficial (@google/design.md, licencia Apache-2.0). Hay cuatro comandos.
| Comando | Función |
|---|---|
lint |
Valida la estructura, las referencias de tokens y el contraste WCAG |
diff |
Compara dos versiones e informa de los cambios a nivel de token |
export |
Convierte tokens a configuración de Tailwind o formato W3C DTCG |
spec |
Muestra la especificación completa para inyectarla en prompts de agentes |
lint resulta especialmente interesante. Convierte internamente los colores a sRGB y comprueba el contraste WCAG (Web Content Accessibility Guidelines, pautas de accesibilidad para el contenido web). Aunque el agente genere una combinación que «parezca correcta», se descarta mecánicamente si no cumple la accesibilidad. Las reglas de diseño pasan a poder validarse en CI, sin depender de la diligencia del agente; Google también destaca este punto. En palabras de Anuncio oficial, el objetivo es que el agente «sepa exactamente para qué sirve cada color y pueda validar sus elecciones frente a las reglas de accesibilidad WCAG», en lugar de adivinar.
En la práctica también importa poder extraer la configuración de Tailwind con export. DESIGN.md puede ser la única fuente de verdad y la configuración CSS real derivarse de ella.
Cómo se usa en la práctica
Hay dos formas de empezar.
Generarlo en Stitch. Al crear el diseño en Stitch, puedes exportarlo como DESIGN.md. Diseñas varias pantallas, extraes su lenguaje visual al archivo y se lo entregas al agente de programación.
Escribirlo a mano. Es Markdown normal, así que puedes redactarlo directamente en el editor. Si el equipo ya tiene tokens de diseño organizados, mueve los tokens existentes al front matter y traslada a las secciones del cuerpo la parte del documento de guía que explica «por qué».
Una vez creado, coloca el archivo en la raíz del repositorio y haz que el agente lo consulte. Importante: a diferencia de CLAUDE.md, DESIGN.md no se carga automáticamente en la sesión. Como aún es una especificación nueva en alpha, conviene añadir en CLAUDE.md o AGENTS.md una línea como «antes de trabajar en la UI, lee DESIGN.md y sigue sus tokens». No hace falta ocupar el contexto con todo el sistema de diseño en sesiones sin UI; leerlo bajo demanda también reduce el coste de contexto.
Limitaciones y perspectivas
También hay que mirar algunos aspectos con realismo.
Sigue en alpha. El valor version de Especificación es literalmente «alpha» y la estructura de campos puede cambiar. Adoptarlo ahora exige estar dispuesto a seguir los cambios de la especificación.
El cumplimiento del agente sigue siendo probabilístico. Aunque los tokens estén descritos con precisión, no se puede garantizar que el agente los siga al pie de la letra: al final, es un LLM ejecutando instrucciones. Es el mismo motivo por el que a veces ignora las indicaciones de CLAUDE.md. Por eso se incluyen herramientas deterministas como lint. En producción, «instrucciones en archivo + validación en CI» debe tratarse como un conjunto.
La cobertura todavía es limitada. La especificación actual se centra en color, tipografía, espaciado, esquinas y componentes. Áreas como motion, conjuntos de iconos y breakpoints responsive pueden describirse en prosa, pero no tienen un esquema de tokens.
Aun así, la dirección es clara. El contexto para agentes pasa del prompt a un archivo versionado en el repositorio; tras CLAUDE.md y AGENTS.md, el patrón llega ahora al diseño. Como el archivo permanece aunque cambie la herramienta, es una inversión independiente del agente. Si has estado copiando reglas de marca en prompts para mantener la coherencia de la UI, empieza por moverlas a un único DESIGN.md.
Seguir leyendo
Fuentes y verificación
- Stitch's DESIGN.md format is now open-sourceGoogle (2026-04-21) · Anuncio oficial · Consultado 8 de agosto de 2026Respalda: Hecho de que DESIGN.md sea de código abierto, propósito de su publicación (que el agente conozca el uso de los colores y pueda validar WCAG) y compatibilidad con la generación en Stitch
- google-labs-code/design.mdGoogle Labs · Documentación oficial · Consultado 8 de agosto de 2026Respalda: Licencia Apache-2.0, estado alpha y comandos y funciones lint·diff·export·spec de la CLI @google/design.md
- DESIGN.md SpecificationGoogle Labs · Estándar o especificación · Consultado 8 de agosto de 2026Respalda: Campos del front matter (name obligatorio, color primary obligatorio), 8 secciones del cuerpo, sintaxis de referencias a tokens, campo omitted y método de comprobación del contraste WCAG