Дизайн-система и компоненты

Зачем это изучать

Вы закрепите визуальные решения в коде так, чтобы Codex мог последовательно развивать сайт, не создавая новый стиль на каждой странице.

Проверено: 23 августа 2026 года.

Дизайн-система — это не отдельная витрина компонентов. Это общий язык решений: токены, доступные primitives, варианты, правила применения, контент и тесты. Зрелые системы GOV.UK и USWDS связывают компоненты с пользовательскими паттернами, доступностью и проверкой, а не только с внешним видом.

Сначала инвентаризация

Перед созданием нового Codex ищет:

• CSS custom properties, theme/config и utility presets;
• базовые компоненты, icon library и typography primitives;
• повторяющиеся значения цвета, spacing, radius, shadow и z-index;
• существующие stories, screenshots и component tests;
• тёмную тему, high contrast, RTL, локализацию и reduced motion;
• deprecated-компоненты и незавершённые миграции.

Результат — короткая карта: что является источником истины, что переиспользовать и какой пробел действительно требует нового API.

Слои системы

Слой	Примеры	Правило Codex
Primitives	raw palette, font family, base units	не использовать напрямую в feature-коде без причины
Semantic tokens	color-text-muted, space-section	называть по назначению, а не по оттенку или странице
Foundations	reset, type scale, grid, focus, motion	держать глобальное поведение предсказуемым
Components	Button, Field, Dialog, Table	один контракт, все обязательные состояния
Patterns	checkout, search, authentication	описывать порядок и связь нескольких компонентов
Templates	layout конкретного класса страниц	не превращать каждую страницу в новый primitive

Токены должны иметь владельца и ограниченный словарь. Если любое произвольное значение немедленно становится токеном, система лишь переименовывает хаос.

Контракт компонента

Для каждого публичного компонента определите:

1. назначение и ситуации, когда его не следует использовать;
2. semantic HTML и доступное имя;
3. варианты размера, плотности и визуального приоритета;
4. hover, focus-visible, active, disabled, loading, error и success;
5. keyboard model и управление focus;
6. поведение при длинном тексте, zoom, RTL и узком контейнере;
7. допустимую композицию и публичный API;
8. stories/examples и уровень тестового покрытия.

Сначала предпочитайте нативный элемент. Если нужен сложный widget, сверяйте роль, состояния и keyboard interaction с WAI-ARIA Authoring Practices. Наличие ARIA-атрибутов не компенсирует неверное поведение.

Состояния как матрица

Codex не должен проверять компонент только в default/happy path. Минимальная матрица:

Измерение	Варианты
Данные	пусто, минимум, типично, максимум, ошибка
Управление	default, hover, focus, active, disabled, loading
Среда	narrow, wide, zoom 200%, reduced motion, dark/high contrast
Контент	длинный текст, другая локаль, отсутствующее медиа
Пользователь	мышь, клавиатура, touch, screen reader

Храните поддерживаемые варианты как stories или эквивалентные fixture-страницы. Это одновременно документация, площадка review и набор входов для component, accessibility и visual tests.

CSS и layout

• Используйте normal flow, Grid, Flexbox и container/media queries по смыслу.
• Breakpoint вводится там, где ломается контент, а не ради названия устройства.
• Компонент не должен знать ширину всей страницы, если достаточно контейнера.
• Предпочитайте fluid sizing через min(), max() и clamp(), но сохраняйте читаемость и предсказуемые границы.
• Не исправляйте структуру растущим набором z-index, absolute positioning и viewport-specific magic numbers.
• Резервируйте размеры медиа, используйте responsive images и не загружайте изображение заметно больше фактической области показа.

Управление изменениями

Изменение токена или базового компонента имеет большой радиус. Codex должен:

1. найти всех потребителей;
2. перечислить изменившиеся варианты и страницы;
3. обновить stories и документацию;
4. запустить component, accessibility и visual regression checks;
5. показать diff человеку до обновления baseline;
6. сохранить migration note при изменении публичного API.

Нельзя автоматически принимать новые screenshots только ради зелёного CI: baseline — утверждённое поведение, а не побочный файл теста.