diff --git a/openspec/changes/complete-shared-design-system/.openspec.yaml b/openspec/changes/complete-shared-design-system/.openspec.yaml new file mode 100644 index 0000000..7d363ac --- /dev/null +++ b/openspec/changes/complete-shared-design-system/.openspec.yaml @@ -0,0 +1,2 @@ +schema: wealth-ledger-sdd +created: 2026-09-08 diff --git a/openspec/changes/complete-shared-design-system/design.md b/openspec/changes/complete-shared-design-system/design.md new file mode 100644 index 0000000..1d050da --- /dev/null +++ b/openspec/changes/complete-shared-design-system/design.md @@ -0,0 +1,127 @@ +## Context + +Baseline: app/theme задаёт blue 0–9, primaryColor blue, defaultRadius md и +системный sans-serif; прочие шкалы разрешаются Mantine 9.5.1. App/styles задаёт +фон gray.2 и текст dark.7. StateView и LoadingSkeleton уже используются в shared/ui. +Каталог содержит 6 групп / 21 историю; preview импортирует тему из app. +Локальные card gradients, размеры, shadows и бизнес-цвета остаются у владельцев. + +## Goals / Non-Goals + +**Goals:** shared-владение темы и базовых стилей, явные шкалы и семантические +роли без копий значений, полезный общий набор и два блока Storybook. + +**Non-Goals:** редизайн приложения, перенос всех CSS literals в tokens, +новые зависимости, смена Mantine, перенос AppShell/навигации, бизнес-реализаций +или auth в дизайн-систему, продуктовый пилот и правка исторических artifacts. + +## Decisions + +- `shared/theme` — FSD segment с public API `index.ts`: тема Mantine, + CSSVariablesResolver и семантические color roles. Базовые CSS импортируются + public entrypoint темы. App владеет MantineProvider; preview подключает свой + изолированный MantineProvider с тем же public API. Дублирующий app/theme удаляется. +- Blue palette и font family сохраняют исходные bytes. Шкалы spacing, radius, + fontSizes, lineHeights, headings, shadows, breakpoints и mono font явно + принимаются из DEFAULT_THEME, без повторения числовых значений. Primary shade + и focus behavior также сохраняют defaults. Это используемый Mantine contract, + а не отдельный token engine. +- Семантические CSS aliases `--wl-color-*` ссылаются на Mantine CSS variables: + canvas gray.2, surface white (body светлой схемы), subtle gray.0, text dark.7, muted gray.6 (dimmed), + border gray.3, primary filled, info blue.6, positive green.6, negative red.6, + warning yellow.6. Цвет не заменяет текстовый статус; warning не предназначен + для мелкого текста на белом. Глобальный фон/текст используют соответствующие + aliases; локальные роли можно принимать постепенно без массовой миграции. +- Общий набор — существующие StateView (empty/error, optional action) и + LoadingSkeleton (busy/status wrapper с caller-owned decorative shapes). + Они уже решают реальные задачи, не требуют новых wrappers. AppShell содержит + маршруты и не входит в заявленный общий каталог. Mantine Button показывается + напрямую в принятых конфигурациях primary/default/subtle/loading/disabled; + никаких WLButton и изменения глобальных defaults ради витрины. +- CSF stories остаются colocated. StateView и новые foundations/loading/buttons + относятся к Design System; пять существующих бизнес-групп — Product. + Theme foundations читают effective theme через useMantineTheme, labels роли + ссылаются на тот же alias map; значения не копируются в stories. + +## UI/UX Applicability and Package + +**Applicability and scope:** new/changed для каталога; приложение сохраняет +существующий UI, новый макет приложения не нужен. + +**Package revision:** 1; пакет полностью inline Markdown, exports не нужны. + +**Screens, states and interactions:** + +| Блок / экран | Содержание и поведение | +| --- | --- | +| Design System / Foundations / Colors | Подписанные роли, образец цвета, фактическое значение; blue 0–9 и используемые neutral/status palettes. Цвет всегда сопровождается текстом. | +| Design System / Foundations / Typography | Семейства sans/mono, heading и body шкалы с размерами, весом, line-height и примерами. | +| Design System / Foundations / Layout | Spacing, radius, shadows, breakpoints из effective theme, default radius и правила применения. | +| Design System / Components / StateView | Сохраняются все 4 истории: empty/error с действием и без, error role alert, keyboard button и локальный callback. | +| Design System / Components / LoadingSkeleton | Нейтральные structural shapes; status/busy label, no focusable shapes. Форма страницы остаётся у page. | +| Design System / Components / Button | Реальный Mantine Button; primary/default/subtle, loading/disabled, доступное имя, keyboard focus и наблюдаемый local action. | +| Product | Все 17 исходных бизнес-историй: список счетов, позиции, события, обновление сохранённых сумм и loading страницы. Синтетические fixtures, локальные Actions и MemoryRouter, без API/auth runtime. | + +Docs каждой группы задаёт назначение, правила применения и границы. Manager +явно сортирует Design System перед Product. Controls меняют поддерживаемые args, +reset/remount сохраняют штатную семантику Storybook. + +**Responsive behavior:** foundations используют переносящиеся grids/stack, +длинные значения и labels не расширяют viewport 375px. Button variants переносятся; +StateView сохраняет доступную кнопку. Product сохраняет существующее responsive +поведение; проверяется узкий и desktop iframe, без нового breakpoint contract. + +**Reused source and differences:** исходные реализации текущей baseline, +без ссылки на изменяемую витрину как authority и без reuse исторического пакета. + +## Delivery Map + +| Area | Status | Architectural outcome or N/A reason | +| --- | --- | --- | +| frontend | affected | Shared theme и базовые styles, общий набор, два блока каталога | +| backend | N/A | API, auth и хранение данных не меняются | +| specs | affected | Новый corrective contract и evidence в canonical store | +| docs | affected | As-built foundation ownership, coverage и использование каталога | + +### Contract Gate Decision + +| Gate | Status | Reason | +| --- | --- | --- | +| runtime-openapi | N/A | Ни одна сторона API contract не меняется | + +## Solution Assessment + +Mantine 9.5.1 уже предоставляет зрелые тему, типы, CSS variables, scales, +компоненты и focus/loading/disabled semantics. Его native theme сохраняет +совместимость и не увеличивает operating cost. Storybook 10.6.0 уже установлен, +CSF/autodocs достаточно для двух блоков. Отдельный token framework либо новая +UI-библиотека дублировали бы ownership, увеличили зависимости и стоимость +миграции без нужного поведения. Выбран текущий stack; custom code ограничен +семантическим map и демонстрацией effective scales, без runtime интеграций. + +## Risks / Trade-offs + +- DEFAULT_THEME — источник встроенных шкал: обновление Mantine требует проверки + foundations и приложения, а не скрытого сохранения старой копии defaults. +- Перенос CSS может повлиять на cascade; сохраняются content/order и сравниваются + computed styles и снимки до/после. Не заявляется exhaustiveness визуальной проверки. +- Новые story IDs меняют прямые ссылки; документация использует новые пути. +- Изоляция подтверждается существующим transitive runtime graph guard; + browser проверяет доступность и взаимодействия, не API recovery. + +## Migration Plan + +Зафиксировать baseline, перенести ownership темы и styles, подключить оба +provider, оформить общий набор и foundations, классифицировать Product, +обновить документацию. После проверок — независимый read-only review и canonical +completion mechanics только при актуальном PASS. Исторические archives и чужие +changes/state исключены из записи. Прямое разрешение владельца в запросе +заменяет промежуточные session/approval stops для этого bounded corrective scope; +независимость review сохраняется. + +### Rollback Contract + +| Field | Decision | +| --- | --- | +| Status | N/A | +| Reason | Обратимый перенос frontend-владения и каталог, без данных, auth или public API изменений; возврат delivery diff восстанавливает исходную структуру | diff --git a/openspec/changes/complete-shared-design-system/proposal.md b/openspec/changes/complete-shared-design-system/proposal.md new file mode 100644 index 0000000..69fb487 --- /dev/null +++ b/openspec/changes/complete-shared-design-system/proposal.md @@ -0,0 +1,38 @@ +## Why + +Поставленный каталог реальных компонентов не даёт явно оформленного общего +визуального фундамента и не разделяет общие решения и продуктовые композиции. +Это corrective change поверх текущей baseline после integrate-ui-ux-design-workflow; +исторические artifacts и evidence двух архивированных changes остаются неизменными. + +## What Changes + +- Единая визуальная основа с определёнными шкалами и семантическими ролями, + общая для приложения и каталога, с сохранением текущего вида и поведения. +- Минимальный полезный набор используемых общих компонентов без бизнес-знаний. +- Два содержательных блока Design System и Product: foundations, общие + компоненты, реальные продуктовые композиции, состояния и правила применения. +- Проверяемые границы покрытия, изоляции и as-built описание результата. + +Non-goals: массовый редизайн, замена всех локальных значений, полный каталог +библиотеки или приложения, новый продуктовый пилот, изменение backend/API, +переписывание архивов и чужого state. По прямому разрешению владельца planning +и implementation выполняются в одном контексте без sdd-session/session records. + +## Capabilities + +### New Capabilities + +- `frontend-design-system`: `specs/frontend-design-system/spec.md` — общий + визуальный фундамент и независимые от домена общие компоненты. + +### Modified Capabilities + +- `frontend-ui-catalog`: `specs/frontend-ui-catalog/spec.md` — обязательные + содержательные блоки Design System и Product и критерии готовности. + +## Impact + +Frontend и участники разработки получают переиспользуемую визуальную основу +и каталог с явными границами. Specs фиксирует corrective contract; docs — +фактически поставленный результат. Backend и данные пользователей не затронуты. diff --git a/openspec/changes/complete-shared-design-system/specs/frontend-design-system/spec.md b/openspec/changes/complete-shared-design-system/specs/frontend-design-system/spec.md new file mode 100644 index 0000000..94ae429 --- /dev/null +++ b/openspec/changes/complete-shared-design-system/specs/frontend-design-system/spec.md @@ -0,0 +1,55 @@ +## Purpose + +Определяет единый визуальный фундамент WealthLedger и переиспользуемые общие +компоненты, чтобы приложение и каталог сохраняли согласованное представление. + +## ADDED Requirements + +### Requirement: Приложение и каталог используют единый визуальный фундамент + +Приложение и каталог SHALL использовать один источник темы и токенов: цвета +с семантическими ролями, типографику, интервалы, радиусы, тени и применимые +адаптивные параметры. Общий фундамент MUST быть независим от бизнес-сущностей +и уровня приложения; подключение провайдеров принадлежит приложению и runtime +каталога. Параллельные копии значений MUST NOT создаваться там, где существующий +механизм темы уже владеет шкалой. Выделение фундамента MUST сохранять текущий +внешний вид, светлую схему и поведение приложения без массовой замены локальных +значений оформления. + +#### Scenario: Компонент отображается в приложении и каталоге + +- **WHEN** один компонент с одинаковыми props отображается в обоих runtime +- **THEN** он получает одинаковые тему, токены и общие визуальные правила + +#### Scenario: Участник выбирает токен + +- **WHEN** участник изучает фундамент дизайн-системы +- **THEN** доступны используемые шкалы, их значения, семантические роли и правила + применения без необходимости обращаться к данным приложения + +#### Scenario: Владение темой перенесено + +- **WHEN** приложение использует выделенный общий фундамент +- **THEN** исходные эффективные значения и внешний вид остаются прежними, + включая встроенные шкалы, глобальные стили и локальное оформление + +### Requirement: Общие компоненты независимы от предметной области + +Дизайн-система SHALL предоставлять минимальный набор реально используемых +общих компонентов с описанием назначения, вариантов, состояний и доступности. +Они MUST NOT знать о счетах, позициях, API или authentication. Существующие +компоненты SHALL переиспользоваться, если удовлетворяют этой границе; новые +обёртки MUST NOT вводиться только ради имени или покрытия каждого примитива. +Принятые конфигурации библиотечных компонентов MAY демонстрироваться напрямую. + +#### Scenario: Требуется общее состояние интерфейса + +- **WHEN** разработчик выбирает общее empty/error или loading представление +- **THEN** он получает используемый приложением компонент с доступной семантикой, + необязательными действиями там, где они применимы, без бизнес-зависимостей + +#### Scenario: Композиция имеет бизнес-смысл + +- **WHEN** композиция представляет счёт, позицию или продуктовый запросный экран +- **THEN** она остаётся у продуктового владельца и не становится общей только + ради классификации каталога diff --git a/openspec/changes/complete-shared-design-system/specs/frontend-ui-catalog/spec.md b/openspec/changes/complete-shared-design-system/specs/frontend-ui-catalog/spec.md new file mode 100644 index 0000000..9ba09a9 --- /dev/null +++ b/openspec/changes/complete-shared-design-system/specs/frontend-ui-catalog/spec.md @@ -0,0 +1,31 @@ +## ADDED Requirements + +### Requirement: Каталог разделяет Design System и Product + +Каталог SHALL иметь два явно различимых содержательных блока: Design System +и Product. Design System SHALL показывать foundations из действующей общей темы, +семантические роли, используемые шкалы и общие компоненты, их варианты, состояния, +доступность и правила применения. Product SHALL содержать реальные бизнес-компоненты +и композиции приложения с полезными существующими историями, классифицированными +по ответственности без перемещения бизнес-реализаций в общий слой. Оба блока +MUST сохранять общую тему и изоляцию от application API, auth и данных пользователя. + +#### Scenario: Участник открывает Design System + +- **WHEN** выбран блок Design System +- **THEN** доступны наглядные foundations с актуальными значениями токенов, + общие empty/error и loading компоненты, а также принятые конфигурации примитивов + с правилами использования и применимыми интерактивными состояниями + +#### Scenario: Участник открывает Product + +- **WHEN** выбран блок Product +- **THEN** доступны существующие примеры списка счетов, карточек позиций, событий, + обновления сохранённых сумм и skeleton страницы с их вариантами и ограничениями + +#### Scenario: Оценивается готовность каталога + +- **WHEN** каталог представлен как поставленный результат +- **THEN** существуют общий фундамент и оба содержательных блока, проверены + отображение и применимые взаимодействия, явно описаны границы покрытия; + сборка и наличие stories сами по себе не доказывают полноту или продуктовый пилот diff --git a/openspec/changes/complete-shared-design-system/tasks.md b/openspec/changes/complete-shared-design-system/tasks.md new file mode 100644 index 0000000..e31e933 --- /dev/null +++ b/openspec/changes/complete-shared-design-system/tasks.md @@ -0,0 +1,17 @@ +## 1. Общий фундамент и каталог + +- [x] 1.1 [frontend] Перенести тему и базовые styles в shared/theme, явно определить шкалы и семантические роли через native Mantine, подключить оба provider к public API. + - **Covers:** `frontend-design-system` — `Приложение и каталог используют единый визуальный фундамент` + - **Verification:** Сравнить effective theme, computed styles и browser снимки до/после; проверить public imports и отсутствие дублирующих values. +- [x] 1.2 [frontend] Оформить используемые StateView и LoadingSkeleton в Design System, foundations и принятые конфигурации Button; классифицировать все существующие бизнес-истории как Product. + - **Covers:** `frontend-design-system` — `Общие компоненты независимы от предметной области`; `frontend-ui-catalog` — `Каталог разделяет Design System и Product` + - **Verification:** npm run verify после npm ci под .nvmrc; browser обеих групп, foundations, empty/error/loading/disabled, keyboard/local callbacks, 375px и desktop; deps и deps:storybook. + +## 2. Спецификации и as-built + +- [x] 2.1 [specs] Согласованно оформить corrective Proposal, Delta Specs, Design revision 1 и Tasks в wealth-ledger-specs без session records и изменения архивов. + - **Covers:** `frontend-design-system` — `Приложение и каталог используют единый визуальный фундамент`; `frontend-design-system` — `Общие компоненты независимы от предметной области`; `frontend-ui-catalog` — `Каталог разделяет Design System и Product` + - **Verification:** openspec schema validate wealth-ledger-sdd --verbose; openspec validate complete-shared-design-system --type change --strict --store wealth-ledger-specs; openspec validate --specs --strict --store wealth-ledger-specs; semantic review относительно текущей baseline. +- [x] 2.2 [docs] Обновить as-built описание общего фундамента, FSD ownership, обоих блоков, coverage и ограничений без заявления о пройденном продуктовом пилоте. + - **Covers:** `frontend-design-system` — `Приложение и каталог используют единый визуальный фундамент`; `frontend-design-system` — `Общие компоненты независимы от предметной области`; `frontend-ui-catalog` — `Каталог разделяет Design System и Product` + - **Verification:** npm ci и npm run verify под docs .nvmrc; scoped local link review, соответствие путей и состава фактическому каталогу.