# frontend-design-system Specification

## Purpose
Определяет единый визуальный фундамент WealthLedger и переиспользуемые общие
компоненты, чтобы приложение и каталог сохраняли согласованное представление.

## Requirements

### Requirement: Приложение и каталог используют единый визуальный фундамент

Приложение и каталог SHALL использовать один источник темы и токенов: цвета
с семантическими ролями, типографику, интервалы, радиусы, тени и применимые
адаптивные параметры. Общий фундамент MUST быть независим от бизнес-сущностей
и уровня приложения; подключение провайдеров принадлежит приложению и runtime
каталога. Объявленные общие токены SHALL иметь единый переносимый машиночитаемый
источник значений, единиц, семантических ссылок и описаний, доступный без
приложения или UI-библиотеки. Адаптер приложения SHALL потреблять этот источник
без ручного дублирования значений. Перенос владения опубликованными шкалами
из UI-библиотеки в токены MUST сохранять их эффективные значения; не включённые
в контракт библиотечные defaults MAY оставаться у библиотеки. Выделение фундамента MUST сохранять текущий
внешний вид, светлую схему и поведение приложения без массовой замены локальных
значений оформления. Источник SHALL поставляться вместе с приложением как
доверенная конфигурация; загрузка внешних или пользовательских токенов
и отдельная runtime-валидация произвольных документов не поддерживаются.

#### Scenario: Компонент отображается в приложении и каталоге

- **WHEN** один компонент с одинаковыми props отображается в обоих runtime
- **THEN** он получает одинаковые тему, токены и общие визуальные правила

#### Scenario: Участник выбирает токен

- **WHEN** участник изучает фундамент дизайн-системы
- **THEN** доступны используемые шкалы, их значения, семантические роли и правила
  применения без необходимости обращаться к данным приложения

#### Scenario: Владение темой перенесено

- **WHEN** приложение использует выделенный общий фундамент
- **THEN** исходные эффективные значения и внешний вид остаются прежними,
  включая встроенные шкалы, глобальные стили и локальное оформление

#### Scenario: Токены использует другая система

- **WHEN** потребитель читает исходный файл обычным парсером данных
- **THEN** объявленные цвета, роли, типографика, интервалы, радиусы, тени и
  адаптивные пороги доступны с определёнными единицами и ссылками без React,
  Mantine, CSS runtime или запуска приложения; интеграция конкретного инструмента
  не заявляется автоматически

#### Scenario: Изменён исходный токен

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

#### Scenario: Исходные токены некорректны

- **WHEN** разработчик вносит некорректное значение в локальный источник
- **THEN** отдельный runtime-валидатор не применяется; корректность изменения
  проверяется при review и проверке представления, автоматическое отклонение
  любого некорректного документа не гарантируется

### Requirement: Общие компоненты независимы от предметной области

Дизайн-система SHALL предоставлять минимальный набор реально используемых
общих компонентов с описанием назначения, вариантов, состояний и доступности.
Они MUST NOT знать о счетах, позициях, API или authentication. Существующие
компоненты SHALL переиспользоваться, если удовлетворяют этой границе; новые
обёртки MUST NOT вводиться только ради имени или покрытия каждого примитива.
Принятые конфигурации библиотечных компонентов MAY демонстрироваться напрямую.

#### Scenario: Требуется общее состояние интерфейса

- **WHEN** разработчик выбирает общее empty/error или loading представление
- **THEN** он получает используемый приложением компонент с доступной семантикой,
  необязательными действиями там, где они применимы, без бизнес-зависимостей

#### Scenario: Композиция имеет бизнес-смысл

- **WHEN** композиция представляет счёт, позицию или продуктовый запросный экран
- **THEN** она остаётся у продуктового владельца и не становится общей только
  ради классификации каталога