Design Systems и их документация

1) Что такое дизайн-система и зачем она нужна

Дизайн-система — это единый источник правды для интерфейса: набор токенов, компонентов, практик и документации, который обеспечивает предсказуемость UX, скорость разработки и масштабируемость.

• Согласованность визуального и поведенческого слоя во всех продуктах.
• Скорость: переиспользование компонентов, меньше издержек на ревью.
• Качество: общие паттерны A11y, локализация, тесты, стандарты контента.
• Управляемость: четкая ответственность, релизы, дорожная карта.

2) Архитектура дизайн-системы (слои)

1. Дизайн-токены (foundation): цвета, типографика, размеры, радиусы, тени, отступы, состояния, а также семантические токены (`color.surface.warning`, `space.xs`).
2. Компоненты UI: кнопки, поля ввода, модальные окна, дропдауны, таблицы, тосты, баннеры, алерты, пустые состояния, скелетоны.
3. Паттерны и композиции: формы KYC, платежные флоу, нулевые результаты, пошаговые мастера, карточки контента.
4. Контент-гайд (microcopy): тон, словарь терминов, шаблоны ошибок/успехов, push/баннеры.
5. Инфраструктура: гайд по A11y, тестированию, локализации, версиям, вкладчикам (contributing).

3) Дизайн-токены: принципы

Семантика > “сырой” стиль. Используйте `color.text.muted` вместо `#6B7280`.
Темизация и платформы. Токены источник → платформенные маппинги (Web, iOS, Android, email).
Светлая/темная тема и контраст по WCAG на уровне токенов.
Глобальные и контекстные шкалы: `space.2`, `radius.md`, `elevation.1`, `opacity.disabled`.
Версионирование токенов: изменения — через deprecation policy и миграционные заметки.

4) Компоненты: требования и состав страницы в документации

• Описание и назначение. Когда использовать/не использовать.
• Варианты/состояния. Размеры, виды (primary/secondary/ghost), disabled, loading, destructive.
• Доступность. Роль, клавиатурная навигация, `aria-`, контраст, фокус-кольца.
• Текст и примеры microcopy. Валидные лейблы/плейсхолдеры, ошибки, помощь.
• Примеры кода. Минимальные API, controlled/ uncontrolled.
• Интеграция с формами и i18n. Кейсы длинных строк, числа/валюты/даты.
• Анти-примеры. Ошибочные паттерны использования.
• Тест-матрица. Визуальные снапшоты, unit/interaction, скринридеры.

5) Паттерны композиции (Recipes)

Формы регистрации/KYC: пошаговый мастер, прогресс, валидация inline + summary, шаблоны ошибок.
Платежные флоу: выбор метода, комиссии, сроки, правило same-method, подтверждение и статус.
Пустые состояния: контекст + ценность + CTA, нулевые результаты поиска.
Сообщения успеха/ошибки: иерархия статусов, визуальные токены, тосты/баннеры/модалки.
Навигация и фильтры: глобальный поиск, быстрые пресеты, теги.
Страницы паттернов должны показывать композицию из компонентов, готовую для копирования, с microcopy и A11y-примечаниями.

6) Контент-гайд (voice & tone, microcopy)

Голос: профессиональный, ясный; тон зависит от контекста (онбординг, оплата, безопасность).
Единый словарь терминов: платежи, бонусы, лимиты, KYC — одно значение по продукту.
Шаблоны: CTA, ошибки, предупреждения, успехи, пустые состояния, уведомления.
Локализация-first: запас под длину строк, числа/валюты/даты по региону.
A11y-лексика: четкие лейблы, aria-описания, без двусмысленностей.

7) Accessibility (A11y) как стандарт системы

Базовые критерии: WCAG 2.1 AA для контраста, фокус виден всегда, навигация с клавиатуры.
Роли и атрибуты: компоненты описывают `role`, `aria-label`, `aria-describedby`, лайв-регионы для тостов/алертов.
Экранные ридеры: примеры фраз, порядок чтения, корректные статусы (`assertive/polite`).
Тест-процедуры: автоматические проверки + ручные сценарии.

8) Локализация и интернационализация

i18n-ключи рядом с кодом компонента + описание контекста.
Числа/валюты/даты через утилиты форматирования; не хардкодить текст в шаблонах.
Тесты длины: “длинный немецкий”, “узкий мобильный”, RTL-варианты.
Тон на языках: tone-map для критичных шагов (платежи/безопасность).

9) Документация: структура и навигация

1. Введение: миссия, принципы, зоны ответственности.

2. Токены: цвета, типографика, сетка, размеры, тени, состояния, темы.

3. Компоненты: каталог с фильтрами (по роли, по платформе, по A11y).

4. Паттерны: сценарии (формы, платежи, пустые состояния, успех/ошибки).

5. Контент-гайд: голос и тон, словарь, шаблоны microcopy.

6. Accessibility: стандарты, чек-листы, тест-кейсы.

7. Локализация: принципы, примеры, глоссарии по рынкам.

8. Интеграция и код: установка, версии, примеры, “how-to migrate”.

9. Contributing: процессы вклада, дизайн-ревью, код-ревью, definition of done.

10. Changelog и Roadmap: релизы, deprecations, план развития, known issues.

10) Управление и процессы (governance)

Роли: владелец системы (DesignOps/UX Platform), мейнтейнеры (дизайн/FE), консультанты (BE, A11y, локализация).
Комитет изменений: оценка запросов, приоритизация, согласование API/токенов.
Процессы: RFC на новые компоненты, внутренние issue-формы, SLA по багам.
Definition of Done: дизайн (Figma) ↔ код (UI-пакет) ↔ дока (пример + гайд) ↔ тесты.

11) Contributing: как добавлять/менять

Шаблон RFC: проблема → варианты → выбранное решение → A11y → i18n → миграция → риски.
Флоу PR: дизайн-ревью → код-ревью → UX-копирайтер → A11y-чек → релиз-ноты.
Правила обратной совместимости: minor/patch для неразрушающих, major — с деprecation и автоматической миграцией, где возможно.

12) Версионирование, релизы, миграции

SemVer для пакетов (`@company/ds-core`, `@company/ds-forms`, `@company/ds-charts`).
Release notes: изменения токенов, API компонентов, поведение по умолчанию, breaking changes, гайды миграции.
Deprecations: пометки в доке, линтер-правила, код-моды для массовой замены.
Design-tokens pipeline: единый источник (JSON/YAML) → платформенные билды (CSS vars, iOS, Android).

13) Тестирование качества

Юнит-тесты поведения и состояний.
Визуальные снапшоты (регрессия тем/состояний).
A11y-тесты: автоматические + ручные сценарии скринридера.
E2E-кейсы для критичных флоу (регистрация, платежи, KYC).
Perf-бюджеты: лимиты на бандл/рендер и запреты на тяжелые зависимости.

14) Метрики зрелости дизайн-системы

Adoption: % экранов/репозиториев, использующих DS.
Velocity: время от макета до поставки.
Quality: дефекты UI/A11y на 1 релиз.
Consistency: число “одноразовых” компонентов/стилей вне DS.
Docs: покрытие компонентов докой, NPS внутренней аудитории (дизайнеры/разработчики/аналитики).

15) Анти-паттерны

Токены как палитра без семантики (“просто цвет”).
Компоненты без документации и без примеров крайних случаев.
Игнорирование A11y (нет фокуса, низкий контраст, нет `aria`).
Ломающее версионирование без deprecation и миграционного гайда.
Скрытая логика в компонентах (бизнес-правила вместо UI-поведения).
Дублирование компонентов под узкие кейсы вместо расширения API.

16) Чек-листы

• Семантические названия и назначение.
• Контраст AA в обеих темах.
• Документированы скейлы и принципы использования.

• Варианты/состояния покрыты.
• A11y-описание, `aria-`, фокус.
• Примеры microcopy (лейблы, ошибки, подсказки).
• Примеры кода и edge-кейсы (длинные строки, загрузка, пусто).
• Unit/visual/A11y-тесты зеленые.

• Release notes с примерами до/после.
• Migration guide и deprecations.
• Обновлены сториз/демо, ссылки в доке.

17) Примеры «до/после»

• Разные первичные кнопки: цвета/радиусы/отступы не совпадают; разные тексты CTA.

• Единый `Button` с токенами: `size=md`, `variant=primary`, `radius=lg`, `spacing=md`, текст в стиле «действие + объект».

• Техничные сообщения, без подсказок.

• Компонент `Неверный формат даты. Используйте ДД.ММ.ГГГГ.` + авто-фокус.

18) Шаблон страницы компонента (скелет)

Название: Button

Описание: запускает действие; 1 основной на экран.
Варианты: primary, secondary, ghost, destructive; размеры sm/md/lg.
Состояния: hover, focus, active, loading, disabled.
A11y: доступен с клавиатуры; `aria-pressed` для переключаемых.
Microcopy: «Сохранить изменения», «Продолжить верификацию». Избегать «ОК».
Код (пример API): `Button { variant, size, icon, loading }`.
Анти-примеры: двойной primary на одном уровне иерархии.
Тесты: визуальные снапшоты, контраст, focus-ring.

19) Плейбук внедрения дизайн-системы (rollout)

1. Аудит интерфейсов: инвентаризация цветов/типографики/компонентов/паттернов.
2. MVP токенов и основных компонентов: Button, Input, Select, Modal, Alert, EmptyState, Toast.
3. Документация и сторибук: живые примеры, код-сниппеты, гайды.
4. Пилотный продукт: замена виджетов, сбор обратной связи.
5. Гайд миграции: код-моды, правила deprecation.
6. Расширение набора: таблицы, пагинация, форумы форм, шаги мастера.
7. Масштабирование: продуктовые паттерны (платежи, KYC), интеграция с аналитикой и A/B.
8. Поддержка: канал вопросов, SLA, внутренние воркшопы.

20) Быстрые шаблоны документации

• Имя: `color.border.warning`
• Назначение: рамки предупреждений и баннеров Notice/Warning
• Контраст: AA на фоне `color.surface.default`
• Нельзя: использовать для текста мелкого кегля
• Связанные: `color.surface.warning`, `icon.warning`

Шаблон паттерна: Пустое состояние (noResults)

Цель: корректировка запроса без чувства “ошибки”

Состав: заголовок (опц.), текст (1–2 предложения), CTA, вторичный CTA, иконка/иллюстрация

Microcopy: «По “{query}” ничего не нашлось. Сбросьте фильтры или уточните запрос.»

A11y: `role="status"`, `aria-live="polite"`

Итоговая шпаргалка

Семантические токены + дисциплина A11y = база.
Страницы компонентов полные: назначение, варианты, A11y, microcopy, код, тесты.
Паттерны = композиции из компонентов с готовыми текстами и правилами.
Docs — продукт: версия, релизы, миграции, процесс вклада.
Меряйте зрелость: adoption, скорость, дефекты, консистентность, NPS внутренних команд.