10 errori da design system che distruggono la coerenza a scala

Un team spedisce la sua decima feature del trimestre. Otto contengono nuovi bottoni. Tre di quei bottoni assomigliano al primary button del design system, ma ognuno porta padding, raggio o ombra leggermente diversi. Nessuno ha deciso di forkare. Tutti hanno solo spedito. Ecco come si vede l'incoerenza di un design system a scala: non una decisione sbagliata, ma mille piccole che nessuno ha dovuto difendere.

Gli errori qui sotto sono i dieci che continuiamo a trovare quando facciamo un audit di design system su un prodotto cresciuto più in fretta del suo sistema. Nessuno è esotico. Tutti compongono. La buona notizia: ognuno ha un rimedio meccanico, una volta deciso di pagarlo.

1. Trattare il design system come progetto laterale

L'errore: nessuno possiede il sistema. Una designer senior lo tiene in vita nel 20% del tempo. L'engineering tratta i fix come "poi ci arriviamo". Niente roadmap, niente on-call, niente release note.

Quanto costa: ogni contributor reinventa ciò che manca. La libreria accumula quasi-duplicati perché nessuno ha l'autorità di rifiutare una pull request che aggiunge il 41esimo variant del bottone.

Il rimedio: assegnare un owner reale con una percentuale di tempo allocata formalmente, una roadmap pubblica e una sola coda Slack o Linear. Un ciclo di vita definito per i componenti (proporre, revisionare, costruire, documentare, rilasciare, misurare, deprecare) trasforma uno scatolone di pezzi in un prodotto.

2. Aggiungere un componente per ogni nuovo design

L'errore: ogni feature aggiunge due o tre componenti alla libreria. Sei mesi dopo, il team non sa se usare Card, CardCompact, CardWithHeader o CardLegacy.

Quanto costa: fiducia. Lo sprawl mina i benefici stessi che il design system dovrebbe creare. I team smettono di andare alla libreria perché non riescono a navigarla.

Il rimedio: un criterio severo per la promozione alla libreria condivisa. Noi ne usiamo tre: il pattern compare in almeno due feature non collegate, è stato stabile per almeno un rilascio e una designer più un engineer hanno firmato sull'API. Tutto il resto resta locale finché non si guadagna l'upgrade.

3. Saltare il layer semantico dei token

L'errore: i componenti referenziano i token primitivi direttamente. Button usa color-blue-500 al posto di color-action-primary. Il layer semantico non viene mai costruito perché "lo aggiungiamo dopo".

Quanto costa: ogni cambio di tema diventa un find-and-replace globale. La maggior parte dei sistemi definisce token primitivi generici aliasati a usi intenzionali di spazio e colore. Senza quell'aliasing, non si spedisce dark mode senza riscrivere ogni componente.

Il rimedio: tre layer. I primitivi tengono i valori (color-blue-500 = #3B82F6). I token semantici tengono l'intento (color-action-primary punta a color-blue-500). I token di componente tengono le decisioni locali (button-bg-default punta a color-action-primary). I componenti referenziano il layer semantico o quello di componente, mai il primitivo. Abbiamo coperto i tradeoff in token vs CSS variables vs Tailwind.

4. Lasciare che gli override locali diventino normali

L'errore: ogni team di prodotto forka un componente "giusto per questa view" e cambia una prop. Sei mesi dopo, metà delle surface usa l'override e metà la base. Il sistema ha due verità e nessun modo per scegliere.

Quanto costa: design drift. Gli override locali su spacing, colore, tipografia o prop di componente diventano normali e frammentano lentamente il sistema finché "cosa è davvero standard" è una domanda a cui nessuno sa rispondere.

Il rimedio: trattare l'override rate come metrica di prima classe. Se un componente è sovrascritto in più del 10% delle sue istanze, il sistema sta perdendo un variant e l'override è il segnale. O lo riassorbi come variant supportato, o lo elimini insieme al caso d'uso che serviva.

5. Nessun budget di variant

L'errore: un bottone è partito con tre variant. Al secondo anno ne ha 22, incluso primary-with-icon-on-right-disabled-loading.

Quanto costa: il team che dovrebbe costruire feature passa i pomeriggi del martedì a discutere quale variant esistente usare. Storybook diventa un labirinto.

Il rimedio: cap dei variant per componente. Noi usiamo un budget: un componente sopra i cinque variant attiva una review. Aggiungere un nuovo variant richiede di deprecarne uno vecchio o di dimostrare che non si esprime componendo primitive esistenti. Il tetto è artificiale. La disciplina è reale.

6. Nessun percorso di deprecazione

L'errore: i componenti vengono solo aggiunti, mai rimossi. ButtonV1 vive accanto a ButtonV2 perché toglierlo romperebbe sei pagine che nessuno nel team attuale possiede.

Quanto costa: confusione al livello di import ("quale Button uso"), bundle gonfio e un costo di audit che cresce linearmente con l'età della libreria.

Il rimedio: un sistema a tier di qualità. Experimental, Beta, Stable, Deprecated, Removed. Un componente vive in Deprecated per due cicli di rilascio con un codemod disponibile, poi sparisce. Quel calendario lo dichiariamo pubblicamente, nel changelog, il giorno in cui depreciamo.

7. Nominare i token per valore invece che per intento

L'errore: color-red-600, spacing-16, shadow-large. I nomi descrivono l'output visivo. Il giorno in cui il brand cambia il rosso in magenta, ogni nome mente.

Quanto costa: un nome come color-text-red descrive un valore visivo, quindi si rompe nel momento in cui il colore cambia. Un nome come color-text-error descrive l'intento e resta stabile.

Il rimedio: nominare per il perché. color-feedback-error, spacing-stack-md, elevation-overlay. La prima volta che una designer ribatte ("ma è rosso"), spiega che il sistema serve i prossimi cinque anni, non il mockup di oggi.

8. Trattare Figma come fonte della verità

L'errore: la libreria di design vive in Figma. Gli engineer la traducono a mano nel codice. I due divergono in settimane.

Quanto costa: un problema di handoff vestito da design system. A ogni rilascio, design spedisce componenti che engineering non ha implementato, ed engineering spedisce fix che design non ha assorbito. Il gap di audit si allarga finché qualcuno fa una riconciliazione manuale che nessuno vuole rifare.

Il rimedio: il codice è la fonte della verità. I token vivono in un singolo repository come JSON o export tipato, e Figma legge da lì via Variables e un sync tool. I componenti hanno una sola implementazione canonica; design fornisce spec annotate, non sorgenti paralleli. La libreria Figma rispecchia quella di codice, non viceversa.

9. Nessuna metrica di adozione misurata

L'errore: nessuno sa rispondere a "che percentuale di UI usa il design system". Il team stima 80%. L'audit trova 38%.

Quanto costa: è difficile dire cosa sia un conteggio sano senza un obiettivo. Senza misura, ogni conversazione sul sistema è aneddoto contro aneddoto.

Il rimedio: strumenta la copertura. Analisi statica sul codebase che riporta il rapporto fra istanze di componenti del design system e quelle bespoke, per surface. Mews ha costruito la propria scansionando l'albero React in produzione. Noi facciamo una scansione simile nelle nostre ops, settimanalmente, e trattiamo ogni calo come un incidente.

10. Progettare il sistema solo intorno ai designer

L'errore: il sistema è bellissimo in Figma e doloroso nel codice. Le API dei componenti sono incoerenti, le prop hanno nomi di concetti visivi che engineering non usa, mancano le primitive di accessibilità. Gli engineer aggirano il sistema invece di combatterlo.

Quanto costa: l'adozione si blocca. Engineering scrive le proprie primitive, design ne fa l'audit e trova drift, il ciclo si ripete.

Il rimedio: portare engineering nel sistema dal giorno uno. Le API dei componenti si progettano insieme alla specifica visiva, non dopo. L'accessibilità è un requisito hard su ogni componente (gestione del focus, handler da tastiera, ruoli ARIA). Il sistema spedisce come pacchetto che un engineer installa e importa in una riga, non come libreria Figma più pagina wiki. Un sistema custom che gli engineer rifiutano di usare è il peggiore di entrambi i mondi.

Il pattern sotto tutti e dieci

Il filo comune: un design system o si governa o si sparpaglia. Gli errori sopra non sono fallimenti di gusto o di talento. Sono fallimenti di governance. Una roadmap, un budget, un sistema a tier, una misura, un owner. Nessuno è esotico e nessuno richiede uno strumento nuovo. Richiedono che qualcuno decida che il sistema è un prodotto e ne tratti l'evoluzione come tale.

I sistemi che reggono a scala condividono una regola sommessa: ogni nuovo componente, variant, token o override deve giustificarsi rispetto al costo che aggiunge. La risposta di default è no.