DESIGN.md di Google: guida al file per agenti AI e design system

Negli ultimi mesi il rapporto tra design system e intelligenza artificiale è cambiato rapidamente. Non basta più avere componenti in Figma, token in un file JSON o linee guida sparse in un documento interno: se un team usa agenti AI per generare interfacce, refactoring frontend o prototipi, anche quegli agenti devono capire il linguaggio visivo del prodotto.

È qui che entra in gioco DESIGN.md, il nuovo formato open source pubblicato da Google Labs Code per descrivere una visual identity in modo leggibile sia dagli esseri umani sia dagli agenti di coding. L’idea è semplice ma molto potente: creare un file testuale, versionabile e validabile che contenga design token, razionale visivo, regole sui componenti e indicazioni pratiche su cosa fare e cosa evitare.

In altre parole, DESIGN.md prova a diventare per il design quello che altri file di configurazione sono già diventati per sviluppo, linting, formattazione e automazione: una fonte di verità chiara, portabile e adatta ai workflow moderni con AI.

Cos’è DESIGN.md e perché è importante

DESIGN.md è un formato pensato per descrivere l’identità visiva di un prodotto agli agenti di codice. La definizione ufficiale del repository google-labs-code/design.md parla di una specifica per dare agli agenti una comprensione persistente e strutturata di un design system.

Il punto chiave è la parola persistente. Un agente AI può ricevere istruzioni nel prompt, ma quelle istruzioni spesso sono temporanee, incomplete o ambigue. Un file DESIGN.md, invece, può stare nel repository accanto al codice, essere revisionato in pull request, validato con una CLI e riutilizzato da strumenti diversi.

Il formato unisce due livelli:

• una parte machine-readable in YAML front matter, dove vengono definiti token come colori, tipografia, spacing, radius e componenti;
• una parte human-readable in Markdown, dove si spiega il perché delle scelte e come applicarle in situazioni reali.

Questa combinazione è interessante perché i soli token non bastano. Sapere che il colore primario è #1A1C1E dice poco sul tono dell’interfaccia. Sapere anche che quel colore rappresenta “deep ink”, autorevolezza e leggibilità editoriale aiuta l’agente a usarlo con più coerenza.

Il problema che DESIGN.md prova a risolvere

Molti team hanno già un design system, ma spesso è distribuito in troppi luoghi: Figma, Storybook, documentazione interna, file CSS, Tailwind config, component library, issue di progetto e memoria informale del team. Quando entra in scena un agente AI, questa frammentazione diventa un problema tecnico.

Un agente può generare una pagina funzionante, ma senza un contesto stabile rischia di:

• inventare colori non presenti nel brand;
• usare font o pesi tipografici incoerenti;
• creare bottoni con radius e padding casuali;
• mescolare stili editoriali, SaaS, dashboard e landing page;
• ignorare contrasto e accessibilità;
• produrre componenti apparentemente belli ma scollegati dal sistema reale.

DESIGN.md riduce questo rischio perché trasforma le linee guida di design in un contratto leggibile dal codice e dagli agenti. Non sostituisce Figma o una libreria componenti, ma aggiunge un livello di istruzioni condivise che può viaggiare con il repository.

Come è fatto un file DESIGN.md

La struttura ufficiale prevede un file Markdown con front matter YAML opzionale. Il front matter contiene i token normativi; il corpo Markdown contiene spiegazioni, razionale e linee guida.

Ecco un esempio semplificato:

---
version: alpha
name: Editorial Tech
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  headline-lg:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

Interfaccia editoriale, tecnica e autorevole. Il prodotto deve comunicare
precisione, leggibilità e affidabilità, evitando decorazioni inutili.

## Colors

Il colore primario è usato per testi e titoli. Il terziario è riservato
alle azioni principali e agli stati di enfasi.

Questo esempio mostra il principio operativo: i valori precisi sono nei token, mentre il Markdown spiega come interpretarli. Un agente può quindi rispettare sia la misura esatta sia l’intenzione progettuale.

I token supportati: colori, tipografia, spacing e componenti

La specifica ufficiale descrive un insieme di gruppi token pensati per coprire gli aspetti fondamentali di una UI.

I gruppi principali sono:

• colors, per palette e ruoli cromatici;
• typography, per font, dimensioni, pesi, line-height e letter-spacing;
• rounded, per la scala dei bordi arrotondati;
• spacing, per distanze, margini e ritmo visivo;
• components, per collegare i token a elementi come bottoni, chip, input e stati.

Un dettaglio tecnico importante è il supporto ai riferimenti tra token con sintassi {path.to.token}. Per esempio, un bottone può usare backgroundColor: "{colors.tertiary}", evitando duplicazione e riducendo il rischio di divergenze.

Questa scelta rende DESIGN.md più simile a un piccolo linguaggio di configurazione che a una semplice pagina di documentazione. È leggibile, ma anche analizzabile da un linter.

Le sezioni Markdown consigliate

Il corpo del file non è libero in modo caotico. La specifica suggerisce un ordine canonico delle sezioni, tutte basate su heading ##:

1. Overview;
2. Colors;
3. Typography;
4. Layout;
5. Elevation & Depth;
6. Shapes;
7. Components;
8. Do’s and Don’ts.

Questo ordine serve a dare prevedibilità agli strumenti. Un agente sa dove cercare la personalità visiva, dove trovare le regole tipografiche, dove leggere i vincoli di layout e dove individuare errori da evitare.

La scelta è pragmatica: DESIGN.md non vuole essere un trattato di brand identity, ma un formato operativo. Deve essere abbastanza espressivo per guidare un’interfaccia reale, ma abbastanza strutturato per essere letto e validato da una CLI.

Esempio pratico: usare DESIGN.md in un progetto frontend

Immagina un team che sta costruendo una dashboard SaaS. Nel repository sono presenti componenti React, Tailwind, test e documentazione. Senza DESIGN.md, un agente AI chiamato a creare una nuova pagina “Billing” potrebbe copiare pattern visti in altre parti del codice, ma potrebbe anche introdurre nuove sfumature, radius non standard o gerarchie tipografiche incoerenti.

Con DESIGN.md, il workflow diventa più controllabile:

1. il team definisce colori, tipografia, spacing e componenti principali;
2. il file viene salvato nel repository;
3. l’agente legge DESIGN.md prima di generare UI;
4. la CLI valida token, riferimenti e contrasto;
5. eventuali modifiche al design system vengono confrontate con diff.

Il risultato non è una garanzia assoluta di qualità, ma riduce drasticamente l’improvvisazione. In un contesto con più agenti o più sviluppatori, questo è un vantaggio concreto.

Comandi CLI: lint, diff, export e spec

Google distribuisce anche una CLI installabile come pacchetto npm @google/design.md. Dal README ufficiale emerge un set di comandi pensato per validare, confrontare ed esportare il formato.

Il comando più immediato è il lint:

# comando lint
npx @google/design.md lint DESIGN.md

Il linter restituisce JSON strutturato con finding, severità, percorso e messaggio. Questo è utile perché un agente può leggere l’output e correggere il file in modo mirato.

Per confrontare due versioni:

# confronto due versioni
npx @google/design.md diff DESIGN.md DESIGN-v2.md

Questo aiuta a capire se sono stati aggiunti, rimossi o modificati token. In una pull request, può diventare un controllo utile per evitare regressioni nel design system.

Per esportare i token:

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Gli export sono importanti perché collegano DESIGN.md agli strumenti già usati dai team: Tailwind, CSS custom properties e formati compatibili con il mondo dei design token.

Un riferimento pratico da aggiungere al workflow è Stitch di Google, che consente di lavorare su interfacce e prototipi con un percorso orientato anche all’esportazione nel formato DESIGN.md. Questo rende il file ancora più interessante: non è solo una specifica da scrivere manualmente, ma può diventare un formato di passaggio tra progettazione visuale, generazione assistita e codice.

Le regole di linting più utili

La documentazione cita diverse regole di linting, tra cui riferimenti rotti, contrasto, assenza di colore primario, token orfani, sezioni mancanti, tipografia mancante e ordine delle sezioni.

Queste verifiche rendono DESIGN.md più serio di una semplice convenzione testuale. Un file può essere scritto male, ma la CLI permette di intercettare almeno una parte degli errori prima che arrivino nel codice generato.

Perché DESIGN.md interessa a chi lavora con AI coding agent

Il valore più evidente è per chi usa agenti AI nel frontend. Strumenti di coding assistito possono già generare componenti, landing page e layout, ma spesso hanno bisogno di contesto. DESIGN.md offre quel contesto in una forma leggera.

Un agente può leggere frasi come:

• “usa il colore primario solo per l’azione più importante”;
• “evita ombre pesanti, usa gerarchie tonali”;
• “mantieni radius da 4px per un aspetto tecnico”;
• “non usare più di due pesi tipografici nella stessa schermata”.

Queste indicazioni sono diverse dai token numerici. Sono regole di comportamento progettuale. Per un essere umano sono normali linee guida; per un agente diventano vincoli espliciti da seguire.

Differenze rispetto a tokens.json, Figma variables e Tailwind config

DESIGN.md non nasce per sostituire tutto. Un file tokens.json resta più adatto allo scambio formale di token tra strumenti. Figma variables restano fondamentali nel lavoro dei designer. Tailwind config resta centrale quando si implementa una UI con utility class.

La differenza è che DESIGN.md mette nello stesso posto token e razionale. Questo lo rende particolarmente adatto agli agenti, perché gli agenti non hanno bisogno solo di valori: hanno bisogno di contesto.

Per esempio, un token può dire che tertiary vale #B8422E; il testo può spiegare che quel colore è “Boston Clay” e che deve essere usato solo per interazioni primarie. Questa seconda informazione può fare la differenza tra una UI coerente e una UI tecnicamente corretta ma visivamente confusa.

Limiti attuali del formato

DESIGN.md è indicato come formato in stato alpha. Questo significa che lo schema, la CLI e le convenzioni potrebbero cambiare. È quindi intelligente adottarlo con aspettative realistiche.

I limiti più evidenti sono:

• la specifica è ancora giovane;
• la sezione componenti è flessibile e in evoluzione;
• non sostituisce test visivi, review di design o accessibilità manuale;
• richiede disciplina nella manutenzione;
• può diventare obsoleto se non viene aggiornato insieme al prodotto.

Detto questo, il formato è già utile per sperimentare un workflow più ordinato tra design system e AI coding.

Come introdurre DESIGN.md in un team

Il modo migliore non è provare a documentare tutto subito. Conviene partire da un file piccolo ma accurato.

Un percorso pratico può essere:

1. definire nome, descrizione e personalità del prodotto;
2. inserire palette primaria, secondaria, accento e neutral;
3. aggiungere 4-6 livelli tipografici realmente usati;
4. documentare spacing e radius principali;
5. descrivere 3 componenti critici: bottone primario, card e input;
6. scrivere 5 regole “do” e 5 regole “don’t”;
7. eseguire il lint e correggere gli errori;
8. usare il file in una singola feature generata con agenti AI;
9. confrontare output generato prima e dopo DESIGN.md.

Questo approccio evita il classico errore dei design system: puntare alla perfezione iniziale e non arrivare mai all’adozione reale.

SEO tecnico e opportunità per sviluppatori WordPress

Anche se DESIGN.md nasce per agenti di codice e design system, il tema è rilevante anche per chi lavora con WordPress, temi custom e page builder avanzati. Un file di questo tipo potrebbe aiutare a mantenere coerenza visiva quando si generano componenti, blocchi Gutenberg, pattern di tema o layout con strumenti AI.

Per esempio, un team WordPress potrebbe creare un DESIGN.md per descrivere:

• palette del brand;
• gerarchia tipografica del tema;
• spaziature dei blocchi editoriali;
• stile di card, bottoni e call to action;
• regole per landing page e template WooCommerce;
• vincoli di accessibilità e contrasto.

In futuro, agenti AI capaci di leggere DESIGN.md potrebbero generare pattern Gutenberg più coerenti, componenti React per block editor o CSS custom properties allineate alla brand identity. È un ponte naturale tra content management, frontend engineering e automazione.

Per approfondire il tema nel contesto WordPress, sono collegati due percorsi utili: una guida su AI per migliorare SEO, UX e design su WordPress e un approfondimento sui tool essenziali per il web design WordPress. Entrambi aiutano a collegare DESIGN.md a casi d’uso concreti: coerenza visiva, automazione dei layout, qualità UX e produzione di interfacce più controllabili.

FAQ

DESIGN.md è un file di configurazione ufficiale di Google?

È un progetto open source pubblicato nel repository Google Labs Code. La specifica è in fase alpha e propone un formato per descrivere visual identity e design system agli agenti di coding.

DESIGN.md sostituisce Figma?

No. Figma resta uno strumento visuale per progettare, discutere e prototipare. DESIGN.md aggiunge un formato testuale, versionabile e leggibile dagli agenti, utile dentro i repository di codice.

Qual è la differenza tra DESIGN.md e design tokens?

I design token definiscono valori come colori, font, spacing e radius. DESIGN.md può contenere quei token, ma aggiunge anche spiegazioni in Markdown, cioè il razionale che aiuta gli agenti a capire come applicarli.

Si può usare DESIGN.md con Tailwind?

Sì. La CLI documenta export verso Tailwind v3 in JSON e Tailwind v4 tramite CSS @theme, oltre al formato DTCG per design token.

È pronto per la produzione?

È utilizzabile per sperimentazioni e workflow interni, ma va considerato un formato alpha. Prima di inserirlo in processi critici, conviene testarlo su un progetto pilota e monitorare l’evoluzione della specifica.

Conclusione

DESIGN.md è interessante perché affronta un problema reale: gli agenti AI possono scrivere codice, ma senza una memoria progettuale rischiano di generare interfacce incoerenti. Un file testuale, versionabile e validabile può diventare il ponte tra design system, frontend e automazione.

Il valore non sta solo nei token, ma nel contesto: colori con significato, tipografia con ruolo, componenti con stati, regole pratiche e divieti espliciti. Per chi lavora con AI coding agent, design system o sviluppo WordPress avanzato, DESIGN.md è un formato da osservare subito e da testare in un piccolo progetto reale.

Il consiglio pratico è semplice: crea un primo DESIGN.md con pochi token affidabili, aggiungi rationale chiaro, esegui il lint e usalo come contesto per un agente AI. La differenza nella coerenza dell’output diventa evidente appena il progetto supera la singola pagina dimostrativa.