Дизайн-система от нуля до Storybook

Orchestrator-промт: построй дизайн-систему за один проход. Продукт: {{product_context}}. Текущее состояние UI: {{existing_ui}}. Команда: {{team_size}}.

Действуй как Head of Design Systems с опытом запуска DS в 3+ продуктах. Не торопись, не пропускай фазы. Каждая фаза имеет вход, выход и критерий готовности.

Когда применять

Чёткое решение строить DS:

• Продукт растёт (3+ продуктовые команды, 5+ потоков фич в неделю)
• Дублирование UI кода видно (8 вариантов кнопки, 12 типов карточки)
• Боль уже горит: дизайнеры рисуют один компонент по-разному, фронты копипастят, QA ловит регрессии в визуале

Когда НЕ строить:

• MVP 1-2 экрана — overhead больше пользы
• Exit меньше года — не окупится
• Solo founder без планов нанимать — tokens достаточно

7 фаз

Phase 1: Audit (день 1-2)

Цель: понять, что у тебя уже есть, прежде чем решать что добавить.

Что сделать:

• Скриншоты 10-15 ключевых экранов (login, dashboard, settings, list, detail, form, modal, empty state, error, loading)
• Inventory компонентов: сколько разных кнопок? карточек? форм? Назови каждый вариант ("Button A", "Button B"…)
• Spacing chaos: измерь padding/margin в 20 местах — найди все используемые значения
• Color coverage: вытащи hex/rgb из CSS — сколько уникальных? Группируй по семантике (success/danger/info)
• Typography: сколько font-size, line-height, font-weight встречается?

Output: inventory.md с таблицей + screenshots/ папка. Критерий готовности: команда смотрит и говорит "да, реально так и есть".

Phase 2: Tokens (день 3-4)

Цель: создать единый источник правды для дизайн-решений. Не цвета — решения о цветах.

Что сделать:

• Color: семантические токены (color-bg-primary, color-text-danger, color-border-subtle) — НЕ red-500, НЕ #FF0000. Цветовая шкала: 9-11 шагов на каждый brand color
• Typography: typescale 5-7 размеров (xs/sm/base/lg/xl/2xl/3xl) + 3 weights (regular/medium/bold). Line-height и letter-spacing привязаны к size
• Spacing: 4/8 base scale (4, 8, 12, 16, 24, 32, 48, 64, 96). Никаких 13px или 27px
• Radii: max 4 значения (sm/md/lg/full). Больше — визуальный шум
• Shadows: 3-5 elevation levels (xs/sm/md/lg/xl). Каждый — конкретный use case
• Motion: 3-4 duration (instant/fast/normal/slow) + 3 easing (linear/ease-out/ease-in-out)

Output: tokens.json + tokens.css (CSS variables) + tokens.ts (typed export). Критерий готовности: дизайнер и фронт открывают и одинаково понимают.

Phase 3: Primitives (день 5-6)

Цель: building blocks, на которых построят всё остальное. Type-safe, composable.

Что сделать:

• Box — layout primitive с p/m/bg/border props
• Text — компонент типографики (variant="heading-lg" | "body" | "caption")
• Stack/Inline — vertical/horizontal layout с gap
• Icon — wrapper для SVG-иконок с size/color props
• Theme provider — токены доступны через useTheme()

Принцип: API минимальный, но достаточный. Не пихай все возможные props — добавишь когда понадобится.

Output: packages/ui/primitives/ с TypeScript + tests. Критерий готовности: можно собрать любой layout из 4-5 примитивов без custom CSS.

Phase 4: Components (неделя 2, день 7-10)

Цель: 20-30 ключевых компонентов, покрывающих 80% UI потребностей.

Список:

• Forms: Input, Textarea, Select, Checkbox, Radio, Switch, Slider, DatePicker, FileUpload
• Feedback: Toast, Alert, Banner, Modal, Drawer, Popover, Tooltip
• Display: Card, Avatar, Badge, Tag, Skeleton, Spinner, Progress
• Navigation: Tabs, Breadcrumb, Pagination, Menu, Dropdown
• Action: Button (variants: primary/secondary/ghost/destructive + sizes sm/md/lg), IconButton, ButtonGroup

Каждый компонент:

• Минимум props (3-7) — больше = сложнее понять API
• Variants через discriminated unions, не boolean flags
• Composable: <Modal><Modal.Header/><Modal.Body/></Modal>
• Использует primitives и tokens, никаких inline styles
• Story в Storybook со всеми variants

Используй Radix UI / Headless UI как поведенческий слой — не переизобретай accessibility.

Output: packages/ui/components/. Критерий готовности: можно построить 3 разных экрана продукта без выхода за пределы DS.

Phase 5: Docs (день 11-12)

Цель: knowledge transfer. Без этого DS = tribal knowledge, не масштабируется.

Для каждого компонента:

• Usage example (copy-paste готовый код)
• When to use / when NOT (alternatives)
• Accessibility notes (keyboard, ARIA, screen reader)
• Variants table со всеми комбинациями props
• Do/Don't visual pairs (показать антипаттерны)
• API reference (props с типами и defaults)

Output: docs site (Storybook native + MDX, или Docusaurus). Критерий готовности: новый разработчик открывает docs и за 10 минут собирает форму без вопросов.

Phase 6: Storybook (день 13)

Цель: песочница + visual regression + источник правды для дизайна.

Setup:

• Storybook 8 (vite builder, не webpack — быстрее)
• Controls для всех props
• MDX docs page для каждого компонента
• Visual regression: Chromatic или Percy (snapshot diff на каждый PR)
• Accessibility addon (axe-core под капотом)
• Design tokens addon (визуализация tokens.json)
• Viewport addon (тестирование responsive)

Output: working Storybook URL (deployed). Критерий готовности: дизайнер смотрит сториз вместо того чтобы спрашивать "а как кнопка disabled выглядит?".

Phase 7: Governance (день 14)

Цель: DS не умрёт через 6 месяцев. Решает bus factor и долгосрочную поддержку.

Документы:

• RFC процесс для новых компонентов (template + примеры accepted/rejected)
• Deprecation flow (3 этапа: announce → mark deprecated → remove, мин 2 месяца)
• Версионирование: semver строго (breaking → major, новая фича → minor, fix → patch)
• Contribution guide (как добавить компонент, кто ревьюит, когда merge)
• Code review checklist (a11y, tokens used, no inline styles, story added, tests passing)
• Design review checklist (для дизайнеров: tokens вместо hex, spacing с scale)
• Ownership model: DS team (центральная) vs federated (each team contributes) vs hybrid

Output: GOVERNANCE.md + CONTRIBUTING.md + RFC template. Критерий готовности: новый член команды читает доки и понимает как предложить изменение.

Контракт между фазами

Каждая фаза → следующая checkpoint:

• Phase 1 → 2: inventory утверждён, нет споров про "что у нас сейчас"
• Phase 2 → 3: tokens.json утверждён дизайн-лидом и tech lead
• Phase 3 → 4: primitives работают, написан hello-world экран
• Phase 4 → 5: 20+ компонентов с stories, на них собран 1 реальный экран продукта
• Phase 5 → 6: docs покрывают 100% компонентов
• Phase 6 → 7: Storybook deployed, visual regression baseline зафиксирован
• Phase 7 → done: governance подписан DS owner, первый внешний contributor сделал PR

Если предыдущая фаза не closed — не начинай следующую. Бэктрек дешевле чем переделка.

Anti-patterns

• ❌ Сразу Phase 4 (components) без Phase 2 (tokens) — tokens переписываешь после, ломая всё, что построил
• ❌ Components с 30+ props — "догадайся как использовать"; правильный путь — composition + variants
• ❌ Без Phase 5 (docs) — tribal knowledge, не масштабируется; через год никто не помнит зачем компонент сделан так
• ❌ Без visual regression — silent breaking changes; меняешь токен, ломаются 40 экранов, узнаёшь от QA через неделю
• ❌ DS как side project одного человека без Phase 7 (governance) — bus factor = 1; уйдёт автор, DS заброшен через месяц
• ❌ Сразу 50 компонентов — 80% не используются, поддержка пожирает время; начни с 20, добавляй по запросу
• ❌ Игнор существующих библиотек (Radix, Headless UI, React Aria) — переизобретаешь accessibility, тратишь месяцы
• ❌ Цвета как red/blue/green вместо semantic (danger/info/success) — невозможно сделать темизацию без полного переписывания
• ❌ Tokens только в Figma или только в коде — рассинхрон неизбежен; нужен single source (tokens.json) + sync процесс
• ❌ Версионирование "v1.0 — v1.0.1 — v1.0.2" без semver semantics — потребители DS не знают что ломается
• ❌ Запуск DS без 1-2 пилотных продуктовых команд — построил в вакууме, реальные кейсы не учёл, придётся переделывать
• ❌ Storybook как "галерея для дизайнера" вместо source of truth — фронт пишет компоненты ещё раз "по-своему"

Tech stack рекомендации

• Monorepo: pnpm workspaces или Turborepo (нужно делить packages между приложениями)
• TypeScript: strict mode, никаких any в публичном API компонентов
• Styling: Tailwind v4 + CSS variables (tokens) ИЛИ vanilla-extract / CSS Modules; в любом случае — токены через CSS variables, чтобы темы переключались без ребилда
• Behaviour layer: Radix UI primitives или React Aria — accessibility бесплатно
• Build: tsup или Vite library mode для packages/ui; tree-shakeable ESM + типы
• Tests: Vitest для unit + Playwright для interaction tests на ключевых компонентах
• Visual regression: Chromatic (если бюджет есть) или Percy / Playwright screenshots (если нет)
• Docs: Storybook 8 + addon-docs (MDX); деплой на Vercel/Netlify
• Versioning: Changesets — автоматический changelog + версионирование на основе PR labels
• Distribution: публикация в внутренний npm registry (Verdaccio) или GitHub Packages

Метрики успеха

Через 3 месяца после Phase 7:

• 80%+ новых экранов собираются только из DS компонентов (метрика — grep по inline styles в новом коде)
• Time to first screen для нового разработчика — менее 1 дня (раньше неделя)
• Visual regression ловит 90%+ unintended changes (меряется по false negatives в QA)
• 5+ компонентов добавлены через RFC процесс внешними командами (federated работает)
• Storybook посещается дизайнерами 3+ раза в неделю на человека (DS — рабочий инструмент, не музей)

Финальный output

В конце 14 дней у тебя должно быть:

1. Git репозиторий с packages/ui (primitives, components, tokens)
2. Deployed Storybook URL с visual regression baseline
3. inventory.md, tokens.json, GOVERNANCE.md, CONTRIBUTING.md, RFC template
4. 1 продуктовый экран переписан на DS как proof of concept
5. Onboarding doc для нового разработчика (как импортировать, как контрибьютить)
6. План rollout: какие 5 экранов переписываем в Q1, какие в Q2

Если чего-то нет — фаза не закрыта, не считай работу законченной.