Documentación

¿Qué es DESIGN.md?

DESIGN.md es un archivo de texto plano que describe un sistema de diseño para agentes de IA. El front matter en YAML de la parte superior contiene los tokens de diseño exactos: colores, tipografía, espaciado, esquinas redondeadas y componentes. El cuerpo en Markdown de debajo explica cómo y por qué aplicarlos. Tanto personas como agentes pueden leerlo, editarlo y hacerlo cumplir.

README.md explica qué es un proyecto. AGENTS.md les dice a los agentes de programación cómo construirlo. DESIGN.md les dice qué aspecto y qué sensación debe transmitir, para que las pantallas que genera un agente compartan una misma paleta, escala tipográfica y lenguaje de componentes en lugar de ir cada una por su lado.

De dónde viene DESIGN.md

Google presentó DESIGN.md con Google Stitch, su herramienta de diseño con IA, como el equivalente de AGENTS.md para el diseño. Google Labs publica el formato como especificación abierta en el repositorio google-labs-code/design.md bajo la licencia Apache 2.0. La especificación DESIGN.md está marcada como alfa, así que espera que el formato cambie a medida que madure.

El mismo repositorio incluye un paquete npm, @google/design.md, con un comando lint que comprueba la estructura, las referencias a tokens rotas y el contraste WCAG, y un comando diff que compara dos versiones de un archivo token a token.

Anatomía de un archivo DESIGN.md

Todo archivo DESIGN.md tiene dos capas. El front matter en YAML contiene tokens de diseño legibles por máquina, como valores de color exactos, propiedades de fuentes, escalas de espaciado y referencias a tokens de componentes. El cuerpo en Markdown aporta la lógica del diseño legible para personas.

La especificación trata los tokens como los valores normativos y el texto como el contexto para aplicarlos. Los tokens dan a los agentes valores precisos. El texto les dice por qué existen esos valores y cómo usarlos de forma coherente en todas las pantallas.

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

Las ocho secciones canónicas

El cuerpo en Markdown usa títulos ##. Las secciones se pueden omitir cuando no aplican, pero cuando están deben seguir este orden. Un título que aparece dos veces hace que el archivo no sea válido; las secciones desconocidas se conservan.

Overview (también Brand & Style). El aspecto y la sensación en unas pocas frases: ambiente, densidad, personalidad.
Colors. Cada token de color y el papel que cumple, como las acciones principales o las superficies de la página.
Typography. Las familias tipográficas y la escala tipográfica, desde los titulares display hasta las etiquetas pequeñas.
Layout (también Layout & Spacing). La escala de espaciado, la cuadrícula, los anchos de contenido y los márgenes.
Elevation & Depth (también Elevation). Cómo se separan las superficies: sombras, bordes, tintes.
Shapes. Los radios de las esquinas y otras reglas de forma.
Components. Botones, campos, tarjetas y otros átomos, con sus tokens y estados.
Do's and Don'ts. Las reglas que un agente no debe romper.

Un cuerpo en Markdown compacto con cada sección canónica en orden. Adapta el contenido a tu producto y mantén los títulos y el orden.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Tokens de diseño y esquema

DESIGN.md incluye los tokens de diseño como front matter en YAML al principio del archivo. El bloque de front matter empieza con una línea que contiene exactamente --- y termina con el mismo delimitador.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Los nombres de escala habituales son xs, sm, md, lg, xl y full, pero cualquier clave descriptiva es válida. Los tokens de espaciado van en el YAML bajo spacing: y se describen en la sección Layout del cuerpo en Markdown.

Tipos de token

Color: Cualquier cadena de color CSS válida. El hex en forma #RRGGBB es el valor predeterminado recomendado, por ejemplo "#1A1C1E".
Dimensión: Un número más una unidad px, em o rem. Ejemplos:48px,-0.02em.
Referencia a token: Va entre llaves y apunta a un valor del árbol YAML. Ejemplo:{colors.primary}.
Tipografía: Un objeto compuesto con propiedades de fuente como familia, tamaño, peso, interlineado y espaciado entre letras. Consulta Propiedades tipográficas.

Propiedades tipográficas

fontFamily: El nombre de la familia tipográfica.
fontSize: El tamaño de fuente como dimensión.
fontWeight: Peso numérico, como 400 o 700.
lineHeight: Una dimensión o un multiplicador sin unidad. Se recomiendan valores sin unidad.
letterSpacing: Ajuste del espaciado entre letras como dimensión.
fontFeature: Configura font-feature-settings.
fontVariation: Configura font-variation-settings.

Referencias a tokens

Una referencia a token va entre llaves y contiene la ruta a otro valor del árbol YAML. En la mayoría de los grupos de tokens, la referencia debe apuntar a un valor primitivo y no a un grupo. Dentro de la sección de componentes se permiten referencias a valores compuestos, como los niveles tipográficos.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Componentes

La sección de componentes recoge pautas de estilo para átomos de componentes como botones, chips, listas, campos, casillas de verificación, botones de opción y tooltips. Los sistemas de diseño pueden definir componentes adicionales que importen en su dominio de producto.

Las variantes para los estados hover, activo o pulsado se definen como entradas de componente separadas con nombres de clave relacionados, como button-primary-hover.

backgroundColor: Color
textColor: Color
typography: Tipografía
rounded: Dimensión
padding: Dimensión
size: Dimensión
height: Dimensión
width: Dimensión

Nombres de token recomendados

Estos nombres son orientativos, no obligatorios. Ofrecen valores predeterminados útiles para mantener la coherencia entre sistemas.

Colores: primary, secondary, tertiary, neutral, surface, on-surface, error

Tipografía: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Redondeado: none, sm, md, lg, xl, full

Cómo usan DESIGN.md los agentes de IA

Pon DESIGN.md en la raíz de tu repositorio, junto a README.md y AGENTS.md. Cualquier agente con acceso a archivos puede leerlo, pero la mayoría no lo carga por su cuenta. Haz referencia a él desde las instrucciones que tu agente ya lee, o nómbralo en el prompt cuando pidas trabajo de interfaz. Basta con una indicación breve:

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code: Lee los archivos de tu repositorio y carga CLAUDE.md al empezar. Añade ahí una línea que apunte a DESIGN.md, o menciona el archivo en tu prompt.
Cursor: Añade DESIGN.md al contexto del chat, o haz referencia a él desde una regla del proyecto para que se aplique a cada petición de interfaz.
GitHub Copilot: Haz referencia a DESIGN.md desde el archivo de instrucciones de Copilot de tu repositorio, o adjúntalo en el chat cuando pidas trabajo de interfaz.
Google Stitch: Donde nació el formato. Stitch usa un DESIGN.md para que las pantallas generadas compartan una misma paleta, escala tipográfica y lenguaje de componentes.

Después, el agente toma los valores exactos de los tokens (el hex de un botón primario, el tamaño de una etiqueta body-md) y usa el texto para decidir dónde van.

DESIGN.md vs AGENTS.md vs README.md

Los tres archivos conviven y responden a preguntas distintas. DESIGN.md no sustituye a AGENTS.md; los dos funcionan juntos.

Archivo	Escrito para	Responde a
`README.md`	Las personas que usan el proyecto o contribuyen a él	¿Qué es esto y cómo lo ejecuto?
`AGENTS.md`	Agentes de programación	¿Cómo construyo, pruebo y cambio este código?
`DESIGN.md`	Agentes de programación y de diseño	¿Qué aspecto y qué sensación debe transmitir la interfaz?

Ejemplos reales de DESIGN.md

La forma más rápida de entender el formato es leer algunos archivos reales. Cada una de estas páginas de la galería muestra un DESIGN.md extraído del sitio web público de la marca, con su paleta y su muestra tipográfica. No son guías de marca oficiales.

Ver todos los ejemplos de DESIGN.md

Cómo conseguir un DESIGN.md

Escríbelo a mano. Parte de la especificación y de los ejemplos de arriba y luego comprueba el archivo con el validador de DESIGN.md gratuito o con el comando lint de Google.
Parte de un ejemplo. Copia un archivo de la galería y edita los tokens y el texto para que encajen con tu producto.
Genéralo a partir de un sitio web en vivo. Pega una URL pública en Design Extractor. Renderiza el sitio en un navegador y devuelve un DESIGN.md con sus colores, tipografía, espaciado y componentes que sigue la especificación anterior. La página del generador de DESIGN.md explica lo que obtienes. La misma extracción funciona desde la extensión de Chrome y desde tu agente a través del servidor MCP.

Preguntas frecuentes

Preguntas sobre DESIGN.md

Respuestas breves sobre el formato DESIGN.md, de dónde viene y cómo usarlo con agentes de IA.

Un DESIGN.md es un archivo de texto plano que describe un sistema de diseño para agentes de IA. El front matter en YAML de la parte superior contiene los tokens exactos (colores, tipografía, espaciado, esquinas redondeadas y componentes), y el cuerpo en Markdown de debajo explica cómo y por qué aplicarlos. Los agentes leen los tokens para obtener los valores y el texto para entender la intención.

Google presentó DESIGN.md con Stitch, su herramienta de diseño con IA. Google Labs publica la especificación en GitHub (google-labs-code/design.md) bajo la licencia Apache 2.0. El formato está marcado como alfa, así que espera cambios a medida que madure.

AGENTS.md les dice a los agentes de programación cómo construir un proyecto y trabajar en él: comandos, convenciones, tests. DESIGN.md les dice qué aspecto y qué sensación debe transmitir el producto: colores, tipografía, espaciado, formas y componentes. README.md es para las personas que usan el proyecto o contribuyen a él. Muchos repositorios tienen los tres juntos.

Ponlo en la raíz del repositorio, junto a README.md y AGENTS.md, para que los agentes con acceso a archivos puedan encontrarlo. Después haz referencia a él desde las instrucciones que tu agente ya carga, como AGENTS.md, CLAUDE.md, una regla de Cursor o tus instrucciones de Copilot, o menciónalo en el prompt cuando pidas trabajo de interfaz.

No. La especificación te permite omitir las secciones que no aplican, pero las que mantengas deben seguir el orden canónico: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Un título de sección no puede aparecer dos veces, y las secciones desconocidas se conservan en lugar de rechazarse.

El paquete npm de Google @google/design.md tiene un comando lint que comprueba la estructura, las referencias a tokens rotas y el contraste WCAG. Design Extractor también tiene un validador de DESIGN.md gratuito que comprueba la estructura y los tokens en tu navegador y muestra una vista previa del archivo, sin subirlo.

Escríbelo a mano a partir de la especificación, copia uno de una galería de ejemplos reales como punto de partida o genera uno a partir del sitio en vivo. Design Extractor toma una URL pública, renderiza el sitio en un navegador y devuelve un DESIGN.md con sus colores, tipografía, espaciado y componentes, listo para poner en tu repositorio.

¿Quieres uno de un sitio que te gusta?

Pega una URL pública y obtén su DESIGN.md.

Extraer un sitio

Tipos de token

Propiedades tipográficas

Referencias a tokens

Componentes

Nombres de token recomendados

Preguntas sobre DESIGN.md

¿Qué es un archivo DESIGN.md?

¿Quién creó el formato DESIGN.md?

¿Qué diferencia hay entre DESIGN.md y AGENTS.md?

¿Dónde pongo DESIGN.md en mi proyecto?

¿Necesito las ocho secciones?

¿Cómo compruebo que un DESIGN.md es válido?

¿Cómo consigo un DESIGN.md de un sitio web existente?