Documentazione del design system: 6 passi perché venga letta

Alla fine di questa guida avrai una documentazione del design system organizzata in sei passi: un solo indirizzo per ogni risposta, pagine divise in base alla domanda di chi legge, un modello fisso per i componenti che parte dalla decisione, una tabella delle prop generata dal codice, un formato che gli agenti AI possono interrogare e una regola che fa cambiare documentazione e codice nella stessa pull request. La documentazione di un design system è l'insieme delle pagine che dice a designer, sviluppatori e ormai anche agenti di coding quale componente usare, quando e come. Ripaga quello che costa solo se la si apre prima di mettersi al lavoro.

È sulla documentazione che i team di design system faticano di più. Il Design Systems Report 2025 di zeroheight, basato su poco meno di 300 risposte, la indica come il problema principale. Dallo stesso sondaggio risulta che il 47% dei team documenta il sistema in più di un posto, con Figma e Storybook come coppia più diffusa, e che il 60% mette la documentazione tra gli strumenti di formazione che offre, contro il 32% di workshop e corsi. In più, sul web si legge poco: Nielsen Norman Group ha misurato che chi naviga legge circa il 20% delle parole di una pagina media. Una pagina di documentazione deve funzionare per chi legge una riga su cinque.

Cosa ti serve prima di cominciare

• Una libreria di componenti nel codice, con prop tipizzate (TypeScript o equivalente).
• Una libreria di design in Figma, o nello strumento che usano i designer, con componenti che hanno lo stesso nome di quelli nel codice.
• Un posto dove pubblicare la documentazione: Storybook, zeroheight, un sito fatto con il framework del prodotto o una combinazione. I passi che seguono valgono per tutti.
• Una persona che ha la documentazione tra i propri compiti, con ore dedicate in calendario.
• Le domande che arrivano oggi: il canale di supporto, i commenti in revisione, le issue sul repository del design system.

Passo 1: dai alla documentazione un solo indirizzo e fai puntare lì tutto il resto

Scegli un posto dove sta la risposta e fai in modo che ogni altro strumento ci rimandi. Se la documentazione è sparsa tra descrizioni in Figma, una wiki, un README e Storybook, nel giro di un trimestre le versioni non coincidono più, e chi trova due risposte non si fida di nessuna delle due.

Quell'indirizzo non deve contenere tutto. Deve essere il primo posto dove si arriva. Una divisione che funziona: la descrizione del componente in Figma ha una frase e un link; la story di Storybook ha l'esempio dal vivo; la pagina di documentazione ha le indicazioni d'uso e richiama le altre due. Quando una domanda su Slack trova risposta, la risposta va nella pagina e nel thread resta il link.

Passo 2: dividi le pagine in base alla domanda di chi legge

Chi apre la documentazione ha uno di quattro bisogni, e ognuno chiede una pagina diversa. Il framework Diátaxis, scritto da Daniele Procida e adottato da Canonical per la documentazione dei suoi prodotti, li chiama tutorial, guide pratiche, riferimento e spiegazione.

• Tutorial (imparare): i primi passi. Installare il pacchetto, mostrare una prima schermata, pubblicarla. Pensato per chi è appena arrivato nel team.
• Guida pratica (un compito): le ricette. Un form con la validazione, un nuovo tema, il passaggio dal vecchio modale.
• Riferimento (cercare): prop, token, eventi, comportamento da tastiera. Si consulta, non si legge dall'inizio alla fine.
• Spiegazione (capire): i principi, perché la scala degli spazi è quella, perché non esiste una terza variante del pulsante.

Una pagina di componente che mescola le quattro costringe il designer che cerca indicazioni a scorrere oltre la tabella delle prop, e lo sviluppatore che cerca una prop a scorrere oltre tre paragrafi di filosofia. Nella pagina del componente tieni il riferimento e le indicazioni d'uso; principi e ricette vanno in pagine a parte che rimandano lì.

Passo 3: apri ogni pagina di componente con la decisione, sempre nello stesso ordine

La prima schermata di una pagina di componente risponde a una domanda: è il componente giusto? Anatomia, storia e varianti vengono dopo. Il GOV.UK Design System usa lo stesso ordine su ogni pagina di componente: quando usarlo, quando non usarlo, come funziona, le ricerche fatte sul componente. Chi legge impara l'ordine una volta e su ogni altra pagina salta subito alla sezione che gli serve.

Il modello che usiamo per ogni pagina di componente:

1. Una frase su a cosa serve il componente.
2. Un esempio dal vivo, generato dal componente vero, mai uno screenshot.
3. Quando usarlo.
4. Quando non usarlo, e cosa usare al suo posto, con il link.
5. Cosa fare e cosa evitare, a coppie, ognuna con un'immagine presa da schermate reali del prodotto.
6. Indicazioni sui testi: lunghezza delle etichette, tono, cosa dice il testo.
7. Accessibilità: comportamento da tastiera, cosa annuncia uno screen reader, il contrasto che ogni variante rispetta.
8. La tabella delle prop, generata (passo 4).
9. Stato e changelog.

La riga «quando non usarlo» è quella che rende di più: ferma il componente sbagliato prima che finisca in un rilascio. Anche lo stato va nella pagina. GOV.UK segna i componenti nuovi come Trial e, come spiega la pagina sugli stati del ciclo di vita, li passa a Stable dopo 6 mesi senza riscontri negativi. Chi vede l'etichetta sa quanto può fidarsi della pagina.

Passo 4: genera quello che il codice sa già, scrivi a mano solo quello che non può sapere

Ogni informazione che il codice contiene già deve arrivare dal codice. Nomi, tipi, valori di default e obbligatorietà delle prop cambiano a ogni release, e una tabella scritta a mano è vecchia già alla prima. Autodocs di Storybook crea una pagina a partire dalle story e dagli argTypes di ogni componente, e ricava la tabella delle prop dai tipi TypeScript; altri strumenti fanno lo stesso con react-docgen o con uno script che legge i tipi durante la build.

Il codice non sa il perché. Quando usare un componente, quando no, le regole sui testi e il compromesso dietro una variante sono giudizio, ed è il giudizio che si viene a cercare. Queste parti si scrivono a mano, in paragrafi brevi, accanto a quelle generate, sulla stessa pagina. Una regola pratica: se una frase resta vera dopo un refactoring, la scrive una persona. Se cambia quando cambia il codice, la scrive uno script.

I commenti sulle prop aiutano tutte e due le parti. Un commento di una riga su ogni prop, nel file del componente, diventa la sua descrizione nella tabella generata: chi cambia la prop ne aggiorna la documentazione nello stesso file. Nel nostro articolo sulle API dei componenti spieghiamo perché una buona API ha bisogno di meno spiegazioni.

Passo 5: pubblica la documentazione in un formato che gli agenti AI possono interrogare

Anche gli agenti di coding leggono i design system, e un agente legge la documentazione ogni volta che scrive un'interfaccia, non una volta sola. Storybook oggi distribuisce un server MCP, @storybook/addon-mcp: gira dentro il server di sviluppo di Storybook su localhost:6006/mcp, raccoglie componenti, story e documentazione in manifest JSON e dà all'agente un gruppo di strumenti per la documentazione (list-all-documentation, get-documentation, get-documentation-for-story) con cui cercare un componente e le sue prop prima di scrivere codice.

È la pagina del passo 3 a dare valore a tutto questo. Un agente che legge «quando non usarlo: per la navigazione usa Link» sceglie il link. Un agente che legge solo la tabella delle prop sceglie qualunque cosa compili. Scrivi le indicazioni in frasi semplici, una regola per frase, con l'alternativa indicata per nome: lo stesso testo serve alla persona e al modello. Le regole che applichiamo quando sono gli agenti a usare il sistema sono in design system e agenti AI.

Passo 6: rilascia la documentazione nella stessa pull request del codice

La documentazione invecchia quando cambia in un giorno diverso dal componente. Rendila parte della definizione di fatto: una pull request che cambia comportamento, prop o aspetto di un componente non viene unita senza le modifiche alla documentazione e una riga di changelog. Chi fa la revisione controlla la pagina come controlla il test.

Il report di zeroheight lega la documentazione trascurata alla poca fiducia: nei team che si fidano meno del proprio sistema, la mancanza di persone e di tempo finisce per lasciare all'abbandono elementi importanti come accessibilità e documentazione. Un responsabile della documentazione con ore protette, più la regola della stessa pull request, è il rimedio più economico che conosciamo. Costa pochi minuti a modifica e risparmia i giorni di una riscrittura trimestrale che nessuno mette mai in calendario.

Come verificare che funzioni

• Il test del nuovo arrivato. Dai a chi è entrato nel team questo mese un compito («aggiungi una conferma per un'azione distruttiva nella pagina delle impostazioni») e guarda dove cerca. Deve arrivare alla pagina giusta in meno di un minuto, senza chiedere a nessuno.
• Domande ripetute. Conta le domande nel canale di supporto a cui la documentazione risponde già. Il numero deve scendere mese dopo mese; ognuna che resta è una frase mancante o una pagina che nessuno trova.
• Ricerche senza risultati. Se il sito della documentazione ha una ricerca, leggi le query che non restituiscono nulla. Sono le parole che usano i lettori e che le pagine non usano.
• Disallineamento. Prendi cinque componenti a caso e confronta documentazione e codice. Ogni differenza è una release che ha saltato il passo 6.

Errori frequenti e come correggerli

• Scritta una volta al lancio, poi mai più. Rimedio: la regola della stessa pull request del passo 6, più un responsabile con nome e cognome.
• Screenshot al posto degli esempi dal vivo. Invecchiano al primo cambio grafico. Rimedio: ogni esempio generato dal componente stesso.
• Pagine che partono dall'anatomia. Chi legge voleva una decisione e trova uno schema con le etichette. Rimedio: l'anatomia va sotto «quando non usarlo».
• Figma e codice non coincidono. Rimedio: un solo indirizzo (passo 1) e nomi dei componenti identici nei due strumenti.
• Le indicazioni le scrive l'AI. zeroheight lo dice chiaramente: parte del valore della documentazione sta in quello che si scopre mentre la si scrive. Rimedio: l'AI prepara i modelli o asciuga il linguaggio, il giudizio su «quando usarlo» resta a chi è responsabile del componente.

Per andare oltre

La documentazione è l'ultimo tratto di un sistema che sta già in piedi. Se il problema vero è l'adozione, parti da perché l'adozione di un design system si ferma. Se i token sotto sono difficili da nominare, le nostre convenzioni di naming dei design token fissano il vocabolario che la documentazione poi usa.