Un design system verificabile per una maison del lusso
Costruire il design system di un PIM come si costruisce il software: programmaticamente, con un agente AI dentro Figma, dimostrandone la qualità con audit automatici invece di prometterla
Case study
Un design system verificabile per una maison del lusso
La Sfida
I requisiti delivery-grade erano contrattuali: stile applicato solo per riferimento (zero valori hardcoded), property delle varianti che mappano 1:1 sulle props dei componenti, Auto Layout sistematico, naming gerarchico. Mancarne uno aveva un prezzo, perché il contratto permetteva di riaprire il preventivo di sviluppo.
Un PIM (Product Information Management) è il posto dove un catalogo moda succede davvero: gli operatori prendono i prodotti dal gestionale ERP e li preparano per l'e-commerce filtrando, completando schede, gestendo la visibilità per canale, esportando. È un lavoro denso e ripetitivo, dove gli errori costano. Il mio compito era trasformare i prototipi HTML/CSS approvati in un design system in Figma, la libreria che un team di sviluppo avrebbe consumato per costruire l'applicazione reale in Vue.
Questo progetto ha due utenti, e solo uno è l'operatore. L'altro è lo sviluppatore che apre Figma Dev Mode: per lui il prodotto sono i token, le property delle varianti e il naming prevedibile. Ogni ambiguità nel file diventa una domanda su Slack o, peggio, una decisione silenziosa.
La cosa insolita di questo incarico: il contratto dava un prezzo esplicito alla qualità del design. Se il file di consegna non rispettava i requisiti definiti (Variables ovunque, componenti con varianti che mappano sulle props Vue, Auto Layout sistematico, naming pulito), i tempi di sviluppo salivano e il preventivo si rivedeva. La qualità era a tutti gli effetti una condizione economica.
"Gli operatori del catalogo lavorano per ore su un'interfaccia densa dove un cambio di stato non notato costa denaro reale. Lo sviluppatore che consuma la libreria ha bisogno di ogni stato esplicito e ogni valore tokenizzato. Tutto il resto impone reinterpretazione, ed è lì che i design system muoiono."
A questa scala, decine di componenti ognuno con stati completi, size e property, il fallimento tipico non è il design brutto. È l'incoerenza che non si vede: l'esadecimale raw visivamente identico al token, lo stato costruito diversamente dagli altri diciannove. Esattamente la classe di errori che la revisione umana becca peggio.
I prototipi approvati erano HTML/CSS: reali, ma non un sistema. Valori ripetuti inline, stati interattivi incoerenti da schermata a schermata (focus e active mancanti quasi ovunque), naming improvvisato. Ricostruirli a mano in Figma avrebbe riprodotto la stessa deriva, una decisione manuale alla volta.
Ricerca
Archeologia dei prototipi
~40 componenti riusabili
Identificati nei prototipi e separati dalle composizioni di schermata e dal codice morto: la superficie reale del sistema
190 design token
Derivati e strutturati come sorgente DTCG: primitivi colore e ruoli semantici, spacing, raggi, tipografia
Le label reali battono quelle inventate
Ogni componente è stato ancorato all'uso reale: label, stati e contenuti presi dalle schermate approvate, mai inventati in astratto
Focus e active mancanti ovunque
I prototipi coprivano al massimo default, hover e disabled. Gli stati da cui dipende l'accessibilità erano la prima vittima della costruzione a mano.
Benchmark di completezza
Cinque stati o non è finito
Lo standard Carbon è diventato l'asticella: default, hover, focus, active e disabled per ogni controllo interattivo, più anatomia error, warning e read-only per il data entry
Convenzioni uniformi rendono il sistema leggibile dalle macchine
La lezione di Astryx: quando ogni componente segue le stesse regole di naming, property e composizione senza eccezioni, sviluppatori e agenti AI consumano il sistema senza interprete umano
Insight Chiave
Delivery-grade è una proprietà economica, non estetica
Quando un contratto dà un prezzo ai valori hardcoded e agli stati mancanti, il craft smette di essere gusto e diventa un requisito misurabile. Questo riformula l'intero lavoro.
A rompersi a mano è la verifica, non la creazione
Controllare che 40 componenti per 5 stati per N property siano tutti tokenizzati correttamente è esattamente il compito in cui l'occhio umano fallisce e uno script no. Il collo di bottiglia è dimostrare, non disegnare.
Ancorare tutto all'uso reale
I componenti sono astrazioni, ma label, stati e contenuti devono venire dalle schermate approvate. Guardare la pagina, non solo la spec.
Lo sviluppatore è un utente a pieno titolo
Il consumo da Dev Mode è una user experience. Varianti prevedibili, token semantici e naming pulito sono le sue euristiche di usabilità.
Quando il sistema matura, la coerenza batte la fedeltà alla fonte
A metà progetto abbiamo invertito la gerarchia: il sistema Figma consolidato è diventato la base di coerenza, e le deviazioni del CSS dei prototipi si correggono verso il sistema, non il contrario.
Obiettivi e Principi
Ogni variante mappa su una prop
Property dei componenti (variant, size, state, disabled) progettate per tradursi 1:1 in props Vue, senza reinterpretazione.
Zero valori hardcoded
Ogni colore, spazio, raggio e stile tipografico applicato per riferimento a una Variable, e verificato da script.
Copertura completa degli stati
Set di stati a livello Carbon su ogni componente interattivo, inclusi focus e active, quelli che i sistemi costruiti a mano perdono sempre.
Consegna verificabile dalle macchine
I requisiti contrattuali espressi come asserzioni che uno script può controllare. Dalla fiducia a qualcosa che si può lanciare.
Principi guida
I token sono l'unico canale per l'aspetto
Due livelli, primitivi e ruoli semantici, e i componenti bindano solo ruoli. Quando una superficie ha una logica propria riceve una famiglia di ruoli dedicata, mai una presa in prestito.
Struttura flat, parti private
Niente tier atomici. Un registro unico; i sotto-componenti usati solo dentro altri portano il prefisso punto (.Table Row, .Tab), che per Figma significa privato.
Convenzioni senza eccezioni
Naming, property e composizione seguono le stesse regole su ogni componente. Le eccezioni sono il punto in cui i sistemi iniziano a morire.
Quiet luxury, reso operativo
Una palette nata da pigmenti del Rinascimento, niente bianco puro, e una regola di brand applicata ovunque: l'oro è identità, mai interazione.
Progettazione della Soluzione
Architettura token a due livelli in Figma Variables
Il contratto richiedeva stile applicato solo per riferimento, ma una lista piatta di variabili invita all'abuso: ruoli abbastanza simili presi in prestito per il lavoro sbagliato.
Una sorgente token DTCG compilata in due collection di Variables: i primitivi (la palette) e i ruoli semantici che li aliasano. I componenti bindano solo ruoli; i primitivi non compaiono mai in un componente.
I ruoli semantici rendono l'intento verificabile: un ruolo testo usato come sfondo è individuabile come anomalia. Quando una superficie ha avuto bisogno di logica propria (sidebar, inverse, avatar) ha ricevuto una piccola famiglia di ruoli dedicata che punta agli stessi primitivi: zero differenza visiva, piena chiarezza semantica.
Costruzione programmatica con un agente AI
Quaranta componenti con set di stati completi, size e property significano migliaia di micro-decisioni da applicare in modo identico. La costruzione a mano deriva, un componente alla volta, invisibilmente.
Ogni component set è generato da una ricetta esplicita (variante per stato per size, ognuno mappato su ruoli token) eseguita da un agente AI attraverso la Plugin API. Dopo ogni build: screenshot, controllo visivo, correzione, nuova verifica.
Le ricette rendono la coerenza strutturale invece che aspirazionale. Le label diventano property Text in automatico, i focus ring esistono perché la ricetta lo prevede, e la ventesima variante è costruita esattamente come la prima. L'agente ha anche assorbito le trappole della Plugin API (ordine delle operazioni, slot anomali, override delle istanze annidate) in una libreria di pattern riusabile.
Audit automatici sull'intero file
A questa scala dire che è tutto tokenizzato non si verifica a occhio. Il valore raw visivamente identico al token è invisibile in canvas.
Gli script di audit attraversano l'intero file e controllano ogni fill e ogni stroke di ogni nodo dentro ogni componente, a caccia di paint non collegati a una Variable, escludendo le istanze (riflettono il master e generano centinaia di falsi positivi) e filtrando per antenato per saltare i frame di documentazione.
Gli audit si sono ripagati subito: hanno trovato una libreria di 35 icone con i fill dei master raw quasi neri, visivamente indistinguibili dal token ed ereditati in silenzio da ogni istanza nel file. Nessuna revisione umana l'avrebbe visto. Un secondo giro ha esteso la scansione ai nodi contenitore e agli stroke, catturando un'altra classe di residui.
Registro flat con sotto-componenti privati
I tier dell'atomic design non sopravvivono alla pratica. Un atomo finisce dentro un altro atomo, e la gerarchia diventa una bugia che il team mantiene.
Un solo elenco di componenti, taggati per funzione (action, form, data, nav, overlay, layout). I sotto-componenti che vivono solo dentro altri portano il prefisso punto: privati in Figma, nascosti dal pannello assets.
La superficie pubblica della libreria è esattamente ciò che uno sviluppatore dovrebbe istanziare; gli interni restano interni. Il registro fa anche da inventario leggibile dalle macchine, con description su ogni componente.
Risultati e Impatto
~40 componenti riusabili in un registro flat, ognuno con stati interattivi completi (default, hover, focus, active, disabled)
190 design token come Figma Variables: primitivi aliasati da ruoli semantici, i componenti bindano solo ruoli
13 schermate di prototipo approvate sistematizzate
100% dei fill e degli stroke nei componenti collegati a Variables dopo gli audit, zero valori raw
Un bug sistemico di 35 icone trovato da script, invisibile alla revisione a occhio
Ogni label visibile esposta come property Text
Requisiti contrattuali verificati come asserzioni, non promessi in una nota di handoff
Ambiguità di stato eliminata: il tipo di errore che costa denaro reale agli operatori
Consumo da Dev Mode senza interprete umano: varianti prevedibili, token semantici, naming pulito
La conoscenza sopravvive agli handover: guidelines, standard dei componenti e registro viaggiano col repo
Il metodo stesso è diventato una toolchain riusabile: ricette, script di audit e pattern della Plugin API applicabili a qualsiasi sistema cliente
Riflessioni
Cosa ha funzionato
L'ancoraggio ai prototipi approvati
Non inventare mai una label o uno stato ha tenuto onesto il sistema e brevi le conversazioni col cliente: ogni componente poteva indicare la schermata da cui veniva.
Gli audit come infrastruttura di fiducia
Gli script di audit hanno cambiato il rapporto coi requisiti: invece di difendere la qualità del file potevo dimostrarla. Lancia questo batte qualsiasi deck di handoff.
Trattare il design system come software
Ricette, asserzioni, build riproducibili: le discipline che rendono affidabile il codice rendono affidabili anche le librerie. Questo è il progetto in cui ha smesso di essere un'analogia.
Sfide
La Plugin API è un campo minato di fallimenti silenziosi
Property di layout da impostare in un ordine preciso, slot che nascono con fill bianchi opachi, override che non si resettano dentro le istanze annidate, screenshot vecchi nelle sessioni lunghe. Ogni trappola è costata una sessione di debugging ed è diventata un pattern documentato e riusabile.
La verifica ha bisogno della sua propria verifica
Il primo giro di audit controllava solo vettori e testi, e ha mancato i fill raw sui nodi contenitore e sugli stroke. Auditare l'auditor (estendere i tipi di nodo, controllare gli stroke, escludere le istanze) è stato un progetto a sé.
Lezioni Chiave
Un design system è un insieme di affermazioni; un design system auditato è un insieme di prove
Gli agenti AI non sostituiscono il giudizio di design, lo rendono applicabile su scala
Possedere entrambi i lati dell'handoff, le decisioni di design e il codice che le verifica, è la competenza a maggior leva nel lavoro sui design system
I contratti che danno un prezzo alla qualità del design sono un regalo: rendono il craft misurabile, e il craft misurabile è difendibile
I bug più rari sono quelli invisibili: valori identici all'apparenza con semantiche diverse. Solo l'infrastruttura li becca