Taste hacking

guía en español

DESIGN.md

El archivo que le explica tu sistema de diseño a un agente de código: qué es, cómo se escribe y cómo lo resuelven tres marcas.

Qué es

Un agente que construye interfaces sin contexto elige colores, tipografías y espaciados genéricos. DESIGN.md resuelve eso con un archivo markdown que vive en el repositorio y describe la identidad visual del producto, para que el agente la lea antes de tocar una pantalla.

El formato nació en Stitch, la herramienta de diseño de Google Labs. El 21 de abril de 2026 Google abrió el borrador de la especificación con licencia Apache 2.0, en estado alpha. Se basa en el formato de tokens de la W3C (DTCG), así que convive con los tokens que ya usa tu equipo.

Anatomía

La especificación define dos capas. Los tokens, en YAML al inicio del archivo, son los valores normativos: colores, tipografía, radios, espaciado y componentes. La prosa, en secciones de markdown, explica para qué existe cada valor y cuándo no usarlo.

DESIGN.md mínimo, adaptado de la especificaciónmarkdown
---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  md: 8px
spacing:
  md: 16px
---

## Colors

- **Tertiary (#B8422E):** el único color de interacción.
- **Neutral (#F7F5F2):** fondo cálido, más suave que el blanco puro.

La especificación trae una CLI. lint revisa la estructura, que cada referencia a un token exista y el contraste WCAG de cada par de colores. diff compara dos versiones y falla si la nueva tiene más problemas, así que sirve en CI para que un cambio de tokens no rompa la accesibilidad.

Validar y compararshell
  1. npx @google/design.md lint DESIGN.md
  2. npx @google/design.md diff DESIGN.md DESIGN-v2.md

Cuatro formas de escribirlo

En la práctica, cada equipo lo resuelve distinto. La diferencia que más importa es dónde vive la verdad de los tokens y quién escribe el archivo.

FormaEjemploDónde viven los tokensFuerte enCuidado con
Formato de la especificaciónEl ejemplo de GoogleEn el YAML del archivoSe valida con lint y diffPoco criterio si la prosa es corta
Puente a un registryCrafterEn un theme.json instalableLos tokens se instalan, no se copianDepende de su stack de componentes
Brief de marcaVercelEn una API de CSS publicadaProceso, prioridades y criterioLargo y pensado para un tipo de página
Extraído por tercerosSupabaseInferidos del CSS del sitioRápido para cualquier marcaNo es oficial y envejece

Caso Crafter: un DESIGN.md que instala su sistema

crafter.run/design.md es el de Crafter Station, el estudio detrás de Taste hacking, y conecta la prosa con su librería Crafter UI. Pesa unos 10 KB y no repite los tokens en YAML: manda al agente a instalar theme.json desde el registry y declara que, en una librería derivada, ese archivo manda sobre la paleta base.

Captura de crafter.run
crafter.run · La landing de Crafter Station, con el lenguaje visual que su DESIGN.md describe para Crafter UI.

Lo más útil son las reglas con números, que un agente puede cumplir o violar sin ambigüedad:

  • Ningún texto por debajo de 14 px, ni siquiera en SVG o canvas: si no entra, se reacomoda el layout.
  • Nunca blanco ni negro puros para fondo o texto.
  • El amarillo de marca es superficie o detalle, nunca texto chico sobre papel; para texto hay un color de acento accesible.
  • Espaciado desde un ritmo de 4 px: 4 a 8 dentro de un grupo, 12 a 16 entre campos, 24 a 32 entre secciones.
  • Pares de “bien” y “evitar” en cada sección, y una lista final para revisar la pantalla terminada.

Para los componentes no describe cada uno: apunta a llms.txt y a /r/<componente>.json, así que el agente descubre e instala solo lo que falta.

Caso Vercel: un brief con criterio

vercel.com/design.md no sigue el YAML de la especificación. Empieza con un encabezado de nombre y descripción, como una skill de agente, y está pensado para un trabajo concreto: los sitios de reportes, propuestas y calculadoras que Vercel arma para sus clientes. Son unas 380 líneas, cerca de 40 KB.

Captura de vercel.com
vercel.com · La landing de Vercel. Su DESIGN.md no describe esta página, sino los reportes que Vercel arma para sus clientes con Geist.
  • Un orden de prioridades para cuando los requisitos chocan: primero los datos y las restricciones, después el proyecto del cliente, recién después el estilo.
  • Cuatro pasadas de trabajo: entender la tarea del lector, elegir la composición, aplicar el sistema visual y revisar en privado.
  • Una lista de reflejos de diseño generado que prohíbe, como gradientes decorativos, tarjetas dentro de tarjetas o un hero centrado seguido de una grilla de tarjetas.
  • Una API de CSS publicada, con clases como vbg-stat o vbg-chart, y la orden de no inventar sinónimos.

Es el ejemplo más claro de que un DESIGN.md puede transmitir criterio, no solo valores.

Caso Supabase: lo que circula sin ser oficial

Supabase no publica un DESIGN.md: supabase.com/design.md responde 404 (lo comprobamos el 21 de noviembre de 2026). Aun así, aparece en todas las colecciones. awesome-design-md, de VoltAgent, con más de 128 mil estrellas en GitHub, incluye uno, y DesignMD Directory publica otro extraído del sitio a partir de 2,860 elementos.

Captura de supabase.com
supabase.com · La landing de Supabase, la fuente de la que las colecciones extraen sus tokens.

Sirven para estudiar una marca en minutos, pero tienen límites claros. Infieren el rol de cada color por cuántas veces aparece en el CSS, no por la intención del equipo. Quedan viejos en cuanto el sitio cambia. Y no dan permiso para usar la identidad de otra marca en un producto propio.

Cómo escribir el tuyo

  1. Empieza por la tarea: qué tiene que entender o hacer quien usa la interfaz, antes que los colores.
  2. Nombra los tokens por su rol (fondo, texto secundario, acción principal), no por su valor.
  3. Escribe reglas con números: pisos de tamaño, rangos de espaciado, cuándo sí y cuándo no.
  4. Acompaña cada regla con un ejemplo de “bien” y uno de “evitar”.
  5. Cubre los estados (cargando, vacío, error, deshabilitado), la accesibilidad y los temas claro y oscuro.
  6. Deja la verdad en un solo lugar: el YAML del archivo, un theme.json o tu CSS, pero no tres copias.
  7. Valídalo con lint en CI y revisa el resultado en la pantalla, no solo en el build.

Conectarlo con Claude Code

Claude Code lee CLAUDE.md al inicio de cada sesión, y ese archivo puede importar otros con @ruta. Con una línea, tu DESIGN.md entra en todas las sesiones:

CLAUDE.mdmarkdown
# CLAUDE.md

Sigue el sistema de diseño de @DESIGN.md en todo cambio de interfaz.

Si todavía no lo usas, la guía de Claude Code para diseño cubre la instalación y la primera sesión.

Preguntas frecuentes

¿Qué es DESIGN.md?

Es un archivo markdown que describe la identidad visual de un producto para que un agente de código la respete. Combina tokens con valores exactos y prosa que explica cuándo y por qué usarlos.

¿DESIGN.md es un estándar?

Es un borrador abierto. Google Labs publicó la especificación en abril de 2026 con licencia Apache 2.0 y la marca como alpha. Muchas empresas publican su propio DESIGN.md sin seguir el formato al pie de la letra.

¿Dónde va el archivo?

En la raíz del repositorio, para que el agente lo lea junto al código. Algunas marcas también lo sirven en su dominio, como crafter.run/design.md o vercel.com/design.md, para que cualquier agente lo descargue.

¿Sirve con Claude Code, Cursor o Codex?

Sí. Es texto plano: cualquier agente que lea archivos del proyecto puede usarlo. En Claude Code se importa desde CLAUDE.md con @DESIGN.md para que cargue en cada sesión.

¿Puedo usar el DESIGN.md de otra marca?

Para estudiar cómo está hecho, sí. Para lanzar un producto con la identidad de otra marca, no: los colores se pueden inspirar, pero logos, fuentes con licencia y la marca en sí no son tuyos.

Sigue leyendo

O vuelve a la guía de design engineering y al rol de agentic design systems engineer.

Un DESIGN.md dice cómo se ve; falta pedir lo que admiras

Taste hacking es un curso en vivo, en español, para construir con un agente las interfaces, animaciones y videos que admiras.

Anótate a la edición 02