Un riferimento a Chakra UI v3 per token, ruoli semantici dei colori, ricette e componenti composti per i moduli. Esamina le scale effettive di spaziatura e tipografia, poi prova un modulo nativo per il profilo dell’area di lavoro con convalida, simulazione del salvataggio non riuscito e aspetto chiaro o scuro.
Guida OpenDesign9 capitoli47 voci di riferimentoGuida applicativa originale
01
Anteprima dell’interfaccia del sistema di progettazione sistema di design Chakra UI
Prova la convalida dei campi vuoti, un salvataggio non riuscito simulato, il mantenimento dei dati inseriti, la conferma locale riuscita e il cambio di aspetto.
Chakra UI nativo 3.37.0 con React 19; bundle autonomo. I token semantici e le ricette personalizzati dell’applicazione sono mostrati per intero. · Riferimento per l’implementazione
02
Riferimento di progettazione per il sistema di progettazione sistema di design Chakra UI
Riferimenti al tema predefinito di Chakra UI 3.37.0, oltre ai token dell’applicazione OpenDesign identificati esplicitamente. I valori rem seguono la dimensione del carattere radice; gli equivalenti in pixel presuppongono 16px. Questo è un riferimento operativo selezionato, non il tema esportato completo.
Sistema di progettazione sistema di design Chakra UI: il sistema v3, configurazione, token e componenti
Crea un sistema invece di passare un vecchio oggetto tema
L’implementazione ha tre livelli: theme.js definisce le scelte di progettazione, main.jsx fornisce il sistema risultante e App.jsx compone il modulo. createSystem(defaultConfig, config) mantiene le ricette dei componenti predefinite unendo la configurazione dell’applicazione. Un sistema personalizzato essenziale richiederebbe altre definizioni; qui si sceglie deliberatamente di estendere i valori predefiniti.
L’anteprima usa componenti Chakra, non elementi sostitutivi disegnati a mano. La barra laterale è un elenco ordinato di avanzamento specifico dell’applicazione, non l’affermazione che sia montato il componente Chakra Steps. La scheda del profilo, i campi, il menu di selezione, gli avvisi e i pulsanti sono composizioni Chakra native.
tokens: valori primitivi riutilizzabili, tra cui i due colori del brand usati nell’esempio.
semanticTokens: ruoli dipendenti dal contesto, come workspace.action, indipendenti dalle singole schermate.
recipes: varianti riutilizzabili dei componenti; lo stato dell’applicazione React determina se il modulo non è valido, è in attesa, non è riuscito o è stato confermato.
Sistema di progettazione sistema di design Chakra UI: colori primitivi e ruoli semantici del tema
Usa i ruoli quando cambia l’aspetto
bg.panel e fg.muted descrivono rispettivamente il ruolo di superficie e quello del testo; gray.950 e gray.400 sono i valori sottostanti. La tabella di riferimento mostra come vengono risolti in modalità chiara e scura. Nella demo, cambiare il documento radice tra modalità chiara e scura attiva quei valori condizionali senza dover modificare ogni Field o Card. Questo selettore locale non prevede volutamente la persistenza né l’integrazione con le preferenze di sistema.
I ruoli workspace.* sono aggiunte specifiche dell’applicazione. Definiscono un’azione color teal scuro su una superficie chiara e un’azione color teal chiaro su una superficie scura, con il relativo colore del testo abbinato. Non sono nomi ufficiali dei token Chakra. Mantenere la coppia nel tema evita che, in modalità scura, cambi lo sfondo del pulsante ma l’etichetta rimanga bianca.
La sintassi di riferimento è diversa dalla forma abbreviata dei componenti
Nelle definizioni dei token, usa il riferimento completo {colors.gray.950}. In una proprietà di stile, bg="workspace.canvas" viene risolto nella categoria dei colori. In un valore composito CSS è invece necessario usare di nuovo il percorso completo del token. Questa distinzione evita che una stringa letterale venga scambiata per un riferimento al tema.
Sistema di progettazione sistema di design Chakra UI: una scala tipografica leggibile con token espliciti
Adatta la scala a questa composizione
Il titolo usa fontSize="2xl" e lineHeight="shorter"; l’intestazione della scheda usa xl, il testo di supporto sm e l’annotazione dell’esempio xs. Queste scelte creano una gerarchia senza modificare i livelli semantici delle intestazioni: il titolo della schermata è h1 e il titolo del modulo è h2. Il contenuto normale del modulo mantiene la dimensione predefinita del testo del corpo.
La famiglia predefinita per il testo del corpo e le intestazioni di Chakra inizia con Inter e prosegue con i caratteri di sistema. La demo autonoma non effettua richieste di caratteri esterne, quindi il carattere alternativo visualizzato può variare in base al sistema operativo. Se serve una tipografia esatta, servi localmente un carattere con licenza appropriata: impostare un token per il carattere non fornisce i file del carattere.
L’indicatore della fase corrente è un metadato compatto, non l’istruzione principale. I messaggi di obbligatorietà e di errore rimangono accanto al campo e hanno dimensioni leggibili. Modificare la spaziatura tra le lettere del sopratitolo non influisce sulle etichette del modulo; il nome lungo dell’area di lavoro rimane all’interno del campo senza modificare la larghezza della scheda circostante.
Sistema di progettazione sistema di design Chakra UI: comporre Field, NativeSelect, Card e Alert
Field è una relazione, non un input stilizzato
Field.Root raggruppa l’etichetta, il controllo, il testo di supporto e l’errore. Il flag required e RequiredIndicator comunicano l’obbligatorietà; invalid controlla lo stato di errore. L’esempio mantiene l’input controllato tramite React e inserisce l’errore relativo al nome dell’area di lavoro in Field.ErrorText. Non applica stili di errore in modo indipendente a un paragrafo scollegato.
Per la dimensione del team si usano NativeSelect.Root, NativeSelect.Field e NativeSelect.Indicator. In questo modo si mantiene il comportamento nativo del menu di selezione per un insieme ridotto e fisso di opzioni. Non si simula un controllo con risultati remoti ricercabili: quello richiederebbe un controllo e un’interazione con i dati diversi.
Sistema di progettazione sistema di design Chakra UI: applicare i token di spaziatura e le proprietà di stile responsive
Una regola di spaziatura concreta
Usa gap="6" tra i gruppi di campi, gap="3" tra le azioni e gap="8" tra la colonna di avanzamento e il modulo. La pagina passa da p="4" a p="8" a partire da md. Con una radice da 16px, questi valori corrispondono a 24px, 12px, 32px, 16px e 32px. I valori in rem si adattano alla dimensione del font radice impostata dall’utente.
La scheda usa rounded="xl" e l’etichetta di stato rounded="md". I diversi raggi sono intenzionali: il contenitore grande e l’etichetta compatta hanno geometrie diverse. Non considerare queste scelte d’uso come regole predefinite che tutte le applicazioni Chakra devono seguire.
La griglia usa una colonna sotto md e, da md in su, una colonna di avanzamento da 220px accanto a un modulo flessibile. minmax(0, 1fr) consente al modulo di ridursi all’interno della griglia. La disposizione delle azioni cambia a partire da sm. Questi valori degli oggetti sono override mobile-first, non rilevamento del dispositivo.
Sistema di design Chakra UI: sistema di progettazione per collegare validazione, caricamento e recupero
La macchina a stati dell’anteprima
L’invio di un nome vuoto dopo aver rimosso gli spazi iniziali e finali imposta lo stato su invalid e sposta il focus sull’input. Un invio valido passa allo stato pending, disabilita la modifica e mostra Button loadingText. Al termine del timer locale, la casella di controllo dell’errore determina se la dimostrazione mostra lo stato failed o complete. Nessuno dei due rami invia una richiesta di rete o salva dati.
Un risultato failed mantiene il nome controllato e la dimensione selezionata. Disattivare la simulazione dell’errore consente di riprovare. Il completamento disabilita i campi del profilo e modifica la prima etichetta di avanzamento; Reset torna alla modifica. Questo dimostra la composizione degli stati visibili, non garantisce un contratto di salvataggio lato backend.
Reimposta il modulo e invialo senza un nome; controlla il messaggio del campo e l’input con il focus.
Inserisci un nome, attiva la simulazione del salvataggio non riuscito e invia; verifica che i valori restino dopo l’errore.
Disattiva la simulazione dell’errore e invia di nuovo; controlla il riepilogo di conferma, poi modifica l’aspetto.
Sistema di design Chakra UI: sistema di progettazione per mantenere la semantica nativa nella composizione
Validazione e avanzamento restano comprensibili
Il modulo usa noValidate affinché questo esempio possa mostrare il proprio percorso di errore tramite Field, invece di fermarsi all’interfaccia di validazione del browser. L’etichetta resta associata tramite Field e il primo input non valido riceve il focus. Il lavoro in corso è descritto da un’area di stato live; non viene comunicato solo tramite un indicatore di caricamento.
L’elenco di avanzamento usa la semantica di un elenco ordinato e aria-current="step" sull’elemento attivo. Non include collegamenti fittizi a schermate non disponibili. Il secondo e il terzo passaggio dell’anteprima forniscono un contesto, ma non sono selezionabili. In questo modo i limiti della dimostrazione sono chiari.
Il focus fa parte della configurazione personalizzata dell’azione
La variante di onboarding definisce esplicitamente il contorno focus-visible e il relativo offset. L’aspetto scuro modifica il ruolo del contorno insieme al ruolo dell’azione. La casella di controllo e il selettore nativi restano utilizzabili da tastiera. Verifica anche il focus, gli annunci dei campi, lo zoom e l’output dello screen reader nell’applicazione che li integra: un esempio a livello di componente non può dimostrare l’accessibilità di un intero prodotto di onboarding.
Sistema di design Chakra UI: sistema di progettazione, configurazione del provider e limiti di versione
Estendi Button; definisci Status localmente
La variante Button per l’onboarding viene aggiunta in theme.recipes.button. Le varianti esistenti, come outline, restano disponibili perché la configurazione estende defaultConfig. L’etichetta di stato usa localmente defineRecipe e useRecipe: le sue varianti di stato associano current, complete e waiting a ruoli semantici diversi. È un componente dell’applicazione, non un’esportazione di Chakra.
Una recipe per un singolo elemento restituisce un unico oggetto di stile. I componenti composti da più parti, come Field, hanno diversi slot e richiedono recipe per slot quando si tematizzano insieme le loro parti. Applicare a un intero Field una recipe simile a quella di un pulsante non consentirebbe di controllare separatamente l’etichetta, il controllo e l’errore.
Non importare una configurazione v2 con extendTheme né passare theme={...} a questo provider v3. La radice effettiva usa ChakraProvider value={system}. Per scelta, l’esempio non aggiunge un secondo provider per la modalità colore: il selettore locale di classe chiara/scura è sufficiente per questa anteprima isolata, mentre un’app reale potrebbe richiedere il salvataggio delle preferenze e il supporto al rendering lato server.
Sistema di design Chakra UI: sistema di progettazione per verificare insieme tema e modulo
Cosa dimostra questo esempio
L’unità di revisione significativa è l’intera scheda del profilo in entrambe le modalità: etichetta, input, testo di aiuto, feedback di errore, pulsante in caricamento, avviso di errore e riepilogo di conferma. Un singolo pulsante non può mettere in evidenza uno sfondo semantico mancante o un controllo il cui stato di errore non è associato alla relativa etichetta.
Confronta la tabella di riferimento con l’interfaccia calcolata. L’azione personalizzata color teal dovrebbe essere diversa dall’azione outline predefinita; la spaziatura 6 dovrebbe separare i campi; sotto md la griglia dovrebbe passare a una colonna. Queste verifiche collegano le regole scritte al risultato visualizzato.
Cosa non è incluso nell’esempio
L’anteprima non include la creazione di account, l’invio di inviti, la persistenza, l’autenticazione o l’integrazione con un’altra schermata di onboarding. Il timer è esplicitamente una simulazione. Quando colleghi un endpoint reale, mantieni la distinzione mostrata tra lo stato del campo e quello della richiesta, sostituisci il timer con la richiesta e definisci se il completamento significa accettazione locale, salvataggio remoto o attivazione completa.
Esempi di componenti del sistema di progettazione sistema di design Chakra UI
theme.js — token primitivi, ruoli semantici e recipe
Tema completo dell’applicazione per l’esempio. I ruoli dell’area di lavoro e la variante di onboarding sono aggiunte originali; defaultConfig fornisce il tema standard di Chakra.
I valori del brand corrispondono intenzionalmente ai token primitivi teal di riferimento.
La recipe di stato è locale; la variante Button è registrata nel sistema.
App.jsx — esempio completo di modulo nativo e gestione degli stati
La composizione effettiva di React usata nell’anteprima. Include il cambio di tema, la validazione Field, un selettore nativo, il feedback di caricamento, la simulazione dell’errore, la conferma e il ripristino.
jsx
import React, { useEffect, useRef, useState } from 'react';
import { Box, Button, Card, Field, Grid, Heading, Input, NativeSelect, Stack, Text, Alert, chakra, useRecipe } from '@chakra-ui/react';
import { statusRecipe } from './theme';
function Status({ state, children }) {
const recipe = useRecipe({ recipe: statusRecipe });
return <chakra.span css={recipe({ state })}>{children}</chakra.span>;
}
export default function App() {
const [dark, setDark] = useState(false);
useEffect(() => { document.documentElement.className = dark ? 'dark' : 'light'; }, [dark]);
const [name, setName] = useState('Northstar Studio');
const [size, setSize] = useState('2–10');
const [invalid, setInvalid] = useState(false);
const [phase, setPhase] = useState('editing');
const [simulateFailure, setSimulateFailure] = useState(false);
const nameInput = useRef(null);
const pending = phase === 'pending';
const complete = phase === 'complete';
const save = (event) => {
event.preventDefault();
if (!name.trim()) { setInvalid(true); nameInput.current?.focus(); return; }
setInvalid(false); setPhase('pending');
window.setTimeout(() => setPhase(simulateFailure ? 'failed' : 'complete'), 600);
};
return <Box className={dark ? 'dark' : 'light'} bg='workspace.canvas' color='fg' p={{ base: '4', md: '8' }}>
<Box maxW='960px' mx='auto'>
<Stack direction={{ base: 'column', sm: 'row' }} justify='space-between' align={{ base: 'stretch', sm: 'center' }} gap='4' mb='8'>
<Box><Text fontSize='xs' fontWeight='semibold' color='teal.fg' letterSpacing='wide'>CHAKRA UI · NATIVE SPECIMEN</Text><Heading as='h1' fontSize='2xl' lineHeight='shorter' mt='2'>Set up your workspace</Heading></Box>
<Button variant='outline' size='sm' onClick={() => setDark(!dark)} aria-pressed={dark}> {dark ? 'Light appearance' : 'Dark appearance'} </Button>
</Stack>
<Grid templateColumns={{ base: '1fr', md: '220px minmax(0, 1fr)' }} gap='8'>
<Box as='nav' aria-label='Setup progress'>
<Stack as='ol' gap='6' listStyleType='none' m='0' p='0'>
<Box as='li' aria-current={complete ? undefined : 'step'}><Status state={complete ? 'complete' : 'current'}>{complete ? 'Complete' : 'Current'}</Status><Text fontWeight='semibold' mt='2'>1. Workspace profile</Text><Text fontSize='sm' color='fg.muted'>Name and team size</Text></Box>
<Box as='li'><Status state='waiting'>Next</Status><Text fontWeight='medium' mt='2'>2. Invite your team</Text><Text fontSize='sm' color='fg.muted'>Available in the full product</Text></Box>
<Box as='li'><Status state='waiting'>Optional</Status><Text fontWeight='medium' mt='2'>3. Connect tools</Text><Text fontSize='sm' color='fg.muted'>Complete this later</Text></Box>
</Stack>
<Box mt='8' borderTopWidth='1px' borderColor='border' pt='4'><Text fontSize='xs' color='fg.muted'>Scale in this specimen</Text><Text fontSize='sm' mt='2'>Field gap 6 · Card padding 6<br/>Page gap 8 · Radius xl</Text></Box>
</Box>
<Card.Root bg='bg.panel' borderColor='border' rounded='xl'>
<Card.Header><Heading as='h2' fontSize='xl'>Workspace profile</Heading><Text color='fg.muted' fontSize='sm'>The name appears on your team's workspace.</Text></Card.Header>
<Card.Body>
<form onSubmit={save} noValidate>
<Stack gap='6'>
<Field.Root required invalid={invalid} disabled={pending || complete}>
<Field.Label>Workspace name <Field.RequiredIndicator /></Field.Label>
<Input ref={nameInput} value={name} onChange={e => {setName(e.target.value);setInvalid(false);}} autoComplete='organization' />
<Field.HelperText>Use a name your teammates will recognize.</Field.HelperText>
<Field.ErrorText>Enter a workspace name.</Field.ErrorText>
</Field.Root>
<Field.Root disabled={pending || complete}>
<Field.Label>Team size</Field.Label>
<NativeSelect.Root><NativeSelect.Field value={size} onChange={e => setSize(e.target.value)}><option>Just me</option><option>2–10</option><option>11–50</option><option>51+</option></NativeSelect.Field><NativeSelect.Indicator /></NativeSelect.Root>
<Field.HelperText>Used only for this local preview summary.</Field.HelperText>
</Field.Root>
<Box><label style={{display:'flex',gap:'8px',alignItems:'center',fontSize:'14px'}}><input type='checkbox' checked={simulateFailure} disabled={pending || complete} onChange={e=>setSimulateFailure(e.target.checked)} />Simulate a failed save</label></Box>
{phase === 'failed' && <Alert.Root status='error'><Alert.Indicator /><Alert.Content><Alert.Title>Demo save failed</Alert.Title><Alert.Description>Your values are still here. Turn off failure simulation and retry.</Alert.Description></Alert.Content></Alert.Root>}
{complete && <Alert.Root status='success'><Alert.Indicator /><Alert.Content><Alert.Title>Profile confirmed in this preview</Alert.Title><Alert.Description>{name.trim()} · {size} people. Nothing was sent or stored.</Alert.Description></Alert.Content></Alert.Root>}
<Stack direction={{base:'column',sm:'row'}} gap='3'>
<Button type='submit' variant='onboarding' loading={pending} loadingText='Checking profile' disabled={complete}>Confirm profile</Button>
<Button type='button' variant='outline' disabled={pending} onClick={()=>{setPhase('editing');setInvalid(false);setName('');setSize('2–10');setSimulateFailure(false);nameInput.current?.focus();}}>Reset example</Button>
</Stack>
<Text role='status' aria-live='polite' fontSize='sm' color='fg.muted'>{pending ? 'Simulating a response. No network request is made.' : complete ? 'Profile step complete. Reset to try another state.' : 'Try an empty name, a failed save, or a different appearance.'}</Text>
</Stack>
</form>
</Card.Body>
</Card.Root>
</Grid>
<Text mt='6' fontSize='xs' color='fg.muted'>Actual Chakra UI 3.37.0 components. Custom workspace semantic tokens and button recipe. Memory-only demonstration.</Text>
</Box>
</Box>;
}
Non viene inviata alcuna richiesta; il ritardo di 600ms mostra l’interfaccia di caricamento.
I passaggi successivi sono etichette contestuali, non elementi di navigazione funzionanti.
04
Configurazione dell’agente AI per il sistema di progettazione sistema di design Chakra UI
Punto di partenza per l’implementazione
Usa una versione di Node.js supportata dalla versione di Vite e Chakra installata (Chakra documenta Node 20 o versioni successive). Questo blocco separa i comandi del terminale da src/main.jsx. I file completi del tema e App sono riportati sopra; non servono frammenti nascosti del provider né CSS esterni.
testo
# Terminal: create a JavaScript React application
npm create vite@latest chakra-profile -- --template react
cd chakra-profile
npm install
npm install @chakra-ui/[email protected] @emotion/react
# Save the two complete examples as src/theme.js and src/App.jsx.
# Replace src/main.jsx with:
import React from 'react';
import { createRoot } from 'react-dom/client';
import { ChakraProvider } from '@chakra-ui/react';
import { system } from './theme';
import App from './App';
createRoot(document.getElementById('root')).render(<ChakraProvider value={system}><App /></ChakraProvider>);
# Start from the project directory:
npm run dev
Un prompt per il tuo progetto
Prompt per l’agente
Usa Chakra UI 3.37.0 e i file theme.js e App.jsx forniti come punto di partenza. Mantieni i ruoli semantici dell’area di lavoro, la composizione Field, il selettore nativo e la distinzione tra input non valido e invio non riuscito. Sostituisci solo il timer simulato con la nostra API di persistenza effettiva; non contrassegnare il profilo come completato prima di aver ricevuto conferma. Mantieni il focus da tastiera, il layout responsive base/md e i valori per la modalità chiara/scura. Spiega eventuali nuovi token o varianti di recipe.
05
Fonti e ambito del sistema di progettazione sistema di design Chakra UI
Guida all’implementazione originale di OpenDesign, basata sulle fondamenta documentate di Chakra UI v3. I riferimenti ai token predefiniti sono separati dai ruoli specifici dell’area di lavoro dell’applicazione. L’anteprima nativa dimostra gli stati locali; non salva i dati dell’area di lavoro né implementa l’intero percorso di onboarding.
