Архитектура

Слои системы

Репозиторий построен как многослойный стек дизайн-системы:

1. packages/tokens Исходные дизайн-токены: цвета, отступы, скругления, тени, типографика и слои.
2. packages/theme Семантические переменные темы поверх токенов. Здесь определены .light и .dark.
3. packages/ui React-компоненты и CSS-модули компонентов, которые используют семантику темы.
4. docs/ и Storybook Документация для людей, примеры и рекомендации по интеграции поверх опубликованного API.

Читайте этот стек слева направо:

tokens -> theme -> ui -> stories/tests/docs

Пакеты воркспейса

• packages/ui: основной React-пакет, публикуется как @vega-ui/react
• packages/theme: глобальный семантический слой темы, публикуется как @vega-ui/theme-core
• packages/tokens: исходные дизайн-токены, публикуются как @vega-ui/tokens-core
• packages/icons: ассеты и экспорты иконок
• packages/hooks: общие хуки — контролируемое состояние, выделение, отслеживание размеров
• packages/utils: низкоуровневые утилиты — слияние пропсов, рефы, даты и небольшие помощники для данных
• packages/react-context: общие помощники для контекста, которые используют составные компоненты
• packages/i18n: независимые от фреймворка адаптеры календарных систем, помощники для локалей и форматирования и календарно-зависимые помощники для ISO-дат, публикуется как @vega-ui/i18n (см. Даты и календарные системы)

Модель зависимостей

Важное направление зависимостей:

• ui зависит от hooks, i18n, icons, react-context и utils
• theme зависит от tokens
• компоненты в ui стилизуются через семантические переменные из theme

Это значит:

• изменения токенов затрагивают всю систему стилей
• изменения темы переназначают семантику, не переписывая каждый компонент
• локальные CSS-переменные компонента должны оставаться локальными и не подменять слой темы

Структура UI-пакета

Большинство компонентов в packages/ui/src/<Component>/ следуют повторяемой структуре:

• Component.tsx: публичная реализация компонента
• types.ts: экспортируемые типы и объединения, когда они нужны
• index.ts: публичные экспорты для точки входа пакета
• style.module.css: локальные стили компонента
• components/: экспортируемые дочерние части составных компонентов
• contexts/: общий локальный контекст для состояния составного компонента
• __tests__/*.browser.test.tsx: браузерные тесты взаимодействия
• *.stories.tsx: примеры использования в виде историй

Пример:

• packages/ui/src/TextField/TextField.tsx
• packages/ui/src/TextField/components/TextFieldInput/TextFieldInput.tsx
• packages/ui/src/TextField/style.module.css
• packages/ui/src/TextField/tests/TextField.browser.test.tsx

Истории, тесты и документация

Эти три слоя служат разным целям и должны оставаться согласованными:

• истории описывают реалистичное поддерживаемое использование и визуальные состояния
• тесты описывают поведение, взаимодействия и пограничные случаи
• документация описывает контракт для потребителя: когда использовать компонент, как его собрать и что обычно ломается

В этом репозитории истории в основном лежат рядом с компонентами в packages/ui/src/**, а конфигурация Storybook — в .storybook/.

Источники истины документации

При документировании компонента придерживайтесь приоритетов:

1. исходный код — для публичных экспортов и формы типов
2. истории — для поддерживаемых примеров и вариантов
3. тесты — для пограничных случаев и гарантий поведения
4. CSS-модули — для точек настройки стилей и локальных переменных компонента

Так документация не уходит в паттерны, которые исходный код на самом деле не поддерживает.

Общее определение источника истины — в глоссарии.