Design Tokens, DESIGN.md y Design to Code

Los agentes de IA de codificación escriben código que funciona, pero la UI que producen se ve genérica. Cada app generada parece construida con los mismos componentes por defecto, porque lo está. El agente no tiene un ancla para tu marca. Pídele que "cree un botón secundario" y se inventa un color. Pídele que "ponga la app en dark mode" e inspecciona cada componente, adivinando qué colores reemplazar.

La otra mitad del problema es la fidelidad. Diseñas algo en una herramienta de diseño, lo entregas, y el código que vuelve no coincide. El espaciado está mal, los colores se acercan pero no son correctos, la escala de tipografía se ha perdido. El diseño tenía estructura, pero la entrega la perdió.

Estos son los problemas que un conjunto entero de herramientas y formatos está intentando resolver ahora mismo. El hilo común son los design tokens, y el formato que los lleva a los agentes de IA se llama DESIGN.md. Este post es lo que aprendí intentando entender cómo encajan las piezas.

Los tokens llevan significado, no solo valores

Un design token es un valor con nombre. En vez de guardar #2563EB en un botón, guardas color.primary. En vez de 8px en una esquina, guardas radius.md.

La diferencia es la intención. Cuando alguien, o algo, mira un valor en bruto, todo lo que ve es el valor. Un rectángulo azul con esquinas de 8px. Tiene que adivinar: ¿este es el botón primario? ¿Ese azul se usa en otro lado? ¿Es 8px una decisión deliberada o un número que alguien tecleó?

Con un token, la intención es legible. color.primary dice para qué es el color. radius.md dice que esto es parte de una escala, no un número arbitrario. Un desarrollador que lee esto no tiene que adivinar. Un agente de IA que lee esto no tiene que adivinar.

El mismo token, color.primary, se convierte en --color-primary en CSS, Color.primary en iOS, theme.colors.primary en Tailwind. Una decisión, expresada en el lenguaje de cada plataforma. Eso es lo que la gente significa cuando llama a los design tokens una fuente única de verdad.

Un design system es toda la estructura. Los tokens son las variables dentro de ella. La relación se ve así:

Design System
│
├── Foundations
│   │
│   ├── Tokens
│   │   ├── Colors
│   │   ├── Typography
│   │   └── Spacing
│   │
│   └── Themes
│       ├── Light
│       └── Dark
│
├── Components
│   ├── Button
│   ├── Card
│   └── Input
│
└── Documentation
    ├── Usage rules
    └── Examples

Vale la pena notar que Light y Dark no son el design system en sí. Son temas dentro de él. Los tokens son las variables que permiten que los temas se intercambien. Los componentes consumen los tokens. El design system es el todo.

Un token no es para dibujar

Aquí lo tenía al revés. Pensaba que los tokens trataban de hacer que la herramienta de diseño dibujara las cosas de la manera correcta. No es así. Los tokens tratan de describir las decisiones detrás de lo que se dibuja.

Un botón en una herramienta de diseño sigue siendo un rectángulo y texto. Con tokens, el rectángulo no guarda #2563EB. Guarda una referencia: fill → color.primary. La geometría es la misma. Lo que cambió es que el archivo de diseño ahora lleva la razón, no solo el resultado.

Un componente no se vincula a un valor en bruto. Se vincula a un token semántico, que apunta a un primitivo. Cambia el primitivo, y todo lo que sigue se actualiza. Ese es el punto de la jerarquía. Un cambio arriba se propaga a todas partes.

Eso importa cuando el diseño pasa a código. Sin tokens, el generador de código hace ingeniería inversa de los píxeles. Ve un rectángulo azul y escribe background: #2563EB. Con tokens, lee color.primary y escribe background: var(--color-primary). El código generado se ve como algo que un desarrollador escribiría, no un volcado de píxeles.

Los tokens no son suficientes

Un archivo JSON lleno de tokens te dice los valores. No te dice por qué existen esos valores, cuándo usarlos, o cuándo no. No puedes expresar "usa primary solo para el CTA principal" en un archivo tokens.json.

Esta es la brecha que DESIGN.md llena. Salió de Google Stitch, la herramienta de diseño de IA de Google, y fue open-sourced en abril de 2026 bajo Apache 2.0. El pitch es un archivo, en la raíz de tu proyecto, que le da a un agente de IA una comprensión persistente de tu design system.

Un archivo DESIGN.md tiene dos capas. Arriba hay YAML front matter: tus tokens, escritos como valores estructurados. Colores, tipografía, espaciado, esquinas redondeadas, componentes. Debajo hay prosa markdown que explica para qué son los tokens y cómo aplicarlos.

Los tokens le dan a un agente valores exactos. La prosa le dice por qué existen esos valores.

Un componente de botón en DESIGN.md se ve así:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px

La sintaxis de referencia {colors.tertiary} viene del W3C Design Tokens Format Module. Cambia colors.tertiary una vez, y el botón se actualiza donde sea que se referencie. El mismo estándar que herramientas de diseño como Penpot usan nativamente.

Ocho secciones

Un DESIGN.md tiene ocho secciones, en un orden fijo:

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

La sección de Do's and Don'ts es donde la prosa gana su valor. "Nunca uses drop shadows en cards." "Siempre usa sentence case para las etiquetas de botones." Estas son restricciones que los tokens puros no pueden expresar. Un archivo de tokens JSON dice cuáles son los valores. DESIGN.md dice qué hacer con ellos y qué evitar.

Por qué se popularizó

Se sienta en la raíz de tu repo junto a README.md y CLAUDE.md / AGENTS.md. Los agentes ya leen markdown desde la raíz del proyecto. README.md explica el proyecto a los humanos. CLAUDE.md y AGENTS.md le dicen a los agentes cómo comportarse. DESIGN.md les dice cómo debería verse la UI.

El repo awesome-design-md en GitHub, una colección de archivos DESIGN.md listos para usar extraídos de sitios de producción reales, superó las 58.000 estrellas en semanas tras su lanzamiento. Una tasa de fork del 12,6%, lo que significa que aproximadamente 1 de cada 8 personas que lo encontraron copió un archivo en su propio proyecto. Eso no es guardar en marcadores. Eso es adopción.

No tienes que escribir uno desde cero. Hay catálogos. getdesign.md tiene más de 300 análisis de DESIGN.md de sitios de producción reales. Open Design envía 151 paquetes de design system. designmd.app indexa 461. Eliges uno cercano a tu marca y lo adaptas.

La spec sigue en alpha. Los valores de color son sRGB solamente. Formatos de gamut amplio como Oklch y Display P3, ambos soportados por el estándar W3C, aún no están en DESIGN.md. El CLI puede exportar a Tailwind v3/v4 y al formato DTCG del W3C, así que los tokens fluyen hacia tu pipeline existente.

Dónde encajan las herramientas de diseño

DESIGN.md es la fuente de verdad. Las herramientas de diseño son donde aplicas los tokens para hacer pantallas. Penpot y Figma son dos ejemplos, y hay otros. Toman enfoques diferentes al mismo concepto.

Penpot es la primera herramienta de diseño en integrar nativamente el W3C Design Tokens Format Module. El mismo estándar del que se inspiran las referencias de tokens de DESIGN.md. En Penpot, los tokens viven en sets, que son colecciones de tokens relacionados. Tus fundamentos van en un set: colores base, valores de espaciado, radios. Tus tokens semánticos van en otro: primary, success, error. Combinas sets en temas para diferentes contextos. Light es un tema. Dark es un tema. Light y dark no son design systems diferentes, son temas diferentes aplicados a los mismos nombres de tokens.

Como Penpot habla el formato W3C nativamente, tus tokens se exportan en el formato estándar. Sin capa de traducción.

Figma toma un enfoque diferente. Figma Variables es la implementación nativa de Figma del concepto de tokens. Figma usa colecciones donde Penpot usa sets, y modos donde Penpot usa temas. Una colección de Figma contiene variables relacionadas, y los modos almacenan valores paralelos para diferentes contextos. El aliasing construye la jerarquía primitivo → semántico → componente: un token semántico como text-primary apunta a un primitivo como gray-900, y cambiar el primitivo actualiza todo lo que sigue.

La diferencia es que las variables de Figma usan un formato propietario. Sacar tokens de Figma en el formato estándar W3C requiere plugins como Tokens Studio. Penpot exporta W3C nativamente. Ambos implementan el mismo concepto. Uno habla el estándar, uno habla su propio dialecto.

El punto no es qué herramienta usas. El punto es que los tokens, como sea que la herramienta los almacene, deberían rastrearse a la misma fuente de verdad: tu design system, codificado en DESIGN.md.

Design to Code

Aquí es donde las piezas se conectan.

El handoff viejo era: diseñas en una herramienta, exportas un archivo, se lo entregas a un desarrollador, esperas que lea la spec bien. El desarrollador hace ingeniería inversa del diseño a partir de píxeles y adivina la intención.

El handoff nuevo es: codificas tu design system en DESIGN.md. Diseñas en una herramienta usando los tokens. Tu agente de IA lee el DESIGN.md y genera código de producción que usa los mismos nombres de tokens.

Design system → DESIGN.md → AI agent → production code

El agente obtiene los valores exactos de los tokens YAML. Obtiene las reglas de la prosa. No tiene que adivinar si un rectángulo azul es el botón primario, porque el DESIGN.md dice que button-primary usa colors.tertiary. El código generado usa var(--color-tertiary), no un valor hex hardcodeado.

En la práctica, el flujo va en ambas direcciones. Un proyecto nuevo empieza con los tokens. Defines tus tokens, escribes el DESIGN.md, y dejas que tu agente de IA lea el DESIGN.md desde el repo. El agente entonces sube los tokens a la herramienta de diseño a través de su CLI o MCP. Penpot importa el formato W3C nativamente. Figma necesita un plugin como Tokens Studio. La herramienta de diseño y el agente leen la misma fuente.

Un proyecto existente va en la otra dirección. Descompones el diseño actual en tokens, estandarizas el nombrado, y escribes un DESIGN.md a partir de ellos. Luego subes esos tokens a la herramienta de diseño. Si el proyecto no tiene diseño en absoluto, solo código, el agente de IA puede leer la codebase actual, extraer el frontend, y mover el diseño a la herramienta de diseño. Desde ahí, la herramienta de diseño y la codebase comparten la misma fuente.

La conexión entre la herramienta de diseño y el agente pasa por MCP, o por el CLI de la herramienta si tiene uno. pen.dev arranca un servidor MCP local al que ambos lados se conectan.

pencil.dev (ahora pen.dev)

pen.dev lleva esto más allá al colapsar la herramienta de diseño y el editor de código en un entorno. Es un canvas de diseño que vive dentro de tu IDE, no una aplicación separada. Los archivos de diseño (.pen) se sientan en tu repo junto a tu código. Git los rastrea. Haces branch y merge de diseños de la misma manera que haces branch y merge de código.

Cuando pen.dev está corriendo, arranca un servidor MCP local. Tu agente de IA, sea Claude Code, Cursor, Codex u OpenCode, se conecta por MCP y puede leer y modificar los archivos de diseño. Las variables en pen.dev se mapean a custom properties de CSS. Diseñas visualmente, el agente genera código, y ambos lados leen los mismos tokens.

La comunidad ha construido herramientas alrededor de esto. Hay un plugin de Claude Code llamado pencil-atelier que extrae el lenguaje visual de un archivo .pen y lo escribe en un design.md en la raíz del proyecto. A partir de ahí, cada pasada de generación de diseño y código lee el mismo contrato. Sin re-briefing manual entre sesiones.

Qué no está resuelto todavía

Atlassian probó DESIGN.md en producción y encontró que carga todo a la vez, no on demand. Comparado con un servidor MCP que obtiene contexto por componente, DESIGN.md usó aproximadamente 92% más tokens y tuvo 2,7x la varianza entre ejecuciones. Es una instantánea portátil, no un reemplazo para un pipeline completo de design system. La spec es alpha. Las herramientas todavía están verdes.

Lo que funciona es la forma. Codificas tus decisiones de diseño una vez, en un formato que tanto humanos como agentes pueden leer. Diseñas en una herramienta que usa los mismos tokens. Tu agente lee el mismo archivo y genera código con los mismos nombres. La parte que se reemplaza es la capa de traducción, la que solía ser una persona con un archivo de Figma y una conjetura.