Как спроектировать дизайн-систему и UI-кит
На этой странице
Дизайн-система — общий язык дизайна и разработки: дизайн-токены (цвета, отступы, типографика, радиусы, тени), библиотека компонентов (Button, Input, Modal, Table), правила использования, доступность и документация. Во фронтенде это пакет компонентов с понятным API, темами через CSS-переменные, витриной в Storybook, визуальными и a11y-тестами и версионированием по semver. Задача «спроектируй UI-кит» проверяет умение проектировать API компонентов и думать о десятках команд-потребителей.
Вопрос
Как спроектировать дизайн-систему и библиотеку компонентов? Как устроить токены, темы, API компонентов, документацию и выпуск версий?
Уровни дизайн-системы
Токены --color-primary, --space-4, --radius-md, --font-size-lg
↓
Примитивы Box, Stack, Text, Icon, VisuallyHidden
↓
Компоненты Button, Input, Select, Checkbox, Modal, Tooltip, Tabs, Toast
↓
Паттерны форма, пустое состояние, страница ошибки, таблица с фильтрамиТокены и темы
:root {
/* базовые (primitive) */
--blue-600: #2563eb;
--gray-900: #111827;
/* семантические — их используют компоненты */
--color-bg: #ffffff;
--color-text: var(--gray-900);
--color-accent: var(--blue-600);
--space-2: 0.5rem;
--space-4: 1rem;
--radius-md: 8px;
}
[data-theme="dark"] {
--color-bg: #0b1120;
--color-text: #e5e7eb;
}Компоненты используют только семантические токены — смена темы или бренда не требует правки компонентов. Источник токенов — JSON (Style Dictionary, Tokens Studio), из которого генерируются CSS, TS и токены для мобильных платформ.
API компонентов
<Button variant="primary" size="md" loading={isSaving} leftIcon={<SaveIcon />} onClick={save}>
Сохранить
</Button>
<Select label="Город" options={cities} value={city} onChange={setCity} error={errors.city} />
<Dialog open={open} onOpenChange={setOpen}>
<Dialog.Title>Удалить проект?</Dialog.Title>
<Dialog.Description>Действие нельзя отменить.</Dialog.Description>
<Dialog.Actions>…</Dialog.Actions>
</Dialog>Принципы:
- ограниченный набор вариантов (
variant,size) вместо десятков булевых флагов; - нативные атрибуты прокидываются (
...rest,ref), типы расширяютComponentProps<"button">; - controlled и uncontrolled режимы (
value/defaultValue,open/defaultOpen); - композиция через compound-компоненты и
asChildдля сложных виджетов; - доступность встроена: фокус, клавиатура, ARIA — потребителю не нужно об этом думать;
- для сложных виджетов берут headless-основу (Radix UI, React Aria, Headless UI) и добавляют свои стили.
Стили
| Подход | Плюсы | Минусы |
|---|---|---|
| CSS Modules + CSS-переменные | без рантайма, понятно | вариативность через классы |
| Tailwind + cva | быстро, согласованность токенов | разметка потребителя зависит от Tailwind |
| Zero-runtime CSS-in-JS (vanilla-extract, Panda) | типизированные стили | сборка сложнее |
| Runtime CSS-in-JS | динамика | рантайм, проблемы с RSC и SSR |
Документация, тесты, выпуск
- Storybook: истории всех состояний, контролы, документация, примеры использования «делай / не делай»;
- тесты: unit и взаимодействия (RTL), визуальные регрессии (Chromatic, Playwright screenshots), a11y (axe);
- версионирование: semver, changelog (Changesets), breaking changes — только в major с гайдом миграции и codemod;
- распространение: npm-пакет с tree shaking (ESM,
sideEffects), отдельный пакет иконок и токенов; - принятие: линтер-правила против «самописных» кнопок, метрики использования компонентов.
Что важно помнить
- Дизайн-система — продукт для разработчиков: важны документация, стабильный API и поддержка.
- Семантические токены вместо прямых цветов делают темы и ребрендинг дешевыми.
- Доступность — одно из главных преимуществ общей библиотеки: исправили один раз — исправлено везде.
- Не делайте компонент слишком гибким: каждый новый prop — это поддержка навсегда.
- Связанные темы: Atomic Design, Compound Components, Storybook и визуальные тесты.
Мини-шпаргалка
Токены (primitive → semantic) → примитивы → компоненты → паттерны. Темы — CSS-переменные. API: варианты вместо флагов, проброс атрибутов и ref, controlled/uncontrolled, compound, встроенная a11y, headless-основа. Storybook, визуальные и a11y-тесты, semver + changelog, tree shaking.
Документация
Storybook, Radix UI Primitives, React Aria, Style Dictionary, Design Tokens Community Group.