# UI-каталог Storybook

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

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

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

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

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

```bash
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 — цвета](http://localhost:6006/?path=/story/design-system-foundations--colors)
и [Product — карточка позиции](http://localhost:6006/?path=/story/product-positioncard--stock-gain).
Все исходные 21 истории сохранены; 9 новых добавляют foundations и общие примеры.
Бизнес-компоненты остаются в entities/pages, а общие StateView и LoadingSkeleton
— в shared/ui. Button показан напрямую: новое имя-wrapper не вводится.

Каталог не перечисляет весь Mantine или все компоненты приложения. AppShell
с product navigation не объявлен компонентом общего набора. Отсутствие компонента
в каталоге не запрещает его использование. Foundations показывает опубликованные
шкалы из `shared/theme/tokens.json`, описания ролей и эффективные Mantine значения.
Локальные размеры и особые тени не объявляются глобальными токенами;
неопубликованные defaults остаются у Mantine. [Дизайн-система](design-system.md)
описывает 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`; `theme.ts` напрямую адаптирует этот локальный файл
в Mantine, 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](../../frontend/.ai/conventions/frontend-ui.md#состояния-и-recovery): сохранение данных при 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 задаче

Каталог помогает выбрать existing component, состояние и ограничения. Ожидаемое
поведение определите из задачи: экраны, states, interactions и узкий viewport.
Для сложного варианта покажите конкретный макет/пример до дорогой реализации;
простой согласованный вариант реализуйте сразу по [UI policy](engineering-governance.md#ui-решения).

Story — reference текущей реализации. Сборка не доказывает visual match,
keyboard accessibility или работу настоящего API. Проверяйте соответствие задаче
и применимые states в браузере. Использование установленного каталога не требует
повторного approval установки или OpenSpec Design artifact.