Un design system verificabile per una maison del lusso
Dai prototipi HTML/CSS a una libreria Figma che gli sviluppatori potessero usare senza reinterpretare ogni scelta, con token, componenti e controlli automatici.
- Ruolo
- Design Engineer, Design Systems
- Team
- Design engineer solo, con il team dell'agenzia e gli sviluppatori del cliente
- Durata
- 2026 · in corso
- Cliente
- Maison del lusso fiorentina (via agenzia, sotto NDA)
Il progetto in un minuto
La Sfida
Le schermate approvate dovevano diventare una libreria coerente e implementabile, preservandone i comportamenti.
Il mio contributo
Ho tradotto 13 schermate approvate in architettura dei token, libreria di componenti e script di verifica automatica.
Risultati e portata
Un audit dell’intero file ha individuato colori non collegati ai token nei master di 35 icone: un difetto invisibile a occhio che si propagava alle istanze.
01Osservazione
Un colore libero può apparire identico a uno collegato a un token.
02Interpretazione
L’uguaglianza visiva non dimostra la coerenza strutturale.
03Scelta progettuale
Verificare riempimenti e bordi di ogni componente rispetto al sistema di Variables.
Lettura del progetto ricostruita dal case study, non un artefatto originale di ricerca.
Cosa resta da verificare: Sono verifiche di consegna, non riduzioni misurate dei costi di sviluppo o degli errori degli operatori.
La Sfida
Di cosa mi sono occupato
- Estratto e razionalizzato il design system da 13 schermate di prototipo HTML/CSS approvate
- Progettato l'architettura dei token: sorgente DTCG compilata in Figma Variables, primitivi aliasati da ruoli semantici
- Costruito la libreria di componenti programmaticamente via Figma Plugin API, orchestrando un agente AI
- Definito lo standard di completezza (benchmark IBM Carbon) e le convenzioni di nomenclatura e struttura
- Scritto gli script di audit sull'intero file che verificano i requisiti contrattuali come asserzioni
- Mantenuto registro componenti, linee guida e documentazione di consegna
Le schermate approvate descrivevano il prodotto, ma non ancora le regole necessarie per costruirlo in modo coerente. Il design system doveva rendere espliciti token, varianti, Auto Layout e naming in una forma direttamente utilizzabile nello sviluppo.
Il punto di partenza erano tredici schermate HTML/CSS già approvate per un PIM, il software con cui gli operatori preparano il catalogo moda per i diversi canali di vendita. Il mio compito era ricavarne una libreria Figma abbastanza precisa da diventare il riferimento per lo sviluppo in Vue.
Il file aveva quindi due utenti: chi avrebbe usato il PIM e chi avrebbe dovuto costruirlo. Per lo sviluppatore contavano soprattutto stati espliciti, token coerenti, proprietà prevedibili e componenti che non richiedessero interpretazioni aggiuntive.
Questa precisione aveva anche un peso contrattuale. Il contratto prevedeva requisiti specifici per il file di consegna; se non fossero stati rispettati, tempi e costi di sviluppo avrebbero potuto essere rivisti.
"Gli operatori lavorano per ore su un'interfaccia densa, mentre gli sviluppatori devono tradurre quella stessa interfaccia in componenti Vue. Per entrambi, ambiguità e stati mancanti diventano errori o domande da risolvere durante l'implementazione."
Il rischio maggiore erano i componenti che sembravano corretti ma sotto la superficie seguivano regole diverse: valori hardcoded, token aggirati o stati costruiti in modo non uniforme.
Nei prototipi i valori erano spesso ripetuti inline, gli stati interattivi non erano completi e il naming era nato schermata per schermata. Ricostruire tutto manualmente in Figma avrebbe rischiato di trasferire le stesse incoerenze nella libreria.
Ricerca
Analisi dei prototipi
~40 componenti riusabili
Identificati nei prototipi e separati dalle composizioni di schermata e dal codice morto: è ciò che il sistema doveva coprire davvero
190 design token
Derivati e strutturati come sorgente DTCG: primitivi colore e ruoli semantici, spacing, raggi, tipografia
Etichette e contenuti presi dalle schermate approvate
Ogni componente parte da casi reali: etichette, stati e contenuti vengono dalle schermate approvate e non da esempi inventati per la libreria
Focus e active mancanti ovunque
I prototipi coprivano al massimo default, hover e disabled. Mancavano proprio gli stati da cui dipende l'accessibilità.
Benchmark di completezza
Cinque stati per ogni controllo interattivo
Ho adottato lo standard di Carbon: default, hover, focus, active e disabled per ogni controllo interattivo, più l'anatomia error, warning e read-only per il data entry
Le stesse regole su tutti i componenti
Da Astryx ho ripreso un'idea: se ogni componente segue le stesse regole di nomenclatura, proprietà e composizione, sviluppatori e agenti AI possono usare il sistema senza che qualcuno debba spiegarlo
Insight Chiave
La qualità del file aveva un costo
Il contratto attribuiva un costo ai valori scritti direttamente nel file e agli stati mancanti. La qualità del file andava quindi verificata come qualsiasi altro requisito.
Il problema era verificare la coerenza del file
Controllare a mano decine di componenti, stati e proprietà porta facilmente a errori. Disegnare i componenti era la parte più semplice; la difficoltà era verificare che fossero tutti costruiti con le stesse regole.
Ogni componente parte da una schermata approvata
Per ogni componente ho ripreso etichette, stati e contenuti dalle schermate approvate, controllando la pagina oltre alla specifica.
Ho progettato la libreria pensando anche a chi l'avrebbe implementata
Anche Dev Mode ha una sua esperienza d'uso: varianti prevedibili, token semantici e nomi chiari riducono domande e interpretazioni durante lo sviluppo.
A metà progetto il sistema Figma è diventato il riferimento
A metà progetto abbiamo invertito la gerarchia: il sistema Figma consolidato è diventato il riferimento, e da lì in poi le differenze nel CSS dei prototipi sono state corrette per allinearle al sistema.
Obiettivi e Principi
Ogni variante corrisponde a una prop
Le proprietà dei componenti (variant, size, state, disabled) sono progettate per tradursi 1:1 in prop Vue, senza reinterpretazione.
Zero valori scritti direttamente nel file
Ogni colore, spazio, raggio e stile tipografico applicato per riferimento a una Variable, e verificato da script.
Copertura completa degli stati
Set di stati al livello di Carbon su ogni componente interattivo, compresi focus e active, che nei prototipi mancavano.
Controlli automatici sul file di consegna
I requisiti contrattuali sono tradotti in controlli che uno script può eseguire sul file.
Principi guida
Colori, spazi e tipografia passano sempre dai token
Due livelli, primitivi e ruoli semantici; i componenti usano solo i ruoli. Quando una superficie ha una logica propria riceve una famiglia di ruoli dedicata, invece di riusarne una pensata per altro.
Struttura piatta, parti private
Nessuna gerarchia atomica. Un registro unico; i sotto-componenti usati solo dentro altri portano il prefisso punto (.Table Row, .Tab), che per Figma significa privato.
Le stesse regole su ogni componente
Naming, proprietà e composizione seguono le stesse regole su ogni componente. Quando serve un'eccezione, viene resa esplicita.
Le regole del brand dentro la libreria
Una palette nata da pigmenti del Rinascimento, niente bianco puro e una regola di brand applicata ovunque: l'oro identifica il marchio e non si usa per gli elementi interattivi.
Progettazione della Soluzione
Schema interattivo
Dal token agli stati del componente
Seleziona un nodo per evidenziarne i collegamenti e leggere la scelta progettuale.
Valore di base
Una primitiva contiene un valore riutilizzabile. Il suo aspetto non ne spiega da solo la funzione.
Collegato a: Token semantico
Ricostruzione concettuale del legame tra token e componenti, non un inspector Figma live.
Token a due livelli in Figma Variables
Il contratto richiedeva stile applicato solo per riferimento, ma una lista piatta di variabili rende facile riutilizzare un ruolo solo perché sembra abbastanza simile, anche quando ha un significato diverso.
Alternative considerate
- Solo stili Figma (niente token numerici, Dev Mode debole)
- Una sola collection piatta di Variables (semplice, ma i ruoli finiscono usati per scopi diversi)
- Architettura a due livelli: primitivi aliasati da ruoli semantici
Una sorgente token DTCG compilata in due collection di Variables: i primitivi (la palette) e i ruoli semantici che li aliasano. I componenti usano solo i ruoli; i primitivi non compaiono mai in un componente.
Con i ruoli semantici l'intento si può verificare: un ruolo testo usato come sfondo si individua come anomalia. Quando una superficie ha avuto bisogno di una logica propria (sidebar, inverse, avatar) ha ricevuto una piccola famiglia di ruoli dedicata che punta agli stessi primitivi: a schermo non cambia nulla e il ruolo resta riconoscibile.
Compromesso: Più lavoro di naming all'inizio, e nei momenti in cui manca un ruolo bisogna crearlo invece di prenderlo in prestito. È un passaggio in più, ma impedisce che il livello semantico perda significato nel tempo.
Costruzione programmatica con un agente AI
Quaranta componenti con set di stati completi, dimensioni e proprietà significano migliaia di micro-decisioni da applicare in modo identico. Costruendoli a mano, le differenze si accumulano un componente alla volta senza che nessuno se ne accorga.
Alternative considerate
- Build manuale con checklist (a questa scala le differenze si accumulano)
- Script una tantum per componente (meglio, ma non verificato)
- Un agente AI che guida la Plugin API di Figma da ricette esplicite, con loop di verifica visiva
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.
Con le ricette, la coerenza non dipende più dalla memoria di chi costruisce il componente. Le etichette diventano proprietà Text in automatico, i focus ring esistono perché la ricetta li prevede e la ventesima variante è costruita esattamente come la prima. L'agente ha anche raccolto le trappole della Plugin API (ordine delle operazioni, slot anomali, override delle istanze annidate) in una serie di pattern riusabili.
Compromesso: La Plugin API fallisce spesso senza segnalare errori: proprietà di layout che dipendono dall'ordine, slot che nascono con fill opachi, override che non si resettano nelle istanze annidate. Ognuno è costato una sessione di debugging, una volta sola, ed è diventato un pattern documentato.
Audit automatici sull'intero file
A questa scala non si può verificare a occhio che tutto sia tokenizzato. Un valore raw identico al token non si distingue in canvas.
Alternative considerate
- Revisione a occhio (non vede i valori raw identici ai token)
- Controlli a campione sui componenti chiave (i campioni mancano i bug sistemici)
- Scansioni scriptate di ogni nodo del file
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 sono serviti subito: hanno trovato una libreria di 35 icone con i fill dei master raw quasi neri, identici a occhio al token ed ereditati in silenzio da ogni istanza nel file. In una revisione visiva sarebbe stato impossibile notarlo. Un secondo giro ha esteso la scansione ai nodi contenitore e agli stroke, e ha trovato un'altra classe di residui.
Compromesso: Gli script di audit sono codice: vanno mantenuti, e abbiamo dovuto imparare a riconoscere i loro falsi positivi. In cambio, chiunque può rilanciarli e verificare i requisiti contrattuali.
Registro piatto con sotto-componenti privati
Nella pratica i livelli dell'atomic design reggono poco: un atomo finisce dentro un altro atomo e la gerarchia smette di descrivere come sono fatti davvero i componenti.
Alternative considerate
- Atomic design (atomi, molecole, organismi)
- Organizzazione improvvisata per pagina
- Registro piatto con sotto-componenti privati col prefisso punto
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.
Compromesso: I tag di funzione sono meno strutturati dei livelli atomici, ed è una scelta voluta: la tassonomia descrive a cosa serve ogni componente.
Risultati e Impatto
La consegna finale può essere controllata con gli stessi criteri con cui è stata costruita. Gli audit verificano token, naming e struttura del file e hanno già individuato incoerenze che a occhio apparivano corrette, come colori raw usati dentro alcuni master di icone.
~40 componenti riusabili in un registro piatto, ognuno con stati interattivi completi (default, hover, focus, active, disabled)
190 design token come Figma Variables: primitivi aliasati da ruoli semantici, i componenti usano solo i 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 etichetta visibile esposta come proprietà Text
Requisiti contrattuali verificati da script invece che dichiarati in una nota di handoff
Nessuno stato lasciato ambiguo, un tipo di errore che per gli operatori ha costi concreti
In Dev Mode il file si legge senza bisogno di spiegazioni: varianti prevedibili, token semantici, nomi coerenti
Linee guida, standard dei componenti e registro stanno nel repo e restano disponibili dopo l'handoff
Ricette, script di audit e pattern della Plugin API sono riutilizzabili su altri sistemi cliente
Cosa ho realizzato
- Libreria Figma: collection di Variables e component set con stati completi
- Sorgente token DTCG (versionata col progetto)
- Script di audit sull'intero file (colori raw, struttura, naming)
- Documentazione: linee guida Figma e standard dei componenti
- Registro componenti leggibile dalle macchine
- State recipes che documentano la mappatura token di ogni variante
Riflessioni
Gli audit sono stati più utili sulle regole difficili da vedere a occhio; dove duplicavano una revisione visiva aggiungevano poco.
Costruire i componenti via API ha accelerato il lavoro solo perché token, naming e stati erano stati definiti prima.
Cosa farei diversamente
- Lanciare gli audit dal primo giorno: il bug delle 35 icone è emerso tardi, quando le istanze si erano già diffuse nel file
- Definire prima le famiglie di ruoli dedicate alle superfici speciali (sidebar, inverse), invece di scoprire in revisione i ruoli presi in prestito
- Strumentare il registro componenti dall'inizio invece di ricostruire la copertura a metà progetto
Cosa ha funzionato e quali difficoltà ho incontrato
Cosa ha funzionato
Partire dai prototipi approvati
Non ho mai inventato un'etichetta o uno stato: ogni componente poteva indicare la schermata da cui veniva, e questo ha reso brevi le conversazioni col cliente.
Gli audit hanno cambiato il confronto sui requisiti
Invece di argomentare che il file rispettava i requisiti, potevo far girare uno script e mostrare il risultato.
Costruire la libreria con i metodi del software
Ho usato ricette, asserzioni e build riproducibili, le stesse pratiche con cui si rende affidabile il codice, applicandole direttamente alla libreria Figma.
Sfide
La Plugin API fallisce spesso senza segnalare errori
Proprietà 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.
Anche gli audit andavano verificati
Il primo giro di audit controllava solo vettori e testi, e non ha visto i fill raw sui nodi contenitore e sugli stroke. Correggere gli audit stessi (estendere i tipi di nodo, controllare gli stroke, escludere le istanze) ha richiesto un lavoro a parte.
Prossimo progetto
Ricerca CBDC: un sistema qualitativo e quantitativo