⏱️ Lectura: 16 min
Si alguna vez le pediste a Claude o Cursor que te haga una landing «como la de Vercel» y recibiste algo que parece Bootstrap 3 con esteroides, no estás solo. El problema no es el modelo; es el contexto. En 2026 apareció una convención que está cambiando la forma en que los agentes IA diseñan interfaces: DESIGN.md, un archivo markdown plano que describe el sistema de diseño de un producto y queda listo para que cualquier agente lo lea como parte de su contexto.
📑 En este artículo
- Por qué los agentes IA fallan al diseñar
- Qué es DESIGN.md, explicado desde cero
- Origen: Google Stitch 2.0 (marzo 2026)
- DESIGN.md vs AGENTS.md vs CLAUDE.md
- Anatomía de un DESIGN.md
- El repo awesome-design-md y por qué explotó
- Cómo usar DESIGN.md paso a paso
- 3 prompts listos para copiar y pegar
- Limitaciones y pitfalls reales
- Alternativas y contexto del ecosistema
- Cuándo usar DESIGN.md y cuándo no
- Contexto 2026: por qué esta convención está explotando
- Preguntas frecuentes
- Referencias
Esta guía cubre de punta a punta qué es design.md, de dónde viene (spoiler: Google Stitch 2.0), cómo se compara con AGENTS.md y CLAUDE.md, cómo se usa paso a paso, qué limitaciones tiene y cuándo conviene evitarlo. Incluye además tres prompts listos para copiar y pegar, y una advertencia honesta sobre el repo viral que puso esta idea en el mapa.
Por qué los agentes IA fallan al diseñar
El problema con los coding agents y el diseño visual es que tienen gusto propio — y ese gusto, casi siempre, es genérico. Cuando le decís a un LLM «hacé una landing moderna», lo que generalmente obtenés es una reinterpretación estadística de millones de sitios: tipografía sans-serif anodina, un degradé púrpura, botón redondeado, badge de «AI-powered». Es lo que en Twitter ya empezaron a llamar el slop visual.
La raíz es simple: los modelos no tienen acceso al sistema de diseño de tu producto. No saben que tu marca usa Geist Mono para código, que los botones son de 40px con border-radius de 6px, o que la voz de la marca evita el hype. Sin ese contexto, el modelo adivina. Y cuando adivina, adivina genérico.
Hasta hace poco, la solución era mostrarle screenshots, pegar fragmentos de Tailwind config o pasarle un link de Figma que el agente tampoco podía abrir. Funcional, pero frágil. DESIGN.md propone algo más limpio: un único archivo de texto que el agente lee automáticamente y convierte en contexto de diseño persistente.
Qué es DESIGN.md, explicado desde cero
DESIGN.md es, literalmente, un archivo de markdown llamado DESIGN.md que vive en la raíz de tu proyecto. No hay runtime, no hay linter, no hay esquema obligatorio. Es texto plano estructurado por encabezados, pensado para que un modelo de lenguaje lo consuma como contexto.
La idea clave es que todo lo que hace que tu producto se vea como tu producto — colores, tipografía, escala de espaciado, radio de bordes, estilo de sombras, componentes típicos, tono de voz — cabe cómodamente en una página o dos de markdown. No hace falta construir un storybook ni publicar tokens a npm para que un agente empiece a generar UIs coherentes.
Un DESIGN.md típico tiene seis bloques: Brand, Color Palette, Typography, Spacing, Components y Voice. Cada bloque es markdown humano, no JSON: más cerca de unas guidelines bien redactadas que de un archivo de configuración.
💭 Clave: DESIGN.md no pretende reemplazar a Figma ni a los design tokens. Es una capa de contexto para agentes IA, no una fuente de verdad para equipos de diseño maduros.
Origen: Google Stitch 2.0 (marzo 2026)
La convención la introdujo Google el 18-19 de marzo de 2026 como parte del lanzamiento de Stitch 2.0, la segunda versión de su herramienta para generar interfaces con IA. Stitch, originalmente lanzado en 2025 dentro de Google Labs, apuntaba a resolver el problema de «dime cómo querés que se vea y te entrego el HTML». La versión 2.0 sumó un detalle decisivo: permitir que los sistemas de diseño se expresen en un archivo markdown legible tanto por humanos como por modelos.
El anuncio oficial de Stitch 2.0 en blog.google presentó la especificación de DESIGN.md como una propuesta abierta, y la documentación quedó pública desde el día uno. Google dejó claro que no era un formato propietario: cualquier agente podía leerlo, cualquier proyecto podía adoptarlo.
La jugada fue astuta. Google no controla Claude, Cursor, Codex ni Warp, pero controla los primeros templates, la documentación y el blog post inicial. DESIGN.md no necesita permiso para funcionar en un proyecto de Claude Code: basta con que el archivo exista en la raíz.
DESIGN.md vs AGENTS.md vs CLAUDE.md
En 2026 ya hay todo un pequeño ecosistema de archivos markdown pensados para agentes IA. Conviene entender que no compiten, sino que describen cosas distintas:
- AGENTS.md — Convención colaborativa empujada por OpenAI Codex, Cursor, Amp, Jules y Factory, hoy bajo la Linux Foundation. Describe cómo se buildea, se testea y se despliega un proyecto. Responde preguntas como «¿qué comando corre los tests?» o «¿qué lint aplica?». Referencia: agents.md.
- DESIGN.md — Iniciativa 100% de Google Stitch. Describe cómo se ve un producto: paleta, tipografía, espaciado, tono. No habla de CI ni de builds.
- CLAUDE.md — Archivo específico que Anthropic recomienda para Claude Code. Funciona como memoria de proyecto: reglas, convenciones, contexto de negocio. Suele solaparse un poco con AGENTS.md, pero está pensado exclusivamente para Claude.
- .cursorrules — El equivalente histórico de Cursor. Texto plano con reglas específicas para su agente. Documentado en docs.cursor.com.
La tendencia es clara: un .md por rol de IA. DESIGN.md y AGENTS.md son los dos más estandarizables porque no dependen del agente; CLAUDE.md y .cursorrules son vendor-specific pero igualmente útiles. En un proyecto real, los cuatro pueden convivir sin problema.
Anatomía de un DESIGN.md
La mejor forma de entender DESIGN.md es mirar uno. Este es un snippet representativo, cercano a los templates que circulan en awesome-design-md para marcas tipo Vercel o Linear:
# DESIGN.md — ExampleCo
## Brand
- Name: ExampleCo
- Mission: Build fast, beautiful web apps.
- Personality: Minimal, confident, technical.
## Color Palette
- Primary: #000000 (Black)
- Background: #FFFFFF (White)
- Accent: #0070F3 (Blue)
- Muted: #666666 (Gray 500)
- Border: #EAEAEA (Gray 200)
## Typography
- Headings: Geist Sans, weights 500-700
- Body: Inter, weight 400
- Code: Geist Mono, weight 400
- Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48
## Spacing
- Base unit: 4px
- Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64
## Components
- Buttons: rounded-md, px-4, py-2, transition 150ms
- Cards: border, shadow-sm, rounded-lg, padding 24px
- Inputs: border 1px, focus ring 2px blue
## Voice
- Tone: direct, human, technical
- Avoid: hype, emojis, buzzwords
- Prefer: short sentences, active voice
Fijate en un detalle: todo está en prosa estructurada, no en JSON. Un humano lo lee en treinta segundos y tiene una imagen mental completa del sistema. Un LLM lo parsea trivialmente. Es la misma razón por la que README.md ganó frente a manifiestos XML hace una década.
El repo awesome-design-md y por qué explotó
El 31 de marzo de 2026, un repo llamado VoltAgent/awesome-design-md apareció en GitHub con un puñado de templates. Para el 16 de abril tenía 57,054 estrellas, con 68 DESIGN.md curados de marcas como Claude, Cursor, Vercel, Ollama, Mistral, Warp, Raycast, ClickHouse y HashiCorp. MIT license, cero código ejecutable: solo archivos markdown.
57 mil estrellas en 17 días para una awesome list es una señal bastante clara de que la comunidad estaba esperando algo así.
⚠️ Ojo: awesome-design-md es legítimamente útil, pero no es vendor-neutral. VoltAgent monetiza el proyecto vía sponsors y a través de getdesign.md, un host propio. En el estado actual, el README redirige cada link del índice a getdesign.md en lugar de al archivo directo del repo; el contenido completo de cada DESIGN.md todavía vive en commits históricos si preferís ir a la raíz de Git.
Nada de esto es grave — el repo sigue siendo un recurso excelente — pero conviene saberlo antes de citarlo como si fuera una colección imparcial.
Cómo usar DESIGN.md paso a paso
El flujo es intencionalmente aburrido, que es lo que lo hace bueno:
- Elegí un template. Clonás awesome-design-md o copiás uno a mano. Si querés tu propio estilo, arrancá por un template cercano y editalo.
- Pegá el archivo en la raíz del proyecto con el nombre
DESIGN.md. No hace falta una carpeta; la raíz es lo que muchos agentes leen por defecto. - Abrí Claude Code o Cursor en el proyecto. Claude Code lee automáticamente archivos en la raíz y los agrega a su contexto. Cursor requiere que el archivo esté en el contexto actual: podés configurar auto-attach de archivos
.mden settings o arrastrar el archivo al chat. - Promptear con referencia explícita. Algo como «lee
DESIGN.mdy aplicá el sistema al componente Navbar». Es redundante pero efectivo. - Iterar. El primer resultado casi nunca es perfecto. Ajustás el DESIGN.md cuando notás que el agente sigue equivocándose en algo concreto — ejemplo: agregar una línea explícita sobre altura de botones.
El flujo básico visto como diagrama:
flowchart LR;
A[DESIGN.md en raiz] --> B[Agente IA lee contexto];
B --> C[Prompt del usuario];
C --> D[Codigo generado coherente];
D --> E{Esta bien?};
E -- Si --> F[Listo];
E -- No --> G[Refinar DESIGN.md];
G --> B;3 prompts listos para copiar y pegar
Funcionan con Claude Code, Cursor, Windsurf o cualquier agente con acceso a archivos del proyecto. Ajustá los nombres a tu caso:
- Landing tipo Vercel:
"Leé DESIGN.md y creá una landing hero section para un producto SaaS. Respetá la paleta, tipografía y espaciado del archivo. Output: un componente React con Tailwind. No agregues gradientes ni glassmorphism." - Portar estilo existente:
"Tomá el archivo src/pages/signup.tsx y convertilo al sistema definido en DESIGN.md. Conservá la lógica, cambiá solo tokens visuales: colores, radio, espaciado y tipografía." - Auditoría de UI:
"Auditá los componentes en src/components contra DESIGN.md. Listá cada inconsistencia con archivo, línea y la regla violada. No modifiques código todavía, solo reportá."
Limitaciones y pitfalls reales
DESIGN.md resuelve un problema puntual pero está lejos de ser una bala de plata. Algunas cosas que vas a encontrar:
- Captura estilo, no interacciones. Un botón con hover complejo, micro-animaciones, transiciones de página o estados condicionales siguen dependiendo de código. El archivo describe cómo se ve, no cómo se comporta.
- Alucinaciones con instrucciones ambiguas. Si tu DESIGN.md dice «botones redondeados» sin especificar el radio, el agente elige uno. Cuanto más vago el archivo, más impredecible el output.
- No reemplaza design tokens en equipos grandes. Un DESIGN.md no se sincroniza con Figma, no tiene versionado semántico ni exporta a CSS variables. Para un producto con decenas de devs y un design system maduro, seguís necesitando W3C Design Tokens.
- Trademark y copia de guidelines. Copiar el DESIGN.md de Anthropic, Google o Vercel a tu proyecto puede meterte en terreno gris con uso de marca. Los templates de awesome-design-md están pensados como referencia, no como kits comerciales listos para hacer un clon.
- Inconsistencia entre agentes. Claude Code, Cursor y Windsurf leen el archivo con prioridades distintas. Puede que tengas que promptear «lee DESIGN.md» más explícitamente en uno que en otro.
Alternativas y contexto del ecosistema
DESIGN.md no apareció en el vacío. Convive con varias alternativas, cada una con su tradeoff:
- W3C Design Tokens: estándar abierto en JSON para tokens de diseño. Fuerte para equipos con tooling de Figma y sincronización automática. Débil para agentes IA, que lo leen pero no lo interpretan con tanta naturalidad como markdown.
- Shadcn/ui themes: copiá-pegá componentes React con variables CSS. Muy bueno en la práctica, pero acoplado a React y Tailwind.
- Tailwind config:
tailwind.config.jsya es un mini sistema de diseño. Funciona bien para proyectos Tailwind-first, pero no es tan legible por modelos como DESIGN.md. - Figma Tokens: fuente de verdad para muchos equipos; acoplado al workflow de Figma.
- Material 3: sistema completo de Google con tokens y componentes. Alternativa si querés adoptar un sistema existente en vez de inventar el tuyo.
Para proyectos pequeños y agentes IA, DESIGN.md gana por simplicidad. Para equipos de producto establecidos, los otros siguen siendo necesarios — y DESIGN.md puede convivir como una capa derivada.
Cuándo usar DESIGN.md y cuándo no
Usalo cuando: prototipás rápido con IA, armás un side project, construís una landing one-off, escribís docs sites o estás haciendo onboarding de un agente a un design system existente. En todos esos casos, DESIGN.md reduce la fricción de «explicarle el estilo al modelo» de cinco minutos a cero.
Evitalo cuando: estás haciendo diseño original de marca (para eso hace falta gente, no archivos), trabajás en apps con interacciones complejas donde la animación y el feedback son parte del producto, formás parte de un equipo con design system maduro y procesos de gobernanza, o desarrollás UIs con requisitos de compliance estricto (banca, salud, gobierno), donde un archivo markdown interpretable libremente es demasiado frágil como fuente de verdad.
💡 Tip: Si tu equipo ya tiene Figma tokens y storybook, podés generar un
DESIGN.mdderivado automáticamente a partir de los tokens. Así mantenés Figma como fuente de verdad y DESIGN.md como capa de contexto para agentes.
Contexto 2026: por qué esta convención está explotando
La explosión de DESIGN.md en pocas semanas no es casualidad. Tres vectores se alinearon:
Primero, el vibe coding ya se consolidó como práctica: buena parte del código nuevo en 2026 se escribe con un agente en el loop. Cuando el autor del código no toca el editor, todo lo que le dé contexto al agente pasa a ser producto terminado. README, AGENTS.md, CLAUDE.md, y ahora DESIGN.md.
Segundo, los agentes autónomos (tareas de horas, no minutos) necesitan contexto persistente. Cada vez que un agente abre un ticket y genera cincuenta archivos, la consistencia visual se derrumba si no tiene una guía clara. DESIGN.md es precisamente eso.
Tercero, la comunidad ya entrenó a Google, Anthropic y OpenAI en que lo que se escribe en markdown en la raíz del repo termina siendo honrado por los agentes. Es un formato con poco costo de adopción y mucha inercia a favor.
En una frase: DESIGN.md existe porque los agentes IA ya son el segundo usuario de tu repo, y necesitan leer tu sistema de diseño sin abrir Figma.
📖 Resumen en Telegram: Ver resumen
Preguntas frecuentes
¿DESIGN.md reemplaza a mi design system?
No. DESIGN.md es una capa de contexto pensada para agentes IA; tu design system sigue viviendo en Figma, storybook o tokens. Lo que hace DESIGN.md es traducir lo esencial de ese sistema a un formato que un modelo lee sin fricción.
¿Qué agentes entienden DESIGN.md hoy?
Cualquier agente con acceso a archivos del proyecto: Claude Code, Cursor, Windsurf, Codex, Warp, Jules y Amp. Algunos lo leen automáticamente si está en la raíz (Claude Code); otros requieren que lo agregues al contexto explícitamente (Cursor). En todos los casos, un prompt del tipo «lee DESIGN.md» garantiza que entre al contexto.
¿Tengo que usar el formato de Google Stitch tal cual?
No. La convención es laxa: seis secciones (Brand, Color, Typography, Spacing, Components, Voice) son una buena base, pero nada te impide agregar o quitar. Lo importante es que un humano lo entienda de un vistazo y un modelo lo parsee sin esfuerzo.
¿Está bien copiar el DESIGN.md de Vercel o Anthropic a mi proyecto?
Como inspiración, sí. Como diseño final de tu producto, no — además de ser perezoso, puede tener implicaciones de marca. El valor real está en adaptar un template al estilo de tu propia marca.
¿Vale la pena usarlo en 2026 si no uso agentes IA?
Probablemente no. DESIGN.md fue pensado como contexto para modelos de lenguaje. Si tu flujo es 100% humano con Figma y CSS, un STYLEGUIDE.md tradicional o tus tokens son suficientes.
¿Cuál es la diferencia práctica con AGENTS.md?
AGENTS.md describe cómo se construye el proyecto (comandos, lint, tests, dependencias). DESIGN.md describe cómo se ve. Los dos archivos pueden, y deberían, coexistir en un mismo repo.
Referencias
- blog.google — Stitch 2.0 announcement — Anuncio oficial de Google con la introducción de DESIGN.md.
- stitch.withgoogle.com — DESIGN.md overview — Documentación oficial del formato.
- github.com/VoltAgent/awesome-design-md — Repo con 68 templates DESIGN.md curados. MIT license.
- getdesign.md — Host alternativo mantenido por VoltAgent.
- agents.md — Sitio oficial de la convención AGENTS.md.
- developers.openai.com/codex — OpenAI Codex, impulsor de AGENTS.md.
- docs.cursor.com — Documentación oficial de Cursor y .cursorrules.
- W3C Design Tokens Community Group — Estándar de tokens en JSON.
- ui.shadcn.com — Shadcn/ui y su sistema de themes.
- tailwindcss.com/docs/theme — Configuración de tema en Tailwind.
- m3.material.io — Material Design 3, alternativa completa de Google.
📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.
0 Comentarios