El formato DESIGN.md es una especificación técnica diseñada para comunicar la identidad visual de un proyecto tanto a humanos como a agentes de inteligencia artificial. Su estructura combina un encabezado YAML con valores numéricos precisos, llamados tokens de diseño, junto con un cuerpo en Markdown que detalla la lógica estética y el estilo de la marca.
Qué es un DESIGN.md
Un DESIGN.md es un documento de sistema de diseño en formato de texto plano diseñado para ser leído, editado y aplicado tanto por seres humanos como por agentes de IA. Su propósito principal es definir la identidad visual de un proyecto (colores, fuentes, espaciado y estilos de componentes) de una manera que las herramientas de codificación automatizada puedan entender para generar interfaces de usuario coherentes.
El archivo, DESIGN.md, combina datos estructurados con explicaciones narrativas. son dos capas fundamentales:
- YAML Front Matter: Ubicado al inicio del archivo, contiene tokens de diseño legibles por máquinas (valores exactos de hex, escalas de fuentes, etc.). Estos son los valores normativos.
- Cuerpo de Markdown: Proporciona la justificación del diseño legible por humanos organizada en secciones. Explica el porqué de los valores y cómo aplicarlos.
Para qué sirve un Design-system.md
Esta herramienta permite que los sistemas de IA generen interfaces coherentes al interpretar datos específicos de color, tipografía, espaciado y componentes. Los documentos también describen una interfaz de línea de comandos (CLI) capaz de validar reglas, detectar errores de contraste y exportar configuraciones a plataformas como Tailwind. Al funcionar como una fuente de verdad viva, este estándar facilita la transición entre el diseño conceptual y la implementación automatizada de código.
A diferencia de un archivo de Figma o un PDF de marca, un DESIGN.md es un artefacto vivo que un agente de IA puede procesar directamente. Al leerlo, el agente asegura que cada pantalla generada siga las mismas reglas visuales, evitando que los diseños parezcan piezas aisladas y logrando que todo el producto tenga una identidad unificada.
Por lo tanto este archivo sirve o permite:
- Garantizar la consistencia visual: Al ser leído por agentes de diseño, asegura que cada pantalla generada siga las mismas reglas visuales (colores, tipografía, patrones de componentes). Sin este archivo, las pantallas generadas por IA pueden parecer piezas aisladas; con él, todas parecen pertenecer al mismo producto.
- Cerrar la brecha entre diseño e IA: Tradicionalmente, la identidad visual reside en archivos de Figma, PDFs de marca o en la mente de un diseñador, formatos que los agentes de IA no pueden procesar directamente. El DESIGN.md traduce esta identidad a un formato que los agentes de codificación pueden «entender» y ejecutar.
- Servir como vocabulario compartido: Actúa como un terreno común para agentes, herramientas y equipos, proporcionando un lenguaje compartido para elementos como la elevación, las formas y el diseño. Todos hablan el mismo idioma.
- Capturar el lenguaje de diseño existente: Permite extraer automáticamente el sistema de diseño de un código fuente ya existente (como configuraciones de Tailwind o archivos CSS). Esto ayuda a que la IA genere nuevas pantallas que coincidan con la estética actual del proyecto en lugar de empezar desde cero.
Partes o secciones de un Design-system.md
Aunque es un formato flexible y extensible, la especificación sugiere un orden específico para las secciones. Un orden estandarizado es que el archivo contenga las siguientes secciones: El documento está organizado en secciones canónicas que incluyen un Resumen (personalidad de marca), Colores, Tipografía, Diseño y Espaciado, Elevación y Profundidad, Formas, Componentes y una guía de Qué hacer y qué no.
Según la especificación técnica, las secciones deben aparecer en el siguiente orden, aunque pueden omitirse si no son relevantes para el proyecto:
- Overview (Resumen o Brand & Style): Describe de forma holística la personalidad de la marca, la audiencia objetiva y la respuesta emocional que debe evocar la interfaz (por ejemplo, si debe sentirse profesional o juguetona).
- Colors (Colores): Define las paletas cromáticas. Generalmente incluye roles semánticos como colores primarios, secundarios, terciarios y neutrales.
- Typography (Tipografía): Establece los niveles tipográficos (como encabezados, cuerpo de texto y etiquetas), definiendo familias de fuentes, pesos y jerarquías visuales.
- Layout (Diseño o Layout & Spacing): Detalla la estrategia de cuadrículas, márgenes, áreas seguras y escalas de espaciado.
- Elevation & Depth (Elevación y Profundidad): Explica cómo se transmite la jerarquía visual, ya sea mediante sombras (en diseños con profundidad) o mediante bordes y contrastes tonales (en diseños planos).
- Shapes (Formas): Define el lenguaje visual de los elementos, como los radios de las esquinas (redondeado) de botones y tarjetas.
- Components (Componentes): Ofrece guías de estilo específicas para átomos de la interfaz como botones, entradas de texto, listas, casillas de verificación y otros elementos específicos del dominio.
- Do’s and Don’ts (Qué hacer y qué no): Proporciona pautas prácticas y restricciones que sirven como «barreras de seguridad» para evitar errores comunes durante la generación de diseños por IA.
Para la flexibilidad del formato se usan las siguientes secciones con especificaciones:
- Encabezados: Las secciones principales utilizan encabezados de nivel 2. Se puede incluir un título opcional con # al principio, pero este no se analiza como una sección técnica.
- Extensiones: El formato es abierto; si se incluyen encabezados desconocidos (por ejemplo, ## Iconography), las herramientas deben preservarlos sin marcar error.
- Variantes: Dentro de los componentes, se pueden definir variantes para estados específicos como hover, active o pressed.
Incluyendo Tokens en un DESIGN.md
Los tokens de diseño son valores que definen los atributos visuales de los elementos de la interfaz de usuario, como colores, tipografías, espaciados, etc. Organizar y definir tokens de manera efectiva es crucial para mantener la consistencia y escalabilidad de un sistema de diseño.
Como el sistema de diseño está creado en Figma, pido a Figma Make que genere un archivo DESIGN.md que cumpla estrictamente con la especificación de Google. Siguiendo esas pautas, el archivo, funciona correctamente y es efectivo para la interpretación de distintas IAs. El prompt debe ser técnico, estructurado y directivo.
Ejemplo de Prompt para Figma Make y que cree el Design-system.md para otras IAs
Actúa como un ingeniero de diseño experto y genera un archivo DESIGN.md basado estrictamente en el sistema de diseño de este archivo de Figma. El documento debe seguir la especificación técnica de Google para ser procesado por agentes de IA.
Estructura requerida:
Capa de Datos (YAML Front Matter): Inicia el archivo con un bloque YAML delimitado por —. Este debe contener los tokens de diseño precisos (valores normativos) inspirados en el formato W3C.
Usa el formato #RRGGBB para colores.
Usa Dimension (número + px/rem/em) para espaciado y tamaños.
Define objetos compuestos para Typography (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing).
Usa referencias cruzadas con la sintaxis {path.to.token} (ej. {colors.primary}).
Capa Narrativa (Markdown Body): Después del YAML, incluye secciones con encabezados ## que proporcionen el racional de diseño (prosa) para humanos y agentes, explicando el porqué de los estilos.
Orden de Secciones (Obligatorio): Sigue este orden canónico exacto, omitiendo solo si no hay datos en Figma:
## Overview: Describe la personalidad de la marca, audiencia y respuesta emocional deseada.
## Colors: Define las paletas (primary, secondary, neutral) y sus roles semánticos.
## Typography: Detalla los niveles (headline, body, label) y su jerarquía visual.
## Layout: Explica el sistema de cuadrícula, escalas de espaciado y márgenes.
## Elevation & Depth: Describe cómo se usa la profundidad (sombras o contrastes tonales).
## Shapes: Define el lenguaje de formas y radios de esquina (rounded).
## Components: Guía de estilo para átomos (Buttons, Inputs, etc.), incluyendo variantes de estado (hover, active) y propiedades como backgroundColor y padding.
## Do’s and Don’ts: Lista pautas prácticas y restricciones para evitar errores de implementación.
Instrucción Final: Extrae el contenido real de este diseño (nombres de producto, terminología, valores exactos) y evita usar texto de relleno o placeholders.
El buen uso de DESIGN.md radica en tratarlo como un artefacto vivo que unifica la visión creativa humana con la precisión técnica requerida por los agentes de IA. Para maximizar su valor, es fundamental respetar su estructura de dos capas —usando el YAML para valores normativos y el Markdown para el racional de diseño— y alimentarlo con datos reales del proyecto en lugar de marcadores de posición, garantizando así una generación de interfaces coherente, consistente y técnicamente validada
Créditos
La imagen de cabecera
What is DESIGN.md?
Write design system guidelines for Make kits
DESIGN.md Format
DESIGN.md