Eine Referenz zu Chakra UI v3 für Tokens, semantische Farbrollen, Rezepte und zusammengesetzte Formular-Komponenten. Sieh dir die tatsächlichen Abstands- und Schriftgrößenskalen an und probiere anschließend ein natives Formular für ein Arbeitsbereichsprofil mit Validierung, Simulation eines fehlgeschlagenen Speichervorgangs und heller/dunkler Darstellung aus.
Teste die Validierung leerer Felder, einen simulierten Speicherfehler, beibehaltene Eingaben, eine erfolgreiche lokale Bestätigung und den Wechsel des Erscheinungsbilds.
Natives Chakra UI 3.37.0 mit React 19; eigenständiges Bundle. Benutzerdefinierte semantische Tokens und Rezepte der Anwendung werden vollständig gezeigt. · Implementierungsreferenz
02
Chakra UI-Designsystem – Designreferenz
Referenzen zum Standard-Theme von Chakra UI 3.37.0 sowie ausdrücklich gekennzeichnete Anwendungstokens von OpenDesign. rem-Werte richten sich nach der Schriftgröße des Root-Elements; Pixel-Entsprechungen basieren auf 16px. Dies ist eine ausgewählte Arbeitsreferenz, nicht das vollständige exportierte Theme.
Chakra UI-Designsystem: Das System v3 – Konfiguration, Tokens und Komponenten
Ein System erstellen, statt ein altes Theme-Objekt zu übergeben
Die Implementierung besteht aus drei Ebenen: theme.js definiert die Designentscheidungen, main.jsx stellt das daraus erzeugte System bereit und App.jsx setzt das Formular zusammen. createSystem(defaultConfig, config) behält die standardmäßigen Komponentenrezepte bei und führt sie mit der Anwendungskonfiguration zusammen. Ein vollständig eigenes System würde weitere Definitionen erfordern; hier werden bewusst die Standardwerte erweitert.
Die Vorschau verwendet Chakra-Komponenten statt rein visueller Platzhalter. Die Seitenleiste ist eine anwendungsspezifische, geordnete Fortschrittsliste und behauptet nicht, dass die Chakra-Komponente Steps eingebunden ist. Die Profilkarte, Felder, Auswahl, Hinweise und Schaltflächen sind native Chakra-Kompositionen.
tokens: wiederverwendbare primitive Werte, darunter die beiden Markenfarben des Beispiels.
semanticTokens: an Bedingungen geknüpfte Rollen wie workspace.action, unabhängig von einzelnen Bildschirmen.
recipes: wiederverwendbare Komponentenvarianten; der Anwendungsstatus React legt fest, ob das Formular ungültig, in Bearbeitung, fehlgeschlagen oder bestätigt ist.
Chakra UI-Designsystem: primitive Farben und semantische Theme-Rollen
Rollen verwenden, wenn sich das Erscheinungsbild ändert
bg.panel und fg.muted beschreiben die Aufgaben von Oberfläche und Text; gray.950 und gray.400 sind die zugrunde liegenden Werte. Die Referenztabelle zeigt ihre Auflösung für helle und dunkle Darstellungen. In der Demo aktiviert ein Wechsel des Dokument-Roots zwischen hell und dunkel diese bedingten Werte, ohne jedes Field oder jede Card neu zu schreiben. Dieser lokale Schalter bietet bewusst weder Persistenz noch eine Integration mit den Systemeinstellungen.
Die Rollen workspace.* sind Ergänzungen der Anwendung. Sie wählen eine dunkel-türkise Aktion auf einer hellen Oberfläche und eine hell-türkise Aktion auf einer dunklen Oberfläche sowie jeweils eine passende Textfarbe. Es handelt sich nicht um offizielle Chakra-Token-Namen. Werden beide Werte gemeinsam im Theme gehalten, lässt sich eine Schaltfläche im Dunkelmodus vermeiden, deren Hintergrund sich ändert, während die Beschriftung weiß bleibt.
Die Referenzsyntax unterscheidet sich von der Kurzschreibweise in Komponenten
Verwende in Token-Definitionen die vollständige Referenz {colors.gray.950}. In einer Style-Prop wird bg="workspace.canvas" innerhalb der Farbkategorie aufgelöst. In einem zusammengesetzten Wert CSS wird der vollständige Token-Pfad erneut benötigt. Durch diese Unterscheidung wird eine Zeichenfolge nicht versehentlich für eine Theme-Referenz gehalten.
Chakra UI-Designsystem: eine gut lesbare Schriftgrößenskala mit expliziten Tokens
Die Skala auf diese Komposition abstimmen
Der Titel verwendet fontSize="2xl" und lineHeight="shorter"; die Kartenüberschrift verwendet xl, der Hilfetext sm und die Anmerkung des Beispiels xs. So entsteht eine Hierarchie, ohne die semantischen Überschriftenebenen zu verändern: Der Seitentitel ist ein h1- und der Formulartitel ein h2-Element. Der normale Formularinhalt behält die standardmäßige Fließtextgröße.
Der standardmäßige Text- und Überschriftenstapel von Chakra beginnt mit Inter und verwendet Plattformschriften als Fallback. Die eigenständige Demo fordert keine externen Schriftdateien an; daher kann sich die angezeigte Fallback-Schrift je nach Betriebssystem unterscheiden. Wenn eine exakte Typografie erforderlich ist, stelle eine entsprechend lizenzierte Schrift lokal bereit. Ein Schrift-Token allein liefert keine Schriftdateien.
Der Chip für den aktuellen Schritt ist kompakte Metainformation, nicht die zentrale Anweisung. Hinweise zu Pflichtfeldern und ungültigen Eingaben bleiben neben dem Feld in gut lesbarer Größe. Eine Änderung des Zeichenabstands der Überzeile wirkt sich nicht auf die Formularbeschriftungen aus. Ein langer Workspace-Name bleibt im Eingabefeld, statt die Breite der umgebenden Karte zu verändern.
Chakra UI-Designsystem: Field, NativeSelect, Card und Alert kombinieren
Field beschreibt eine Beziehung, nicht ein gestaltetes Eingabefeld
Field.Root gruppiert Beschriftung, Steuerelement, Hilfetext und Fehlermeldung. Das Pflichtfeldkennzeichen und RequiredIndicator weisen auf die erforderliche Eingabe hin; invalid steuert den Fehlerzustand. Im Beispiel bleibt die Eingabe über React gesteuert, und der Fehler zum Workspace-Namen wird in Field.ErrorText angezeigt. Fehlerstile werden nicht unabhängig auf einen losgelösten Absatz angewendet.
Für die Teamgröße werden NativeSelect.Root, NativeSelect.Field und NativeSelect.Indicator verwendet. So bleibt das native Auswahlverhalten bei einer kurzen, festen Optionsliste erhalten. Eine Suche in Remote-Ergebnissen wird dadurch nicht vorgetäuscht; dafür wären ein anderes Steuerelement und eine andere Dateninteraktion erforderlich.
Chakra UI-Designsystem: Abstandstokens und responsive Style-Props anwenden
Eine konkrete Abstandsregel
Verwenden Sie gap="6" zwischen Feldgruppen, gap="3" zwischen Aktionen und gap="8" zwischen Fortschrittsspalte und Formular. Bei md wechselt das Seiten-Padding von p="4" zu p="8". Bei einer Root-Schriftgröße von 16px entsprechen diese Werte 24px, 12px, 32px, 16px und 32px. Rem-basierte Werte skalieren mit der Root-Schriftgröße des Nutzers.
Die Karte verwendet rounded="xl", der Status-Chip rounded="md". Die unterschiedlichen Radien sind beabsichtigt: Der große Container und die kompakte Beschriftung haben eine unterschiedliche Geometrie. Diese Anwendungsbeispiele sind keine Standardregeln, die für alle Chakra-Anwendungen gelten müssen.
Unterhalb von md verwendet das Grid eine Spalte. Ab md steht neben dem flexiblen Formular eine 220px breite Fortschrittsspalte. minmax(0, 1fr) ermöglicht es dem Formular, innerhalb des Grids zu schrumpfen. Bei sm wechselt die Aktionsanordnung. Diese Objektwerte sind Mobile-First-Überschreibungen und keine Geräteerkennung.
Chakra UI-Designsystem: Validierung, Ladezustand und Wiederherstellung verbinden
Die Zustandsmaschine der Vorschau
Wird ein leerer, getrimmter Name übermittelt, wird der Status auf invalid gesetzt und der Fokus auf das Eingabefeld verschoben. Bei einer gültigen Eingabe wechselt der Zustand zu pending, die Bearbeitung wird deaktiviert und Button loadingText wird angezeigt. Nach dem lokalen Timer bestimmt das Kontrollkästchen für fehlgeschlagene Speicherungen, ob die Demo failed oder complete anzeigt. Keiner der beiden Abläufe sendet eine Netzwerkanfrage oder speichert Daten.
Bei einem fehlgeschlagenen Ergebnis bleiben der eingegebene Name und die ausgewählte Größe erhalten. Wird die Simulation fehlgeschlagener Speicherungen deaktiviert, kann der Vorgang erneut versucht werden. Bei erfolgreichem Abschluss werden die Profilfelder deaktiviert und der erste Fortschritts-Chip geändert. Mit Reset kehrt das Formular in den Bearbeitungszustand zurück. Damit wird die sichtbare Zustandszusammensetzung veranschaulicht, nicht die Funktionsweise eines Speicher-Backends.
Setzen Sie das Formular zurück und übermitteln Sie es ohne Namen. Prüfen Sie die Feldmeldung und das fokussierte Eingabefeld.
Geben Sie einen Namen ein, aktivieren Sie die Simulation fehlgeschlagener Speicherungen und übermitteln Sie das Formular. Prüfen Sie, ob die Werte nach dem Fehler erhalten bleiben.
Deaktivieren Sie die Simulation und übermitteln Sie das Formular erneut. Prüfen Sie die bestätigte Zusammenfassung und ändern Sie anschließend das Erscheinungsbild.
Chakra UI-Designsystem: Native Semantik bei der Zusammensetzung beibehalten
Validierung und Fortschritt bleiben verständlich
Das Formular verwendet noValidate, damit dieses Beispiel den benutzerdefinierten Fehlerpfad von Field veranschaulichen kann, anstatt bei der Validierungsoberfläche des Browsers anzuhalten. Das Label bleibt über Field mit dem Eingabefeld verknüpft, und das erste ungültige Eingabefeld erhält den Fokus. Ein Live-Statusbereich gibt über laufende Vorgänge Auskunft; ein Spinner allein reicht dafür nicht aus.
Die Fortschrittsliste verwendet die Semantik einer geordneten Liste und aria-current="step" für den aktiven Eintrag. Sie enthält keine vorgetäuschten Links zu nicht verfügbaren Ansichten. Der zweite und dritte Schritt der Vorschau beschreiben den Kontext, sind aber nicht anklickbar. So werden die Grenzen der Demo deutlich.
Fokus gehört zum Rezept für benutzerdefinierte Aktionen
Die Onboarding-Variante definiert ausdrücklich eine Kontur für den sichtbaren Fokus samt Abstand. In der dunklen Darstellung ändert sich die Rolle der Kontur gemeinsam mit der Aktionsrolle. Das native Kontrollkästchen und die Auswahlliste lassen sich weiterhin per Tastatur bedienen. Prüfen Sie Fokus, Feldansagen, Zoom und Screenreader-Ausgabe auch in der Anwendung, die die Komponente verwendet. Ein Komponentenbeispiel kann die Barrierefreiheit eines gesamten Onboarding-Produkts nicht nachweisen.
Chakra UI-Designsystem: Rezepte, Provider-Konfiguration und Versionsgrenzen
Button erweitern; Status lokal definieren
Die Onboarding-Variante für Button wird unter theme.recipes.button hinzugefügt. Vorhandene Varianten wie outline bleiben verfügbar, da die Konfiguration defaultConfig erweitert. Der Status-Chip verwendet lokal defineRecipe und useRecipe: Seine Zustandsvarianten ordnen current, complete und waiting unterschiedlichen semantischen Rollen zu. Er ist eine Anwendungskomponente und kein Chakra-Export.
Ein Rezept für ein einzelnes Element gibt ein einzelnes Style-Objekt zurück. Zusammengesetzte Komponenten wie Field haben mehrere Slots und benötigen Slot-Rezepte, wenn ihre Teile gemeinsam gestaltet werden. Ein buttonähnliches Rezept auf das gesamte Field anzuwenden, würde Label, Eingabefeld und Fehlertext nicht einzeln steuern.
Importieren Sie keine v2-Konfiguration mit extendTheme und übergeben Sie diesem v3-Provider nicht theme={...}. Die tatsächliche Root-Komponente verwendet ChakraProvider value={system}. Das Beispiel fügt absichtlich keinen zweiten Color-Mode-Provider hinzu: Für diese isolierte Vorschau reicht der lokale Wechsel zwischen der hellen und dunklen Klasse aus. Eine echte Anwendung benötigt möglicherweise eine gespeicherte Einstellung und Unterstützung für serverseitiges Rendering.
Chakra UI-Designsystem: Theme und Formular gemeinsam überprüfen
Was dieses Beispiel veranschaulicht
Die relevante Prüfeinheit ist die gesamte Profilkarte in beiden Darstellungen: Label, Eingabefeld, Hilfetext, Fehlermeldung, Button im Ladezustand, Fehlermeldung zum Speichern und Erfolgsmeldung. Bei einem einzelnen Button fallen weder ein fehlender semantischer Hintergrund noch ein Fehlerzustand auf, der nicht mit dem Label verknüpft ist.
Vergleichen Sie die Referenztabelle mit der gerenderten Oberfläche. Die benutzerdefinierte türkisfarbene Aktion sollte sich von der standardmäßigen Kontur-Aktion unterscheiden; Abstand 6 sollte die Felder voneinander trennen; unterhalb von md sollte das Grid auf eine Spalte wechseln. Mit diesen Prüfungen lassen sich die dokumentierten Regeln mit der gerenderten Ausgabe abgleichen.
Was nicht Teil des Beispiels ist
Die Vorschau umfasst weder Kontoerstellung noch Einladungsversand, dauerhafte Speicherung, Authentifizierung oder die Integration mit einem anderen Onboarding-Bildschirm. Der Timer ist ausdrücklich eine Simulation. Wenn Sie einen echten Endpunkt anbinden, behalten Sie die gezeigte Unterscheidung zwischen Feld- und Anfragezustand bei, ersetzen Sie den Timer durch die Anfrage und legen Sie fest, ob der Abschluss bedeutet, dass die Eingabe lokal akzeptiert, remote gespeichert oder der Vorgang vollständig aktiviert wurde.
Chakra UI-Designsystem: Komponentenbeispiele
theme.js — primitive Tokens, semantische Rollen und Rezepte
Vollständiges Anwendungstheme für das Beispiel. Die Workspace-Rollen und die Onboarding-Variante sind eigene Ergänzungen; defaultConfig stellt das Standardtheme von Chakra bereit.
Die Markenwerte stimmen bewusst mit den referenzierten Teal-Primitiven überein.
Das Statusrezept ist lokal definiert; die Button-Variante ist im System registriert.
App.jsx — vollständiges Beispiel mit nativen Formularfeldern und Statusverwaltung
Die tatsächliche React-Zusammenstellung, die in der Vorschau verwendet wird. Enthält den Themewechsel, die Validierung von Field, ein natives Auswahlfeld, eine Rückmeldung zum ausstehenden Vorgang, einen simulierten Fehler, eine Bestätigung und die Möglichkeit zum Zurücksetzen.
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>;
}
Es wird keine Anfrage gesendet; die Verzögerung von 600ms veranschaulicht die ausstehende UI.
Die nächsten Schritte sind kontextbezogene Beschriftungen und keine funktionierende Navigation.
04
Einrichtung des Chakra UI-Designsystems-Agenten
Ausgangspunkt für die Implementierung
Verwende eine Node.js-Version, die von der installierten Vite-Version und Chakra unterstützt wird (Chakra dokumentiert Node 20 oder höher). In diesem Block sind Terminalbefehle von src/main.jsx getrennt. Das vollständige Theme und die App-Dateien sind oben enthalten; ein nicht gezeigter Provider-Snippet oder ein externes CSS ist nicht erforderlich.
text
# 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
Ein Prompt für dein Projekt
Agenten-Prompt
Verwende Chakra UI 3.37.0 sowie die bereitgestellten Dateien theme.js und App.jsx als Ausgangspunkt. Behalte die semantischen Workspace-Rollen, die Field-Zusammenstellung, das native Auswahlfeld und die Trennung zwischen ungültiger Eingabe und fehlgeschlagener Übermittlung bei. Ersetze ausschließlich den simulierten Timer durch unsere tatsächliche Persistenz API; markiere das Profil erst nach bestätigtem Ergebnis als abgeschlossen. Bewahre den Tastaturfokus, das responsive base/md-Layout sowie die Werte für helles und dunkles Design. Erläutere alle neuen Tokens oder Rezeptvarianten.
05
Quellen und Geltungsbereich des Chakra UI-Designsystems
Eigenständiger Implementierungsleitfaden für OpenDesign auf Grundlage der dokumentierten Chakra UI-v3-Basiselemente. Standard-Tokenreferenzen sind von anwendungsspezifischen Workspace-Rollen getrennt. Die native Vorschau demonstriert lokale Zustände; sie speichert keine Workspace-Daten und bildet nicht den gesamten Onboarding-Ablauf ab.
