Llevo semanas leyendo posts en X y Reddit sobre DESIGN.md. Algunos dicen que es «el cambio más importante en AI design desde que Figma existió». Otros aseguran que ahora todos los design systems deberían estar en un archivo .md.
A ver…
Soy adicto al Markdown desde hace años, escribo en MD desde 2016, cuando compré mi licencia de Ulysses para macOS. Me siento muy cómodo con los archivos Markdown de Astro, Claude Code, Cursor, etc.
Así que cuando descubrí al DESIGN.md, pensé: «Esto tiene que ser para mí.»
Ahora bien…
- Qué es realmente un DESIGN.md?
- Es hype o algo que necesito ahora?
La respuesta corta:
Es un archivo de texto que describe tu sistema de diseño en un formato que Claude Code, Cursor, y casi cualquier agente de IA puede leer y aplicar automáticamente cuando genera UI.
Si quieres la respuesta larga, sigue leyendo.
El problema que DESIGN.md resuelve
El workflow actual con agentes de IA es tedioso y repetitivo.
Generas un componente > Te das cuenta que el color no es el tuyo > Iteras > El próximo componente usa un spacing diferente > Iteras otra vez > El tercero tiene corners de 8px cuando debería ser 2px…
Es decir:
- Pides UI
- La IA no tiene contexto de tu sistema
- Haces 2 o 3 iteraciones
- Repites esto con cada feature
Por qué?
Los agentes de IA leen tu prompt palabra por palabra. Si no especificas «usa #E94F37 como primary», usa lo que asume por defecto… Tailwind default colors, Material Design, etc.
Tienes que re-especificar tu design system en cada prompt…
Entonces:
DESIGN.md elimina la fricción.
Es un archivo que dice: «Aquí está mi sistema exacto, usa esto.»
La IA lo lee una sola vez y aplica los tokens en todo, sin re-especificaciones.
Qué es DESIGN.md
Es un archivo de texto Markdown que describe tu sistema de diseño en un formato que los agentes de IA pueden leer.
Qué tiene dentro el DESIGN.md
Básicamente contenido organizado en 2 bloques:
1) Metadata YAML
name: nombre del design systemversion: versión actualdescription: descripción breve
2) Markdown (información organizada en secciones)
- Overview: resumen del producto
- Colors, Typography, Spacing, Components (definiciones y cómo usarlos)
- Do’s and Don’ts (reglas explícitas, lo que puede hacer y lo que no puede hacer)
El archivo DESIGN.md fue creado por Google Labs y se presentó en marzo de 2026.
Se puede usar en Claude Code, Cursor, Copilot, Windsurf, v0, Lovable, etc.
Qué no es un archivo DESIGN.md
- No es un reemplazo de Figma, más bien «complementa» el design system que tenemos en Figma
- No es JSON schema, es un texto Markdown que entiende tu abuela
- No es una solución de «set and forget», quiero decir… un DESIGN.md requiere cariño (mantenimiento)
Tu Figma tiene todo, el DESIGN.md tiene lo que importa. La IA lo lee y genera UI que es tuya, no genérica.
Pinta bien?
Sigamos…
Por qué DESIGN.md amplifica el diseño pero no lo reemplaza?
Importante: DESIGN.md no reemplaza al UX Designer, más bien amplifica lo que ya hace un UX Designer.
La IA es buena en:
- Generar layouts rápido
- Aplicar tokens mecánicamente
- Sugerir variaciones de componentes
- Implementar decisiones que ya tomaste
Los UX o Product designers somos buenos en:
- Entender por qué una jerarquía funciona
- Decidir cuándo romper las reglas (me encanta esto)
- Priorizar qué feature tiene peso visual
- Entender contexto del usuario
Un DESIGN.md documenta lo que un buen UX Designer ya sabe (las rules), y la IA aplica esas rules.
Es una división de tareas, no un reemplazo.
El flujo de uso habitual sería:
- Tú tomas decisiones de diseño
- Las documentas en el DESIGN.md
- La IA las aplica a tus componentes
- Tú revisas e iteras si es necesario
- Listo, trabajas 3 veces más rápido que antes
Recuerda: sin el DESIGN.md, la IA adivina esas decisiones, y con un DESIGN.md, la IA sigue tus reglas.
Cómo funciona un DESIGN.md
Vamos a imaginar 3 situaciones en la práctica.
Escenario 1: sin usar DESIGN.md
Usando Cursor pones en la caja de prompt:
«construye un form de login limpio y profesional»
La IA hace lo siguiente:
- Usa un color azul genérico -por ejemplo- obtenido de Material Design
- Pone corners redondeados por defecto
- Usa fuente Inter o Roboto
- Aplica 4 tamaños de spacing distintos
Lo que obtienes es una UI genérica que no se parece en nada a tu producto.
Escenario 2: usando DESIGN.md
Arrastras o metes el DESIGN.md en el directorio raíz de tu proyecto.
La IA lee el archivo automáticamente.
En el prompt le pones:
«construye un form de login»
Lo que hace la IA:
- Lee los colores exactos (#E94F37, #FFFFFF, etc.)
- Entiende que la fuente que debe usar es Geist
- Ve que los border-radius de tu text-input son de 8px
- Genera un FORM que se parece a tu producto
Obtienes una UI consistente (pixel-perfect).
Estructura real de un DESIGN.md
Vamos a revisar la estructura real de un archivo DESIGN.md
---
name: Portfolio UX de Elena
version: 1.0.0
description: Sistema de diseño para el Portfolio UX de Elena
colors:
primary: "#E94F37"
primary-light: "#F5A89D"
primary-dark: "#A32321"
secondary: "#4A90E2"
secondary-light: "#7BA8E8"
secondary-dark: "#2E5AA8"
neutral-50: "#FFFFFF"
neutral-100: "#F9FAFB"
neutral-200: "#F3F4F6"
neutral-300: "#E5E7EB"
neutral-400: "#D1D5DB"
neutral-500: "#9CA3AF"
neutral-600: "#6B7280"
neutral-700: "#374151"
neutral-800: "#1F2937"
neutral-900: "#111827"
status-success: "#10B981"
status-warning: "#F59E0B"
status-error: "#EF4444"
status-info: "#3B82F6"
typography:
font-family-display: "'Geist', -apple-system, BlinkMacSystemFont"
font-family-body: "'Geist', -apple-system, BlinkMacSystemFont"
font-family-mono: "'Geist Mono', monospace"
display-lg:
size: 48px
weight: 600
line-height: 1.2
letter-spacing: -0.02em
display-md:
size: 40px
weight: 600
line-height: 1.2
letter-spacing: -0.02em
heading-lg:
size: 32px
weight: 600
line-height: 1.3
letter-spacing: -0.01em
heading-md:
size: 24px
weight: 600
line-height: 1.3
letter-spacing: -0.005em
heading-sm:
size: 18px
weight: 600
line-height: 1.4
letter-spacing: 0em
body-lg:
size: 18px
weight: 400
line-height: 1.6
letter-spacing: 0em
body-md:
size: 16px
weight: 400
line-height: 1.6
letter-spacing: 0em
body-sm:
size: 14px
weight: 400
line-height: 1.5
letter-spacing: 0em
label:
size: 12px
weight: 500
line-height: 1.4
letter-spacing: 0.02em
spacing:
unit: 8px
xs: 4px
sm: 8px
md: 16px
lg: 24px
xl: 32px
2xl: 48px
3xl: 64px
rounded:
none: 0
sm: 2px
md: 4px
lg: 8px
full: 9999px
shadows:
sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)"
md: "0 4px 6px -1px rgba(0, 0, 0, 0.1)"
lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1)"
xl: "0 20px 25px -5px rgba(0, 0, 0, 0.1)"
components:
button-primary:
background: "{colors.primary}"
color: "{colors.neutral-50}"
padding: "12px 24px"
rounded: "{rounded.md}"
typography: "{typography.body-md}"
font-weight: 500
border: none
button-secondary:
background: "{colors.neutral-100}"
color: "{colors.primary}"
padding: "12px 24px"
rounded: "{rounded.md}"
typography: "{typography.body-md}"
border: "1px solid {colors.neutral-300}"
text-input:
background: "{colors.neutral-50}"
color: "{colors.neutral-900}"
padding: "12px 16px"
rounded: "{rounded.sm}"
border: "1px solid {colors.neutral-300}"
typography: "{typography.body-md}"
card:
background: "{colors.neutral-50}"
rounded: "{rounded.lg}"
padding: "{spacing.lg}"
shadow: "{shadows.md}"
border: "1px solid {colors.neutral-200}"
---
## Overview
Tu Producto es un [descripción corta]. El sistema de diseño se centra en [personalidad: minimalista, bold, clean, etc.]. Cada decisión de color, tipografía y spacing está pensada para [objetivo específico: velocidad, claridad, confianza, etc.].
## Brand Essence
2-3 párrafos describiendo el feeling general del producto:
- Qué respuesta emocional buscas
- Qué principios de diseño dominan
- Qué te diferencia visualmente
## Colors
### Primary Palette
- **Primary (#E94F37)** — Usado en CTAs, buttons, y elementos activos. Representa [significado]. Nunca lo uses en backgrounds grandes.
- **Primary-light (#F5A89D)** — Estados hover de primary. No usar para texto.
- **Secondary (#4A90E2)** — Información, links, secondary actions. Más accesible que primary.
### Neutral Palette
- **Neutral-50 a Neutral-100** — Backgrounds y superficies elevadas
- **Neutral-200 a Neutral-400** — Borders y dividers
- **Neutral-500 a Neutral-700** — Secondary text
- **Neutral-800 a Neutral-900** — Primary text y headings
### Semantic Colors
- **Success (#10B981)** — Confirmaciones, estados positivos
- **Warning (#F59E0B)** — Alertas, atención requerida
- **Error (#EF4444)** — Errores, estados críticos
- **Info (#3B82F6)** — Información contextual
### Accessibility
Todos los colores pasan WCAG AA (4.5:1 contrast ratio mínimo para texto).
## Typography
### Font Stack
**Display & Headings:** Geist
**Body text:** Geist
**Monospace:** Geist Mono
Por qué Geist: claridad, modernidad, excelente legibilidad en todos los tamaños.
### Type Scale
| Level | Size | Weight | Use Case |
|-------|------|--------|----------|
| Display LG | 48px | 600 | Títulos de página, hero sections |
| Display MD | 40px | 600 | Subtítulos grandes |
| Heading LG | 32px | 600 | Títulos de sección |
| Heading MD | 24px | 600 | Subtítulos |
| Heading SM | 18px | 600 | Card titles |
| Body LG | 18px | 400 | Intro text, descriptive |
| Body MD | 16px | 400 | Body text estándar |
| Body SM | 14px | 400 | Secondary text, metadata |
| Label | 12px | 500 | Labels, badges, micro-copy |
### Rules
- Nunca uses weights menores a 400 para body text (legibilidad)
- Los headings siempre tienen letter-spacing negativo (tightness)
- Máximo 2 niveles de tipografía en una sección
- Labels siempre en uppercase + letter-spacing
## Layout & Spacing
### Base Unit
Todo spacing está basado en **8px grid**. Valores: 4, 8, 16, 24, 32, 48, 64px.
### Common Patterns
- **Container padding:** 24px (mobile) a 32px (desktop)
- **Card gap:** 16px
- **Section margin:** 32px a 48px
- **Line height:** 1.6 para body, 1.3 para headings
### Negative Space
Usa generosamente. Mínimo 24px entre secciones. Breathing room > visual density.
## Components
### Button Primary
**Usage:** Main CTAs, confirmations, primary actions. Uno por pantalla máximo.
**States:**
- Default: background primary
- Hover: background primary-dark + cursor pointer
- Active: scale 0.98 (subtle press effect)
- Disabled: opacity 0.5 + cursor not-allowed
### Text-Input
**Usage:** Formularios, búsqueda.
**Rules:**
- Rounded: 2px (específico, no 12px)
- Border color: neutral-300. On focus: primary
- Padding: 12px left/right mínimo
- Font size: 16px (previene mobile zoom)
### Cards
**Usage:** Contenido agrupado, contenedor visual.
**Rules:**
- Rounded: 8px
- Padding: 24px
- Border: 1px solid neutral-200
- Shadow: md (depth without heaviness)
- Nunca shadow + border juntos (elige uno)
## Do's and Don'ts
### Do's
✓ Usa primary color para calls-to-action (máximo 1 por pantalla)
✓ Pairea headings bold con body text light (contrast)
✓ Mantén negative space generoso
✓ Checkea contrast ratios (WCAG AA minimum)
✓ Usa semantic colors para status (success/error/warning)
✓ Stick al color palette. No inventes colores.
### Don'ts
✗ No uses gradientes.
✗ No hagas corners redondeados en inputs (solo 2px)
✗ No apiles múltiples buttons (máximo primary + secondary + tertiary)
✗ No uses primary color en backgrounds grandes
✗ No uses múltiples type sizes en un párrafo
✗ No uses fonts que no estén en el stack
✗ No bajes debajo de 16px para body text
✗ No uses espacios menores a 8px (la unidad es 8px)Este es el formato completo que necesitas…
Como ves, 2 partes:
- YAML front matter (entre
---) con todos los tokens - Secciones Markdown con Overview, Colors, Typography, Components y Do’s and Don’ts
La IA lee esto automáticamente y aplica los tokens exactamente.
Cómo crear tu propio DESIGN.md (desde cero)
Ahora veamos cómo puedes escribir el tuyo:
Paso 1: define tu color palette
Empieza por tu color Primary (por ejemplo el que aparece en tu logo o marca).
colors:
primary: "#tu-código-HEX"
# Luego, variaciones
primary-light: "(tint al +20%)"
primary-dark: "(shade al -20%)"
# Después, los neutrals
neutral-50: "#FFFFFF"
neutral-900: "#000000"
(y todo lo que va entre medio)
# Finalmente, los semánticos
success: "#10B981"
error: "#EF4444"
(y todos los demás)Paso 2: elige tu tipografía
Todo dependerá de cómo sea tu sistema de diseño, por ejemplo:
- 1 font para display
- 1 font para body
Con Geist, Inter, o System stack:
typography:
font-family-display: "'Geist', system-ui"
font-family-body: "'Geist', system-ui"
display-lg: { size: 48px, weight: 600, line-height: 1.2 }
body-md: { size: 16px, weight: 400, line-height: 1.6 }Paso 3: Define spacing (8px grid)
Vamos con los espaciados:
spacing:
unit: 8px
xs: 4px # exceptions only
sm: 8px # standard
md: 16px # standard
lg: 24px # standard
xl: 32px # large sectionsPaso 4: Añade las reglas de componentes
Aquí empieza lo bueno (y muy importante).
components:
button-primary:
background: "{colors.primary}"
padding: "12px 24px"
rounded: "{rounded.md}"Paso 5: Escribe el Markdown
Todos lo que metas en el bloque Markdown también marcará la diferencia, dale cariño.
## Do's and Don'ts
- Usa primary color para ONE CTA por pantalla
- Mantén spacing consistente al 8px grid
- No uses gradientes
- No hagas una columna vertical de botones, no los apiles.Nota: cuántos más detalles pongas en el apartado de reglas, más consistencia obtendrás.
Implementación práctica para ti Product Maker o UX Designer
Tu flujo ideal
Crea o extrae un DESIGN.md
- Opción A: escríbelo en 30 minutos (basado en tu Figma)
- Opción B: descarga uno de awesome-design-md
- Opción C: genera uno con Design Extractor
Mételo en la raíz de tu proyecto
tu-proyecto/
├── DESIGN.md
├── CLAUDE.md (ya lo tienes)
├── src/
└── README.mdReferéncialo en tus prompts a Claude Code o Cursor
«construye [tu feature], usa DESIGN.md como referencia para colores, tipografía y spacing.»
La AI automáticamente:
- Lee el archivo
- Aplica tokens exactos
- Genera UI consistente
- Primera versión está lista
Itera localmente si es necesario
- Me atrevo a decir que el 90% de las veces, no tendrás que iterar.
Ahorra 20 hs por proyecto usando DESIGN.md
Sin DESIGN.md
- Generas un componente
- Te das cuenta que ese azul no es el tuyo…
- Iteras 2 o 3 veces
- Total, de 30 a 45 minutos
Con DESIGN.md
- Generas el componente
- Exactamente con tus colores y tokens
- Primera versión ok!
- Total, en 5 minutos
Imagina la cantidad de horas que ahorrarás si tienes que montar un proyecto con 30 componentes, organismos y templates…
Limitaciones del DESIGN.md
Ahora vamos con lo que no todo el mundo dice…
Lo que un DESIGN.md NO es
- No reemplaza un design system completo
- No genera layouts complejos (la IA necesitará tus indicaciones)
- No es suficiente para temas de accesibilidad (necesitas hacer QA y testing)
- No resuelve la creatividad (aún necesitas buenos prompts)
Cuando es menos útil
- Proyectos con design system muy personalizados
- Cuando necesitas iteración ultra-rápida en los colores (si necesitas cambiar colores cada 5 minutos, DESIGN.md te va a frenar)
- Si ya tienes un sistema complejo con Figma y otras herramientas, añadir un DESIGN.md es más trabajo
Recuerda:
El archivo DESIGN.md resuelve un problema real: cómo le digo a la IA exactamente cómo se ve mi producto.
Pon cariño y mucho detalle. Úsalo en todos tus proyectos.
Ya empezaste con a usar tu DESIGN.md? cuéntame tu experiencia.
Una cosa más…
En próximos posts te mostraré algunas herramientas y «técnicas» para crear tu DESIGN.md más rápido y con más control.
Seguimos!
Aprende sobre UX/UI + IA, Figma y Product Design
📣 Apúntate a mi newsletter semanal
