specs/openspec/changes/integrate-ui-ux-design-workflow/design.md

## Context

Frontend использует React 19, Vite 8, Mantine 9, общую app-owned theme, светлую
схему и русскую i18n. Продуктовые presentation components уже отделены от VM и
API. Каталог использует Storybook и покрывает реальные компоненты и композиции
приложения; прежняя Vite-витрина удаляется. Продуктовые экраны не меняются.

Поставленная baseline — schema v4 и canonical authority после завершённого
`optimize-session-oriented-sdd-v2`; его immutable bundle расположен в
`wealth-ledger-specs`, `changes/archive/2026-09-07-optimize-session-oriented-sdd-v2/`
относительно canonical OpenSpec root.
Его canonical archive содержит Completion Evidence. Процессное расширение
сохраняет поставленные bounded outcomes, approval/input binding, независимую
Validation и canonical completion ownership. Два пересекающихся MODIFIED
requirements дополнены визуальными обязанностями поверх этой baseline со всеми
её существующими scenarios. UI/UX package revision 2 ниже сохраняется.

## Goals / Non-Goals

**Goals:**

- Использовать специализированную инфраструктуру витрины с готовыми stories,
  controls, docs, navigation и изолированным preview.
- Показывать реальные решения WealthLedger, применимые состояния и правила
  использования на общей визуальной основе приложения.
- Сохранить изоляцию демонстраций от application API, auth и пользовательских
  данных, действующие FSD boundaries и canonical verification.
- Включить переносимый визуальный пакет в существующий Design после завершения
  процессной зависимости, без нового lifecycle.

**Non-Goals:**

- Собственная navigation/controls система, каталог стандартных Mantine demos,
  wrappers над примитивами ради нового имени, массовый UI refactor или редизайн.
- Полная каталогизация, отдельный publishing service, CI, browser mock mode,
  автоматическая visual regression либо продуктовая фича в роли пилота.

## Decisions

### 1. Каталог использует Storybook на существующем Vite stack

Выбран Storybook 10.6.0 с React/Vite framework и Docs addon той же версии.
Published peer ranges React/Vite framework включают React 19 и Vite 8.
Dependencies фиксируются точными versions в общем frontend lockfile. Другие
addons не добавляются без конкретной потребности. Storybook владеет navigation,
Controls, Docs, Actions и remount preview; собственный catalog shell удаляется.

Локальный Storybook и static build существуют отдельно от app entrypoint и
продуктовых маршрутов. Сохраняются понятные scripts dev:catalog и build:catalog;
static output — storybook-static. Продуктовая сборка не включает stories.
Telemetry Storybook выключена. Manager может хранить собственные настройки
витрины; это не разрешает stories читать application storage, cookies или secrets.

Общий preview decorator использует экспортируемую app theme, Mantine CSS,
application styles, русскую i18n и светлую схему без чтения сохранённой темы.
Stories находятся рядом с принадлежащими slice presentation modules и используют
относительные imports внутри slice; cross-slice imports сохраняют public API.
Storybook configuration — tooling composition, а не новый application слой.

Примеры получают синтетические typed props. MemoryRouter используется только
для реальных components со ссылками; он не меняет URL приложения и не подключает
product routes. AuthProvider, QueryClient, API clients, page containers и runtime
VM hooks не входят в preview graph. Type-only ссылки на VM/API-derived props
допустимы: они стираются и не запускают запросы. Проверка FSD сохраняет эти связи,
а отдельный runtime pass того же dependency-cruiser проверяет именно выполняемый
graph stories/preview без ослабления основной boundary проверки.

Внешние logos не загружаются: synthetic props используют null и реальный
fallback компонента. Retry/actions используют локальный Storybook callback.
Пример не выполняет денежные расчёты и не доказывает API recovery. Существующие
pure presentation helpers допустимы для подготовки synthetic props.

### 2. Начальный набор представляет шесть групп решений WealthLedger

| Группа / реальные components | Состояния и конфигурации | Применение и ограничения |
| --- | --- | --- |
| BrokerageAccountList | summary available, unavailable, empty; длинное имя и несколько валют | Выбор счёта, сводка и их реальные ограничения; synthetic account IDs и MemoryRouter, без auth/API. |
| PositionCard | stocks gain, bonds loss, other, missing valuation/identifiers | Карточка позиции с готовыми display props, null logo и реальным fallback; вычисления VM и котировки не воспроизводятся. |
| RecentEvents | loaded, loading, error, empty, missing amount | Реальная секция ближайших событий; fixed synthetic items и локальная ссылка, без запроса календаря. |
| PortfolioRefreshState вместе с PortfolioTotals | idle, refreshing, refresh error; локальный retry | Отображение сохранённых сумм при refetch/ошибке, без скрытия данных. Это presentation Client Cached Snapshot, не исполнение query lifecycle. |
| StateView | empty/error, с действием и без него | Общий компонент пустого состояния/ошибки с alert semantics и локальным callback. |
| AccountPageLoading через LoadingSkeleton | существующая структура заголовка, сводки и строк | Реальный page-owned structural loading; busy-region и декоративные shapes без фокуса. |

Названия, назначение и ограничения находятся в Storybook Docs для каждой группы;
каждая история представляет определённое состояние. Controls изменяют только
допустимые props; synthetic объекты и callbacks не становятся URL/API inputs.
Истории с ссылками явно описывают, что полный переход на продуктовую страницу не
демонстрируется. Storybook Actions показывает локальный callback.

Отдельный раздел стандартных Button/TextInput/Select/Checkbox/Alert/Paper не
создаётся: в текущем scope нет отличающегося contract, который оправдывает копию
Mantine docs. Эти primitives видны внутри настоящих compositions. Если появится
реальная принятая конфигурация или app-owned abstraction, она рассматривается
вместе с соответствующим изменением, без предварительных wrappers.

### 3. UI/UX package revision 2 — существующий Storybook shell и app preview

Применимость: **reuse** стандартного Storybook 10.6.0 manager/Docs/Controls и
**new/changed** composition начальных stories на существующей теме WealthLedger.
Процессная часть имеет UI/UX N/A, поскольку не вводит пользовательский экран.
Пакет revision 2 полностью встроен в Design: таблица групп выше и правила ниже;
отдельных attachments или изменяемых внешних макетов нет.

- Широкая витрина использует штатное дерево историй Storybook, Canvas/Docs и
  панель Controls/Actions. Выбор истории открывает её определённые synthetic args.
- Узкая витрина использует штатную адаптивную navigation Storybook. Для проверки
  UI самого приложения доступен изолированный iframe preview; его область
  проверяется на 320, 768 и 1280 CSS px без горизонтальной прокрутки.
- Цвета, typography, поверхности и responsive поведение внутри Canvas принадлежат
  существующим компонентам и app theme. Manager не стилизуется под продукт.
- Controls отражают supported props; reset args и remount используют штатные
  действия Storybook. Изменение размера preview не сбрасывает args. Собственный
  сброс/счётчик и кастомный breakpoint navigation из revision 1 удаляются.
- Ошибка/loading относятся к выбранной истории. Семантика alert/busy, доступные
  labels, keyboard/focus и сохранение данных при refetch остаются реальными.
- Docs объясняет назначение, состояние, synthetic-data boundary и ограничения.
  Наличие истории не подтверждает полный journey или сквозной пилот процесса.

### 4. Визуальные материалы принадлежат одному canonical Design

Design получает компактный раздел UI/UX Applicability: `new/changed`, `reuse`
либо `N/A` с причиной. Для применимого scope он определяет экраны, состояния,
interactions и responsive rules; при reuse называет конкретную версию, часть
решения и отличия. Новый формальный макет для неизменяемой области не нужен.

Основное переносимое представление — Markdown внутри Design. Если изображение
необходимо для однозначного результата, используются локальные PNG/SVG exports
в `visuals/` того же canonical change. Design содержит состав пакета: revision,
идентификатор каждого материала, относительный путь, назначение/экран/состояние
и SHA-256 для внешних по отношению к Markdown файлов. Содержимое самого Design
входит в его обычную identity; self-referential hash не вводится. SVG exports
самодостаточны, без scripts, внешних fonts/assets и исполняемых обработчиков.

Внешний редактор или preview может быть вспомогательным источником, но approved
результат должен открываться из canonical пакета без аккаунта в этом сервисе.
Ссылка на изменяемый каталог также не заменяет сохранённое решение: Design
фиксирует выбранную конфигурацию и идентичность переиспользуемого источника.
Reuse из другого archive ссылается на его точный immutable пакет, а не `latest`.

Revision описывает комплект, digest обнаруживает замену файла; ни то ни другое
не доказывает owner approval. Approval относится ко всему представленному
Design с его составом. Семантическая замена изображения, responsive rule или
interaction меняет Design и возвращает его к обычному approval boundary.
При несовместимости со Specs возврат начинается со Specs, при изменении intent —
с Proposal. Форматное исправление не маскирует визуальное изменение.

При archive относительная структура Design/visuals переносится вместе с change.
Проверяется доступность каждого материала и совпадение его identity после
переноса; утрата файла блокирует завершение, а не компенсируется внешним URL.
Historical archives не дополняются новыми пакетами задним числом.

### 5. Процесс расширяется в существующих владельцах

Project-local OpenSpec schema владеет формой Design и phase instructions;
governance/lifecycle — единым правилом approval, переносимости и feedback.
Runtime-neutral authority описывает поведение без обязательного конкретного
skill, browser или design service. Локальные session skills/entrypoints только
направляют к ней и читают выбранный пакет из Design; отдельный visual handoff,
новая роль или отдельный UI/UX gate не возникают.

Implementation и Validation получают Design штатным native context routing,
а из него — применимые материалы. Недоступность, отсутствующий материал или
несовпадение digest блокирует зависимую работу до восстановления точного пакета
либо owner decision на нужной boundary. Восстановление известных байтов не
разрешает дорисовать отсутствующее решение по памяти.

Semantic verification сравнивает область изменения с согласованными экранами,
состояниями, interactions и responsive behavior. Однозначный visual mismatch
даёт исправление реализации; противоречие или неоднозначность самого пакета —
возврат в Specification. Validation остаётся read-only. Native structural
success, наличие screenshots и наличие каталога не дают semantic PASS.

Проверка комплектности использует обычные файловые операции, относительные
ссылки и стандартный SHA-256; отдельный parser/registry или approval engine не
создаётся. Native structural validation не заявляется автоматической проверкой
качества макета или произвольных attachments. Содержательность applicability,
полнота пакета и визуальное соответствие остаются явными обязанностями review.
После завершения зависимости существующий approval/input binding расширяется
на перечисленные attachments, не создавая параллельной модели state.

## Delivery Map

| Area | Status | Architectural outcome or N/A reason |
| --- | --- | --- |
| frontend | `affected` | Storybook с шестью группами реальных компонентов/композиций, общей theme, безопасными stories, Docs и отдельной static build в canonical gate. |
| backend | `N/A` | Каталог не использует API/auth clients и реальные финансовые данные; endpoints, DTO, хранение, денежные вычисления и backend gate не меняются. |
| specs | `affected` | Новая capability каталога, расширение lifecycle/session requirements и существующей schema для полного Design package после dependency reconciliation; planning остаётся только в canonical store. |
| docs | `affected` | As-built описание доступного каталога, его границ, визуальной основы и фактически внедрённого UI/UX workflow; обновлённые routing links к canonical archive/Completion Evidence без отдельного evidence store в docs. |

### Contract Gate Decision

| Gate | Status | Reason |
| --- | --- | --- |
| runtime-openapi | `N/A` | Ни одна сторона API contract не изменяется; каталог изолирован от application API. |

Workspace entrypoints — локальная non-authority orchestration. Они следуют
versioned specs/docs contract; их адаптация не подменяет repository-owned
реализацию, Delivery Map или canonical gates.

## Solution Assessment

| Вариант | Fit и зрелость | Стоимость и ограничения | Решение |
| --- | --- | --- | --- |
| Storybook 10.6.0 + React/Vite + Docs | Специализированная поддерживаемая витрина; готовые navigation, args/controls, docs, actions и static build. Peer ranges включают React 19 и Vite 8. | Новые devDependencies и их обновления; конфигурация и stories остаются project-owned. Совместимость build и gate проверяется при интеграции. | Выбран: снижает объём собственного catalog tooling. |
| Собственная Vite composition | Использует уже установленный stack | Требует сопровождать navigation, controls, reset, descriptions и responsive shell; малое число stories не устраняет эту стоимость. | Удаляется, конкретного gap Storybook не установлено. |
| Ladle | Готовая React-витрина | Нет потребности во втором runner при выбранном Storybook; отдельная интеграция и lifecycle. | Не выбран. |
| Mantine docs / screenshots | Полезный reference библиотеки | Не показывают реальные WealthLedger compositions и их состояния. | Вспомогательный reference, не каталог проекта. |

Для переносимого visual package сохраняются OpenSpec, Git, Markdown и при
необходимости самодостаточные exports; Storybook показывает текущее состояние
реализации и не заменяет сохраняемую согласованную версию Design.

## Risks / Trade-offs

- Dependency может изменить main specs и approval model. Текущая проверка
  authority не даёт права применить сегодняшние MODIFIED blocks после неё без
  повторного сопоставления и нужного reapproval.
- Общая theme предотвращает drift tokens; изменение descriptions или
  демонстрируемой конфигурации всё равно требует review вместе с компонентом.
- Локальные synthetic examples доказывают UI interaction, но не API, денежную
  семантику или полный investment journey. Ограничение видно рядом с примером.
- Переносимые exports увеличивают размер specs repository и нуждаются в ручном
  review. Используются только материалы, необходимые для конкретного Design;
  временные captures не становятся частью approved пакета автоматически.
- Storybook в этом scope не предоставляет автоматическую visual regression.
  Проверка клавиатуры и responsive behavior выполняется browser review;
  отдельный browser test framework или числовой visual threshold не вводится скрыто.

## Migration Plan

1. Продолжить planning только по явным approvals текущего change. Этот Design
   фиксирует решения, но не включает новые process rules сейчас. Каталог может
   реализовываться после утверждения всех его planning artifacts; внедрение
   процессной части дополнительно зависит от завершения predecessor change.
2. Перед process implementation подтвердить фактическое завершение
   `optimize-session-oriented-sdd-v2` по canonical archive и completion evidence,
   затем заново прочитать поставленную authority, schema и session routing.
   Наличие всех planning files или native `isComplete` недостаточно.
3. Сопоставить пересекающиеся MODIFIED requirements с новыми main specs,
   сохранив поставленные predecessor invariants и scenarios. Если их текущая
   редакция требует изменения Requirement/Scenario, остановиться на Delta Specs
   approval boundary; после approval повторно согласовать зависимые Design и
   Tasks. Перенос future predecessor текста сейчас и автоматический merge при
   archive не заменяют этот шаг. При более раннем изменении intent возврат —
   к Proposal. До разрешения расхождения process implementation заблокирована.
4. Поставить Storybook и истории, удалив прежний custom catalog, а после dependency
   reconciliation — согласованное расширение существующих schema,
   policy и локальных adapters. Не дублировать новые predecessor rules о роли
   Validation, evidence и bounded outcomes; добавить только visual package
   responsibilities. Docs описывают фактически проверенное состояние.
5. Применять обновление к новым changes и к ещё не утверждённому Design активного
   change. Для уже утверждённого Design сохранить его исходную approval boundary:
   миграция пакета требует явного решения владельца; добавление или изменение
   содержательного UI/UX решения возвращает к Design и инвалидирует Tasks,
   затронутые Specs — к Specs. Для changes уже в Implementation/Validation нет
   автоматического retrofit или нового PASS: owner-requested migration проходит
   ту же boundary. Неизменяемые legacy changes продолжают по своему согласованному
   scope; исторические archives остаются неизменными. Не мигрировать чужие state
   в рамках этой поставки.
6. Завершить текущую поставку с affected gates и независимым semantic review,
   сохранив Design package при archive. Готовность означает доступность каталога
   и работающего процесса. Отдельный последующий небольшой UI change выбирается
   владельцем, получает собственные approvals и использует оба результата;
   только его наблюдённый проход позволяет заявить успешность совместного пилота.

### Rollback Contract

| Field | Decision |
| --- | --- |
| Status | `N/A` |
| Reason | Локальный tooling и versioned process artifacts обратимы; auth/security behavior, реальные данные, API и необратимая инфраструктура не меняются. Каталог имеет отдельный entrypoint. Возврат frontend/process редакции не удаляет canonical visual packages или archive и не восстанавливает approval автоматически. |