DESIGN.md di Google: un contratto di design leggibile anche dagli agenti di coding
Il progetto DESIGN.md propone un formato per rendere persistenti identità visiva e regole di interfaccia. Come provarlo senza confondere specifica, design system e codice.
Scritto da Redazione Daniel Vedovato · Revisionato il 21 luglio 2026
Articolo preparato con assistenza AI, verificato e revisionato da Daniel Vedovato.
DESIGN.md è una specifica open source di Google Labs per descrivere un’identità visiva e un design system in un file strutturato, leggibile sia dalle persone sia dagli agenti di coding. L’idea nasce da un problema pratico: un agente può generare componenti funzionanti ma incoerenti se vede soltanto frammenti di CSS, screenshot e istruzioni sparse. Un documento persistente può rendere esplicite regole che oggi vivono nella testa dei designer o in molte fonti diverse.
Non è un generatore automatico di una buona interfaccia. È un formato di comunicazione. La qualità dipende da quanto la squadra riesce a definire priorità, vocabolario, componenti e casi limite. Un file pieno di aggettivi come “moderno” o “premium” aiuta poco un umano e ancora meno un agente.
Cosa descrive una specifica utile
Il repository presenta DESIGN.md come formato per dare agli agenti una comprensione persistente e strutturata di un sistema visivo. In pratica il documento può collegare identità del prodotto, palette, tipografia, griglie, componenti, tono della microcopy e regole di comportamento. Il suo punto forte è concentrare un contratto che può essere revisionato insieme al codice.
Una specifica utile non prova a prescrivere ogni pixel. Dovrebbe invece chiarire decisioni riusabili: quali livelli di gerarchia esistono, quando usare un’azione primaria, come appare uno stato di errore, quali informazioni non devono essere nascoste e come cambia l’interfaccia su schermi piccoli. Queste sono le decisioni che impediscono a dieci pagine generate separatamente di sembrare dieci prodotti diversi.
| Sezione | Domanda da rendere esplicita | Esempio verificabile |
|---|---|---|
| Identità | quale impressione deve dare il prodotto? | tre aggettivi e tre cose da evitare |
| Tipografia | come si distingue il contenuto prioritario? | scala di titoli e testo base |
| Colori | quale significato hanno gli stati? | token per errore, successo, avviso |
| Componenti | come sono composti e variati? | input con label, errore e focus |
| Accessibilità | quale comportamento è obbligatorio? | contrasto, focus e navigazione tastiera |
| Contenuto | come si comunicano limiti e azioni? | copy di caricamento e fallback |
Perché può aiutare gli agenti
Un agente di coding è bravo a trasformare indicazioni in file, ma non possiede il contesto implicito di un prodotto. Se riceve solo “aggiungi una pagina di fatturazione”, può inventare spaziature, pulsanti e terminologia. Se legge una specifica ben mantenuta, può invece recuperare token, componenti consentiti e gerarchia delle azioni prima di scrivere codice.
Il beneficio non riguarda soltanto l’AI. Anche un nuovo sviluppatore o un freelance può usare lo stesso documento per capire perché un bottone è secondario o perché un messaggio d’errore richiede una soluzione, non una frase generica. Rendere le regole visibili riduce le decisioni ripetute in review.
Limiti da non ignorare
Una specifica testuale non sostituisce una libreria di componenti, un sistema di token o test visivi. Dice cosa il sistema dovrebbe fare, non garantisce che la build finale lo rispetti. Se i componenti reali sono diversi dal documento, l’agente può riprodurre l’incoerenza con grande velocità.
Esiste anche il rischio opposto: trasformare DESIGN.md in un manuale enorme che nessuno aggiorna. In quel caso diventa una fonte di conflitto, non di chiarezza. La regola operativa dovrebbe essere semplice: le parti che influenzano una modifica devono essere aggiornate nella stessa pull request, e qualsiasi contraddizione con i componenti esistenti va trattata come bug di design system.
Un pilota piccolo e misurabile
Scegli una superficie di prodotto limitata, per esempio impostazioni account o una procedura di checkout. Prima descrivi componenti già esistenti, stati, azioni e linguaggio. Poi assegna a una persona o a un agente due modifiche equivalenti, una con la specifica e una con il solo ticket. Confronta coerenza con componenti attuali, numero di commenti in review, regressioni di accessibilità e tempo necessario per ottenere il risultato.
La valutazione deve includere un controllo manuale. Un’interfaccia può rispettare token e dimensioni ma restare confusa: etichette ambigue, azioni irreversibili troppo vicine o messaggi che non spiegano cosa succede. Designer, sviluppatori e persone di supporto possono ciascuno scoprire un tipo diverso di problema.
Accessibilità come requisito di sistema
La parte più utile di una specifica condivisa è spesso quella meno spettacolare: focus visibile, contrasto, alternative testuali, dimensioni dei target e comportamento con tastiera. Se queste regole sono opzionali, una generazione rapida tenderà a ignorarle. Se sono una checklist nella definizione del componente, diventano più facili da testare e da fare rispettare.
Inserire accessibilità nel documento non basta, ma cambia il momento in cui viene considerata: prima del merge e non dopo una segnalazione dell’utente. Per questo vale la pena collegare la specifica a test automatici dove possibile e a una review visuale per le modifiche importanti.
Quando adottarlo
DESIGN.md può essere un buon complemento per un team che ha già componenti e decisioni disperse e sta usando agenti per produrre UI. Non serve imporlo a tutto il prodotto in una volta. Se il pilota riduce incoerenze e chiarisce le review, il file può crescere insieme al design system. Se aggiunge soltanto documentazione senza cambiare il processo, conviene ridurne lo scopo.
Il valore finale è una cosa molto concreta: rendere le scelte di design discutibili, verificabili e riutilizzabili. L’agente può allora accelerare l’implementazione senza dover indovinare che cosa il prodotto dovrebbe sembrare e comunicare.