DESIGN.md: el contrato entre diseño y código

¿Qué es?

DESIGN.md es un archivo de texto donde documentas el design system de un producto —tokens, componentes canónicos y reglas de uso— en un formato que tanto un humano como un agente de IA pueden leer y accionar. Es el contrato entre el diseño y el código: lo que está escrito ahí es lo que se implementa.

Surge de un problema concreto del flujo AI-first: herramientas como Stitch o Claude Design generan un sistema visual, pero ese sistema vive en imágenes y conversaciones. Cuando le pides a un agente de código que implemente, necesita una fuente de verdad en texto. DESIGN.md es esa fuente.

El formato DESIGN.md nació en Google Stitch y se liberó como estándar abierto, pensado para portarse entre herramientas y plataformas: exportas tus reglas de diseño de un proyecto a otro y cualquier agente las puede leer.

Modelo mental

Piensa en DESIGN.md como el README del diseño: no es el diseño en sí, es el documento que cualquiera —humano o IA— lee para entender las reglas antes de tocar una línea.

Sin contrato, cada prompt de implementación reinventa decisiones: un tono de azul acá, otro allá. Con el contrato, el agente hereda el sistema y las decisiones ya están tomadas.

graph LR D[Diseño en Stitch / Claude Design] --> M[DESIGN.md] M --> C[Claude Code implementa] M --> H[Diseñador humano itera] M --> A[Otro agente extiende]

Qué vive en el contrato:

Sección	Contenido
Tokens	colores, tipografía, escala de espaciado, radios, sombras
Componentes	botón, card, input… con sus variantes y estados
Reglas de uso	do / don't, cuándo usar cada variante
Estructura	dónde va cada cosa en el repo

¿Cómo se usa?

Después de definir el sistema visual (en Stitch o Claude Design), lo destilas a texto.
Lo guardas como DESIGN.md en la raíz del repo, junto al código.
Se lo pasas al agente como contexto, o lo referencias desde el archivo de reglas del agente.

Ejemplo mínimo de un DESIGN.md:

# Design System — Mimo
 
## Tokens
- color.primary: #E8927C   (coral, acciones primarias)
- color.surface: #FBF7F0   (fondo)
- color.text:    #0A2540
- space:  4 / 8 / 16 / 24 / 32
- radius: sm 4px / md 8px / lg 12px
 
## Componentes
- Button: variantes primary | secondary | ghost. Estados: default, hover, disabled.
  Regla: solo un primary por vista.
- Card: padding md, radius lg, sombra sutil.
 
## Reglas
- No usar hex directo en componentes: siempre el token.
- Mobile-first. Breakpoints: 640 / 1024.

Tip Pro: El DESIGN.md no se escribe una vez y se abandona. Cuando el sistema cambia, se actualiza primero el contrato y después el código — nunca al revés. El contrato es la fuente de verdad, no el código.

¿Cuándo usarlo / cuándo no?

Úsalo cuando:

Vas a implementar un diseño con un agente de código (Claude Code, Cursor).
El proyecto tiene más de un puñado de pantallas y necesita coherencia.
Más de una persona —o más de un agente— va a tocar el diseño.

No hace falta cuando:

Es un prototipo desechable de una sola pantalla.
Estás explorando y el sistema todavía no se estabilizó: documentar demasiado pronto congela decisiones que aún deben moverse.