DESIGN.md: genera UI consistente con agentes de IA

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:

1. Pides UI
2. La IA no tiene contexto de tu sistema
3. Haces 2 o 3 iteraciones
4. 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 system
• version: versión actual
• description: 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:

1. Tú tomas decisiones de diseño
2. Las documentas en el DESIGN.md
3. La IA las aplica a tus componentes
4. Tú revisas e iteras si es necesario
5. 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.

Pero aquí viene algo importante que necesito que entiendas.

El DESIGN.md documenta tus reglas, no documenta el porqué detrás de cada una.

La IA puede leer que uses 12px de border-radius en inputs y lo aplicará en todas partes, perfecto. Tu UI se ve consistente, sigue el sistema exactamente.

Pero…

• La regla existe porque en tu contexto tiene sentido?
• Eiste porque así lo hacía Material Design?

La diferencia importa.

Lo que pasa en la práctica: la IA genera una interfaz que sigue tu DESIGN.md al 100%. Se ve consistente. Y aun así puede estar equivocada. No porque haya roto una regla, sino porque nadie hizo las preguntas previas correctas.

• Para quién es esto?
• Qué necesita alguien que llegue aquí?
• Qué tiene que pasar después?

Un archivo de texto no puede responder esas preguntas.

El DESIGN.md es una herramienta de ejecución. Documenta lo que sabes. Pero el trabajo que importa, el que no se puede automatizar, es saber por qué lo sabes.

Si no puedes responder «por qué esta regla existe en mi sistema», el DESIGN.md te ayuda poco. Te permite generar rápido, vale. Pero no te asegura que lo que generes sea correcto.

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 sections

Paso 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

Recursos: en el post Cómo crear tus archivos DESIGN.md te dejo más información sobre las opciones B y C.

Mételo en la raíz de tu proyecto

   tu-proyecto/
   ├── DESIGN.md
   ├── CLAUDE.md (ya lo tienes)
   ├── src/
   └── README.md

Referé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)

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!