re:re:actable
Урок 013 минуты чтения

Как спроектировать дизайн-систему и 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам