Integrate Storybook and portable UI design workflow

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

@@ -0,0 +1,271 @@
+## 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 автоматически. |