¿Qué es design.md? Guía para sistemas de diseño con IA

Design.md es un archivo Markdown en la raíz de un proyecto que documenta las decisiones visuales —colores, tipografía, bordes, componentes— en un formato que humanos y agentes de IA pueden leer sin abrir Figma. Funciona como el README del diseño: no sustituye el criterio de un diseñador, pero evita que cada pantalla nueva nazca con otro azul, otra fuente y otro radio de borde.

Si trabajas con Claude Code, Cursor, v0 o cualquier flujo donde la IA escribe frontend, un design.md bien armado reduce la «convergencia distribucional» —ese look genérico de Inter, fondo oscuro y acento cian— porque el modelo parte de tokens concretos en lugar de adivinar.

Navegación rápida

Qué es design.md | Por qué importa ahora | Qué debe incluir | Qué no sustituye | Generar con Converly | vs Figma | FAQ

Qué es design.md

Design.md (a veces escrito design md o Design.md) es documentación de diseño en Markdown pensada para vivir junto al código. La analogía más útil: si README.md explica qué hace el proyecto y cómo arrancarlo, design.md explica cómo debe verse y sentirse.

En equipos que ya usan convenciones para IA —como CLAUDE.md, reglas de Cursor o Skills de frontend—, design.md encaja en la misma capa: contexto persistente que el agente carga antes de tocar CSS o componentes.

No hay un estándar único ratificado por un consorcio. Lo que importa es que sea legible, específico y accionable: hex o variables CSS nombradas, roles tipográficos con familia y peso, y reglas de uso («botón primario = paso 9 de la escala de acento») en lugar de adjetivos vagos («azul corporativo moderno»).

Por qué importa ahora

Hace dos años bastaba con un PDF de marca. Hoy buena parte del UI se genera o refactoriza con IA:

• Claude Code y Cursor leen archivos del repo como contexto.
• v0, Bolt y herramientas similares producen componentes a partir de prompts.
• Los Skills y rules empujan estética, pero sin tokens concretos el modelo vuelve a sus defaults.

Un design.md para IA cumple tres funciones prácticas:

1. Alineación — Diseño y desarrollo (o tú y el agente) comparten la misma fuente de verdad.
2. Menos iteración — Menos «hazlo más azul» en bucle porque el azul ya está definido como --blue-9.
3. Handoff barato — Pegas el archivo en el chat o lo dejas en el repo; no hace falta exportar capturas de Figma para cada pantalla.

Design.md no hace magia: si el archivo es pobre, la salida seguirá siendo pobre. Pero un archivo rico sí cambia el punto de partida de cada generación.

Qué debe incluir un design.md útil

Un design.md orientado a implementación —no a storytelling de marca— suele cubrir estas áreas. Cuanto más cerca esté del CSS real, mejor lo interpreta la IA.

Tokens de color

• Semillas — Acento, gris neutro y fondo base en light y dark.
• Escalas de 12 pasos — Patrón popularizado por Radix: cada paso tiene un rol (fondos 1–2, interactivo 3–5, bordes 6–8, sólidos 9–10, texto 11–12).
• Tokens semánticos — --accent-contrast, --gray-surface, --color-background.
• Modo claro y oscuro — Tablas paralelas; el dark no es «invertir hex».

Tipografía

• Roles, no solo nombres de fuente: heading, labels, body.
• Familia, pesos y variable CSS (--font-heading, etc.).
• Enlace de import (p. ej. Google Fonts) listo para copiar.
• Dónde aplica cada rol — h1, etiquetas de formulario, cabeceras de tabla.

Bordes y superficies

• Radio global (--radius: 8px o pill).
• Qué pasos de gris usar para borde, separador y focus ring.

Componentes clave

Al menos botones primario y secundario con token de fondo, hover y texto. Opcional: inputs, links, estados de foco.

Bloque CSS exportable

Un bloque :root / .dark con variables listas para pegar acelera mucho el trabajo del agente.

Enlace compartible (opcional pero valioso)

Si la paleta vive en una URL con parámetros, incluirla en el design.md permite que cualquiera regenere el mismo archivo tras un cambio.

El Design.md que exporta Converly Colors incluye todo lo anterior en inglés —formato habitual para repos y modelos— más la URL de tu configuración actual.

Qué no sustituye design.md

Ser honestos evita frustración. Design.md es una herramienta de especificación, no de diseño en el sentido amplio.

Si crees que diseño es solo seguir reglas, un design.md te dará interfaces uniformes pero no necesariamente buenas. La uniformidad es el piso; el techo sigue siendo juicio humano: jerarquía, ritmo, accesibilidad en contextos reales, decisiones de layout.

Tampoco reemplaza un design system completo en Figma con componentes, variantes y documentación de patrones complejos. Es el subset que el código necesita hoy, en un solo archivo que la IA puede ingerir.

Cómo generar design.md con Converly Colors

Escribir un design.md a mano desde cero lleva horas y es fácil equivocarse en contrastes o en el paso 7 del modo oscuro. Converly Colors genera el archivo a partir de una paleta real que configuras en la interfaz —no de plantillas genéricas.

Pasos:

1. Abre converly.es/colors/custom.
2. Define color principal, secundario y fondo; revisa light y dark.
3. Asigna tipografías en los tres roles (títulos, etiquetas, cuerpo) desde el catálogo de Google Fonts.
4. Ajusta el radio de bordes con el slider o los presets.
5. Comprueba la preview con botones, formularios y tabs.
6. Pulsa Exportar → Copiar Design.md o Descargar Design.md.

Desde el mismo menú puedes obtener CSS completo, CSS por escala, SVG de la paleta y un enlace compartible que restaura colores, fuentes y radio. El Design.md generado enlaza esa URL para que el equipo regenere la documentación tras cualquier cambio.

Para el detalle de cada opción de exportación, escalas de 12 pasos y parámetros de la URL, consulta la guía del generador de paletas de colores de Converly.

Dónde colocar el archivo en tu repo

• Raíz del proyecto: Design.md o design.md (sé consistente con lo que referencies en CLAUDE.md o reglas de Cursor).
• O en docs/design.md si tu convención separa documentación — pero entonces indica la ruta en las reglas del agente.

Cómo usarlo con IA

• Añade en CLAUDE.md: «Antes de cambiar estilos, lee Design.md y usa sus variables CSS».
• En Cursor, incluye el archivo en Project Rules o menciónalo en el prompt: «Implementa esta vista siguiendo Design.md».
• Combínalo con guías de estética como en mejora de prototipos de IA con Skills y Gemini: tokens de Converly + criterio de layout en el Skill.

design.md vs Figma vs documentación de design system

En la práctica se complementan: Figma (o boceto) para explorar; design.md + CSS para lo que se mergea al repo. Para MVPs y prototipos con IA, muchos equipos empiezan solo por design.md y CSS exportado —y añaden Figma cuando el producto lo exige.

Preguntas frecuentes

¿Design.md es un estándar oficial?

No hay un RFC único. El nombre sigue la convención de README.md y archivos de contexto para IA (CLAUDE.md). Lo relevante es el contenido accionable, no el nombre exacto del fichero.

¿En qué idioma debe estar?

Para repos y modelos en inglés, un design.md en inglés suele integrarse mejor —es lo que genera Converly Colors por defecto. Puedes añadir una sección en español para tu equipo si lo necesitáis; lo crítico son los tokens y el CSS, que son independientes del idioma.

¿Puedo crear design.md sin Converly?

Sí. Puedes escribirlo a mano o exportar tokens desde Figma Tokens, Style Dictionary, etc. Converly aporta valor cuando ya tienes un color de marca y quieres escalas light/dark, tipografías y CSS coherentes sin montar el pipeline tú mismo.

¿La IA seguirá el design.md al 100 %?

No siempre. Conviene referenciarlo en reglas del proyecto y pegar el bloque CSS en tu hoja global. Cuanto más concrete el archivo (variables nombradas, no «azul bonito»), mayor la adherencia.

¿Sustituye a un diseñador?

No. Genera y documenta decisiones visuales repetibles. La identidad, el research y las excepciones con criterio siguen siendo humanas —como explicamos en la guía del generador de paletas.

¿Qué relación tiene con los Skills de frontend?

Los Skills empujan dirección estética (tipografía distintiva, composición, motion). Design.md fija tus valores: qué fuente, qué escala, qué radio. Juntos evitan el look genérico y mantienen tu marca.

¿Puedo versionar design.md en Git?

Sí —y deberías. Al cambiar la paleta, regenera el archivo, commitea y el historial queda trazable. La URL compartible de Converly ayuda a alinear al equipo antes del merge.

---

Genera tu design.md ahora: converly.es/colors/custom

Lecturas relacionadas

• Generador de paletas de colores: herramienta gratuita en Converly
• Mejora prototipos de IA con Skills, prompts y Gemini
• ¿Qué es el prompt engineering?

Última actualización: julio de 2026.