84 lines
7.0 KiB
Markdown
84 lines
7.0 KiB
Markdown
# 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** она остаётся у продуктового владельца и не становится общей только
|
|
ради классификации каталога
|