Système de composants thématisé · Nouvelle ressource
Système de design Chakra UI.
Une référence Chakra UI v3 sur les jetons, les rôles de couleurs sémantiques, les recettes et les composants de formulaire composés. Examinez les échelles réelles d’espacement et de typographie, puis testez un formulaire natif de profil d’espace de travail avec validation, simulation d’échec de l’enregistrement et apparence claire ou sombre.
Guide OpenDesign9 chapitres47 entrées de référenceGuide de l’application d’origine
01
Aperçu de l’interface du système de design Chakra UI
Essayez la validation d’un champ vide, l’échec simulé de l’enregistrement, la conservation de la saisie, la confirmation locale de réussite et le changement d’apparence.
Chakra UI natif 3.37.0 avec React 19 ; bundle autonome. Les jetons sémantiques et les recettes personnalisés de l’application sont présentés dans leur intégralité. · Référence de mise en œuvre
02
Référence de conception du système de design Chakra UI
Références au thème par défaut de Chakra UI 3.37.0, ainsi qu’aux jetons d’application OpenDesign explicitement identifiés. Les valeurs en rem suivent la taille de police racine ; les équivalents en pixels supposent 16px. Il s’agit d’une sélection de référence pratique, et non du thème exporté complet.
Système de design Chakra UI : le système v3 — configuration, jetons et composants
Créez un système au lieu de transmettre un ancien objet de thème
L’implémentation comporte trois couches : theme.js définit les choix de conception, main.jsx fournit le système qui en résulte et App.jsx compose le formulaire. createSystem(defaultConfig, config) conserve les recettes de composants par défaut tout en fusionnant la configuration de l’application. Un système personnalisé sans base demanderait davantage de définitions ; le choix est délibérément d’étendre les valeurs par défaut.
L’aperçu utilise des composants Chakra, et non des éléments de remplacement dessinés. Sa barre latérale est une liste ordonnée de progression propre à l’application ; elle ne prétend pas que le composant Chakra Steps est monté. La carte de profil, les champs, la liste de sélection, les alertes et les boutons sont des compositions Chakra natives.
tokens : valeurs primitives réutilisables, notamment les deux couleurs de marque de l’exemple.
semanticTokens : rôles conditionnels, tels que workspace.action, indépendants des écrans individuels.
recipes : variantes de composants réutilisables ; l’état de l’application React détermine si le formulaire est invalide, en attente, en échec ou confirmé.
Système de design Chakra UI : couleurs primitives et rôles sémantiques du thème
Utilisez des rôles lorsque l’apparence varie
bg.panel et fg.muted décrivent les rôles de surface et de texte ; gray.950 et gray.400 sont les valeurs sous-jacentes. Le tableau de référence indique leur résolution en mode clair et sombre. Dans la démonstration, le passage de la racine du document du mode clair au mode sombre active ces valeurs conditionnelles sans modifier chaque Field ou Card. Ce changement local n’inclut volontairement ni persistance ni intégration des préférences système.
Les rôles workspace.* sont des ajouts propres à l’application. Ils définissent une action bleu sarcelle foncé sur une surface claire et une action bleu sarcelle pâle sur une surface sombre, avec une couleur de texte assortie. Ce ne sont pas des noms de jetons Chakra officiels. Le fait de conserver ces deux valeurs associées dans le thème évite qu’en mode sombre l’arrière-plan du bouton change alors que son libellé reste blanc.
La syntaxe des références diffère de celle des raccourcis de composants
Dans les définitions de jetons, utilisez la référence complète {colors.gray.950}. Dans une propriété de style, bg="workspace.canvas" est résolu dans la catégorie des couleurs. Dans une valeur composée CSS, le chemin complet du jeton est de nouveau nécessaire. Cette distinction évite de confondre une chaîne littérale avec une référence au thème.
Système de design Chakra UI : une échelle typographique lisible avec des jetons explicites
Adapter l’échelle à cette composition
Le titre utilise fontSize="2xl" et lineHeight="shorter" ; le titre de la carte utilise xl, le texte d’aide sm et l’annotation du spécimen xs. Ces choix créent une hiérarchie sans modifier les niveaux de titre sémantiques : le titre de l’écran est un h1 et celui du formulaire, un h2. Le contenu normal du formulaire conserve l’échelle par défaut du corps de texte.
Les piles de polices par défaut de Chakra pour le corps et les titres commencent par Inter, puis utilisent les polices de la plateforme en remplacement. La démonstration autonome ne fait aucune requête de police externe ; la police de remplacement affichée peut donc varier selon le système d’exploitation. Si une typographie précise est nécessaire, hébergez localement une police sous licence appropriée ; définir un jeton de police ne fournit pas les fichiers de police.
La pastille de l’étape en cours est une métadonnée compacte, et non l’instruction principale. Les messages indiquant qu’un champ est requis ou invalide restent à côté de celui-ci, dans un format lisible. Modifier l’espacement des lettres du surtitre ne change pas les libellés du formulaire, et le nom d’espace de travail, même long, reste contenu dans le champ sans modifier la largeur de la carte qui l’entoure.
Système de design Chakra UI : composer Field, NativeSelect, Card et Alert
Field décrit une relation, et non un champ mis en forme
Field.Root regroupe le libellé, le contrôle, l’aide et l’erreur. L’indicateur obligatoire et RequiredIndicator signalent que le champ est requis ; invalid contrôle l’état d’erreur. L’exemple garde l’input contrôlé par React et place l’erreur de nom d’espace de travail dans Field.ErrorText. Il n’applique pas de styles d’erreur séparément à un paragraphe indépendant.
La taille de l’équipe utilise NativeSelect.Root, NativeSelect.Field et NativeSelect.Indicator. Cela préserve le comportement natif d’une liste de sélection pour un ensemble restreint d’options fixes. Le composant ne prétend pas proposer des résultats distants avec recherche : il s’agirait d’un autre contrôle et d’une autre interaction avec les données.
Système de design Chakra UI : appliquer les jetons d’espacement et les propriétés de style adaptatives
Une politique d’espacement concrète
Utilisez gap="6" entre les groupes de champs, gap="3" entre les actions et gap="8" entre la colonne de progression et le formulaire. La marge intérieure de la page passe de p="4" à p="8" au breakpoint md. Avec une racine de 16px, ces valeurs correspondent à 24px, 12px, 32px, 16px et 32px. Les valeurs en rem s’adaptent à la taille de police de la racine définie par l’utilisateur.
La carte utilise rounded="xl" et la pastille d’état, rounded="md". Ces rayons différents sont intentionnels : le grand conteneur et le libellé compact ont des formes distinctes. Ne prenez pas ces choix d’utilisation pour des règles par défaut qui s’imposeraient à toutes les applications Chakra.
Sous md, la grille comporte une seule colonne. À partir de md, une colonne de progression de 220px côtoie un formulaire flexible. minmax(0, 1fr) permet au formulaire de rétrécir dans la grille. La pile d’actions change à partir de sm. Ces valeurs d’objet sont des surcharges mobile-first, et non une détection de l’appareil.
Chakra UI Connecter le système de design : validation, chargement et reprise
La machine à états de l’aperçu
La soumission d’un nom vide après suppression des espaces superflus définit l’état comme invalide et place le focus sur le champ. Une soumission valide passe à l’état pending, désactive la modification et affiche Button loadingText. À la fin du délai local, la case à cocher de simulation d’échec détermine si la démonstration affiche un échec ou une confirmation. Aucune des deux branches n’effectue de requête réseau ni ne stocke de données.
En cas d’échec, le nom contrôlé et la taille sélectionnée sont conservés. Désactiver la simulation d’échec permet de réessayer. Une fois la soumission terminée, les champs du profil sont désactivés et la première pastille de progression change. Reset permet de revenir à la modification. Cela démontre la composition des états visibles, et non un contrat d’enregistrement côté serveur.
Réinitialisez le formulaire et soumettez-le sans nom ; observez le message affiché pour le champ et vérifiez qu’il reçoit le focus.
Saisissez un nom, activez la simulation d’échec de l’enregistrement et soumettez le formulaire ; vérifiez que les valeurs sont conservées après l’erreur.
Désactivez la simulation d’échec et soumettez de nouveau le formulaire ; examinez le récapitulatif de confirmation, puis changez l’apparence.
Chakra UI Préserver la sémantique native dans le système de design par composition
La validation et la progression restent compréhensibles
Le formulaire utilise noValidate afin que cet exemple puisse montrer le parcours d’erreur personnalisé de Field au lieu de s’arrêter à l’interface de validation du navigateur. Le libellé reste associé au champ via Field, et le premier champ invalide reçoit le focus. Le travail en attente est signalé par une région d’état dynamique ; il ne repose pas uniquement sur un indicateur de chargement.
La liste de progression utilise la sémantique d’une liste ordonnée et l’attribut aria-current="step" sur l’élément actif. Elle ne contient pas de faux liens vers des écrans indisponibles. Les deuxième et troisième étapes de l’aperçu donnent du contexte, mais ne sont pas cliquables. Les limites de la démonstration sont ainsi clairement visibles.
Le focus fait partie de la configuration d’action personnalisée
La variante d’intégration définit explicitement un contour visible au focus, avec un décalage. En mode sombre, le rôle du contour change en même temps que celui de l’action. La case à cocher native et le menu de sélection restent utilisables au clavier. Vérifiez également le focus, les annonces des champs, le zoom et le rendu par les lecteurs d’écran dans l’application qui intègre cet exemple ; un exemple au niveau d’un composant ne suffit pas à prouver l’accessibilité d’un produit d’intégration complet.
Chakra UI Recettes, configuration du fournisseur et limites de version du système de design
Étendre Button ; définir Status localement
La variante Button pour l’intégration est ajoutée sous theme.recipes.button. Les variantes existantes, comme outline, restent disponibles, car la configuration étend defaultConfig. La pastille d’état utilise defineRecipe et useRecipe localement : ses variantes d’état associent current, complete et waiting à différents rôles sémantiques. Il s’agit d’un composant de l’application, et non d’un export de Chakra.
Une recette à un seul élément renvoie un objet de styles. Les composants multipièces comme Field comportent plusieurs slots et nécessitent des recettes à slots lorsque leurs parties sont thématisées ensemble. Appliquer à l’ensemble de Field une recette conçue pour un bouton ne permettrait pas de contrôler individuellement son libellé, son contrôle et son message d’erreur.
N’importez pas une configuration v2 fondée sur extendTheme et ne transmettez pas theme={...} à ce fournisseur v3. La racine utilise ChakraProvider value={system}. L’exemple n’ajoute volontairement pas de second fournisseur de mode de couleur : son commutateur local de classe clair/sombre suffit pour cet aperçu isolé, tandis qu’une application réelle peut nécessiter la persistance des préférences et la prise en charge du rendu côté serveur.
Chakra UI Vérifier ensemble le thème et le formulaire dans le système de design
Ce que cet exemple permet de vérifier
L’unité de référence pertinente est la carte de profil complète dans ses deux apparences : libellé, champ de saisie, texte d’aide, indication d’invalidité, bouton en attente, alerte d’échec et récapitulatif de réussite. Un bouton seul ne permet pas de repérer un arrière-plan sémantique manquant ni un état d’erreur déconnecté de son libellé.
Comparez le tableau de référence à l’interface calculée. L’action personnalisée de couleur sarcelle doit se distinguer de l’action outline par défaut ; l’espacement 6 doit séparer les champs ; la grille doit passer à une colonne sous md. Ces vérifications relient les règles écrites au rendu.
Ce que l’exemple ne couvre pas
L’aperçu ne comprend ni création de compte, ni envoi d’invitation, ni persistance, ni authentification, ni intégration à un autre écran d’intégration. Le délai est explicitement une simulation. Lors de la connexion à un véritable point de terminaison, conservez la distinction illustrée entre l’état du champ et celui de la requête, remplacez le délai par la requête et précisez si la confirmation signifie que l’opération a été acceptée localement, enregistrée à distance ou entièrement activée.
Chakra UI Exemples de composants du système de design
theme.js — jetons primitifs, rôles sémantiques et recettes
Thème complet de l’application pour cet exemple. Les rôles de l’espace de travail et la variante d’intégration sont des ajouts originaux ; defaultConfig fournit le thème standard de Chakra.
Les valeurs de marque correspondent volontairement aux couleurs sarcelle primitives de référence.
La recette d’état est locale ; la variante Button est enregistrée dans le système.
App.jsx — exemple complet de formulaire natif et de gestion des états
La composition React utilisée par l’aperçu. Elle comprend le changement de thème, la validation Field, un menu de sélection natif, le retour d’état d’attente, la simulation d’échec, la confirmation et la réinitialisation.
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>;
}
Aucune requête n’est envoyée ; le délai de 600ms illustre l’interface d’attente.
Les étapes suivantes sont des libellés contextuels, et non des éléments de navigation fonctionnels.
04
Chakra UI Configuration de l’agent IA du système de design
Point de départ de l’implémentation
Utilisez une version de Node.js prise en charge par la version de Vite et Chakra installée (Chakra indique prendre en charge Node 20 ou version ultérieure). Ce bloc distingue les commandes de terminal de src/main.jsx. Les fichiers theme et App complets sont fournis plus haut ; aucun extrait de fournisseur caché ni CSS externe n’est nécessaire.
texte
# 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 pour votre projet
Prompt pour l’agent IA
Utilisez Chakra UI 3.37.0, ainsi que les fichiers theme.js et App.jsx fournis, comme point de départ. Préservez les rôles sémantiques de l’espace de travail, la composition de Field, le menu déroulant natif et la distinction entre une saisie invalide et un échec de l’envoi. Remplacez uniquement le minuteur simulé par notre persistance réelle API ; ne confirmez pas la fin du profil avant d’avoir obtenu un résultat confirmé. Préservez le focus clavier, la mise en page adaptative base/md et les valeurs pour les thèmes clair et sombre. Expliquez tout nouveau jeton ou toute nouvelle variante de recette.
05
Sources et périmètre du système de design Chakra UI
Guide d’implémentation d’origine de OpenDesign, fondé sur les bases documentées de Chakra UI v3. Les références aux jetons par défaut sont distinctes des rôles propres à l’espace de travail de l’application. L’aperçu natif montre un état local ; il n’enregistre pas les données de l’espace de travail et ne met pas en œuvre l’intégralité du parcours d’intégration.
