DESIGN.md : Un format de spécification pour décrire l'identité visuelle aux agents de codage

Google Labs a publié DESIGN.md, une spécification de format pour décrire une identité visuelle aux agents de codage. Le fichier combine des jetons de design lisibles par machine (YAML front matter) avec une justification de design lisible par l'homme (prose Markdown). Les jetons donnent aux agents des valeurs exactes ; la prose explique pourquoi ces valeurs existent et comment les appliquer.

Aperçu du format

Un fichier DESIGN.md comporte deux couches délimitées par des balises --- en haut : YAML front matter pour les jetons et un corps Markdown avec des sections ##. Exemple d'extrait :

---
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"

Les jetons sont les valeurs normatives. La prose fournit le contexte pour l'application.

Fonctionnalités clés

• Types de jetons : Couleurs (hex sRGB), objets Typographie (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation), Dimensions (nombre+unité), Références de jetons ({path.to.token}).
• Composants : Mapper un nom à des propriétés de sous-jetons, par exemple components.button-primary.backgroundColor: "{colors.tertiary}".
• Ordre des sections (optionnel mais appliqué) : Aperçu, Couleurs, Typographie, Disposition & Espacement, Élévation & Profondeur, Formes, Composants, À faire et à ne pas faire.

Outils CLI

Validez un DESIGN.md avec le linter :

npx @google/design.md lint DESIGN.md
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Détectez les régressions entre versions :

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

Cas d'utilisation

Un agent lisant l'exemple Heritage produira une interface utilisateur avec des titres en encre profonde en Public Sans, un fond en calcaire chaud (#F7F5F2), et des boutons d'appel à l'action en Boston Clay (#B8422E) — le tout à partir d'un seul fichier.