sistema di design Radix Themes.

Tema visivo e atmosfera del sistema di design Radix Themes

Un’interfaccia operativa, non una moodboard

Radix Themes è un riferimento utile per i prodotti in cui le persone leggono, prendono decisioni, inseriscono informazioni e tornano a completare attività in sospeso. Il carattere visivo deriva da spaziature misurate, superfici sobrie, una gerarchia tipografica chiara e stati dei componenti ripetibili. Usa questa guida per creare un’area di lavoro di progetto, una sezione account, una schermata delle impostazioni o un flusso di revisione dei dati. L’obiettivo è una schermata operativa coerente e ricca di contenuti reali, non una raccolta di componenti gradevoli disposti senza uno scopo.

Scegli il punto di partenza giusto

Per un’applicazione React, inizia dal pacchetto Radix Themes originale e usa i suoi componenti prima di scrivere sostituti personalizzati. Per un concept visivo basato su un altro stack, usa questi principi come riferimento e descrivi il risultato come ispirato al sistema. Radix Themes e Radix Primitives sono punti di partenza diversi: questa guida riguarda la libreria Themes con stili applicati. Una guida OpenDesign non trasforma un mockup HTML arbitrario in un’implementazione Radix nativa.

Progetta intorno a un’attività concreta

1. Scegli un’unica azione principale per la prima schermata, ad esempio creare un progetto o salvare le impostazioni dell’account.
2. Metti le informazioni necessarie per prendere quella decisione prima dell’azione.
3. Distingui visivamente la navigazione, i metadati degli oggetti, i campi modificabili e i feedback.
4. In fase di progettazione, usa titoli lunghi realistici, valori di stato diversi e uno stato vuoto.
5. Una schermata che funziona solo con tre brevi etichette segnaposto non definisce ancora un sistema utilizzabile.

Tono e contenuti

Usa etichette descrittive brevi, verbi specifici e spiegazioni dirette. Un pulsante dovrebbe indicare cosa succede dopo: Salva le modifiche, Invita un membro o Crea progetto. Riserva i titoli all’argomento di una sezione; evita di trasformare ogni piccolo controllo in uno slogan pubblicitario. Se un’azione non riesce, spiega cosa si può correggere e conserva il lavoro svolto. Queste sono raccomandazioni editoriali di OpenDesign per applicare il riferimento, non API aggiuntive fornite da Radix.

Palette e ruoli dei colori del sistema di design Radix Themes

Distingui il colore del brand dal significato

Usa il tema invece di definire schermate con colori fissi

La configurazione ufficiale del tema espone accentColor e grayColor. Sceglili a livello principale, così i componenti condividono le stesse impostazioni. Nei componenti personalizzati, usa le variabili CSS del tema corrente invece di copiare un colore da uno screenshot. Il riferimento ai token qui sotto elenca un insieme essenziale per l’uso pratico. Un token è un ruolo all’interno di un tema configurato, non la garanzia che un valore esadecimale rimanga invariato in modalità chiara, scura e con ogni scelta di colore d’accento.

Gerarchia di superfici e bordi

Inizia con uno sfondo sobrio per la pagina. Dai a schede e pannelli modificabili una superficie distinta solo quando raggruppano attività correlate. Usa separatori per le righe che appartengono allo stesso elenco. Evita di applicare contemporaneamente un bordo, un’ombra, uno sfondo colorato e un badge a ogni elemento. In una schermata delle impostazioni, di solito un unico pannello con righe separate è più chiaro di sei schede sospese. Mantieni visibile la gerarchia con contrasti delicati, senza rendere il testo essenziale troppo tenue.

Aspetto chiaro e scuro

Usa l’impostazione ufficiale dell’aspetto per i componenti nativi e verifica entrambe le modalità con gli stessi contenuti. Non creare una schermata scura invertendo i colori alla cieca o riutilizzando le ombre della modalità chiara. Verifica separatamente sovrapposizioni, campi inattivi, separatori, righe selezionate e testo sui colori d’accento. Lo studio interattivo di questa pagina illustra un piccolo insieme di scelte per il tema; il playground ufficiale è il riferimento per la libreria completa e il suo comportamento nativo.

Contrasto e indicatori ridondanti

Controlla le combinazioni finali tra primo piano e sfondo dopo aver cambiato il colore d’accento o la superficie. Abbina il colore al testo per gli stati come In attesa, Completato e Non riuscito. Per le opzioni selezionate, includi un segno di spunta o un’altra distinzione visibile. Non dare per scontato che una libreria di componenti accessibile renda accessibili tutte le combinazioni di contenuti e temi: le etichette, la gerarchia degli elementi, gli elementi CSS personalizzati e l’ordine delle informazioni continuano a incidere sull’usabilità dell’intera schermata.

Regole tipografiche del sistema di design Radix Themes

Una gerarchia di lettura ben studiata

Assegna alla schermata un titolo chiaro, quindi distingui i titoli delle sezioni, il testo del corpo, le etichette dei campi e i metadati di supporto. Usa il minor numero di dimensioni possibile per esprimere queste relazioni. Nelle schermate dense di un prodotto, le etichette leggibili sono più importanti di caratteri display sovradimensionati. Mantieni il paragrafo descrittivo vicino al controllo che illustra e lascia visibili le etichette anche dopo che un campo è stato compilato. Il testo segnaposto è un suggerimento, non sostituisce l’etichetta del campo.

Scala tipografica e peso

Radix documenta una scala tipografica in nove passaggi, con dimensioni dei caratteri, altezze di riga e spaziature tra lettere abbinate. La tabella di riferimento in questa pagina conserva quei valori alla scala base. Scegli un passaggio come combinazione completa, invece di abbinarlo a un’altezza di riga non correlata. Usa il peso normale per il testo del corpo e un peso più marcato per i titoli o le etichette selezionate. Se metti tutto in grassetto, la gerarchia scompare; se schiarisci tutto il testo secondario, la schermata diventa difficile da leggere.

Scelta dei caratteri e fallback

Radix Themes usa per impostazione predefinita uno stack di caratteri di sistema. Mantieni questo stack quando la portabilità è più importante di uno specifico carattere del brand, oppure configura un carattere con licenza tramite il meccanismo di personalizzazione documentato. Il sito OpenDesign circostante usa Albert Sans; questo non rende Albert Sans il carattere ufficiale di Radix. Per le applicazioni multilingue, verifica etichette rappresentative in cinese, giapponese e coreano, oltre a etichette lunghe in lingue europee, usando i caratteri di fallback effettivi.

Numeri, codice e ritorno a capo

Allinea le colonne numeriche per consentire il confronto verticale dei valori. Usa un carattere monospaziato per codice, identificatori e token quando i confini tra caratteri sono importanti. Lascia che titoli e descrizioni vadano a capo in modo naturale; non troncare istruzioni essenziali solo per mantenere uniforme l’altezza delle schede. Per stringhe che non possono andare a capo, come un ID, prevedi un ritorno a capo controllato o un’azione di copia. Su mobile, conserva tutte le informazioni anche quando cambia il layout.

La lunghezza dei contenuti fa parte del design

Prima di considerare riutilizzabile un componente, provalo con un nome di progetto lungo, il ruolo di un membro su due righe e un’azione tradotta. Quando possibile, lascia che i pulsanti si allarghino invece di assegnare a tutti una larghezza fissa. Mantieni i paragrafi del corpo entro una larghezza di lettura confortevole e usa elenchi o tabelle quando è necessario confrontare informazioni parallele. Non suddividere il testo esplicativo in tante piccole schede decorative solo per dare alla pagina un aspetto più curato.

Stili e stati dei componenti del sistema di design Radix Themes

Pulsanti e gerarchia delle azioni

All’interno di un gruppo di azioni, individua la decisione principale e dalle il risalto maggiore. Le azioni secondarie devono essere facili da trovare senza competere allo stesso livello. Separa le azioni distruttive dalle normali conferme. Durante l’invio, impedisci le operazioni duplicate e mostra chiaramente l’avanzamento; al termine, comunica il risultato effettivo. Se il motivo per cui un pulsante è disabilitato non è evidente dal modulo, indicalo nelle vicinanze.

Campi e moduli

• Posiziona un’etichetta persistente sopra o accanto a ogni campo.
• Mantieni il testo di aiuto accanto al campo pertinente e associa i messaggi di convalida al campo, anziché mostrarli soltanto in un banner generico.
• Conserva i valori inseriti in caso di errori di convalida.
• Raggruppa i campi correlati sotto un titolo di sezione significativo.
• Usa il tipo di campo e il valore di completamento automatico appropriati, così il browser e gli strumenti di assistenza possono aiutare la persona a completare l’attività.

Schede, elenchi e tabelle

Usa una scheda per un elemento autonomo con un riepilogo e un’azione significativi. Usa un elenco per una serie di record simili e una tabella quando è necessario confrontare gli attributi tra diversi record. Mostra campi effettivi, come responsabile, ora di aggiornamento e stato, invece di frammenti grafici decorativi. Una scheda non dovrebbe essere cliccabile in modo da entrare in conflitto con link o pulsanti al suo interno; scegli un’area di destinazione chiara e mantieni il normale comportamento da tastiera.

Navigazione e selezione

Mantieni la navigazione globale distinta dalle schede a livello di pagina e dai filtri locali. La destinazione attiva deve essere riconoscibile senza affidarsi soltanto al colore d’accento. Usa i link per la navigazione e i pulsanti per le modifiche in pagina. Se implementi un modello a schede, includi il relativo comportamento da tastiera; altrimenti usa un gruppo chiaramente etichettato di pulsanti normali. Non far sembrare interattiva una fila di elementi span stilizzati se non è possibile interagirvi.

Menu, finestre di dialogo e sovrapposizioni

Quando implementi un prodotto React, usa il componente nativo della libreria per i comportamenti complessi. Una finestra di dialogo richiede un titolo, un modo chiaro per chiuderla, una gestione appropriata del focus e il ripristino del focus sul controllo che l’ha aperta. Evita di creare una finestra modale con una scheda posizionata in modo assoluto, priva di questi comportamenti. Limita la finestra di dialogo a una sola decisione; i flussi di modifica più lunghi spesso meritano una pagina dedicata, invece di una sovrapposizione sempre più affollata.

Caricamento, stato vuoto, errore e completamento

• Progetta ogni stato in funzione della stessa attività reale.
• Un elenco progetti vuoto dovrebbe spiegare come creare il primo progetto.
• Uno stato di caricamento dovrebbe mantenere una struttura sufficiente a evitare salti improvvisi.
• Un errore dovrebbe offrire un’azione successiva utile e non cancellare il lavoro completato.
• Un messaggio di conferma dovrebbe indicare cosa è cambiato.
• I pulsanti campione statici in questa pagina mostrano l’aspetto degli stati; non dimostrano che tali stati funzionino in produzione.

Layout, spaziatura e densità del sistema di design Radix Themes

Usa una scala di spaziatura condivisa

La scala di spaziatura documentata ha nove passaggi base: 4, 8, 12, 16, 24, 32, 40, 48 e 64 pixel. Usa i passaggi più piccoli all’interno di controlli strettamente correlati e quelli più grandi tra sezioni indipendenti. Mantieni un rapporto visibile tra un titolo e il relativo contenuto. Non distribuire lo spazio vuoto in modo uniforme solo per riempire la schermata: la vicinanza dovrebbe comunicare quali informazioni sono correlate.

La densità dipende dall’attività

Una directory di risorse deve mostrare un numero sufficiente di elementi per consentire il confronto. Un modulo di configurazione ha bisogno di spazio per etichette, testo di aiuto ed errori. Una pagina di lettura richiede una larghezza stabile e un indice visibile. Scegli la densità in base all’attività, invece di applicare ovunque le stesse dimensioni alle schede. Radix offre anche un’impostazione di scala che modifica insieme le dimensioni correlate; prima di impostare come predefinita nel prodotto una scala compatta, valuta la leggibilità e le dimensioni delle aree interattive risultanti.

Comportamento di griglie e contenitori

Inizia con un contenitore di pagina, quindi definisci il contenuto principale e le eventuali colonne di supporto. Mantieni il testo lungo in una colonna leggibile anche quando l’area esterna è ampia. Alle larghezze ridotte, sposta i contenuti di supporto sotto il contenuto principale oppure trasforma una colonna lunga in un controllo di navigazione locale accessibile. Mantieni l’ordine del codice sorgente in modo che il flusso su mobile e l’ordine da tastiera siano chiari, senza dipendere dalla disposizione della griglia desktop.

Righe prima delle schede annidate

In un riferimento compatto ai token, disponi nome, valore e utilizzo su un’unica riga facilmente consultabile. In un catalogo, mantieni insieme titolo, categoria, descrizione e destinazione. Le schede annidate ripetute aggiungono rumore visivo e occupano larghezza che dovrebbe essere riservata ai contenuti. Preferisci un separatore sottile tra righe correlate; riserva i pannelli delimitati a un reale cambio di contesto, come un’anteprima dal vivo o un esempio di codice.

Mantieni visibili i contenuti importanti

Non ridurre una guida dettagliata a brevi riepiloghi solo per accorciare la pagina. Fornisci un indice e titoli di sezione chiari, così le persone possono accedere direttamente al punto pertinente. Se un filtro o un elemento a fisarmonica modifica ciò che è visibile, rendi chiari lo stato vuoto e quello selezionato. Evita elenchi interni con scorrimento indipendente, a meno che non risolvano una reale esigenza di interazione; per una raccolta lunga di risorse, di solito è più semplice scorrere la pagina normalmente.

Raggio, profondità e movimento del sistema di design Radix Themes

Il raggio è una questione di relazione

Radix offre impostazioni del raggio con nomi specifici e comportamenti dei componenti contestuali. Scegli un’impostazione a livello di tema invece di assegnare lo stesso raggio arbitrario a ogni elemento. Un pulsante, una casella di controllo e un pannello grande svolgono ruoli strutturali diversi. Mantieni forme correlate senza cancellare queste differenze. Se un tuo componente usa un token di raggio, provalo accanto a un pulsante e a un campo nativi prima di decidere che appartiene allo stesso sistema.

La profondità spiega i livelli

Usa la profondità per distinguere una sovrapposizione dalla pagina sottostante o un pannello interattivo da una superficie sobria. Radix offre una scala delle ombre a sei livelli. Non trattare l’indice dell’ombra come una classifica decorativa di popolarità delle schede. Un catalogo denso può spesso funzionare anche solo con i bordi. Verifica le ombre in entrambe le modalità: una sfocatura del tema chiaro copiata su una superficie scura può scomparire o creare un alone che suggerisce una profondità errata.

Il movimento deve chiarire un cambiamento

Usa transizioni brevi per spiegare una selezione, un’apertura, un avanzamento o il passaggio tra stati correlati. Non ritardare la visualizzazione dei contenuti con un’animazione in entrata. Evita il movimento continuo dello sfondo nelle schermate pensate per il lavoro. Rispetta le preferenze di riduzione del movimento e assicurati che lo stato finale resti leggibile anche senza transizioni. Le scelte di temporizzazione in un’implementazione personalizzata dipendono dall’applicazione; questa guida non inventa un token ufficiale di durata Radix in assenza di una fonte verificata.

Interazione senza decorazioni

Un effetto al passaggio del cursore dovrebbe indicare che un elemento è interattivo. Lo stato di focus deve restare chiaramente visibile rispetto alle superfici adiacenti. Evita di spostare troppo un’intera riga densa al passaggio del cursore, per non far slittare le informazioni mentre qualcuno le legge. Sugli schermi touch, le azioni essenziali devono essere disponibili anche senza il passaggio del cursore. L’effetto è efficace quando aiuta l’utente a capire il controllo, non quando attira l’attenzione sull’animazione in sé.

Radix Themes: cosa fare e cosa evitare nel sistema di design

Da fare: definire una schermata completa

Crea una schermata con la navigazione effettiva, contenuti significativi, un’azione principale e almeno uno stato eccezionale. Esaminala prima di estrarre decine di componenti riutilizzabili. Annota le scelte deliberate, come il colore di accento, la densità, i livelli tipografici e il testo dello stato vuoto. In questo modo fornisci a un agente AI indicazioni precise da seguire e rendi più facile individuare le deviazioni nelle iterazioni successive.

Da fare: mantenere coerenti il lavoro nativo e quello personalizzato

Preferisci i componenti esistenti della libreria per i comportamenti che supportano già. Usa le variabili del tema nei contenitori personalizzati e verificane il funzionamento in entrambe le modalità. Mantieni etichette e semantica HTML durante la definizione degli stili. Se il progetto ha già un design system, confrontalo con questo riferimento prima di sostituirlo: un secondo livello di temi non controllato può introdurre più incoerenze di quante ne elimini.

Da evitare: ricreare un brand cambiando i colori

Cambiare solo il colore di accento non basta a creare un’interfaccia coerente. Spaziatura, tipografia, gerarchia dei contenuti, schemi di interazione e scelte responsive contribuiscono in larga misura all’identità visiva. Non dichiarare un’integrazione ufficiale solo perché un mockup somiglia alla libreria. Evita di copiare in una nuova schermata di prodotto il marchio, le risorse proprietarie o le dichiarazioni commerciali di un altro prodotto.

Da evitare: sacrificare il significato per uno screenshot più pulito

Radix Themes: comportamento responsive e accessibile del sistema di design

Adatta la struttura prima di rimpicciolirla

Quando lo schermo si restringe, riduci il numero di colonne, semplifica il percorso verso l’azione principale e sposta le informazioni secondarie nel normale flusso di lettura. Non ridurre un dashboard desktop come se fosse un’unica immagine per poi chiamarlo layout mobile. Mantieni disponibili gli stessi contenuti, usando l’adattamento delle righe, la disposizione in colonna o una presentazione tabellare adeguata. Conserva link descrittivi, così la destinazione resta comprensibile anche al di fuori della scheda desktop che li contiene.

Usa in modo intenzionale i breakpoint documentati

I nomi ufficiali dei breakpoint sono initial, xs, sm, md, lg e xl. Le rispettive larghezze minime sono 0, 520, 768, 1024, 1280 e 1640 pixel. Considerali strumenti a disposizione, non cambiamenti di layout obbligatori a ogni passaggio. Aggiungi un breakpoint quando i contenuti richiedono una disposizione diversa. Verifica anche una larghezza intermedia tra i breakpoint nominati, oltre ai breakpoint stessi, per individuare i layout fragili nelle dimensioni intermedie.

Tastiera e focus

• Ogni azione significativa deve essere accessibile da tastiera.
• Rendi lo stato di focus visibile e distinto dal passaggio del cursore, e mantienilo visibile anche quando un contenitore taglia i contenuti.
• Evita i valori positivi di tabindex, che possono riordinare i controlli in modo imprevedibile.
• Dopo una modifica ai filtri, mantieni il focus sul controllo e mostra un conteggio sintetico dei risultati.
• Dopo la chiusura di una finestra modale, riporta il focus in una posizione adeguata, senza lasciare la persona all’inizio del documento.

Etichette, aree interattive e testo di supporto

Assegna alle azioni con la sola icona un nome accessibile che descriva l’azione, non la forma dell’icona. Assicurati che le aree touch siano comode da usare anche quando l’icona visibile è piccola. Escludi le icone decorative dall’albero di accessibilità. Rendi disponibili aggiornamenti come le modifiche salvate o il conteggio dei risultati di ricerca senza annunciare ripetutamente contenuti non pertinenti. Quando uno stato è rappresentato sia da un’icona sia da un testo, evita che lo screen reader annunci due volte lo stesso messaggio.

Verifica con contenuti reali

• Controlla un desktop, un tablet e uno smartphone stretto.
• Includi un testo che si espande, un’immagine mancante, un elenco vuoto e un identificatore lungo senza spazi.
• Verifica la pagina con la riduzione del movimento attiva e usando la navigazione da tastiera.
• Esamina entrambe le modalità dopo ogni modifica sostanziale dei colori.
• I controlli automatizzati possono individuare problemi strutturali, ma non possono stabilire se la gerarchia, la densità dei contenuti e il carattere visivo complessivo rispondano alle esigenze previste del prodotto.

Radix Themes: guida ai prompt per agenti AI e all’implementazione del sistema di design

Prepara il contesto del progetto

1. Spiega all’agente AI che cosa stai realizzando, chi lo userà, qual è l’azione principale e quali file esistenti definiscono il design attuale.
2. Allega questa guida come riferimento, invece di chiedere all’agente AI di imitare uno screenshot non specificato.
3. Se usi React, specifica che è preferibile usare i componenti nativi di Radix Themes.
4. Se usi un altro stack, chiedi un’interpretazione esplicitamente indicata come tale e valuta il lavoro aggiuntivo necessario per le interazioni.

Definisci un primo risultato completo

Chiedi una schermata funzionante con contenuti reali e un numero limitato di stati. Specifica la navigazione, i campi, i metadati degli oggetti e il risultato atteso dell’azione principale. Includi nella richiesta il focus da tastiera, uno stato vuoto, la convalida e un layout stretto. Indica i vincoli da mantenere, come un’intestazione esistente, un contratto dati in produzione o un blocco di contenuto già approvato.

Esamina il lavoro seguendo un ordine che faccia emergere i problemi reali

1. Per prima cosa, verifica che la schermata consenta di svolgere l’attività prevista.
2. Poi confronta la gerarchia delle informazioni, la spaziatura, la tipografia e i colori con il riferimento scelto.
3. Infine, verifica gli stati interattivi e i layout responsive.
4. Non accettare una modifica visiva solo perché la pagina viene compilata o perché lo screenshot appare ordinato.
5. Dopo gli interventi visivi, verifica che i contenuti più lunghi, gli errori e le azioni ripetute funzionino ancora.

Estendi il lavoro sulla base di decisioni esplicite

Dopo aver verificato il funzionamento della prima schermata, annota la configurazione del tema, i ruoli tipografici, le scelte di spaziatura e gli schemi dei componenti da ripetere. Chiedi all’agente AI di applicare tali decisioni alla schermata successiva senza riscrivere di nascosto i contenuti approvati. Se una nuova schermata richiede uno schema diverso, documentane il motivo e verifica la coerenza con la schermata precedente. Estendi il lavoro a partire da comportamenti verificati, anziché generare una vasta raccolta di pagine solo superficialmente simili.

Ambito noto e limiti delle fonti