Design system · progetto personale
Grigna. Un design system per chi progetta e per agenti AI.
Un design system serve prima di tutto a chi progetta: dà a designer e sviluppatori le stesse regole, gli stessi nomi e gli stessi componenti. Grigna aggiunge un secondo lettore, l'agente AI. Le regole che rendono coerente il lavoro di un team sono le stesse che impediscono a un agente di inventare colori, spazi e componenti.
- 3 livellidi token, dal valore grezzo di partenza al componente multifunzione
- 7 componenti inizialiin HTML e CSS, senza framework, pronti a crescere
- Light e Dark modestessi nomi, valori diversi
Sei principi
Sei idee guidano Grigna, i principi da tenere sempre alla base per la progettazione e per l'utilizzo dei componenti iniziali. Quando una regola più specifica non copre un caso, si decide partendo da qui.
- 01Il sistema è il contesto.Ogni scelta è scritta, ha un nome ed è verificabile da uno script, non solo da un occhio esperto.
- 02Pulito e luminoso.Superfici chiare, molto spazio, un solo colore d'accento. La UI è al servizio dei puri contenuti.
- 03Il colore ha sempre un significato.Il verde abete indica l'azione. Gli altri colori servono solo a dare un riscontro: successo, attenzione, errore o informazione.
- 04Accessibile per costruzione.Contrasto, area di tocco e focus sono regole controllate, non buone intenzioni.
- 05Meno scelte, più coerenza.Spazi, misure e colori si scelgono con un razionale. Se un valore manca, non si scrive a mano: si aggiunge al sistema, per tutti.
- 06Niente contenuti inventati.Gli esempi usano segnaposto chiari. E un dato che manca non si mostra: niente trattini, «n.d.» o stime.
Componenti
Sette componenti iniziali, in HTML e CSS senza framework. Ogni pagina della documentazione ha le stesse sezioni nello stesso ordine: esempio dal vivo, quando usarlo e quando no, codice, varianti e stati, token, accessibilità, regole per gli agenti.
Scegli un componente e guarda i suoi stati. Gli esempi sono veri, non immagini.
Ogni componente dice anche quando non usarlo.
Accessibile per costruzione
L'accessibilità in Grigna non è frutto di una revisione finale: è scritta nei token fin dall'inizio ed è controllata dalla build.
- Contrasto
- 4,5:1 per il testo, 3:1 per bordi e grafica. Se un abbinamento non passa, la build si ferma.
- Area di tocco
- Almeno 44px per ogni elemento interattivo.
- Testo
- Il testo corrente non scende mai sotto i 16px.
- Focus
- Sempre visibile da tastiera, con lo stesso anello verde ovunque.
- HTML nativo
- Un pulsante per le azioni, un link per la navigazione, un'etichetta per ogni campo, details per l'accordion.
- Mai solo colore
- Ogni colore con un significato è accompagnato da un testo, un'icona o una forma.
Prova a togliere i colori: lo stato dei badge, il filtro attivo e l'errore si capiscono lo stesso, grazie a testo, spunta e messaggio.
Un'informazione che passa solo dal colore non arriva a tutti.
Un DS anche per agenti AI
Le pagine della documentazione si chiudono con una sezione «Per gli agenti»: regole brevi, nomi esatti di classi e token e cosa non inventare mai.
- Per le persone
- Il perché delle scelte, quando usare un elemento e quando no, esempi giusti e sbagliati.
- Per gli agenti
- Un file di regole (AGENTS.md), una versione Markdown accanto a ogni pagina, llms.txt e tutti i token in un file solo.
- Un controllo automatico
- Legge una pagina e segnala ogni colore, spazio o dimensione scritto a mano.
- Quando il sistema non basta
- L'agente non improvvisa: usa la soluzione più vicina e dichiara cosa mancava. Le aggiunte le decide una persona.
Sempre
- Un solo bottone primary per vista.
- Un testo che comincia con un verbo.
Mai
- Mai colori, bordi o spazi personalizzati sul bottone.
- Mai un div cliccabile al posto di un bottone.
Le regole che tengono coerente un team sono le stesse che servono a un agente.
Token e temi
Tre livelli, dal valore grezzo al componente. Light e Dark mode usano gli stessi nomi; cambia solo il valore. Formato standard W3C Design Tokens.
- 01 · Primitivoabete 500
color.abete.500Il valore grezzo. Non si usa direttamente. - 02 · Semanticoaccento
color.accent.defaultUn valore con un significato. - 03 · Componentesfondo del bottone primary
button.primary.bgIl valore di un componente. Punta solo ai semantici.
In Dark mode lo stesso accento punta a un altro verde, abete 300: il bottone non cambia nome, cambia valore.
Grigna DS alla prova con due agenti AI
Un design system ben strutturato plasma quello che un agente può costruire? Ho voluto stressare l'ideazione UI di una pagina di esempio costruita da due agenti, con la stessa richiesta: prevedere un elenco di schede e renderle filtrabili in base alle informazioni contenute.
Uno lavorava senza un framework a disposizione, l'altro utilizzando Grigna. Entrambi privi di dati reali. Sono emerse parecchie riflessioni interessanti, che ho voluto riportare qui.
Va detto con onestà: la pagina senza sistema era più bella, più ricca e «da prodotto». Il sistema non l'ha resa più bella. L'ha resa coerente, verificabile e onesta.
| — | Nessun framework di riferimento | Con Grigna |
|---|---|---|
| Valori scritti a mano, fuori da ogni sistema: colori, spazi, dimensioni | 142 | 0 |
| Colori diversi scritti a mano | 44 | 0 |
| Dimensioni del testo diverse | 11 | Le 9 di Grigna |
| Contenuti | 14 schede con luoghi veri e informazioni inventate, presentate come reali | Nessun dato inventato: testi segnaposto ben riconoscibili e un avviso in cima alla pagina che dice che i dati non sono reali |
La prova ha trovato anche i limiti di Grigna. L'agente ha elencato da solo cosa mancava invece di improvvisare. Da lì sono nati sei interventi, già applicati al sistema:
- 01Un componente per i segnaposto.L'agente aveva copiato a schermo gli esempi della documentazione, con le graffe del codice: «{distanza} km». Ora c'è un componente Segnaposto con un formato chiaro, e una regola: le graffe non arrivano mai a schermo.
- 02I token di layout che mancavano.Per la larghezza massima della pagina e quella minima delle schede non c'era un token: l'agente ha scritto i valori a mano e l'ha dichiarato. Ora sono token del sistema, con un punto di rottura a 768px.
- 03Componenti che si nascondono davvero.Alcuni componenti restavano visibili anche con l'attributo hidden. Ora tutti lo rispettano.
- 04Un filtro che regge molte opzioni.Un gruppo con 16 opzioni era troppo lungo da leggere e da usare. Ora c'è uno schema: le opzioni si dividono in gruppi e si mostra solo quello che serve.
- 05Un controllo automatico più severo.Il controllo non aveva visto due misure scritte a mano dall'agente con Grigna. Ora verifica anche larghezze, griglie e graffe rimaste a schermo.
- 06Regole di lavoro più precise.L'agente aveva aggiornato da solo i file di lavoro del sistema anche durante la prova. Ora lo fa solo quando lavora davvero su Grigna.
Una demo convincente non è una base su cui costruire.