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 и продуктовые маршруты. Публикация отдельным сервисом не настроена.

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

В дереве доступны два блока, 9 групп / 30 историй:

Блок / группа	Что показывает
Design System/Foundations	Восемь палитр и семантические роли, типографику, интервалы, радиусы, тени и breakpoints из общей темы, адаптированной из tokens.json.
Design System/Components/StateView	Четыре empty/error варианта с действием и без.
Design System/Components/LoadingSkeleton	Общую доступную busy-область с нейтральными structural shapes.
Design System/Components/Button	Прямой Mantine Button: primary, default, subtle, loading, disabled; локальное действие и keyboard interaction.
Product/BrokerageAccountList	Сводки счетов в нескольких валютах, недоступную/пустую сводку и длинное название.
Product/PositionCard	Акцию с положительным результатом, облигацию с отрицательным, прочий инструмент и позицию без оценки.
Product/RecentEvents	Полученные события, loading/error/empty и неизвестную ожидаемую сумму.
Product/PortfolioRefreshState с PortfolioTotals	Сохранённые суммы при обновлении и ошибке, локальный retry.
Product/AccountPageLoading	Реальный skeleton заголовка, сводки и строк страницы счёта.

Быстрые входы: Design System — цвета и Product — карточка позиции. Все исходные 21 истории сохранены; 9 новых добавляют foundations и общие примеры. Бизнес-компоненты остаются в entities/pages, а общие StateView и LoadingSkeleton — в shared/ui. Button показан напрямую: новое имя-wrapper не вводится.

Каталог не перечисляет весь Mantine или все компоненты приложения. AppShell с product navigation не объявлен компонентом общего набора. Отсутствие компонента в каталоге не запрещает его использование. Foundations показывает опубликованные шкалы из shared/theme/tokens.json, описания ролей и эффективные Mantine значения. Локальные размеры и особые тени не объявляются глобальными токенами; неопубликованные defaults остаются у Mantine. Дизайн-система описывает JSON-формат, внешнее чтение, ownership и правила расширения.

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

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

Preview и приложение используют один public API shared/theme: theme, CSSVariablesResolver и базовые styles вместе с Mantine CSS. Preview использует русскую i18n и фиксированную светлую схему без чтения сохранённой темы. Stories находятся рядом с существующими presentation components и импортируют их реализации. Токены и описания их семантических ролей принадлежат shared/theme/tokens.json; preview не хранит их копию. 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 change

Каталог помогает выбрать существующий компонент, его состояние и ограничения. Затем в Design своего change зафиксируйте применимость UI/UX, выбранную конфигурацию, затронутые экраны, состояния, взаимодействия и адаптивное поведение. Ссылка на текущую story помогает исследовать реализацию; согласованную версию решения сохраняет единый пакет Design. Его материалы получает Implementation и независимый reviewer через OpenSpec lifecycle.

Каталог и этот процесс доступны для совместного использования в отдельном небольшом UI change. Его выбирает владелец; он проходит собственные planning approvals. Это готовность к пилоту: продуктовая фича автоматически не назначена, сквозной продуктовый пилот не проводился и его успешность не заявляется.