specs/openspec/changes/archive/2026-09-07-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 автоматически.