docs/development/ui-catalog.md

UI-каталог Storybook

Storybook 10.6.0 показывает реальные компоненты и композиции WealthLedger на общей визуальной основе приложения без входа и подключения backend.

Запуск и сборка

Из frontend/ выберите Node 22 и установите зависимости из lockfile:

nvm use --silent
npm ci
npm run dev:catalog

Storybook запускается на localhost:6006; браузер автоматически не открывается. Отдельная статическая сборка и её preview:

npm run build:catalog
npm run preview:catalog

Результат находится в frontend/storybook-static/, вход — index.html. Команда preview выводит адрес статической витрины в терминале. Обычный npm run build сохраняет приложение в frontend/dist/; stories не входят в его entrypoint и продуктовые маршруты. Публикация отдельным сервисом не настроена.

Компоненты и работа с примерами

В дереве Storybook доступны шесть групп:

Группа	Что показывает
BrokerageAccountList	Счета со сводкой по нескольким валютам, недоступной или пустой сводкой и длинным названием.
PositionCard	Акцию с положительным результатом, облигацию с отрицательным, прочий инструмент и позицию без оценки.
RecentEvents	Полученные события, загрузку, ошибку, пустой результат и неизвестную ожидаемую сумму.
PortfolioRefreshState с PortfolioTotals	Сохранённые суммы при фоновом обновлении и его ошибке, локальный retry.
StateView	Пустое состояние и ошибку, с действием и без него.
AccountPageLoading через LoadingSkeleton	Реальный skeleton заголовка, сводки и строк страницы счёта.

Стандартные Mantine primitives видны внутри этих компонентов. Отдельных копий библиотечных demos или обёрток ради каталога нет. Каталог не заявляет полноту: отсутствие компонента не запрещает его использование в приложении.

Выберите историю в дереве, чтобы открыть её состояние в Canvas. Docs описывает назначение, ограничения и свойства группы, а также её примеры. Controls меняют разрешённые свойства; синтетические объекты и callbacks недоступны для редактирования. Например, kind у PositionCard меняет вариант представления фиксированной позиции, а разные данные инструмента выбираются отдельной историей. Actions регистрирует локальные callbacks кнопок и retry.

Для возврата изменённых свойств используйте штатный reset args в Controls; для повторного монтирования примера — remount в панели Canvas. Размер preview можно менять без сброса args. Изолированный iframe позволяет отдельно проверить компонент на узком экране; навигацией самой витрины управляет Storybook.

Preview использует экспортируемую app theme, Mantine CSS, application styles, русскую i18n и фиксированную светлую схему без чтения сохранённой темы. Stories находятся рядом с существующими presentation components и импортируют их реализации. Отдельных tokens нет. Error StateView сохраняет alert semantics, skeleton — busy-область с декоративными фигурами без фокуса. Проверяйте доступность действий и ссылок с клавиатуры вместе с визуальным состоянием.

Границы и сопровождение

Все счета, позиции, события и суммы вымышлены. Stories не читают application storage, cookies, секреты или реальные пользовательские данные. Внешние логотипы не загружаются: примеры используют буквенный fallback существующего компонента. Storybook manager может сохранять собственные настройки витрины; telemetry отключена.

Stories не подключают AuthProvider, QueryClient, API clients и исполняемые VM. Действия не обращаются к application API. Ссылки меняют только локальный маршрут MemoryRouter: страница назначения не отображается, URL приложения не меняется. Retry демонстрирует локальный callback и не доказывает восстановление API или полный пользовательский сценарий. Loading/error относятся к выбранному примеру.

Композиция сохранённых сумм показывает представление Client Cached Snapshot; сам query lifecycle не исполняется. Для запросных экранов действует UI Pattern: сохранение данных при refetch, structural skeleton для initial loading и контекстный индикатор mutation. Skeleton конкретной страницы остаётся ответственностью страницы.

При изменении включённого компонента проверяйте вместе с ним его пример, описание и ограничения. npm run verify включает Storybook в strict TypeScript, Biome, Vitest, Knip и dependency-cruiser, затем собирает приложение и статическую витрину. Основная проверка FSD сохраняется; отдельный deps:storybook проверяет runtime graph stories и preview, запрещая достижимость application data. Type-only ссылки на типы VM и API стираются и не запускают запросы. Declarative stories не требуют искусственного unit coverage, а продуктовые coverage floors сохраняются. Клавиатура, реальные размеры и визуальное соответствие проверяются в браузере; автоматической visual regression нет.

Каталог доступен независимо от процессного расширения UI/UX. Новый contract визуального пакета Design пока не поставлен: он ожидает завершения optimize-session-oriented-sdd-v2 и сверки с его authority. Совместная готовность каталога и обновлённого процесса к пилоту ещё не подтверждена; продуктовый пилот не проводился. Действующий процесс описан в OpenSpec lifecycle.