Interfaccia coerente nelle app React con token di design e regole

Perché le schermate React generate spesso sembrano incoerenti

L'incoerenza nell'interfaccia si nota solitamente in piccoli dettagli che appaiono strani mentre navighi. Una pagina ha padding generoso, un'altra è troppo stretta. I titoli cambiano dimensione, i pulsanti cambiano forma e colore, e lo stesso input si comporta diversamente a seconda della schermata.

Il più delle volte, il drift deriva da poche cose di base:

• Spaziatura: padding, gap e ritmo delle sezioni che variano
• Tipografia: dimensioni, pesi e altezza riga instabili
• Componenti: pulsanti, card, bordi e ombre che cambiano leggermente
• Form: tempistica della validazione, posizione degli errori e stati disabilitati diversi

Questo è comune quando le schermate sono generate da prompt separati. Ogni prompt è praticamente un nuovo inizio, quindi il modello colma le decisioni mancanti a colpi di supposizioni. Anche “usa uno stile moderno” lascia centinaia di piccole scelte: gap da 8px o 12px, testo corpo 14px o 16px, quando mostrare gli errori, come è fatto un primary button.

Puoi correggere manualmente due o tre pagine, ma non scala. Finirai a rincorrere tweak CSS una tantum, copiare stili tra file e rifissare i form. Le regole sono nella tua testa, non nel progetto.

Immagina di generare oggi una schermata di login e domani una di profilo. Se una mostra gli errori solo al submit e l'altra al blur, gli utenti lo notano. Se l'altezza del primary button cambia tra le schermate, l'app sembra rattoppata.

La coerenza diventa il comportamento predefinito quando ogni schermata segue lo stesso sistema condiviso: token di design (spaziatura, tipografia, colori) più un piccolo set di regole per componenti e form.

I design token in parole semplici

I design token sono semplici valori nominati che riusi in tutta l'interfaccia. Invece di chiedere “padding confortevole” su ogni schermata, usi un token come space-4. Invece di “leggermente arrotondato”, usi radius-md. Il nome resta stabile anche se poi cambi il valore a cui punta.

I token sono l'insieme di decisioni che vuoi che ogni schermata condivida. Eliminano il gusto personale e le supposizioni, che sono esattamente ciò che causa il drift quando generi o costruisci nuove pagine.

I token tipici coprono spaziatura, tipografia, colori, forma e una piccola quantità di elevazione. Il vantaggio è pratico: un header usa sempre la stessa dimensione, una card usa sempre lo stesso padding e un primary button mantiene lo stesso colore e raggio.

Cosa tokenizzare e cosa lasciare flessibile?

Tokenizza le cose che influenzano il feeling generale del prodotto: scala di spaziatura, dimensioni dei font e altezza riga, colori core (testo, sfondo, primary, danger, bordo) e un piccolo set di raggi di bordo.

Lascia flessibili le scelte guidate dal contenuto, come la lunghezza del testo, quale icona usare o se una sezione necessita di due o tre card.

Quando generi schermate (inclusi strumenti come Koder.ai), fornire un piccolo set di token all'inizio riduce la quantità di congetture e rende l'output visibilmente più coerente.

Scegliere un set di token piccolo ma completo

Un set di token è solo un breve menù di valori consentiti. Più è piccolo, meglio è perché lascia meno spazio a scelte casuali, ma deve comunque coprire le basi che fanno sembrare le schermate sbagliate.

Inizia dalla spaziatura. Scegli una scala e usala ovunque per padding, gap e layout. Un set come 4, 8, 12, 16, 24, 32 copre la maggior parte delle UI. Se un design richiede 10px o 18px, arrotonda al token più vicino invece di introdurre nuovi numeri.

Poi definisci i default tipografici così titoli e corpo smettono di deragliare. Non ti serve un enorme sistema tipografico: ti servono passi chiari e ripetibili.

Un set compatto e ancora utile:

• Spaziatura: 4, 8, 12, 16, 24, 32
• Tipo: una dimensione corpo, due dimensioni per i titoli, un'altezza riga per il corpo, una per i titoli
• Colori: text-primary, text-muted, bg, surface, border, accent
• Raggio: due valori (per esempio 4 e 12)
• Elevazione: none, small, medium (massimo tre livelli)

L'accessibilità appartiene al sistema. Definisci uno stile di outline per il focus (colore, spessore, offset) così gli utenti da tastiera ottengono stati di focus coerenti. Imposta un target minimo tocco (es. 44x44) per mobile. Limita i colori del testo a un piccolo set fidato per mantenere il contrasto prevedibile.

Se i pulsanti a volte sembrano stretti, spesso è perché una schermata ha usato padding 10 e un'altra 12. Con i token puoi dire: “I pulsanti usano paddingY=8, paddingX=16, radius=12, token per outline focus, altezza minima 44.” Una volta fissati quei numeri, il generatore smette di improvvisare.

Regole dei componenti che mantengono allineate tutte le schermate

I token fissano i numeri. Le regole dei componenti fissano le abitudini.

Scegli un piccolo set di componenti core e trattali come gli unici mattoni per le schermate. Mantienili noiosi e riutilizzabili: Button, Input, Select, Checkbox, Card. Puoi aggiungere TextArea e Modal, ma dovrebbero seguire lo stesso sistema (etichette, spaziatura, stati).

Poi limita le varianti e definisci quando sono permesse. Per esempio: Button ha primary, secondary e danger. Primary è per l'azione principale della schermata (di solito una). Secondary è per annulla o azioni a bassa priorità. Danger solo per azioni distruttive come delete. Se una variante non si giustifica, torna alla secondary.

Le regole di spaziatura prevengono il drift sottile. Definisci default all'interno dei componenti: padding del Button, altezza dell'Input, gap etichetta-campo, il gap standard tra campi impilati. Aggiungi anche poche regole di layout: le Card hanno padding interno fisso e spaziatura header/body coerente; i Modal usano gli stessi step di larghezza e l'allineamento del footer è costante.

Infine, rendi gli stati non negoziabili perché è qui che le UI iniziano a sembrare casuali:

• Loading: disabilita il controllo, mostra uno spinner, mantieni la larghezza stabile
• Disabled: contrasto ridotto, ma non rimuovere del tutto hover/focus
• Empty states: messaggio breve più una chiara azione
• Validation: gli errori appaiono sotto i campi e non causano grandi shift di layout

Quando generi una schermata ricca di form come “Create project”, queste regole evitano mix di dimensioni dei pulsanti, posizioni delle etichette che saltano o una “card speciale” presente solo in una pagina.

Regole sul comportamento dei form: i dettagli che di solito deragliano

Anche con visual stabili, molte sensazioni di “non va bene” provengono dal comportamento dei form. Se ogni schermata gestisce etichette, errori e focus diversamente, gli utenti lo percepiscono come incoerenza.

Scegli un pattern per i form e usalo ovunque: etichetta, indicatore opzionale/obbligatorio, helper text, poi testo di errore. Mantieni anche il linguaggio coerente (es. etichette in sentence case, helper brevi e messaggi di errore che iniziano con un verbo).

Le regole che prevengono la maggior parte del drift:

• Etichette sempre sopra i campi (non placeholder), indicatore required sull'etichetta
• Helper text sempre sotto il campo, stessa dimensione e colore, mai usato per errori
• Tempistica di validazione: mostrare errori dopo blur o submit, cancellarli al change
• Posizione degli errori: una riga d'errore direttamente sotto il campo, allineata con l'helper text
• Comportamento del focus: ordine di tab segue il layout visivo; Enter invia solo sull'ultimo campo o quando il primary button è attivo

Blocca dimensioni e layout così le schermate non “respirano” in modo diverso. Definisci un'altezza unica per gli input, un'altezza per i pulsanti e una larghezza di campo di default. Su desktop allinea i campi a una griglia coerente e impila le etichette sopra gli input. Su mobile rendi i campi full width ed evita form a due colonne a meno che non sia davvero necessario.

Un esempio semplice: una schermata “Create project” potrebbe avere Name, Region e Description. Anche se Region è una select, trattala come un altro campo: stessa altezza, stessa posizione dell'etichetta, stessa riga d'errore. Se l'utente invia con Name vuoto, il focus si sposta su Name, l'errore appare sotto e il layout resta stabile.

Se generi schermate in Koder.ai, metti queste regole dei form nel prompt una volta e riusale tra le feature così ogni nuovo form si comporta allo stesso modo senza pulizie ripetute.

Come esprimere token e regole nel tuo prompt

Tratta il prompt come un piccolo contratto UI. Mantienilo corto, specifico e riutilizzabile così ogni nuova schermata si allinea alla stessa spaziatura, tipografia, componenti e comportamenti.

Un pattern pratico è incollare una spec UI compatta in cima alla richiesta, poi descrivere la schermata in linguaggio naturale.

Un template compatto per il prompt

UI SPEC (apply to every screen)
Tokens:
- Spacing: 4, 8, 12, 16, 24, 32
- Radius: 8
- Typography: H1 24/32, H2 18/26, Body 14/20
- Colors: text, muted, bg, primary, danger (no custom hex)

Components (must use): PageShell, Section, Card, Button, Input, Select, TextArea, FormRow, HelperText, Toast

Layout rules:
- Page padding: 24 desktop, 16 mobile
- Section spacing: 24
- Card padding: 16
- Grid: 12 cols desktop, 4 cols mobile, gap 16

Do:
- Reuse components and tokens only
- Keep labels above inputs, helper text below

Do not:
- Invent new spacing values, font sizes, or one-off CSS
- Mix different button heights or input styles

If a new component is needed:
- Extend an existing component pattern and document it in the output
- Do not create new visual styles outside tokens

Dopo la spec, aggiungi alcuni controlli di accettazione che catturano il drift presto:

• “Usa solo i token sopra; niente stili inline.”
• “Tutti i form devono usare FormRow e mostrare gli errori allo stesso modo.”
• “Se devi aggiungere un componente, basalo su Card più la tipografia esistente.”

Se usi un generatore in chat, mantieni questa spec stabile tra le richieste. Cambiarla ogni volta vanifica lo scopo.

Un workflow che mantiene le schermate coerenti

Scrivi il contratto UI prima di generare qualsiasi cosa: un piccolo set di token (spaziatura, tipo, colori, raggio, ombre) più un inventario corto di componenti (Button, Input, Select, Card, Modal, Table, Toast). Se manca un token o un componente, il modello ne inventerà uno e la tua UI deraglierà.

Poi crea una schermata di riferimento che metta alla prova le regole. Una pagina ricca di form è un buon stress test perché include header, helper text, errori di validazione, pulsanti primari e secondari e un toast di successo. Tratta quella schermata come baseline.

Da lì costruisci nuove schermate componendo ciò che hai già definito. Non chiedere “nuovo styling”. Chiedi la stessa Card, la stessa scala di spaziatura, gli stessi passi tipografici e lo stesso pattern di campo.

Un workflow semplice:

• Conferma token e regole dei componenti, poi congelale per la feature
• Genera una schermata di riferimento e aggiusta la spec finché non va bene
• Costruisci nuove schermate riusando componenti, non restyling
• Revisiona per coerenza, poi cambia le regole (token/componenti), non i pixel
• Salva lo spec come snippet riutilizzabile per la prossima feature

Se una schermata “Search users” finisce con spaziatura più stretta della reference, non sistemare i margini manualmente. Aggiorna i token di spaziatura o la regola di padding della Card una volta, poi rigenera.

Se lavori in Koder.ai, snapshot e rollback possono aiutare: blocca una baseline, sperimenta in sicurezza e ripristina rapidamente se un cambiamento inizia a introdurre drift.

Errori comuni da evitare

Il modo più rapido per perdere coerenza è trattare token e regole come suggerimenti. Le piccole eccezioni si moltiplicano nelle nuove schermate.

Una trappola comune è cambiare la scala di spaziatura a metà progetto. Le prime schermate usano 8, 16, 24. Una nuova schermata introduce 10 e 18 “perché sembra giusto”. Ora il drift è permesso e le vecchie schermate non vengono aggiornate.

Un'altra fonte di drift è lasciare che il generatore inventi nuovi stili di componente. Se non dichiari “esistono solo queste varianti di pulsante”, potrebbe crearne una con raggio diverso o padding differente in una singola schermata.

Gli stati sono un altro errore frequente. Loading, empty ed error state spesso cambiano spaziatura e comportamento. Se li aggiungi alla fine, ottieni pattern affrettati che non corrispondono al resto.

Controlla anche il livello di specificità sbagliato: “fallo moderno con ombre morbide” è vago, mentre regole di comportamento come “gli errori mostrano sotto il campo”, “i pulsanti disabilitati mantengono gli stili di focus” e “Enter invia solo sull'ultimo campo” sono concrete e ripetibili.

Se vuoi un blocco leggero da incollare nei prompt, tienilo corto:

• Usa la stessa scala di spaziatura e token tipografici delle schermate esistenti; non inventare nuovi valori
• Usa solo componenti e varianti approvati
• Includi loading, empty ed error state usando gli stessi token
• Specifica i comportamenti (validazione, ordine del focus, submit, disabilitato) con la stessa chiarezza delle regole visive

Checklist rapida di coerenza prima di accettare una schermata

Prima di mergiare una schermata generata, fai una scansione di due minuti.

Inizia dalla spaziatura. Cerca valori casuali come 13px o margini one-off aggiunti “solo per farlo entrare”. Se usi token, ogni gap dovrebbe provenire dal set approvato, compresi gutter, padding delle card e spaziatura tra i campi del form.

Poi controlla la tipografia rispetto alla scala. I titoli devono diminuire in modo prevedibile. Il testo corpo non dovrebbe cambiare dimensione tra sezioni simili. Anche l'altezza riga conta, specialmente su schermate dense come le pagine di impostazioni.

Controlla i pulsanti. Varianti e dimensioni devono seguire le regole: primary per l'azione principale, secondary per azioni meno importanti, danger solo quando cancella veramente. Altezza del pulsante, posizione dell'icona e stile dell'etichetta devono corrispondere.

Per i form, la coerenza è soprattutto struttura. Le etichette rimangono in un posto, gli indicatori required seguono una regola, helper text ed errori non competono e gli errori appaiono in un punto coerente.

Una checklist breve:

• La spaziatura usa solo valori token (niente numeri casuali)
• La tipografia rispetta la scala (inclusa l'altezza linea)
• I pulsanti seguono le stesse varianti e dimensioni
• I form usano un unico pattern per etichette, helper text ed errori
• Esistono gli stati: hover, focus, disabled, loading, empty

Infine, fai un rapido controllo mobile. Riduci la larghezza e conferma che il layout si adatta senza inventare nuove dimensioni di font o spaziature.

Esempio: generare una piccola feature React senza drift di stile

Immagina un semplice flusso di onboarding: tre schermate (Profile, Preferences, Confirm), più una pagina Settings in seguito. Vuoi che ogni schermata dia l'impressione di essere stata progettata dalla stessa persona, anche se è stata generata in esecuzioni separate.

Prima di generare, fornisci un piccolo set di token e qualche regola componente:

TOKENS
- spacing: xs=4, sm=8, md=12, lg=16, xl=24
- radius: sm=8, md=12
- type: body=14/20, title=20/28, label=12/16
- layout: pageMax=960, sectionGap=24, fieldGap=12

COMPONENT RULES
- Page: max width=pageMax, padding=xl, sectionGap between blocks
- Card: padding=lg, radius=md
- Field: label above, helper below, fieldGap between fields
- Button row: primary on right, gap=sm
- Errors: shown under field, same copy style, no alerts

Genera ora “Profile” e “Preferences” separatamente. Poiché entrambe le schermate devono usare Page, Card, Field e Button row come definiti, arriveranno con gli stessi margini, spaziatura delle etichette e posizione dei pulsanti. Il passaggio Confirm si adatterà, anche se contiene più testo in sola lettura.

Il comportamento dei form è dove spesso entra il drift, quindi definiscilo una volta e riusalo: submit disabilitato finché non è valido, errori inline solo dopo blur o submit, Enter invia solo nell'ultimo step e il pulsante Back non cancella i valori già inseriti.

Quando serve un nuovo elemento UI, non lasciare che il modello improvvisi. Aggiungi una regola e poi rigenera pensando al riuso:

• ProgressStepper: altezza=32, spaziatura=md, step corrente bold, step completati cliccabili

Prossimi passi: rendi la coerenza il comportamento predefinito

Trasforma token e regole in una spec riutilizzabile che usi davvero. Se è troppo lunga da incollare, non verrà seguita.

Una spec pratica include solitamente: la tua tabella di token (spaziatura, tipo, raggi, colori), un breve set di regole per i componenti (button, input, card, heading), regole sul comportamento dei form (tempistica di validazione, errori, disabilitato/loading), default di layout (padding pagina, max width, spaziatura sezioni) e una breve lista “mai fare” (margini casuali, dimensioni font ad-hoc).

Poi crea un'abitudine: aggiorna prima la spec, non i pixel individuali.

Se usi Koder.ai (koder.ai), la modalità planning è un buon posto per ribadire e confermare lo spec prima di generare l'interfaccia. Quando vuoi provare alternative, snapshot e rollback ti aiutano a esplorare senza perdere una baseline stabile.