Справочник по Chakra UI v3: токены, семантические роли цветов, рецепты и составные компоненты форм. Изучите реальные шкалы отступов и типографики, а затем попробуйте встроенную форму профиля рабочего пространства с валидацией, имитацией ошибки сохранения и светлым и тёмным оформлением.
Нативный Chakra UI 3.37.0 с React 19; автономный пакет. Пользовательские семантические токены и рецепты приложения приведены полностью. · Справочник по реализации
02
Справочник по системе дизайна Chakra UI
Справочные материалы по теме по умолчанию Chakra UI 3.37.0 и явно обозначенные токены приложения OpenDesign. Значения в rem зависят от размера корневого шрифта; эквиваленты в пикселях рассчитаны для 16px. Это избранный практический справочник, а не полная экспортированная тема.
Система дизайна Chakra UI: система v3 — конфигурация, токены и компоненты
Создайте систему вместо передачи устаревшего объекта темы
Реализация состоит из трёх уровней: theme.js задаёт решения по дизайну, main.jsx предоставляет полученную систему, а App.jsx собирает форму. createSystem(defaultConfig, config) сохраняет стандартные рецепты компонентов и объединяет их с конфигурацией приложения. Для полностью самостоятельной пользовательской системы потребовалось бы описать больше параметров; здесь намеренно расширяются настройки по умолчанию.
В предварительном просмотре используются компоненты Chakra, а не нарисованные имитации. Боковая панель — созданный для приложения упорядоченный список шагов, а не утверждение, что используется компонент Chakra Steps. Карточка профиля, поля, список выбора, уведомления и кнопки собраны из нативных компонентов Chakra.
tokens: повторно используемые исходные значения, включая два фирменных цвета из примера.
semanticTokens: роли с учётом условий, например workspace.action, не зависящие от отдельных экранов.
recipes: варианты компонентов для повторного использования; состояние React приложения определяет, является ли форма недействительной, ожидающей, завершившейся ошибкой или подтверждённой.
Система дизайна Chakra UI: исходные цвета и семантические роли темы
Используйте роли, когда оформление меняется
bg.panel и fg.muted обозначают назначение поверхности и текста; исходные значения — gray.950 и gray.400. В справочной таблице показано, как они разрешаются для светлой и тёмной темы. В демонстрации переключение корневого элемента документа между светлой и тёмной темами активирует соответствующие условные значения без изменения каждого Field или Card. Этот локальный переключатель намеренно не сохраняет настройки и не учитывает системные предпочтения.
Роли workspace.* добавлены приложением. Они задают тёмно-бирюзовую кнопку действия на светлой поверхности и светло-бирюзовую кнопку на тёмной, а также соответствующий цвет текста. Это не официальные названия токенов Chakra. Хранение пары в теме предотвращает ситуацию, когда в тёмном режиме меняется фон кнопки, а её подпись остаётся белой.
Синтаксис ссылок отличается от сокращённой записи компонентов
В определениях токенов используйте полную ссылку {colors.gray.950}. В свойстве стиля bg="workspace.canvas" разрешается в рамках категории цветов. В составном значении CSS снова требуется полный путь к токену. Это различие не позволяет принять обычную строку за ссылку на тему.
Система дизайна Chakra UI: удобная для чтения шкала размеров с явно заданными токенами
Адаптируйте шкалу под эту композицию
Для заголовка страницы заданы fontSize="2xl" и lineHeight="shorter", для заголовка карточки — xl, для вспомогательного текста — sm, а для аннотации образца — xs. Так создаётся визуальная иерархия без изменения семантических уровней заголовков: заголовок страницы — h1, а заголовок формы — h2. Обычный текст формы сохраняет размер по умолчанию.
В стандартном стеке шрифтов Chakra для основного текста и заголовков первым указан Inter, за которым следуют системные шрифты. Автономная демонстрация не загружает шрифты извне, поэтому отображаемый запасной шрифт может различаться в зависимости от операционной системы. Если нужна точная типографика, разместите локально шрифт с подходящей лицензией: одного задания токена шрифта недостаточно для загрузки файлов шрифтов.
Метка текущего шага — компактная дополнительная информация, а не основная инструкция. Сообщения об обязательном поле и ошибке остаются рядом с полем и набраны читаемым размером. Изменение межбуквенного интервала надзаголовка не затрагивает подписи полей, а длинное название рабочего пространства помещается внутри поля ввода, не меняя ширину окружающей карточки.
Система дизайна Chakra UI: компоненты Field, NativeSelect, Card и Alert
Field — это группа связанных элементов, а не стилизованное поле ввода
Field.Root объединяет подпись, элемент управления, вспомогательный текст и сообщение об ошибке. Обязательность поля обозначают флаг required и RequiredIndicator; параметр invalid задаёт состояние ошибки. В примере значение поля контролируется через React, а сообщение об ошибке для названия рабочего пространства помещено в Field.ErrorText. Стили ошибки не задаются отдельно для несвязанного с полем абзаца.
Для размера команды используются NativeSelect.Root, NativeSelect.Field и NativeSelect.Indicator. Это сохраняет нативное поведение списка выбора для короткого фиксированного набора вариантов. Компонент не имитирует поиск по удалённым результатам: для этого потребовались бы другой элемент управления и иной сценарий взаимодействия с данными.
Система дизайна Chakra UI: используйте токены интервалов и адаптивные свойства стилей
Конкретная политика отступов
Используйте gap="6" между группами полей, gap="3" между действиями и gap="8" между колонкой прогресса и формой. При md значение страницы меняется с p="4" на p="8". При корневом размере шрифта 16px этим значениям соответствуют 24px, 12px, 32px, 16px и 32px. Значения в rem масштабируются вместе с корневым размером шрифта пользователя.
Для карточки используется rounded="xl", а для чипа статуса — rounded="md". Разница в радиусах намеренная: у большого контейнера и компактной метки разная геометрия. Не воспринимайте эти варианты использования как правила по умолчанию для всех приложений Chakra.
Ниже md сетка состоит из одной колонки, а начиная с md рядом с гибкой формой располагается колонка прогресса шириной 220px. minmax(0, 1fr) позволяет форме сжиматься внутри сетки. При sm меняется расположение действий. Эти значения объектов — переопределения в подходе mobile-first, а не определение типа устройства.
Дизайн-система Chakra UI: объедините проверку, загрузку и восстановление
Конечный автомат состояний предпросмотра
Если отправить пустое имя после удаления пробелов по краям, задаётся состояние invalid и фокус переходит на поле ввода. При отправке корректного значения форма переходит в состояние pending, редактирование блокируется, а кнопка показывает Button loadingText. По окончании локального таймера флажок ошибки определяет, будет ли показан результат failed или complete. Ни одна из веток не отправляет сетевой запрос и не сохраняет данные.
После ошибки введённое имя и выбранный размер остаются без изменений. Отключив имитацию ошибки, можно повторить попытку. Завершение блокирует поля профиля и меняет первый чип прогресса; кнопка Reset возвращает форму в режим редактирования. Это демонстрирует композицию видимых состояний, а не контракт сохранения на сервере.
Сбросьте форму и отправьте её без имени; проверьте сообщение поля и фокус на поле ввода.
Введите имя, включите имитацию ошибки при сохранении и отправьте форму; убедитесь, что после ошибки значения не сбрасываются.
Отключите имитацию ошибки и отправьте форму ещё раз; проверьте подтверждённое резюме, а затем измените оформление.
Дизайн-система Chakra UI: сохраняйте нативную семантику при композиции
Проверка и прогресс должны оставаться понятными
В форме используется noValidate, чтобы этот пример показывал пользовательский сценарий ошибки Field, а не останавливался на интерфейсе встроенной проверки браузера. Метка остаётся связанной с полем через Field, а фокус при первой ошибке перемещается на соответствующее поле ввода. О ходе обработки сообщает область с динамическим статусом; одного индикатора загрузки недостаточно.
Для списка прогресса используется семантика упорядоченного списка, а активный пункт помечен атрибутом aria-current="step". Здесь нет фиктивных ссылок на недоступные экраны. Второй и третий шаги предпросмотра описывают контекст, но по ним нельзя перейти. Так становится заметно ограничение демонстрации.
Вариант для онбординга задаёт явную обводку outline для состояния focus-visible и отступ для неё. При тёмном оформлении роль обводки меняется вместе с ролью действия. Нативные флажок и список выбора доступны с клавиатуры. Также проверьте фокус, озвучивание полей, масштабирование и вывод программы чтения с экрана в приложении, где используется компонент: пример отдельного компонента не может подтвердить доступность всего продукта для онбординга.
Дизайн-система Chakra UI: рецепты, настройка провайдера и границы версий
Расширьте Button; определите Status локально
Вариант Button для онбординга добавляется в theme.recipes.button. Существующие варианты, например outline, остаются доступны, поскольку конфигурация расширяет defaultConfig. Для чипа статуса локально используются defineRecipe и useRecipe: варианты состояний связывают current, complete и waiting с разными семантическими ролями. Это компонент приложения, а не экспорт Chakra.
Рецепт для одного элемента возвращает один объект стилей. Составные компоненты, например Field, содержат несколько слотов; если их части оформляются вместе, нужны рецепты слотов. Рецепт для кнопки не позволит отдельно управлять меткой, полем управления и сообщением об ошибке в Field.
Не импортируйте конфигурацию v2 с extendTheme и не передавайте theme={...} этому провайдеру v3. В корневом компоненте используется ChakraProvider value={system}. В примере намеренно не добавлен второй провайдер цветового режима: локального переключения классов light/dark достаточно для изолированного предпросмотра, а реальному приложению может понадобиться сохранять предпочтение и поддерживать серверный рендеринг.
Дизайн-система Chakra UI: проверьте тему и форму вместе
Что демонстрирует этот пример
Проверять следует всю карточку профиля в обоих вариантах оформления: метку, поле ввода, пояснение, сообщение об ошибке, кнопку в состоянии pending, предупреждение об ошибке и сводку об успешном завершении. Одна кнопка не покажет отсутствие семантического фона или то, что состояние ошибки элемента управления не связано с его меткой.
Сравните справочную таблицу с вычисленным интерфейсом. Пользовательское действие бирюзового цвета должно отличаться от стандартного действия с вариантом outline; между полями должен быть отступ 6; ниже md сетка должна переходить в одну колонку. Эти проверки связывают описанные правила с отображаемым результатом.
Что не входит в этот пример
В предпросмотре нет создания учётной записи, отправки приглашений, сохранения данных, аутентификации и интеграции с другими экранами онбординга. Таймер прямо обозначен как имитация. При подключении реальной конечной точки сохраните показанное различие между состояниями поля и запроса, замените таймер запросом и определите, что означает завершение: локальное подтверждение, сохранение на сервере или полную активацию.
Примеры компонентов дизайн-системы Chakra UI
theme.js — примитивные токены, семантические роли и рецепты
Полная тема приложения для этого примера. Роли workspace и вариант для онбординга добавлены специально; defaultConfig предоставляет стандартную тему Chakra.
Значения бренда намеренно соответствуют указанным примитивам бирюзового цвета.
Рецепт статуса локальный; вариант Button зарегистрирован в системе.
App.jsx — пример нативной формы и её состояний
Фактическая композиция React, используемая в предпросмотре. Включает переключение темы, проверку Field, нативный список выбора, обратную связь при обработке, имитацию ошибки, подтверждение и сброс.
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>;
}
Запрос не отправляется; задержка 600ms демонстрирует интерфейс состояния pending.
Следующие шаги — контекстные метки, а не работающая навигация.
04
Настройка агента дизайн-системы Chakra UI
Отправная точка для реализации
Используйте версию Node.js, поддерживаемую установленным выпуском Vite и Chakra (в документации Chakra указана Node 20 или новее). В этом блоке команды терминала отделены от src/main.jsx. Полные файлы темы и App приведены выше; никаких скрытых фрагментов кода провайдера или внешнего CSS не требуется.
текст
# 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
Запрос для вашего проекта
Промпт для AI-агента
Используйте Chakra UI 3.37.0, а в качестве основы — предоставленные theme.js и App.jsx. Сохраните семантические роли workspace, композицию Field, нативный список выбора и различие между некорректным вводом и ошибкой отправки. Замените только имитацию таймера на фактический процесс сохранения API; не отмечайте профиль завершённым до подтверждения результата. Сохраните фокус клавиатуры, адаптивную раскладку base/md и значения для светлого и тёмного оформления. Объясните все новые токены и варианты рецептов.
05
Дизайн-система Chakra UI: источники и область применения
Оригинальное руководство по реализации OpenDesign на основе документированных принципов Chakra UI v3. Ссылки на стандартные токены отделены от специфичных для приложения ролей workspace. Нативный предпросмотр демонстрирует локальные состояния; он не сохраняет данные workspace и не реализует весь сценарий онбординга.
