DESIGN.md: dale a Codex tu sistema de diseño.
DESIGN.md es un archivo de texto que describe tu sistema de diseño a los agentes de IA: colores exactos, tipografía, espaciado y componentes, junto con el razonamiento que hay detrás. Pon uno en tu repositorio y Codex diseñará cada pantalla nueva con el mismo lenguaje visual.
Actualizado el 2 de noviembre de 2026 · 8 min de lectura
¿Qué es DESIGN.md?
DESIGN.md es un formato abierto de Google Labs para describir una identidad visual a los agentes de programación. Nació en Google Stitch, se publica con licencia Apache 2.0 y la especificación sigue marcada como alpha, así que habrá cambios.
Un archivo DESIGN.md tiene dos capas:
- Tokens de diseño en YAML. Valores exactos y legibles por máquina: colores, tipografía, radios de esquina, espaciado y estilos de componentes. Los tokens son los valores normativos.
- Texto en Markdown. El razonamiento: qué sensación debe transmitir el producto, cuándo usar cada color y qué evitar. El texto le dice al agente cómo aplicar los tokens.
Sin un archivo así, un agente elige un tono de azul y un estilo de botón nuevos cada vez que le pides una pantalla. Con él, la pantalla número cincuenta encaja con la primera.
Qué incluye un DESIGN.md
Los tokens pueden ir en un front matter YAML al principio del archivo o en bloques yaml dentro de cada sección. El esquema tiene cinco grupos de tokens:
| Grupo | Qué contiene | Ejemplo |
|---|---|---|
colors | Cualquier color CSS; como mínimo se exige primary | primary: "#1F3D2B" |
typography | Familia, tamaño, peso e interlineado de la fuente | body-md: { fontSize: 16px, ... } |
rounded | Escala de radios de esquina | md: 12px |
spacing | Escala de espaciado | md: 16px |
components | Estilos de componentes, con referencias a tokens | backgroundColor: "{colors.primary}" |
El texto usa secciones ##. Se puede omitir cualquier sección, pero las que incluyas deben aparecer en este orden: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components y Do’s and Don’ts.
Un ejemplo completo
Este DESIGN.md describe la app de lectura que usamos en nuestra página de prompts para apps móviles. Guárdalo como DESIGN.md en la raíz de tu repositorio.
---
version: alpha
name: Pagely
description: Calm, bookish UI for a reading-habit app.
colors:
primary: '#1F3D2B'
on-primary: '#FAF6EE'
secondary: '#E8735A'
tertiary: '#F2C14E'
neutral: '#FAF6EE'
surface: '#FFFFFF'
on-surface: '#1F2A22'
typography:
headline-lg:
fontFamily: Georgia
fontSize: 32px
fontWeight: 400
lineHeight: 1.15
body-md:
fontFamily: system-ui
fontSize: 16px
fontWeight: 400
lineHeight: 1.5
label-caps:
fontFamily: system-ui
fontSize: 13px
fontWeight: 500
letterSpacing: 0.12em
rounded:
md: 16px
lg: 22px
full: 9999px
spacing:
sm: 8px
md: 16px
lg: 24px
components:
button-primary:
backgroundColor: '{colors.primary}'
textColor: '{colors.on-primary}'
rounded: '{rounded.md}'
padding: 18px
---
## Overview
Quiet, warm, and bookish, like a café with good light. Screens feel spacious and
unhurried; one clear next step per screen.
## Colors
- **Primary (#1F3D2B):** Deep forest green for primary actions and the streak card.
- **Secondary (#E8735A):** Coral for progress and small highlights only.
- **Tertiary (#F2C14E):** Warm yellow for streak and goal indicators.
- **Neutral (#FAF6EE):** Cream background for every screen, never pure white.
## Typography
Georgia for headlines gives a literary voice. System UI for everything else keeps
body text crisp. Labels are uppercase with wide letter spacing.
## Layout
24px side margins on phones. Spacing follows an 8px scale. Primary actions sit in
the lower half of the screen, within thumb reach.
## Elevation & Depth
No heavy shadows. Depth comes from white cards with a 1px warm border on the cream
background.
## Shapes
Soft and rounded: 16px for buttons and inputs, 22px for cards.
## Components
Primary buttons are full-width, deep green, 18px padding. One primary button per screen.
## Do's and Don'ts
- Do keep text contrast at WCAG AA or better.
- Do use coral sparingly: progress bars and one highlight per screen.
- Don't use pure black or pure white.
- Don't put more than two type sizes in a single card.
Cómo hacer que Codex lo siga
Codex lee AGENTS.md automáticamente: empieza en la raíz del repositorio y baja hasta la carpeta en la que estás trabajando. No busca DESIGN.md por su cuenta, así que enlázalo desde AGENTS.md:
## Design
- Before any UI work, read DESIGN.md and use only its tokens.
- If a screen needs a value that DESIGN.md doesn't define, ask before inventing one.
- After editing DESIGN.md, run `npx @google/design.md lint DESIGN.md` and fix any errors.
Después pide pantallas como siempre. Mencionar el archivo en el prompt lo deja claro:
Siguiendo DESIGN.md, diseña la pantalla de [ajustes] como un único archivo HTML autocontenido a 390×844. Usa solo colores, tamaños de texto, radios y espaciados de DESIGN.md, y avísame si necesitaste algo que no esté definido ahí.
Escribe un DESIGN.md con Codex
Rara vez hace falta escribir el archivo a mano. Si ya tienes un producto, pídele a Codex que lo extraiga de tu código:
Lee nuestra configuración de Tailwind, el CSS global y los cinco componentes más usados, y escribe un DESIGN.md en la raíz del repositorio. Ejecuta primero `npx @google/design.md spec` y sigue ese formato: tokens en un front matter YAML y después las secciones Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components y Do's and Don'ts. Usa solo valores que existan en el código. Termina ejecutando `npx @google/design.md lint DESIGN.md` y corrigiendo los errores.
Para un producto nuevo, parte de una dirección que te guste, como un mockup que aprobaste en un lienzo o una captura de referencia:
Este es el diseño de pantalla que aprobamos [adjunta una captura o indica el archivo HTML]. Escribe un DESIGN.md que recoja sus colores, tipografía, espaciado, radios de esquina y estilo de botones, con un Overview breve sobre la sensación que debe transmitir y cinco Do's and Don'ts. Sigue el formato DESIGN.md de `npx @google/design.md spec`.
La herramienta de línea de comandos @google/design.md también comprueba las relaciones de contraste y las referencias rotas entre tokens con lint, compara dos versiones con diff y convierte tus tokens en un tema de Tailwind o en design tokens del W3C con export.
DESIGN.md vs SKILL.md vs AGENTS.md
Estos tres archivos suelen convivir en el mismo repositorio y cumplen funciones distintas:
| Archivo | Qué le dice al agente | Ejemplo |
|---|---|---|
DESIGN.md | Qué aspecto debe tener el producto | Colores, tipografía, espaciado, estilos de componentes |
SKILL.md | Cómo hacer un tipo de tarea; se carga cuando hace falta | Una checklist o un flujo de revisión de diseño |
AGENTS.md | Instrucciones permanentes del proyecto; se leen siempre | Comandos de compilación, convenciones, “lee DESIGN.md” |
Funcionan bien juntos. Una skill de diseño puede decir “lee DESIGN.md antes de diseñar nada”, y AGENTS.md se asegura de que ocurra incluso sin la skill. Para saber más sobre las skills, consulta plugins vs skills en Codex.
Dónde encontrar ejemplos
La colección de código abierto awesome-design-md reúne archivos DESIGN.md que describen los sistemas de diseño de sitios web conocidos, cada uno con una página de vista previa. Son útiles para aprender cómo otros describen el color, la tipografía y los componentes. Úsalos como referencia de estructura, no como forma de copiar la marca de otra empresa.
Preguntas frecuentes
¿DESIGN.md es un estándar oficial?
Es una especificación abierta de Google Labs, que usa Google Stitch y que está publicada en GitHub. La especificación sigue en alpha, y su propia documentación advierte que el formato cambiará.
¿Codex es compatible con DESIGN.md?
Codex puede leer y seguir cualquier archivo de tu repositorio. No hay ningún ajuste especial: menciona DESIGN.md desde AGENTS.md o desde tu prompt, como se muestra arriba.
¿DESIGN.md sustituye a Figma o a un sistema de diseño?
No. Es un resumen en texto de tu sistema de diseño que los agentes pueden leer. Los equipos que tienen su fuente de verdad en Figma o en el código pueden generar DESIGN.md a partir de ella y actualizarlo cuando el sistema cambie.