Come governare un design system su 10+ progetti consumer

Pubblichi un design system. Un progetto lo consuma. Facile. Cinque progetti lo consumano. Gestibile. Dieci o più progetti lo consumano, ognuno su una versione diversa, con le proprie scadenze e i propri ingegneri che aprono ticket alle due di notte, e il sistema smette di scalare. I token vanno alla deriva. I breaking change bloccano i treni di rilascio. Nessuno sa chi possiede il componente Button questo trimestre.

Questa guida illustra le sette mosse che mantengono utile un design system quando dieci o più progetti a valle ne dipendono. Il risultato è un modello di governance che ti permette di rilasciare in fretta senza rompere i consumatori, con un team core che resta piccolo, e metriche di adozione difendibili in una review trimestrale.

La forma del problema

Un design system che serve un progetto è una libreria di componenti. Un design system che serve dieci progetti è una piattaforma interna. Il lavoro non riguarda più l'aggiunta di componenti. Riguarda il coordinamento del cambiamento su una flotta che non possiedi, dove ogni consumatore ha la propria roadmap, la propria versione di React e la propria tolleranza alle migrazioni.

Tornano tre modalità di fallimento. Primo, i consumatori fanno il fork del sistema per sbloccarsi e non tornano più. Secondo, il team core blocca ogni modifica in code review, diventando un collo di bottiglia. Terzo, i breaking change vengono rilasciati senza un percorso di migrazione, e i consumatori restano su una versione vecchia di due anni perché aggiornare costa uno sprint.

I sette passi seguenti affrontano direttamente ciascuna modalità di fallimento.

Passo 1: scegli un modello di contribuzione e mettilo per iscritto

Esistono tre modelli. Ognuno si adatta a una forma di team diversa.

Centralizzato. Un singolo team dedicato possiede tutto. Forte coerenza, scalabilità lenta. Come ha scritto Nathan Curtis nel pezzo canonico di EightShapes, gli overlord non scalano. Usalo solo quando il sistema è giovane e i consumatori sono meno di cinque.

Federato. Molti team contribuiscono. Nessun proprietario unico. Veloce nel breve, costoso nel lungo: i componenti divergono, le decisioni si trascinano, la coerenza cala. Una federazione pura è rara e non la consigliamo.

Ibrido (ciclico). Un piccolo team core possiede l'API, i token e la pipeline di rilascio. Contributori embedded dai team di prodotto rilasciano componenti e propongono modifiche. Salesforce lo descrive come un modello ciclico: governance centralizzata più contribuzione federata, ognuno informa l'altro.

Per 10 o più consumatori, l'ibrido è quasi sempre la risposta giusta. Documenta il modello in un CONTRIBUTING.md alla radice del repo: chi può fare merge su main, chi può proporre componenti, chi decide sui token, qual è l'SLA sulla review delle PR. Senza quel documento, ogni escalation diventa una riunione.

Passo 2: congela l'API pubblica

La maggior fonte di rotture accidentali in un design system è esportare cose che non avevi intenzione di esportare. Un consumatore importa una utility privata, tu la refattorizzi sei mesi dopo, la sua build si rompe alle due di notte.

Definisci esplicitamente una superficie API pubblica. Un singolo file barrel (un index.ts alla radice del pacchetto) esporta i componenti, i token, gli hook e i tipi che i consumatori possono usare. Tutto il resto è interno. Configura il bundler in modo che i moduli interni non siano raggiungibili tramite deep import, oppure aggiungi una regola ESLint (no-restricted-imports) che vieta i deep import nei progetti consumer.

Questa singola mossa trasforma l'80% delle rotture accidentali in rotture intenzionali pianificabili.

Passo 3: versiona con SemVer, rilascia un changelog a ogni release

Usa il Semantic Versioning a livello di pacchetto. MAJOR segnala cambi API non retrocompatibili. MINOR aggiunge funzionalità retrocompatibili. PATCH corregge bug senza cambiare il comportamento. Atlassian e altri grandi publisher versionano anche ogni componente in modo indipendente, dando ai consumatori note di rilascio più granulari; per un piccolo team core, il versioning di pacchetto è sufficiente e più semplice da comunicare.

Ogni release rilascia una voce di changelog che dice: cosa è cambiato, chi è coinvolto e (per le release MAJOR) il percorso di migrazione. Strumenti come Changesets o release-please lo automatizzano partendo dalle descrizioni delle PR, così i contributori scrivono il changelog mentre fanno merge, non a posteriori.

La disciplina che conta: un bump MAJOR non è mai silenzioso. I consumatori lo apprendono dal changelog o da un messaggio Slack, mai da una build CI rotta.

Passo 4: rilascia codemod insieme a ogni breaking change

Un breaking change senza percorso di migrazione è una tassa su ogni consumatore. Con dieci consumatori, quella tassa si moltiplica: dieci ingegneri, dieci contesti da caricare in testa, dieci occasioni per un refuso.

La soluzione è jscodeshift o uno strumento di trasformazione AST simile. Quando rinomini una prop, elimini un componente o cambi un percorso di import, scrivi un codemod e lo rilasci nella stessa release del breaking change. MUI e Chakra UI rilasciano entrambi codemod con le major version, e i consumatori eseguono un singolo comando per migrare.

Due regole pratiche:

• Testa il codemod prima sul consumatore più grande. I codemod che si rompono sui casi limite sono peggio dell'assenza di codemod, perché i consumatori smettono di fidarsi.
• Impacchetta i codemod in una CLI dentro il pacchetto del design system, così il percorso di upgrade è un singolo comando documentato e non una caccia su GitHub.

Il team di Hypermod ha documentato in dettaglio il pattern design system guidato da codemod; il loro argomento centrale è che la migrazione automatizzata cambia l'economia dei breaking change da "non possiamo permetterci di rompere" a "possiamo rifattorizzare liberamente finché il codemod segue".

Passo 5: traccia l'adozione con un manifest per ogni consumatore

Non puoi governare ciò che non puoi misurare. Ogni progetto consumer dovrebbe pubblicare un ds.manifest.json nella sua root, committato in git, che registra:

• La versione corrente del design system da cui dipende.
• Il numero di componenti del design system effettivamente usati (contati dagli import).
• Il numero di override (CSS custom che bypassa il sistema).
• La data dell'ultimo audit manuale.

Un job notturno aggrega questi manifest in tutta la flotta e produce una sola dashboard. I numeri che contano sono la coverage (percentuale di file UI che importano il design system), la deriva (numero di override CSS per progetto) e la distanza di versione (quante release MAJOR di ritardo ha ciascun consumatore).

Brevo, Productboard e Mews hanno tutte pubblicato la loro versione di questo approccio. L'adoption tracker di Brevo e il coverage report di Productboard sono buoni riferimenti pubblici. L'intuizione condivisa: le metriche di adozione derivate dal codice di produzione battono ogni trimestre quelle basate sui sondaggi.

Passo 6: imposta scadenze di deprecation e falle rispettare

Un componente deprecato che vive per sempre non è deprecato, è supportato. Per fare deprecation pulite:

1. Marca il componente come deprecato nei sorgenti (un tag JSDoc @deprecated, un warning in console in sviluppo).
2. Annuncia una data di rimozione nel changelog. Usiamo 6 mesi dall'annuncio per i componenti a basso traffico, 12 mesi per quelli ad alto traffico.
3. Traccia quali consumatori importano ancora il componente deprecato usando il manifest del Passo 5.
4. Manda promemoria mirati a 90 giorni, 30 giorni, 7 giorni dalla rimozione.
5. Rimuovi alla data annunciata, in una release MAJOR, con un codemod.

La parte più difficile è far rispettare la scadenza. I team chiedono proroghe, e concedere proroghe insegna a tutti che le scadenze sono negoziabili. Non farlo.

Passo 7: tieni una cadenza di bump fissa

Senza una cadenza, i consumatori si aggiornano a caso e la dispersione delle versioni nella flotta cresce senza limiti. Una cadenza quindicinale o mensile funziona per la maggior parte dei team. La cadenza ha tre artefatti:

• Una release pianificata in un giorno fisso (noi usiamo il primo martedì del mese).
• Un controllo pre-volo la settimana prima, che scansiona i manifest dei consumatori alla ricerca di rischi: quali progetti hanno più override, la maggior distanza di versione o il maggior uso di componenti deprecati.
• Una retrospettiva dopo ogni release, che rivede cosa si è rotto e perché.

L'obiettivo è la prevedibilità. I consumatori possono pianificare mezza giornata per ciclo dedicata all'upgrade. Gli ingegneri non vengono svegliati per migrazioni a sorpresa.

Cosa stai sacrificando

Questa configurazione non è gratis. Il team core dedica tempo reale a changelog, codemod, tracciamento delle deprecation e pipeline del manifest. Per un sistema che serve meno di cinque consumatori, l'overhead è difficile da giustificare e un processo più leggero vince. Oltre i dieci consumatori, l'overhead si ripaga entro due cicli di release, perché l'alternativa è uno spegnere-incendi reattivo che scala peggio di un piccolo team di piattaforma.

L'altro sacrificio è l'autonomia. Un modello ibrido con un'API pubblica congelata significa che i contributori non possono rilasciare quello che vogliono dall'oggi al domani. Propongono, il team core revisiona, la modifica entra nella prossima release. È più lento del lasciare che ogni team modifichi il sistema sul posto. È anche l'unico modo per tenere dieci consumatori sulla stessa versione di Button.

Per uno sguardo più approfondito al tipo di errori che questo modello di governance previene, vedi il nostro pezzo sui design system mistakes che distruggono la coerenza su larga scala.