DESIGN.md : décrire une identité visuelle aux agents de codage
Une spécification de format pour décrire une identité visuelle aux agents de codage. DESIGN.md donne aux agents une compréhension persistante et structurée d'un système de conception.
En bref
- De quoi s’agit-il ?
- Une spécification de Google Labs qui combine tokens YAML et justification Markdown, avec une CLI de lint, de diff et d'export vers Tailwind ou les tokens W3C.
- À qui s’adresse-t-il ?
- DESIGN.md s'adresse aux équipes qui veulent qu'un agent de codage respecte une identité visuelle sans la redécrire à chaque invite : tokens normatifs en front matter YAML, justification en prose, ordre de sections imposé. Le format est en alpha, la CLI aussi, changements attendus selon le README.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement TypeScript, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Un fichier qui explique un design system aux agents
DESIGN.md est une spécification de format dont le but tient en une phrase : donner aux agents de codage une compréhension persistante et structurée d'un système de design. Le projet vient de Google Labs, est écrit en TypeScript, et affiche 27 576 étoiles pour 41 issues ouvertes, un démarrage remarqué. L'idée règle un problème concret : les agents produisent des interfaces, mais rien ne leur dit durablement quelles couleurs, typographies et espacements employer. Le README illustre le propos avec un exemple Heritage, encre profonde, Public Sans pour les titres, fond crayeux, dont un agent qui lit le fichier est censé reproduire les partis pris. La spécification complète vit dans docs/spec.md, avec une page dédiée sur stitch.withgoogle.com.
Deux couches : front matter YAML et prose
Le fichier superpose deux couches aux rôles distincts. Le front matter YAML, délimité par des lignes de trois tirets, porte les tokens normatifs : couleurs, typographie, rayons, espacements, composants. Le corps Markdown porte la justification, organisée en sections qui expliquent pourquoi ces valeurs existent et comment les appliquer. Le schéma de tokens couvre version, actuellement alpha, nom, description, liste omitted et les familles colors, typography, rounded, spacing, components. Les types sont précis : couleurs CSS quelconques, du hex à oklch, dimensions en px, em ou rem, références de tokens entre accolades comme {colors.primary}, et objets typographiques avec fontFamily, fontSize, fontWeight, lineHeight ou letterSpacing. Les composants mappent des propriétés nommées, backgroundColor, textColor, padding, size, height, width, les variantes hover ou active étant des entrées voisines.
Ordre de sections imposé et tolérance aux inconnus
La spécification tranche un compromis entre rigueur et souplesse. Les sections à titres ## peuvent être omises, mais celles qui existent doivent suivre un ordre fixe : Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts, avec des alias admis pour certaines. Face au contenu inconnu, le comportement des consommateurs est spécifié : une section inconnue se conserve sans erreur, un nom de token inconnu est accepté si la valeur est valide, une propriété de composant inconnue est acceptée avec avertissement. Un titre de section dupliqué, en revanche, rejette le fichier. Ce compromis rend le format extensible sans devenir ambigu, chaque agent sachant quoi faire devant l'inattendu.
lint : onze règles, contraste WCAG et code de sortie
La CLI s'installe par npm install @google/design.md ou s'exécute via npx. La commande lint applique onze règles à sévérité fixe : broken-ref en erreur pour une référence de token non résolue, contrast-ratio en avertissement quand une paire arrière-plan et texte passe sous le seuil WCAG AA de 4,5:1, missing-primary quand des couleurs existent sans couleur primaire, section-order pour l'ordre des sections, et des règles d'information comme token-summary ou missing-sections. La sortie est du JSON structuré que des agents peuvent consommer, et le code de sortie vaut 1 en cas d'erreurs, ce qui permet d'accrocher le lint à une CI. Toutes les commandes acceptent un chemin de fichier ou un tiret pour stdin.
diff pour détecter les régressions de design
La commande diff compare deux versions d'un même système de design et rapporte, famille par famille, les tokens ajoutés, supprimés ou modifiés : couleurs, typographie, rayons, espacements et composants. Le résultat inclut aussi le delta des findings de lint avant et après, et un booléen de régression qui synthétise l'ensemble. Ce mode répond à un besoin précis des équipes qui itèrent sur une identité visuelle : savoir si la v2 dégrade ce que la v1 garantissait, par exemple un ratio de contraste passé sous WCAG AA ou une couleur primaire supprimée. Entre les releases 0.2.0, 0.3.0 et 0.4.0, publiées entre mai et juillet 2026, ces outils ont constitué le cœur du projet.
export vers Tailwind et tokens W3C
Au-delà du lint, la commande export convertit les tokens vers d'autres écosystèmes : configuration JSON de Tailwind v3, CSS Tailwind v4 avec blocs @theme, ou tokens.json au format DTCG du W3C, dont les tokens DESIGN.md s'inspirent. Le linter est aussi utilisable comme bibliothèque TypeScript : importer lint depuis @google/design.md/linter, l'appeler sur une chaîne Markdown, et recevoir findings, summary et un DesignSystemState analysé. Cette double exposition, CLI et bibliothèque, permet aussi bien d'accrocher le format à une chaîne de build que de l'intégrer dans un outil interne. La commande spec complète l'ensemble en affichant la spécification du format depuis le terminal.
Alpha assumé, pièges Windows et registre npm
Le statut est affiché clairement : le format est en alpha, la spécification, le schéma et la CLI sont en développement actif et des changements sont attendus. Le README documente deux pièges concrets. Sous Windows, le suffixe .md du binaire entre en conflit avec l'association de fichiers Markdown lors de la résolution de commande ; l'alias sans point, designmd, invoqué par npx -p @google/design.md designmd, contourne le problème partout. L'erreur ENOVERSIONS signale presque toujours un registre mal configuré, registre privé dans .npmrc ou miroir d'entreprise non synchronisé, à vérifier avec npm config get registry. Le projet est sous licence Apache 2.0, et le README précise qu'il n'est pas éligible au programme de récompenses de vulnérabilités de Google.
Conclusion éditoriale
DESIGN.md s'adresse aux équipes qui veulent qu'un agent de codage respecte une identité visuelle sans la redécrire à chaque invite : tokens normatifs en front matter YAML, justification en prose, ordre de sections imposé. Le format est en alpha, la CLI aussi, changements attendus selon le README. Commencez par npx @google/design.md lint DESIGN.md pour valider tokens et contrastes WCAG AA, versionnez vos fichiers pour exploiter diff, et sous Windows utilisez l'alias designmd, le suffixe .md du binaire entrant en conflit avec l'association de fichiers Markdown.
Notes de la communauté