El formato DESIGN.md propuesto por Google Labs en el proyecto Stitch me pareció interesante, así que pasé varios días desmenuzando la especificación y la organicé en coreano en forma de un currículo de 28 capítulos, porque me daba pena quedármelo solo para mí. Lo preparé con la idea de que quienes estén estudiando este mismo tema no tengan que ir a rastrear la especificación en inglés desde el principio, y también para que quienes, como yo, se preguntan “¿cómo hacer que una IA lea un sistema de diseño?” puedan revisarlo de una sola pasada.
DESIGN.md es un formato que busca expresar un sistema de diseño en un solo archivo Markdown. Valores como color, tipografía, spacing, radius y component token se colocan en el YAML frontmatter en una forma legible por máquinas, y debajo, en el Markdown, se escriben criterios de decisión de diseño como “por qué se usa este color”, “en qué situaciones se usa este estilo de botón” o “qué patrones conviene evitar”. Es decir, no es solo una guía de estilos, sino algo más cercano al “archivo fuente del sistema de diseño” que agentes de programación con IA como Claude Code, Cursor o Codex consultarían constantemente.
Antecedentes — cambios que volví a repasar mientras lo organizaba
• Antes la pregunta era: “¿cómo organizamos bien el sistema de diseño en Figma?”
• Ahora la pregunta es: “¿cómo hacemos que las herramientas de programación con IA lean nuestro sistema de diseño?” y “¿qué hace falta para que, al crear una página nueva, la IA siga las reglas de color, espaciado y componentes de nuestra marca?”
• En línea con tendencias como Claude Design, Claude Code y Figma MCP, el sistema de diseño deja de quedarse solo dentro de Figma, entra al codebase, se revisa en los PR y pasa a convertirse en el “contexto persistente” de los agentes de IA
Puntos clave del formato DESIGN.md (lo que más me llamó la atención al leer la especificación)
• Estructura doble de YAML (para máquinas) + Markdown (para personas e IA): los tokens los parsea la máquina y el cuerpo es la capa donde las personas dejan el razonamiento detrás de las decisiones
• Los tokens son la respuesta correcta, el cuerpo explica el porqué: está bien resuelto que se deje definida de antemano la prioridad sobre a cuál creer cuando ambos no coinciden
• El orden de 8 secciones es fijo: colors, typography, spacing, components, etc.; las secciones mismas funcionan como el modelo mental del sistema de diseño
• lint / diff / export / spec CLI: revisa automáticamente elementos como referencias rotas, contraste insuficiente, tokens huérfanos o violaciones del orden de secciones
• También se especifica por separado la política de interoperabilidad con DTCG, Tailwind y variables de Figma
Estructura del currículo (28 capítulos, 7 módulos)
• M1 filosofía del formato · 3 capítulos — el problema que este formato intenta resolver, la estructura doble y la prioridad entre tokens y cuerpo
• M2 esquema de tokens · 5 capítulos — esquema completo / color / longitud y unidades / fuentes / referencias de tokens
• M3 estructura de secciones · 6 capítulos — el orden de 8 secciones y los principios de diseño de cada una
• M4 lectura de ejemplos reales · 3 capítulos — casos de Atmospheric Glass, Paws & Paths y Totality Festival
• M5 CLI · 4 capítulos — lint, diff, export, spec
• M6 reglas de lint · 4 capítulos — 8 reglas como broken-ref, contrast, orphaned, section-order, etc.
• M7 extensibilidad · 2 capítulos — política para manejar contenido desconocido y relación con DTCG y Tailwind
• Cierre final · 1 capítulo — resumen de 27 capítulos + 10 principios para llevar a la práctica profesional
Lo que pensé mientras lo iba organizando
• Cuanto más UI construya la IA, más importante parece volverse el sistema de diseño. La cuestión ya no parece ser “si la IA diseña bien”, sino “qué tan claramente dejó el equipo los criterios que la IA debe seguir”
• DESIGN.md es un intento práctico de poner esos criterios no en Notion o en un PDF, sino dentro del codebase. También implica que los entregables de diseño pasen a ser objeto de revisión a nivel de PR
• Lo comparto porque creo que puede servir a quienes están construyendo un sistema de diseño o a quienes, creando UI con herramientas de programación con IA, han sentido “¿por qué el resultado sale distinto cada vez?”. Si hay partes que entendí o resumí mal, avísenme en los comentarios y las corregiré.
2 comentarios
Tengo una duda: si se entiende que
DESIGN.mdson instrucciones para extraer el diseño, al final se usa para generar las primeras páginas... o una página, un mood board. Luego, ¿no termina produciéndose una discrepancia entre el código y las instrucciones.md, de modo que hay que seguir sincronizando ambos en las dos direcciones?Al final, para el diseño posterior, habría que tomar el código como source of truth y reutilizar de forma consistente cosas como variables o nombres. Si no se actualiza
DESIGN.mdde forma continua y se gestiona como SSoT, me da la impresión de que se terminarán hardcodeando los tokens una y otra vez. Me gustaría saber si en el uso real no surge este tipo de problema.DESIGN.md => la dirección del código es fácil de automatizar, pero al revés, hacer que los nuevos patrones que aparecen en el código suban a DESIGN.md no se automatiza, así que al final una persona tiene que encargarse directamente. Con el tiempo, en el código se van acumulando pequeños hardcodeos, pero eso no se refleja en la documentación, y esa brecha se va acumulando.
Aun así, la filosofía de este formato en sí va más por el lado de "seguir cultivando el sistema de diseño dentro de la base de código", así que creo que esto se parece más a una forma de operación intencional que a una desventaja. Como bajó las guías que antes se dejaban congeladas en Notion o PDF al nivel de revisión por PR, parece una estructura donde también viene incluida la responsabilidad de que alguien las revise y ajuste periódicamente. Lo probamos en nuestro proyecto, y la consistencia de las pantallas definitivamente mejoró frente a antes de adoptarlo; como ese beneficio se siente de verdad, la revisión manual no se percibe como una carga. Al final, llegué a la conclusión de que esto depende de qué tan claramente el equipo deje definidos los criterios que la IA debe seguir, y de que el mantenimiento para que esos criterios sigan vivos todavía queda del lado de las personas.