Uma referência do Chakra UI v3 para tokens, funções de cores semânticas, receitas e componentes compostos de formulário. Examine as escalas reais de espaçamento e tipografia e experimente um formulário nativo de perfil de espaço de trabalho, com validação, simulação de falha ao salvar e aparência clara/escura.
Guia OpenDesign9 capítulos47 itens de referênciaGuia de aplicação original
01
Prévia da interface do sistema de design Chakra UI
Experimente a validação de campos vazios, uma falha simulada ao salvar, a retenção dos dados inseridos, a confirmação local de sucesso e a alternância de aparência.
Chakra UI nativo 3.37.0 com React 19; pacote autocontido. Os tokens semânticos e as receitas personalizados do aplicativo são apresentados na íntegra. · Referência de implementação
02
Referência de design do sistema de design Chakra UI
Referências do tema padrão do Chakra UI 3.37.0, além dos tokens do aplicativo OpenDesign, identificados explicitamente. Os valores em rem seguem o tamanho da fonte raiz; os equivalentes em pixels consideram 16px. Esta é uma referência de trabalho selecionada, não o tema exportado completo.
Sistema de design Chakra UI: o sistema v3 — configuração, tokens e componentes
Crie um sistema em vez de repassar um objeto de tema antigo
A implementação tem três camadas: theme.js define as decisões de design, main.jsx fornece o sistema resultante e App.jsx compõe o formulário. createSystem(defaultConfig, config) mantém as receitas de componentes padrão ao mesclar a configuração da aplicação. Um sistema personalizado sem esses padrões exigiria mais definições; estender os padrões é uma escolha deliberada.
A prévia usa componentes do Chakra, não elementos substitutos desenhados. A barra lateral é uma lista ordenada de etapas, específica da aplicação; ela não afirma que o componente Steps do Chakra esteja montado. O cartão de perfil, os campos, o seletor, os alertas e os botões são composições nativas do Chakra.
tokens: valores primitivos reutilizáveis, incluindo as duas cores de marca do exemplo.
semanticTokens: funções condicionais, como workspace.action, independentes de telas específicas.
recipes: variantes reutilizáveis de componentes; o estado de React da aplicação controla se o formulário está inválido, pendente, com falha ou confirmado.
Sistema de design Chakra UI: cores primitivas e funções semânticas do tema
Use funções semânticas quando a aparência mudar
bg.panel e fg.muted expressam funções de superfície e texto; gray.950 e gray.400 são os valores subjacentes. A tabela de referência mostra como eles são resolvidos nos modos claro e escuro. Na demonstração, alternar o elemento raiz do documento entre os modos claro e escuro ativa esses valores condicionais sem reescrever cada Field ou Card. Essa alternância local não inclui persistência nem integração com as preferências do sistema.
As funções workspace.* são acréscimos específicos da aplicação. Elas definem uma ação em verde-azulado escuro sobre uma superfície clara e uma ação em verde-azulado pálido sobre uma superfície escura, além de uma cor de texto correspondente. Não são nomes oficiais de tokens do Chakra. Manter o par no tema evita um botão de modo escuro cujo fundo muda, mas cujo rótulo continua branco.
A sintaxe de referência é diferente da forma abreviada dos componentes
Nas definições de tokens, use a referência completa {colors.gray.950}. Em uma propriedade de estilo, bg="workspace.canvas" é resolvido na categoria de cores. Em um valor composto de CSS, o caminho completo do token é necessário novamente. Essa distinção evita que uma string literal seja confundida com uma referência ao tema.
Sistema de design Chakra UI: uma escala tipográfica legível com tokens explícitos
Associe a escala a esta composição
O título usa fontSize="2xl" e lineHeight="shorter"; o cabeçalho do cartão usa xl; o texto de apoio usa sm; e a anotação da amostra usa xs. Essas escolhas criam hierarquia sem alterar os níveis semânticos dos títulos: o título da tela é h1 e o título do formulário é h2. O conteúdo normal do formulário permanece na escala padrão do texto corrido.
As pilhas padrão de texto corrido e títulos do Chakra começam com Inter e recorrem às fontes da plataforma como alternativa. A demonstração autocontida não faz solicitações externas de fontes, então a fonte alternativa renderizada pode variar conforme o sistema operacional. Se a tipografia exata for necessária, disponibilize localmente uma fonte com a licença adequada; definir um token de fonte não fornece os arquivos da fonte.
Mantenha a tipografia e o significado independentes
O indicador da etapa atual é um metadado compacto, não a instrução principal. As mensagens de campo obrigatório e de erro permanecem ao lado do campo, em uma escala legível. Alterar o espaçamento entre letras do antetítulo não afeta os rótulos do formulário, e um nome de espaço de trabalho longo permanece dentro do campo de entrada, sem alterar a largura do cartão ao redor.
Sistema de design Chakra UI: componha Field, NativeSelect, Card e Alert
Field representa uma relação, não apenas um campo de entrada estilizado
Field.Root agrupa o rótulo, o controle, o texto de apoio e o erro. O sinalizador de campo obrigatório e RequiredIndicator comunicam a obrigatoriedade; invalid controla o estado de erro. O exemplo mantém o campo de entrada controlado por meio de React e posiciona o erro do nome do espaço de trabalho em Field.ErrorText. Os estilos de erro não são aplicados de forma independente a um parágrafo separado.
O tamanho da equipe usa NativeSelect.Root, NativeSelect.Field e NativeSelect.Indicator. Isso mantém o comportamento nativo de seleção para um conjunto curto e fixo de opções. Não finge oferecer resultados remotos com busca; isso exigiria outro controle e outra interação com os dados.
Sistema de design Chakra UI: aplique tokens de espaçamento e propriedades de estilo responsivas
Uma política de espaçamento concreta
Use gap="6" entre grupos de campos, gap="3" entre ações e gap="8" entre a coluna de progresso e o formulário. O preenchimento da página muda de p="4" para p="8" em md. Com uma raiz de 16px, esses valores correspondem a 24px, 12px, 32px, 16px e 32px. Valores baseados em rem acompanham o tamanho da fonte raiz definido pelo usuário.
O cartão usa rounded="xl" e o indicador de status, rounded="md". Os diferentes raios são intencionais: o contêiner grande e o rótulo compacto têm geometrias distintas. Não interprete essas escolhas de uso como regras padrão que todas as aplicações Chakra devam seguir.
A grade usa uma coluna abaixo de md e, a partir de md, uma coluna de progresso de 220px ao lado de um formulário flexível. minmax(0, 1fr) permite que o formulário encolha dentro da grade. A pilha de ações muda em sm. Esses valores de objeto são substituições com prioridade para dispositivos móveis, não detecção de dispositivos.
Sistema de design Chakra UI: conecte validação, carregamento e recuperação
A máquina de estados da prévia
Enviar um nome vazio após remover os espaços em branco define invalid e dá foco ao campo de entrada. Um envio válido passa ao estado pending, desativa a edição e exibe Button loadingText. Após o temporizador local, a caixa de seleção de falha determina se a demonstração mostra failed ou complete. Nenhum dos caminhos faz uma solicitação de rede ou armazena dados.
Um resultado de falha mantém o nome controlado e o tamanho selecionado. Desativar a simulação de falha permite tentar novamente. A conclusão desativa os campos do perfil e altera o primeiro indicador de progresso; Redefinir retorna ao modo de edição. Isso demonstra a composição visual dos estados, não um contrato de persistência no backend.
Redefina o formulário e envie sem informar um nome; confira a mensagem do campo e o foco no campo de entrada.
Informe um nome, ative a simulação de falha ao salvar e envie; verifique se os valores permanecem após o erro.
Desative a simulação de falha e envie novamente; confira o resumo de confirmação e, em seguida, altere a aparência.
Sistema de design Chakra UI: preserve a semântica nativa na composição
Validação e progresso fáceis de entender
O formulário usa noValidate para que este exemplo demonstre o caminho personalizado de erro do Field, em vez de interromper o fluxo com a interface de validação do navegador. O rótulo continua associado por meio do Field, e o primeiro campo inválido recebe o foco. O trabalho pendente é descrito por uma região de status dinâmica; não é indicado apenas por um ícone de carregamento.
A lista de progresso usa a semântica de lista ordenada e aria-current="step" no item ativo. Ela não inclui links fictícios para telas indisponíveis. A segunda e a terceira etapas da visualização contextualizam o processo, mas não são clicáveis. Assim, os limites da demonstração ficam visíveis.
A variante de integração define explicitamente um contorno para :focus-visible com espaçamento externo. A aparência escura altera a função semântica do contorno junto com a da ação. A caixa de seleção e o menu de seleção nativos continuam operáveis pelo teclado. Revise também o foco, os anúncios dos campos, a ampliação e a saída do leitor de tela no aplicativo que consome o componente; um exemplo isolado de componente não comprova a acessibilidade de todo um produto de integração.
Sistema de design Chakra UI: receitas, configuração do provider e limites de versão
Amplie Button; defina Status localmente
A variante de Button da integração é adicionada em theme.recipes.button. Variantes existentes, como outline, continuam disponíveis porque a configuração amplia defaultConfig. O indicador de status usa defineRecipe e useRecipe localmente: as variantes de estado associam current, complete e waiting a diferentes funções semânticas. É um componente do aplicativo, não uma exportação do Chakra.
Uma receita de elemento único retorna um objeto de estilos. Componentes com várias partes, como Field, têm diversos slots e precisam de receitas de slots quando suas partes são tematizadas em conjunto. Aplicar uma receita semelhante à de um botão a um Field inteiro não permitiria controlar individualmente o rótulo, o controle e o erro.
Não importe uma configuração v2 de extendTheme nem passe theme={...} para este provider v3. A raiz real usa ChakraProvider value={system}. O exemplo intencionalmente não adiciona um segundo provider de modo de cor: a alternância local entre as classes light e dark é suficiente para esta visualização isolada, enquanto um aplicativo real pode precisar de preferência persistida e suporte à renderização no servidor.
Sistema de design Chakra UI: verifique o tema e o formulário em conjunto
O que este exemplo demonstra
A unidade relevante para revisão é o cartão de perfil completo nas duas aparências: rótulo, campo de entrada, texto de ajuda, feedback de erro, botão durante o processamento, alerta de falha e resumo de sucesso. Um botão isolado não revela a ausência de um fundo semântico nem um controle cujo estado de erro não esteja associado ao rótulo.
Compare a tabela de referência com a interface renderizada. A ação personalizada em tons de verde-azulado deve ser diferente da ação padrão com contorno; o espaçamento 6 deve separar os campos; a grade deve passar a uma coluna abaixo de md. Essas verificações relacionam as regras descritas ao resultado renderizado.
O que não está incluído no exemplo
A visualização não inclui criação de conta, envio de convite, persistência, autenticação nem integração com outra tela de integração. O temporizador é explicitamente uma simulação. Ao conectar um endpoint real, mantenha a distinção demonstrada entre o estado do campo e o estado da solicitação, substitua o temporizador pela solicitação e defina se a conclusão significa aceitação local, salvamento remoto ou ativação completa.
Chakra UI Exemplos de componentes do sistema de design
theme.js — tokens primitivos, funções semânticas e receitas
Tema completo do aplicativo para o exemplo. As funções semânticas do workspace e a variante de integração são adições originais; defaultConfig fornece o tema padrão do Chakra.
Os valores da marca correspondem intencionalmente aos primitivos verde-azulados referenciados.
A receita de status é local; a variante de Button é registrada no sistema.
App.jsx — exemplo completo de formulário nativo e estados
A composição React real usada pela visualização. Inclui alternância de tema, validação com Field, menu de seleção nativo, feedback de processamento, falha simulada, confirmação e redefinição.
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>;
}
Nenhuma solicitação é enviada; o atraso de 600ms demonstra a interface durante o processamento.
As próximas etapas são rótulos contextuais, não uma navegação funcional.
04
Chakra UI Configuração do agente de IA para o sistema de design
Ponto de partida para implementação
Use uma versão do Node.js compatível com a versão instalada do Vite e com o Chakra (a documentação do Chakra recomenda Node 20 ou posterior). Este bloco separa os comandos de terminal de src/main.jsx. Os arquivos completos de tema e App estão acima; não é necessário nenhum trecho oculto de configuração do provider nem nenhum CSS externo.
texto
# 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
Um prompt para seu projeto
Prompt para agente de IA
Use Chakra UI 3.37.0 e os arquivos theme.js e App.jsx fornecidos como ponto de partida. Preserve as funções semânticas do workspace, a composição do Field, o menu de seleção nativo e a distinção entre entrada inválida e falha no envio. Substitua apenas o temporizador simulado pela nossa API de persistência real; não indique que o perfil foi concluído antes da confirmação do resultado. Preserve o foco pelo teclado, o layout responsivo base/md e os valores para os modos claro e escuro. Explique quaisquer novos tokens ou variantes de receita.
05
Chakra UI Fontes e escopo do sistema de design
Guia de implementação original de OpenDesign, baseado nos fundamentos documentados do Chakra UI v3. As referências padrão dos tokens são separadas das funções específicas do espaço de trabalho do aplicativo. A prévia nativa demonstra o estado local; ela não salva dados do espaço de trabalho nem implementa toda a jornada de integração.
