Una referencia de Chakra UI v3 para tokens, funciones semánticas del color, recetas y componentes de formulario compuestos. Examina las escalas reales de espaciado y tipografía; después, prueba un formulario nativo de perfil de espacio de trabajo con validación, una simulación de error al guardar y opciones de apariencia clara y oscura.
Guía de OpenDesign9 capítulos47 entradas de referenciaGuía de aplicación original
01
Chakra UI Vista previa de la interfaz del sistema de diseño
Prueba la validación de campos vacíos, un error simulado al guardar, la conservación de los datos introducidos, la confirmación local correcta y el cambio de apariencia.
Chakra UI nativo 3.37.0 con React 19; paquete autocontenido. Se muestran íntegramente los tokens semánticos y las recetas de la aplicación personalizada. · Referencia de implementación
02
Chakra UI Referencia de diseño del sistema de diseño
Referencias al tema predeterminado de Chakra UI 3.37.0, además de los tokens de aplicación de OpenDesign claramente identificados. Los valores en rem dependen del tamaño de fuente raíz; las equivalencias en píxeles suponen 16px. Esta es una referencia de trabajo seleccionada, no el tema exportado completo.
Sistema de diseño Chakra UI El sistema v3: configuración, tokens y componentes
Crea un sistema en lugar de pasar un objeto de tema antiguo
La implementación tiene tres capas: theme.js define las decisiones de diseño, main.jsx proporciona el sistema resultante y App.jsx compone el formulario. createSystem(defaultConfig, config) conserva las recetas predeterminadas de los componentes y combina la configuración de la aplicación. Un sistema personalizado desde cero requeriría más definiciones; aquí se opta deliberadamente por ampliar los valores predeterminados.
La vista previa usa componentes de Chakra, no elementos sustitutos dibujados. La barra lateral es una lista ordenada de progreso específica de la aplicación; no implica que esté montado el componente Steps de Chakra. La tarjeta del perfil, los campos, el selector, las alertas y los botones son composiciones nativas de Chakra.
tokens: valores primitivos reutilizables, incluidos los dos colores de marca del ejemplo.
semanticTokens: roles que tienen en cuenta las condiciones, como workspace.action, independientes de cada pantalla.
recipes: variantes de componentes reutilizables; el estado de la aplicación React determina si el formulario es inválido, está pendiente, ha fallado o se ha confirmado.
Sistema de diseño Chakra UI: colores primitivos y roles semánticos del tema
Usa roles cuando cambia la apariencia
bg.panel y fg.muted expresan funciones de superficie y texto; gray.950 y gray.400 son los valores subyacentes. La tabla de referencia muestra cómo se resuelven en los modos claro y oscuro. En la demostración, cambiar el elemento raíz del documento entre los modos claro y oscuro activa esos valores condicionales sin tener que modificar cada Field o Card. Este selector local no guarda preferencias ni se integra con las preferencias del sistema.
Los roles workspace.* son añadidos específicos de la aplicación. Eligen una acción en verde azulado oscuro sobre una superficie clara y una acción en verde azulado pálido sobre una superficie oscura, junto con un color de texto a juego. No son nombres oficiales de tokens de Chakra. Mantener el par en el tema evita que, en el modo oscuro, cambie el fondo del botón pero la etiqueta siga siendo blanca.
La sintaxis de referencia es distinta de la abreviada de los componentes
Dentro de las definiciones de tokens, usa la referencia completa {colors.gray.950}. En una propiedad de estilo, bg="workspace.canvas" se resuelve dentro de la categoría de colores. En un valor compuesto CSS, vuelve a ser necesaria la ruta completa del token. Esta distinción evita que se confunda una cadena literal con una referencia al tema.
Sistema de diseño Chakra UI: escala tipográfica legible con tokens explícitos
Adapta la escala a esta composición
El título usa fontSize="2xl" y lineHeight="shorter"; el encabezado de la tarjeta usa xl, el texto de ayuda usa sm y la anotación de la muestra usa xs. Estas elecciones crean jerarquía sin cambiar los niveles semánticos de los encabezados: el título de la pantalla es h1 y el título del formulario es h2. El contenido habitual del formulario conserva la escala predeterminada del texto del cuerpo.
La pila predeterminada de texto del cuerpo y encabezados de Chakra empieza con Inter y recurre a las fuentes de la plataforma. La demostración independiente no solicita fuentes externas, por lo que la fuente de sustitución que se muestra puede variar según el sistema operativo. Si necesitas una tipografía exacta, sirve localmente una fuente con la licencia adecuada; definir un token de fuente no proporciona los archivos de fuente.
Mantén la tipografía y el significado por separado
La etiqueta del paso actual es metadato compacto, no la instrucción principal. Los mensajes de campo obligatorio e inválido permanecen junto al campo y tienen un tamaño legible. Cambiar el espaciado entre letras del texto superior no altera las etiquetas del formulario, y el nombre largo del espacio de trabajo se mantiene dentro del campo de entrada, sin cambiar el ancho de la tarjeta que lo rodea.
Sistema de diseño Chakra UI: combina Field, NativeSelect, Card y Alert
Field es una relación, no un campo de entrada con estilo
Field.Root agrupa la etiqueta, el control, el texto de ayuda y el error. La marca de campo obligatorio y RequiredIndicator comunican que el campo es obligatorio; invalid controla el estado de error. El ejemplo mantiene el valor del campo de entrada controlado mediante React y muestra el error del nombre del espacio de trabajo en Field.ErrorText. No aplica estilos de error por separado a un párrafo independiente.
El tamaño del equipo usa NativeSelect.Root, NativeSelect.Field y NativeSelect.Indicator. Así se conserva el comportamiento nativo del selector para un conjunto breve y fijo de opciones. No pretende ofrecer resultados remotos con búsqueda; eso requeriría otro control y otra interacción con los datos.
Sistema de diseño Chakra UI: aplica tokens de espaciado y propiedades de estilo adaptables
Una política de espaciado concreta
Usa gap="6" entre los grupos de campos, gap="3" entre las acciones y gap="8" entre la columna de progreso y el formulario. El relleno de la página cambia de p="4" a p="8" en md. Con una raíz de 16px, equivalen a 24px, 12px, 32px, 16px y 32px. Los valores basados en rem se adaptan al tamaño de fuente raíz del usuario.
La tarjeta usa rounded="xl" y la etiqueta de estado, rounded="md". Los radios distintos son intencionales: el contenedor grande y la etiqueta compacta tienen geometrías diferentes. No interpretes estas elecciones de uso como reglas predeterminadas que deban seguir todas las aplicaciones de Chakra.
La cuadrícula usa una columna por debajo de md y, a partir de md, una columna de progreso de 220px junto a un formulario flexible. minmax(0, 1fr) permite que el formulario se contraiga dentro de la cuadrícula. La pila de acciones cambia en sm. Estos valores de objeto son ajustes adaptables con prioridad para móviles, no detección de dispositivos.
Sistema de diseño Chakra UI: conecta la validación, la carga y la recuperación
La máquina de estados de la vista previa
Al enviar un nombre vacío después de quitar los espacios sobrantes, se establece invalid y el foco pasa al campo de entrada. Un envío válido pasa al estado pendiente, desactiva la edición y muestra loadingText en Button. Cuando termina el temporizador local, la casilla de error determina si la demostración muestra un error o la confirmación. Ninguna de las dos opciones realiza una solicitud de red ni guarda datos.
Un resultado fallido conserva el nombre controlado y el tamaño seleccionado. Al desactivar la simulación de error, se puede volver a intentar. Al completarse, se desactivan los campos del perfil y cambia el primer indicador de progreso; Restablecer vuelve al modo de edición. Esto demuestra la composición de los estados visibles, no un contrato de guardado del backend.
Restablece el formulario y envíalo sin nombre; revisa el mensaje del campo y el foco del campo de entrada.
Introduce un nombre, activa la simulación de error al guardar y envía el formulario; comprueba que los valores se conserven tras el error.
Desactiva la simulación de error y vuelve a enviar el formulario; revisa el resumen de confirmación y, luego, cambia la apariencia.
Sistema de diseño Chakra UI: conservar la semántica nativa al componer componentes
La validación y el progreso siguen siendo comprensibles
El formulario usa noValidate para que este ejemplo pueda mostrar su ruta de error personalizada de Field en lugar de detenerse en la interfaz de validación del navegador. La etiqueta sigue asociada al campo a través de Field, y el primer campo de entrada no válido recibe el foco. El trabajo pendiente se describe mediante una región de estado activa; no se comunica únicamente con un indicador de carga.
La lista de progreso usa la semántica de una lista ordenada y aria-current="step" en el elemento activo. No incluye enlaces ficticios a pantallas no disponibles. Los pasos segundo y tercero de la vista previa describen el contexto, pero no se pueden seleccionar. Así queda claro el alcance de la demostración.
El foco forma parte de la receta de acción personalizada
La variante de incorporación define explícitamente un contorno para focus-visible con un desplazamiento. La apariencia oscura cambia el rol del contorno junto con el rol de la acción. La casilla de verificación y el selector nativos siguen siendo operables con el teclado. Revisa también el foco, los anuncios de los campos, el zoom y la salida del lector de pantalla en la aplicación que los integre; un ejemplo de componente no puede demostrar la accesibilidad de todo un producto de incorporación.
Sistema de diseño Chakra UI: recetas, configuración del proveedor y límites de versión
Ampliar Button; definir Status localmente
La variante de Button para la experiencia de incorporación se añade en theme.recipes.button. Las variantes existentes, como outline, siguen disponibles porque la configuración amplía defaultConfig. El indicador de estado usa defineRecipe y useRecipe localmente: sus variantes de estado asignan current, complete y waiting a distintos roles semánticos. Es un componente de la aplicación, no una exportación de Chakra.
Una receta de un solo elemento devuelve un objeto de estilos. Los componentes con varias partes, como Field, tienen varias ranuras y necesitan recetas de ranura cuando se aplican estilos a sus partes en conjunto. Aplicar a todo un Field una receta pensada para un botón no permitiría controlar por separado la etiqueta, el control y el mensaje de error.
No importes una configuración de extendTheme de v2 ni pases theme={...} a este proveedor de v3. La raíz real usa ChakraProvider value={system}. El ejemplo no añade intencionadamente un segundo proveedor del modo de color: el cambio local de clase entre claro y oscuro basta para esta vista previa aislada, aunque una aplicación real puede necesitar una preferencia persistente y compatibilidad con la representación del lado del servidor.
Sistema de diseño Chakra UI: verificar el tema y el formulario en conjunto
Qué demuestra este ejemplo
La unidad de revisión relevante es toda la tarjeta del perfil en ambas apariencias: etiqueta, campo de entrada, texto de ayuda, aviso de error, botón en estado pendiente, alerta de error y resumen de confirmación. Un botón por sí solo no permite detectar la falta de un fondo semántico ni un estado de error de un control que no esté asociado a su etiqueta.
Compara la tabla de referencia con la interfaz calculada. La acción personalizada de color verde azulado debería diferenciarse de la acción de contorno predeterminada; el espaciado 6 debería separar los campos; y la cuadrícula debería pasar a una columna por debajo de md. Estas comprobaciones vinculan las reglas escritas con el resultado renderizado.
Qué queda fuera del ejemplo
La vista previa no incluye creación de cuentas, envío de invitaciones, persistencia, autenticación ni integración con otra pantalla de incorporación. El temporizador es explícitamente una simulación. Al conectar un endpoint real, conserva la distinción demostrada entre el estado del campo y el de la solicitud, sustituye el temporizador por la solicitud y define si la finalización significa aceptación local, guardado remoto o activación completa.
Chakra UI Ejemplos de componentes del sistema de diseño
theme.js — tokens primitivos, roles semánticos y recetas
Tema completo de la aplicación para el ejemplo. Los roles del espacio de trabajo y la variante de incorporación son añadidos originales; defaultConfig proporciona el tema estándar de Chakra.
Los valores de marca coinciden deliberadamente con los primitivos verde azulado de referencia.
La receta de estado es local; la variante de Button está registrada en el sistema.
App.jsx — ejemplo completo de formulario nativo y estados
La composición React real que usa la vista previa. Incluye cambio de tema, validación de Field, un selector nativo, indicación de estado pendiente, error simulado, confirmación y restablecimiento.
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>;
}
No se envía ninguna solicitud; la demora de 600ms demuestra la interfaz de estado pendiente.
Los pasos siguientes son etiquetas contextuales, no elementos de navegación funcionales.
04
Chakra UI Configuración del agente de sistema de diseño
Punto de partida para la implementación
Usa una versión de Node.js compatible con la versión instalada de Vite y Chakra (Chakra documenta Node 20 o posterior). Este bloque separa los comandos de terminal de src/main.jsx. Los archivos completos del tema y de App aparecen arriba; no se necesita ningún fragmento de proveedor oculto ni ningún 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
Una instrucción para tu proyecto
Instrucción para el agente
Usa Chakra UI 3.37.0 y los archivos theme.js y App.jsx proporcionados como punto de partida. Conserva los roles semánticos del espacio de trabajo, la composición de Field, el selector nativo y la separación entre una entrada no válida y un envío fallido. Sustituye únicamente el temporizador simulado por nuestra API de persistencia real; no marques el perfil como completado antes del resultado confirmado. Conserva el foco del teclado, la disposición adaptable base/md y los valores de los modos claro y oscuro. Explica los tokens o las variantes de receta que añadas.
05
Chakra UI Fuentes y alcance del sistema de diseño
Guía de implementación original de OpenDesign basada en los fundamentos documentados de Chakra UI v3. Las referencias a los tokens predeterminados se separan de los roles específicos del espacio de trabajo de la aplicación. La vista previa nativa es una demostración local del estado; no guarda datos del espacio de trabajo ni implementa todo el proceso de incorporación.
