Cómo generar un DESIGN.md (y qué es)

Un DESIGN.md reside junto al código y describe el diseño previsto en términos sobre los que un agente puede actuar. Los agentes de código implementan bien la interfaz de usuario, pero sin una dirección artística tienden a recurrir a un estilo institucional neutro. Desde entonces, el nombre se ha convertido en un pequeño ecosistema: Google Labs liberó una especificación de formato DESIGN.md (del equipo de Stitch, Apache 2.0, todavía en versión alpha), que atrajo decenas de miles de estrellas en GitHub en pocos meses. Su especificación combina tokens legibles por máquina en el front matter de YAML con una justificación legible por humanos en prosa, e incluye una CLI que valida archivos y exporta a Tailwind y al formato de design-token de la W3C.

Esa estructura —valores exactos más intención escrita en un solo archivo— es la misma conclusión que defiende esta guía, y conviene ser precisos sobre lo que la especificación ofrece y lo que no. Un formato le indica dónde van los tokens y la prosa. No produce el sistema de diseño en sí: los tokens deben provenir de algún lugar, y los motivos, las restricciones y las reglas de estructura de página deben ser decididos por alguien. Los sitios de catálogos recopilan archivos DESIGN.md terminados; los enfoques de generación detallados a continuación producen uno a partir de un sistema real, que es la diferencia entre un archivo que se valida y un archivo que cambia lo que un agente construye.

Un DESIGN.md necesita más que una lista de colores. Los agentes también necesitan directrices sobre maquetación, espaciado, tratamiento de componentes y los detalles que distinguen un diseño de otro. Un brief útil dedica la mayor parte de sus palabras a esas decisiones.

Un brief completo cubre todo el sistema, no solo los tokens. El DESIGN.md que genera Identity Forge se organiza en estas secciones:

• Overview: qué es el diseño, a quién va dirigido y la sensación prevista en una o dos frases.
• Colors: los tokens semánticos como variables CSS listas para pegar en globals.css, en modo claro y oscuro. Explicación de los tokens de color semánticos.
• Typography: la combinación tipográfica, escala, tracking y pesos, además de una configuración de fuentes de Next.js lista para usar.
• Layout: base de espaciado, ancho del contenedor y reglas de composición.
• Elevation & Depth: el sistema de sombras (o la ausencia deliberada de este).
• Shapes: radios de esquina por elemento (botones, tarjetas, inputs, badges) y tratamiento de los bordes.
• Components: cómo deben tratarse los componentes principales, con un ejemplo.
• Page Structure & Layout: cómo componer páginas completas; aquí es donde se evita el resultado genérico de la IA.
• Personality & References: la voz y los referentes detrás del diseño.
• Distinctive Motifs: los elementos distintivos a reproducir; «definen el diseño tanto como los tokens».
• Do's & Don'ts: las reglas que mantienen la interfaz generada dentro del universo del diseño.
• Agent Rules: instrucciones explícitas para el propio agente de código.

La lista anterior es lo que cubre un brief completo. Vale la pena saber hasta qué punto los archivos publicados se quedan cortos, ya que la brecha es constante y le indica exactamente qué secciones priorizar si está escribiendo uno a mano.

Analizamos 299 archivos DESIGN.md publicados en repositorios y directorios públicos: archivos reales, escritos para dar pautas de diseño a los agentes. 72 eran específicamente archivos de diseño visual.

Contraponga las dos últimas filas y el patrón es inconfundible. La tipografía se menciona en el 83% de los archivos, y el 44% de los archivos nunca indica un solo tamaño. Son documentos que hablan de tipografía sin decir qué tamaño tiene nada.

La cifra de los adjetivos explica el resto. "Limpio" aparece en el 39% de estos archivos y "moderno" en el 36%. Ambas son palabras que un modelo satisface produciendo el centro de su distribución de entrenamiento, que es precisamente el resultado genérico que el archivo pretendía evitar.

La única distinción que separa un brief que cambia el resultado de uno que no lo hace: ¿puede una frase verificarse comparándola con una pantalla renderizada? Si no es así, es decoración.

Cada entrada de la columna derecha puede verificarse observando una pantalla o haciendo un grep del código. Cada entrada de la columna izquierda puede satisfacerse con casi cualquier cosa, lo que significa que no impone ninguna restricción.

Tres propiedades diferencian una prohibición que se cumple de una que se ignora.

La tercera fila es la que más se suele omitir. Una prohibición sin alternativa abre un hueco que el modelo rellena basándose en la misma distribución de entrenamiento de la que usted intentaba escapar. Cada "nunca X" necesita un "en su lugar, Y".

Si lo escribe a mano en lugar de generarlo, esta es una estructura de partida sólida. Es breve a propósito. Un brief que nadie puede retener en la memoria compite con la tarea real por la atención del modelo. Aproximadamente 400 líneas es un límite manejable; este esqueleto está muy por debajo.

# DESIGN.md

## Overview

A dense internal tool for operations staff who work in it for hours.
Quiet, information-first. Nothing here has to convince anyone of anything.

## Don'ts

- No gradients
- No drop shadows — elevation is a surface step plus a 1px border
- No font-weight above 600
- No colour value outside the tokens in globals.css
- No border-radius above 12px
- No decorative use of the state colours

## Colours

Defined as semantic roles in globals.css, light and dark.
Do not restate values here — read them from that file.

- `--primary` — primary buttons and active nav state ONLY.
  Never on text, borders, backgrounds or gradients.
- `--muted-foreground` — secondary and supporting text only.
- `--border` — structural edges and dividers.
- `--destructive` / `--success` / `--warning` — reserved for state.

## Typography

Family: Inter (variable). Weights 400 and 600 only.
Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48.
Tracking: -0.02em at 32px and above, 0 below, +0.02em on 12px caps.
Hierarchy comes from size and colour, never from weight above 600.

## Spacing & density

Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. No other values.
Controls: 8–12px padding. Table rows: 32px. Section gap: 32px.

## Elevation

A surface step plus a 1px `--border`. Never a box-shadow.

## Shapes

Controls 6px. Cards and panels 12px. Nothing above 12px.

## Composition

One primary action per section.
Related controls share a group; unrelated ones are separated by a full step.
Tables are never nested inside cards.

## Motifs

Section headings carry a 2px `--primary` rule on the left edge.
Numeric columns are always tabular-nums and right-aligned.
Empty states are a single line of `--muted-foreground` text, never an illustration.

## Agent rules

Read this file before writing or editing any UI.
Match the nearest existing component in this repo rather than inventing a
new pattern. If no similar component exists, say so before writing one.

Hay dos aspectos de ese archivo que merece la pena copiar aunque cambie todo lo demás. Las prohibiciones van en segundo lugar, antes de cualquier elemento que pudieran modificar, para que un modelo que lea de arriba abajo encuentre las restricciones antes que los permisos. Además, la sección de colores apunta a globals.css en lugar de repetir los valores: una vez que un hex existe en dos lugares, uno se actualizará y el otro no, y el modelo usará con confianza la copia obsoleta.

Un DESIGN.md es tan bueno como el sistema que lo respalda. A continuación se muestra el kit gratuito ambient-sage: los tokens, fuentes y tratamientos que describe su DESIGN.md, renderizados en vivo:

1. 1

   CLI: escriba el DESIGN.md + tokens en su repo

   La vía más rápida. Elija un slug de kit de la galería y aplíquelo; obtendrá un DESIGN.md commitado y un archivo de tokens correspondiente.

   Copy

   identityforge apply ambient-sage

2. 2

   MCP: deje que el agente lo obtenga

   Con el servidor MCP instalado, el agente llama a get_design_md(slug) para leer el brief completo y a apply_theme para escribirlo. Instálelo para su herramienta:

   Copy

   npx --yes identityforge@latest install --client claude-code

3. 3

   shadcn: instale los tokens que referencia el DESIGN.md

   Si solo desea los valores, el elemento del registro instala las variables CSS del kit directamente.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

Identity Forge genera el DESIGN.md y los tokens a partir del mismo kit, por lo que la prosa describe los valores de la hoja de estilos. Para saber en qué se diferencia esto de adaptar manualmente una entrada del catálogo de DESIGN.md, consulte Identity Forge vs getdesign.md.

Escribir el archivo y asumir que se ha aplicado correctamente es la razón por la cual los equipos descubren el problema tres semanas después. Cuatro comprobaciones, de la más sencilla a la más compleja.

1. 1

   Buscar valores de color literales con grep

   Si el agente sigue roles semánticos, no debería haber ningún valor hex fuera del archivo de tokens. Esta es la señal más rápida posible.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Use grep para buscar los pesos prohibidos

   El peso es donde la jerarquía revierte silenciosamente al valor por defecto, y es la primera señal de que una restricción no se está aplicando.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Solicite la misma pantalla dos veces, en sesiones separadas

   La consistencia entre sesiones es la prueba real. Si dos ejecuciones difieren significativamente en espaciado, radio o jerarquía, la diferencia indica exactamente qué sección del brief falta.

4. 4

   Construya primero una pantalla en modo oscuro

   Si el modo oscuro fue derivado en lugar de definido, aquí es donde aflora: sombras inertes, grises medios turbios, un color de acento estridente. Es mucho más barato detectarlo en la pantalla uno que en la pantalla veinte.

Las dos primeras deben integrarse en CI. Una comprobación que rechace un pull request que contenga un valor hex bruto aporta más a la consistencia a largo plazo que cualquier cantidad de prosa, que es la misma conclusión a la que Salesforce llegó con el linter de SLDS.