# Архитектура

VegaUI — воркспейс pnpm под управлением Turborepo. Главная архитектурная идея — не само дерево папок, а направление зависимостей между пакетами.

## Слои системы

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

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` (см. [Даты и календарные системы](https://vega-ui.dev/ru/docs/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](https://github.com/vega-ui/ui/blob/main/packages/ui/src/TextField/TextField.tsx)
- [packages/ui/src/TextField/components/TextFieldInput/TextFieldInput.tsx](https://github.com/vega-ui/ui/blob/main/packages/ui/src/TextField/components/TextFieldInput/TextFieldInput.tsx)
- [packages/ui/src/TextField/style.module.css](https://github.com/vega-ui/ui/blob/main/packages/ui/src/TextField/style.module.css)
- [packages/ui/src/TextField/__tests__/TextField.browser.test.tsx](https://github.com/vega-ui/ui/blob/main/packages/ui/src/TextField/__tests__/TextField.browser.test.tsx)

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

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

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

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

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

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

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

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

Общее определение [источника истины](https://vega-ui.dev/ru/docs/glossary/#источник-истины-source-of-truth) — в [глоссарии](https://vega-ui.dev/ru/docs/glossary/#источник-истины-source-of-truth).