DESIGN.md: Una especificación de formato para describir la identidad visual a agentes de codificación

Google Labs lanzó DESIGN.md, una especificación de formato para describir una identidad visual a agentes de codificación. El archivo combina tokens de diseño legibles por máquina (front matter YAML) con una justificación de diseño legible por humanos (prosa Markdown). Los tokens proporcionan valores exactos a los agentes; la prosa explica por qué existen esos valores y cómo aplicarlos.

Resumen del formato

Un archivo DESIGN.md tiene dos capas delimitadas por los separadores --- en la parte superior: front matter YAML para los tokens y un cuerpo Markdown con secciones ##. Ejemplo de extracto:

---
name: "Heritage"
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: "Public Sans"
    fontSize: "3rem"
  body-md:
    fontFamily: "Public Sans"
    fontSize: "1rem"
  label-caps:
    fontFamily: "Space Grotesk"
    fontSize: "0.75rem"
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"

Los tokens son los valores normativos. La prosa proporciona contexto para la aplicación.

Características principales

• Tipos de tokens: Colores (hex sRGB), objetos de tipografía (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation), dimensiones (número+unidad), referencias a tokens ({path.to.token}).
• Componentes: Asigna un nombre a propiedades de subtokens, por ejemplo, components.button-primary.backgroundColor: "{colors.tertiary}".
• Orden de secciones (opcional pero aplicado): Overview, Colors, Typography, Layout & Spacing, Elevation & Depth, Shapes, Components, Do's and Don'ts.

Herramientas CLI

Valida un DESIGN.md con el linter:

npx @google/design.md lint DESIGN.md
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) sobre backgroundColor (#1A1C1E) tiene una relación de contraste de 15.42:1 — cumple con WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Detecta regresiones entre versiones:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
{
  "tokens": {
    "colors": {
      "added": ["accent"],
      "removed": [],
      "modified": ["tertiary"]
    },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Caso de uso

Un agente que lea el ejemplo "Heritage" producirá una interfaz con titulares en tinta profunda en Public Sans, un fondo de piedra caliza cálida (#F7F5F2) y botones de llamada a la acción en Boston Clay (#B8422E) — todo desde un solo archivo.