El formato DESIGN.md propuesto por Google Labs en el proyecto Stitch me pareció interesante, así que después de revisar la especificación durante varios días, lo organicé en coreano con formato de currículum de 28 capítulos porque me daba pena quedármelo solo para mí. Lo preparé con la idea de que quienes estén estudiando el mismo tema no tengan que meterse desde el inicio a la especificación en inglés y de que quienes, como yo, se preguntan "¿cómo hacer que una IA lea un sistema de diseño?" puedan recorrerlo de una sola vez.
DESIGN.md es un formato que busca expresar un sistema de diseño en un solo archivo Markdown. Valores como colores, tipografía, spacing, radius y component token se colocan en YAML frontmatter en una forma legible para máquinas, y en el Markdown de abajo 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 se parece tanto a una simple guía de estilos, sino más bien al "archivo fuente del sistema de diseño" que agentes de codificación con IA como Claude Code, Cursor y Codex consultarían cada vez.
Contexto — cambios que volví a repasar mientras lo organizaba
• Pregunta de antes: "¿cómo organizar bien un sistema de diseño en Figma?"
• Pregunta de ahora: "¿cómo hacer que las herramientas de codificación con IA lean nuestro sistema de diseño?", "¿qué hace falta para que, al crear una nueva página, la IA siga los colores, espaciados y reglas de componentes de nuestra marca?"
• En línea con movimientos 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 PR y se convierte en "contexto persistente" para agentes de IA
Puntos clave del formato DESIGN.md (las partes que más me llamaron la atención al leer la especificación)
• Estructura doble de YAML (para máquinas) + Markdown (para humanos y la IA) — los tokens los parsea la máquina, y el cuerpo es la capa donde las personas dejan la lógica detrás de sus decisiones
• Los tokens son la respuesta correcta; el cuerpo explica el porqué — está bien resuelto que se defina de antemano a cuál creerle cuando ambos no coinciden
• El orden de 8 secciones es fijo — secciones como colors, typography y components funcionan por sí mismas como el modelo mental del sistema de diseño
• lint / diff / export / spec CLI — inspecciona automáticamente referencias rotas, contraste insuficiente, tokens huérfanos y 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ículum (28 capítulos, 7 módulos)
• M1 filosofía del formato · 3 capítulos — el problema que este formato busca 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 y section-order
• 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
Ideas que me quedaron al organizarlo
• Cuanto más UI construya la IA, más importante se volverá 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 dentro del codebase en lugar de dejarlos en Notion o un PDF. También implica que el entregable del diseñador pasa a ser objeto de revisión a nivel de PR
• Lo comparto porque creo que puede servirles a quienes están creando un sistema de diseño o a quienes, al construir UI con herramientas de codificación con IA, alguna vez sintieron "¿por qué el resultado sale diferente cada vez?". Si hay partes que entendí o resumí mal, avísenme en los comentarios y lo 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.