Un ejemplo de DESIGN.md, sección por sección
La forma más rápida de entender DESIGN.md es recorrer uno. Desglosamos un archivo completo en el orden en que lo lee una AI: qué contiene cada sección, cómo se ve y por qué ocupa ese lugar. Puedes usar esta estructura como plantilla.
La estructura general del archivo
Todo DESIGN.md correcto tiene tres capas en el mismo orden: frontmatter con metadatos, secciones de tokens —color, tipografía, espaciado, forma, sombra y movimiento— con valores exactos, y una capa aplicada con lógica de componentes y uso.
El orden importa. El agente avanza de orientación a vocabulario y gramática: qué es, cuáles son los valores y cómo se combinan. Así puede analizarlo en una pasada, sin inferencias.
Frontmatter: nombre, esencia e indicadores
El archivo abre con un bloque YAML de pocos campos: nombre, esencia en una frase e indicadores booleanos, sobre todo si el estilo es oscuro. Para Bauhaus podría decir «claridad geométrica con acentos primarios; la forma sigue a la función».
Aunque pequeño, es el bloque más eficiente. La esencia orienta todo lo posterior y el indicador oscuro cambia contraste, elevación e imágenes. Incluso por sí solo evita los peores errores.
Tokens: valores exactos con nombres por función
The color section lists a named palette where every entry is a role plus an exact value: background <hex>, ink <hex>, a small set of accents <hex>, hairline <hex>. Roles, not appearances — so the agent knows where each color belongs, not just what it looks like.
The typography section names the font families and weights, then gives a type scale as concrete sizes — display, heading, body, caption, each at <px> with a line height. The spacing section states the rhythm the layout snaps to: a base unit in <px> and the steps built on it.
Shape, shadow, and motion round out the vocabulary: corner radii in <px>, elevation levels with their shadow values, and easing curves with durations. Every one of these is a number a machine can apply verbatim — that is the test each line has to pass.
One honest note: the values in this walkthrough are placeholders like <hex> and <px>. The structure of a DESIGN.md is open; the precise values for each of Curio's styles are the paid product. What matters for a template is the shape — swap in your own values and the file works.
Capa aplicada: componentes y límites
Tras los tokens aparecen reglas declarativas para componentes. Un botón primario usa tinta, texto del fondo, radio de forma y ninguna sombra. Una tarjeta lleva línea fina, nunca sombra. La jerarquía usa tamaño y peso, no colores añadidos.
El archivo termina con usos adecuados y límites: por ejemplo, editorial y marketing sí; tablas densas y dashboards no. Esos límites evitan aplicar un buen estilo en el lugar equivocado.
Úsalo como plantilla o consigue uno real
Si codificas tu marca, usa este recorrido como plantilla: abre con frontmatter, define tokens por función y cierra con componentes y límites. Añade tus valores y tendrás una especificación.
Si quieres un estilo establecido, el archivo ya existe. Cada estilo de Curio se entrega como DESIGN.md completo con valores reales, listo para aplicarse mediante MCP, enlace o descarga.
FAQ
¿Puedo copiar esta estructura como plantilla?
Sí. La estructura de DESIGN.md es abierta y este artículo existe para copiarse: frontmatter, tokens por función, lógica y límites. Sigue la forma general de la especificación abierta de Google y cualquier herramienta compatible puede leerla.
¿Por qué hay marcadores en vez de números reales?
Porque los valores son el producto. La estructura de DESIGN.md es pública; los tokens exactos investigados para cada estilo de Curio se desbloquean con un plan de pago. Para tu marca, introduces tus propios valores.
¿Cuál es el DESIGN.md mínimo viable?
Frontmatter con nombre, esencia e indicador oscuro; paleta y escala tipográfica exactas; una unidad de espaciado; y tres reglas para botón, tarjeta y énfasis. Cabe en media página y supera a un prompt de adjetivos.