docs: make project documentation self-contained
This commit is contained in:
+50
-98
@@ -1,120 +1,72 @@
|
||||
# UI-каталог Storybook
|
||||
|
||||
Storybook 10.6.0 показывает реальные компоненты и композиции WealthLedger
|
||||
на общей визуальной основе приложения без входа и подключения backend.
|
||||
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 и продуктовые маршруты. Публикация отдельным сервисом не настроена.
|
||||
Каталог работает как отдельная локальная витрина по адресу
|
||||
[localhost:6006](http://localhost:6006) либо как самостоятельная статическая
|
||||
сборка. Его примеры не входят в пользовательские маршруты приложения.
|
||||
Публикация отдельным сервисом не настроена.
|
||||
|
||||
## Компоненты и работа с примерами
|
||||
|
||||
В дереве доступны два блока, 9 групп / 30 историй:
|
||||
Два блока каталога включают 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 не вводится.
|
||||
Каталог не перечисляет все элементы библиотеки или приложения. Отсутствие
|
||||
представления в витрине не означает его отсутствия в продукте. Основы показывают
|
||||
опубликованные шкалы и смысл ролей; особые размеры и тени конкретных экранов
|
||||
не объявляются общими токенами. Границы описаны в [дизайн-системе](design-system.md).
|
||||
|
||||
Каталог не перечисляет весь Mantine или все компоненты приложения. AppShell
|
||||
с product navigation не объявлен компонентом общего набора. Отсутствие компонента
|
||||
в каталоге не запрещает его использование. Foundations показывает опубликованные
|
||||
шкалы из `shared/theme/tokens.json`, описания ролей и эффективные Mantine значения.
|
||||
Локальные размеры и особые тени не объявляются глобальными токенами;
|
||||
неопубликованные defaults остаются у Mantine. [Дизайн-система](design-system.md)
|
||||
описывает JSON-формат, внешнее чтение, ownership и правила расширения.
|
||||
Canvas показывает выбранный пример. Docs поясняет назначение и ограничения,
|
||||
Controls меняет доступные свойства, Actions показывает локальные действия.
|
||||
Вымышленные исходные данные не редактируются через Controls: другой набор
|
||||
данных выбирается отдельным примером. Свойства можно сбросить, пример —
|
||||
смонтировать заново; изменение размера просмотра не сбрасывает выбранные значения.
|
||||
|
||||
Выберите историю в дереве, чтобы открыть её состояние в 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 отключена.
|
||||
Все счета, позиции, события и суммы вымышлены. Каталог не читает сессии,
|
||||
cookies, секреты и реальные пользовательские данные. Вместо внешних логотипов
|
||||
показываются буквенные заглушки. Сама витрина может сохранять свои настройки;
|
||||
телеметрия отключена.
|
||||
|
||||
Stories не подключают AuthProvider, QueryClient, API clients и исполняемые VM.
|
||||
Действия не обращаются к application API. Ссылки меняют только локальный маршрут
|
||||
MemoryRouter: страница назначения не отображается, URL приложения не меняется.
|
||||
Retry демонстрирует локальный callback и не доказывает восстановление API или
|
||||
полный пользовательский сценарий. Loading/error относятся к выбранному примеру.
|
||||
Действия не обращаются к application API. Ссылки меняют только локальное
|
||||
состояние примера, не открывают продуктовую страницу назначения и не меняют
|
||||
адрес приложения. Повторная попытка демонстрирует локальное действие и не
|
||||
доказывает восстановление реального запроса.
|
||||
|
||||
Композиция сохранённых сумм показывает представление Client Cached Snapshot;
|
||||
сам query lifecycle не исполняется. Для запросных экранов действует
|
||||
[UI Pattern](../../frontend/.ai/conventions/frontend-ui.md#состояния-и-recovery): сохранение данных при refetch,
|
||||
structural skeleton для initial loading и контекстный индикатор mutation.
|
||||
Skeleton конкретной страницы остаётся ответственностью страницы.
|
||||
Сохранённые суммы иллюстрируют Client Cached Snapshot, но его жизненный цикл
|
||||
здесь не исполняется. В приложении первичная загрузка показывает контур
|
||||
ожидаемого содержимого, фоновое обновление сохраняет данные, а выполняемое
|
||||
действие имеет контекстный индикатор. Подробности —
|
||||
[состояния интерфейса](../features/frontend-ui-resilience.md).
|
||||
|
||||
При изменении включённого компонента проверяйте вместе с ним его пример,
|
||||
описание и ограничения. `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 нет.
|
||||
Автоматические проверки frontend охватывают каталог и его изоляцию от
|
||||
продуктовых запросов. Примеры и их пояснения обновляются вместе с включёнными
|
||||
представлениями. Клавиатура, реальные размеры и визуальное соответствие
|
||||
проверяются в браузере; автоматической визуальной регрессии нет.
|
||||
|
||||
## Использование в UI задаче
|
||||
|
||||
Каталог помогает выбрать existing component, состояние и ограничения. Ожидаемое
|
||||
поведение определите из задачи: экраны, states, interactions и узкий viewport.
|
||||
Для сложного варианта покажите конкретный макет/пример до дорогой реализации;
|
||||
простой согласованный вариант реализуйте сразу по [UI policy](engineering-governance.md#ui-решения).
|
||||
|
||||
Story — reference текущей реализации. Сборка не доказывает visual match,
|
||||
keyboard accessibility или работу настоящего API. Проверяйте соответствие задаче
|
||||
и применимые states в браузере. Использование установленного каталога не требует
|
||||
повторного approval установки или OpenSpec Design artifact.
|
||||
Каталог помогает сравнить существующие состояния с ожидаемым пользовательским
|
||||
сценарием. Он дополняет [принципы UI-решений](engineering-governance.md#ui-решения)
|
||||
конкретными примерами, но успешная сборка не доказывает доступность,
|
||||
визуальное соответствие и работу настоящего API.
|
||||
|
||||
Reference in New Issue
Block a user