¿Qué es design.md para agentes de codificación?

Soy Dora. La semana pasada le pedí a Claude Code que añadiera tres nuevas pantallas a un proyecto paralelo. Para la segunda pantalla, el radio de los botones había cambiado, la fuente del titular había cambiado silenciosamente y el gris “secundario” era un gris diferente. Misma estructura de prompt. Mismo modelo. Misma sesión. El output simplemente dejó de importarle lo que había venido antes.

Esta es la fricción que design.md para agentes de codificación intenta eliminar. Es un archivo markdown simple que contiene tu sistema de diseño en una forma que un agente de IA puede leer cada vez que genera UI — no como un prompt de una sola vez, sino como contexto persistente. Stitch lo lee. Claude Code lo lee. Cursor lo lee. Cualquier otra cosa que recoja archivos de contexto desde la raíz de un repositorio también lo lee.

Qué es design.md y por qué Google Labs lo publicó

Formato de archivo y rol en el sistema de diseño

Un archivo DESIGN.md tiene dos capas apiladas en un solo documento. La parte superior es un encabezado YAML — colores, tipografía, espaciado, esquinas redondeadas, componentes — escrito como tokens estructurados. Debajo hay prosa en markdown que explica para qué sirven los tokens y cómo usarlos. Los tokens dan al agente valores exactos. La prosa le dice por qué existen esos valores.

Así es aproximadamente cómo luce el encabezado, extraído de la especificación oficial de DESIGN.md en GitHub:

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

Debajo de eso, ## Overview, ## Colors, ## Typography en markdown simple. El orden de las secciones es fijo — Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts. Las secciones pueden omitirse, pero las que estén presentes deben aparecer en ese orden. Los encabezados de sección duplicados son un error y rechazan el archivo.

La sintaxis de referencia de tokens proviene del Módulo de Formato de Tokens de Diseño del W3C — rutas con llaves como {colors.primary}. Las referencias deben apuntar a valores primitivos (no grupos), excepto dentro de la sección de componentes donde se permiten referencias compuestas a tokens de tipografía. Los valores de color son solo hexadecimal SRGB en la especificación actual. Display P3 y Oklch — ambos compatibles con la especificación estable W3C DTCG 2025.10 — aún no son compatibles con DESIGN.md, lo que el repositorio señala abiertamente con su marcador version: alpha. Vale la pena saberlo si mantienes tokens de gama amplia.

El formato incluye una CLI — @google/design.md en npm. npx @google/design.md lint ejecuta siete reglas contra un archivo analizado. Las dos que encuentro con más frecuencia: broken-ref (severidad de error) detecta referencias de tokens que no se resuelven, y contrast-ratio (advertencia) verifica pares backgroundColor/textColor de componentes contra el mínimo 4.5:1 de WCAG AA. Tres más — missing-primary, orphaned-tokens y las reglas estructurales — detectan problemas que la mayoría de los equipos introducen dentro de una semana de editar el archivo. La CLI también tiene diff (regresiones a nivel de token entre versiones) y export (configuración de Tailwind v3, CSS @theme de Tailwind v4, o JSON W3C DTCG).

Por qué el contexto visual persistente importa para los agentes de codificación

El problema es simple. Un agente que genera UI no tiene memoria de tu sistema de diseño a menos que le des algo estructurado para leer. Puedes describir tu paleta en un prompt, obtener un botón de vuelta, luego pedir una tarjeta y ver cómo la lógica de espaciado se reinicia. El modelo no es malo escribiendo código. No tiene un ancla.

design.md es el ancla. Stitch lo pasa como contexto en cada solicitud de generación. Claude Code y Cursor lo recogen de la misma manera que recogen CLAUDE.md o AGENTS.md — un archivo en la raíz del repositorio que el agente lee antes de responder. El enfoque de Google en el anuncio de código abierto es que esto permite que los agentes “sepan exactamente para qué es un color” en lugar de adivinar la intención a partir de un prompt.

Probé esto en ambos proyectos. Procedimiento: colocar un DESIGN.md en la raíz, regenerar las mismas cinco pantallas que habían derivado antes (landing, precios, registro, dashboard, configuración), luego contar las violaciones de tokens contra el encabezado. Con el archivo presente, Claude Code produjo 5/5 pantallas usando los valores hexadecimales exactos de primary y tertiary y el rounded.sm declarado. Cursor produjo 4/5 — el dashboard seguía sobreescribiendo rounded.sm (4px) con rounded.md (8px) en las tarjetas, lo que la prosa de DESIGN.md no había prohibido explícitamente. Añadir una línea de “Do’s and Don’ts” — “las esquinas de las tarjetas usan rounded.sm, nunca rounded.md” — lo corrigió en la siguiente regeneración.

El problema real que resuelve en la generación de UI con IA

Consistencia entre pantallas e iteraciones

Lo que se rompió en la sesión anterior no fue la calidad de una pantalla. Cada pantalla individual se veía bien. La pantalla dos no sabía qué había decidido la pantalla uno. Cada generación comenzaba desde una interpretación ligeramente diferente de “tu marca.”

Este es el modo de fallo que design.md apunta. No “hacer la UI más bonita” — hacer que sea la misma UI entre generaciones. Los tokens son normativos. Cuando el encabezado dice tertiary: “#B8422E”, el agente no tiene margen para interpretarlo como “un naranja cálido.” Es ese valor hexadecimal o está mal, y lint lo dirá.

Para flujos de trabajo de alta frecuencia — cinco, diez, veinte pantallas a la semana con alguien manteniéndolas — esto importa más que la calidad del primer output. Una inconsistencia por pantalla a escala se convierte en un trabajo de limpieza. Los tokens de diseño de agentes de codificación, definidos una vez en un archivo, eliminan ese trabajo de limpieza antes de que comience.

Por qué prosa más tokens es más fuerte que tokens solos

Casi descarté esta parte. ¿Por qué escribir párrafos de “Boston Clay es el único conductor para la interacción” cuando el valor hexadecimal ya está en el YAML?

Porque el agente usa la prosa para tomar decisiones que los tokens no cubren. Los tokens dicen que tertiary es #B8422E. La prosa dice que ese color es solo para interacción — no para acentos decorativos, no para titulares. Cuando un prompt es ambiguo (“añade una insignia de notificación”), la prosa decide si la insignia obtiene el color de interacción o un neutro. En mi ejecución de Cursor anterior, la restricción de prosa faltante era exactamente por qué el dashboard derivó.

La misma lógica se aplica a Do’s and Don’ts — restricciones explícitas como “nunca uses sombras en las tarjetas” o “siempre usa mayúscula de oración para las etiquetas de botones.” Las restricciones negativas tienen un peso que los tokens puros no pueden expresar. Esto es una especificación de diseño para agentes, no un archivo CSS.

El formato no está ligado a Stitch. La especificación es Apache 2.0, la CLI está en npm, la exportación DTCG significa que los tokens fluyen hacia cualquier herramienta que lea el estándar W3C, y la comunidad ya se está moviendo. La colección awesome-design-md de VoltAgent de archivos DESIGN.md inspirados en marcas superó las 71,000 estrellas de GitHub en semanas después del lanzamiento, y el tema design-md de GitHub ahora lista herramientas de extracción, extensiones de Chrome y registros de SKILL.md complementarios totalmente ajenos a Google. La adopción es lo que te dice que un formato es real.

A quién le debería importar design.md

Siendo honesta sobre el límite, porque design.md no es un ajuste universal.

Vale la pena si:

Estás generando UI con agentes de codificación al menos semanalmente, en más de una pantalla
Tienes un sistema de diseño — incluso uno delgado — que quieres preservar entre generaciones
Trabajas con más de un agente o herramienta y quieres el mismo contexto de marca en todos ellos
Estás cansado de pegar “recuerda que nuestra paleta es X, Y, Z” en cada prompt

No vale la pena si:

Generas maquetas únicas y las descartas
Tu “sistema de diseño” es lo que sea que el agente produzca esta vez
Estás dentro de un flujo de trabajo liderado por Figma con un pipeline DTCG maduro a través de Style Dictionary o similar — design.md es más ligero que lo que tienes, y sería una degradación
Necesitas color de gama amplia (Display P3, Oklch) hoy — la especificación alpha actual es solo SRGB

Para equipos de productos nativos de IA que ejecutan design.md junto con otros archivos de flujo de trabajo de IA (CLAUDE.md, AGENTS.md), encaja limpiamente. Un archivo markdown por preocupación. Sin paso de build. Sin esquema JSON con el que pelear. El costo de probarlo es un archivo en la raíz del repositorio y un comando lint.

Para plataformas que construyen superficies de generación impulsadas por agentes — incluidas capas de generación de IA unificadas que enrutan solicitudes a través de múltiples modelos y necesitan que el contexto de marca se mantenga en cada llamada — design.md es lo más cercano que tiene el ecosistema a un contrato portable entre una marca y un agente. Según el anuncio de Google Labs, el formato fue construido específicamente para ser exportable e importable entre herramientas. Esa portabilidad es el punto.

Preguntas frecuentes

¿Para qué se usa design.md?

Es un archivo markdown que da a los agentes de codificación contexto persistente sobre un sistema de diseño — colores, tipografía, espaciado, componentes, más prosa que explica cómo aplicarlos. El agente lo lee cada vez que genera UI, por lo que el output se mantiene consistente entre pantallas y sesiones sin que tengas que volver a especificar las reglas de marca en cada prompt.

¿Es solo para flujos de trabajo de Google Stitch?

No. El formato se originó en Stitch pero Google abrió la especificación bajo Apache 2.0. Cualquier herramienta de IA que lea archivos de contexto — Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI — puede usarlo. La CLI exporta a configuración de Tailwind, variables CSS o JSON W3C DTCG, por lo que los tokens fluyen también hacia herramientas no agentes.

¿Por qué la UI generada por IA necesita un archivo de sistema de diseño?

Porque los modelos no tienen memoria de tu marca entre generaciones. Sin un archivo de sistema de diseño para IA estructurado, cada prompt reinterpreta tu lenguaje de diseño desde cero. Con uno, los tokens actúan como restricciones estrictas y la prosa cubre las decisiones de juicio. La diferencia se muestra con mayor claridad a escala — cinco pantallas generadas con design.md mantienen su estilo; cinco pantallas generadas sin él derivan.

¿Qué equipos deberían experimentar con él primero?

Equipos que ya generan UI con agentes de codificación semanalmente. Los desarrolladores independientes y los pequeños equipos de productos que ejecutan Claude Code o Cursor obtienen el retorno más rápido — coloca el archivo, regenera, observa la consistencia. Las organizaciones más grandes con pipelines maduros de Figma + Style Dictionary deberían tratar design.md como un complemento, no como un reemplazo: úsalo para dar a los agentes un subconjunto digerible del sistema existente.

Conclusión

design.md no es un formato de archivo revolucionario. Es un archivo markdown con YAML en la parte superior. Ese es el punto — el formato que los LLMs leen mejor es el que más han sido entrenados, y ese es el texto simple.

Lo que realmente hace es cambiar la pregunta de “¿cómo describo mi diseño en este prompt?” a “¿dónde vive mi diseño para que cada agente pueda leerlo?” Un archivo, una ubicación, cada herramienta que lo recoge obtiene la misma respuesta. Una cosa menos que volver a especificar. Suena pequeño. Se acumula rápido.

Lo he tenido en dos proyectos durante una semana. Funciona. A largo plazo — si los equipos mantienen estos archivos con el mismo rigor que un sistema de diseño real, o si se deterioran como se deterioran los READMEs — eso aún está por verificar. Ejecútalo en un proyecto propio. Eso te dirá más que cualquier cosa que yo diga.

Posts anteriores：