refactor: group canonical specs by domain and archive account-top-positions (#74)

2026-11-02 21:50:49 +03:00
parent 1fd7e6ad97
commit 3821d9ed58
61 changed files with 707 additions and 1448 deletions
@@ -0,0 +1,83 @@
+# 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** она остаётся у продуктового владельца и не становится общей только
+  ради классификации каталога