# UI-каталог Storybook

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

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

Каталог работает как отдельная локальная витрина по адресу
[localhost:6006](http://localhost:6006) либо как самостоятельная статическая
сборка. Его примеры не входят в пользовательские маршруты приложения.
Публикация отдельным сервисом не настроена.

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

Каталог включает 14 групп и 54 примера:

| Группа | Что показывает |
| --- | --- |
| Основы дизайн-системы | Палитры, семантические роли, типографику, интервалы, радиусы, тени и адаптивные размеры |
| Пустой результат и ошибки | Четыре варианта с действием и без |
| Загрузка | Доступную область занятости с нейтральными фигурами |
| Кнопки | Основное, вторичное и вспомогательное действие, выполнение и недоступность, работу с клавиатурой |
| Список счетов | Несколько счетов и валют, недоступную и пустую сводку, неоценённые бумаги, длинные названия и суммы |
| Карточка позиции | Акцию с положительным результатом, облигацию с отрицательным, прочий инструмент и отсутствие оценки |
| Ближайшие события | Успешный, загружаемый, ошибочный и пустой результат; неизвестную сумму и длинное название |
| Обновление портфеля | Сохранённые суммы при обновлении и ошибке, локальную повторную попытку |
| Загрузка страницы счёта | Контур ожидаемых заголовка, сводки и строк |
| Структура портфеля | Валюты и типы активов, только деньги, пустую и неполную оценку, неизвестные и отрицательные значения |
| Сводка банковских карт | Расходы и возвраты, отрицательный месяц возврата, известные нули, загрузку, ошибку, сохранённые суммы и длинные точные итоги |
| Внешний вид банковской карты | Цвета банков, маскированный номер, платёжные системы, отсутствующие реквизиты и длинные названия в архиве |
| Иконки банковских операций | Пиктограммы категорий расходов, общую иконку нестандартной категории и пополнение |
| Поля банковской карты | Независимую рублёвую карту и недоступные финансовые поля архива |

Каталог не перечисляет все элементы библиотеки или приложения. Отсутствие
представления в витрине не означает его отсутствия в продукте. Основы показывают
опубликованные шкалы и смысл ролей; особые размеры и тени конкретных экранов
не объявляются общими токенами. Границы описаны в [дизайн-системе](design-system.md).

Canvas показывает выбранный пример. Docs поясняет назначение и ограничения,
Controls меняет доступные свойства, Actions показывает локальные действия.
Наборы вымышленных данных и доступные Controls определяются конкретным
примером; подготовленные варианты перечислены в историях. Свойства можно сбросить, пример —
смонтировать заново; изменение размера просмотра не сбрасывает выбранные значения.

Витрина и приложение используют одну тему. Примеры показываются по-русски
в светлой схеме. Ошибка сохраняет доступное объявление, загрузка — состояние
занятости; декоративные фигуры не получают фокус.

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

Все счета, позиции, события и суммы вымышлены. Каталог не читает сессии,
cookies, секреты и реальные пользовательские данные. Вместо внешних логотипов
показываются буквенные заглушки. Сама витрина может сохранять свои настройки;
телеметрия отключена.

Действия не обращаются к application API. Ссылки меняют только локальное
состояние примера, не открывают продуктовую страницу назначения и не меняют
адрес приложения. Повторная попытка демонстрирует локальное действие и не
доказывает восстановление реального запроса.

Сохранённые суммы иллюстрируют Client Cached Snapshot, но его жизненный цикл
здесь не исполняется. В приложении первичная загрузка показывает контур
ожидаемого содержимого, фоновое обновление сохраняет данные, а выполняемое
действие имеет контекстный индикатор. Подробности —
[состояния интерфейса](../architecture/cross-cutting/ui-resilience.md).

Автоматические проверки frontend охватывают каталог и его изоляцию от
продуктовых запросов. Примеры и их пояснения обновляются вместе с включёнными
представлениями. Клавиатура, реальные размеры и визуальное соответствие
проверяются в браузере; автоматической визуальной регрессии нет.

## Использование в UI задаче

Каталог помогает сравнить существующие состояния с ожидаемым пользовательским
сценарием. Он дополняет [принципы UI-решений](engineering-governance.md#ui-решения)
конкретными примерами, но успешная сборка не доказывает доступность,
визуальное соответствие и работу настоящего API.