# frontend-ui-catalog Specification

## Purpose
Предоставляет участникам разработки воспроизводимый обзор ограниченного набора
реальных UI-компонентов и композиций WealthLedger для выбора решений на
общей визуальной основе приложения.

## Requirements

### Requirement: Каталог предоставляет определённый набор реальных компонентов

Участники разработки SHALL иметь один доступный каталог с явно определённым
ограниченным набором реальных компонентов и UI-композиций WealthLedger, их
назначением, поддерживаемыми вариантами, применимыми состояниями и правилами
использования. Основное содержание SHALL показывать решения, используемые
приложением. Библиотечные примитивы MAY быть вспомогательными примерами принятых
конфигураций, но MUST NOT подменять продуктовые компоненты и композиции. Каталог MUST демонстрировать реальное
поведение компонентов на общей визуальной основе приложения, а не независимые
имитации. Отсутствие компонента в каталоге MUST NOT означать его отсутствие в
приложении или запрет использования.

#### Scenario: Участник выбирает готовое решение

- **WHEN** участник просматривает включённый в каталог компонент
- **THEN** он видит его назначение, доступные варианты и состояния и может
  сопоставить их с потребностью интерфейса на визуальной основе WealthLedger

#### Scenario: Участник изучает принятый UI-паттерн

- **WHEN** участник выбирает композицию или компонент из основного набора
- **THEN** он видит реальное решение WealthLedger, его назначение, состояния и
  ограничения применения, а не только стандартный пример UI-библиотеки

#### Scenario: Компонент не входит в начальный набор

- **WHEN** участник ищет компонент за пределами объявленного набора
- **THEN** граница покрытия каталога остаётся явной, без заявления о полноте
  каталогизации приложения

### Requirement: Примеры воспроизводят состояния и взаимодействия изолированно

Каталог SHALL позволять воспроизводимо просматривать объявленные варианты и
состояния без прохождения полного пользовательского сценария приложения.
Интерактивные примеры SHALL позволять наблюдать поддерживаемые взаимодействия.
Примеры MUST сохранять применимые правила доступности и UI-состояний приложения
и MUST NOT вводить конкурирующую модель их поведения. Состояния, неприменимые к
компоненту, MUST NOT требоваться только ради заполнения каталога.

#### Scenario: Участник повторно открывает пример

- **WHEN** участник повторно выбирает тот же объявленный вариант и состояние
- **THEN** каталог воспроизводит соответствующий пример без предварительного
  прохождения инвестиционного сценария

#### Scenario: Участник взаимодействует с компонентом

- **WHEN** участник использует поддерживаемое взаимодействие интерактивного
  примера, включая клавиатурное управление там, где оно применимо
- **THEN** доступное поведение, focus и ограничения состояния соответствуют
  реальному компоненту приложения

#### Scenario: Представлено запросное состояние

- **WHEN** пример показывает применимое loading, error, empty или loaded
  состояние либо отображение ранее полученных данных при refetch
- **THEN** пример сохраняет действующую семантику соответствующего состояния
  приложения и не подменяет её новой каталоговой договорённостью

### Requirement: Каталог сохраняет достоверность и границы демонстрации

Каталог SHALL отражать фактические поддерживаемые возможности включённых
компонентов и общие визуальные правила приложения. Демонстрационные данные
MUST NOT требовать доступа к реальным финансовым данным или секретам пользователя;
действия в примерах MUST NOT изменять реальные пользовательские данные. Известное
ограничение воспроизведения MUST быть явно обозначено и MUST NOT представляться
как подтверждённое продуктовое поведение.

#### Scenario: Возможность компонента изменилась

- **WHEN** изменённая возможность включённого компонента поставляется
- **THEN** каталог показывает соответствующее фактическое поведение и не
  представляет устаревший вариант как поддерживаемый

#### Scenario: Участник выполняет демонстрационное действие

- **WHEN** участник открывает пример или выполняет в нём действие
- **THEN** для демонстрации не требуются реальные пользовательские финансовые
  данные или секреты и реальные пользовательские данные остаются неизменными

#### Scenario: Изолированный пример имеет ограничение

- **WHEN** пример не воспроизводит некоторый аспект полного пользовательского
  сценария
- **THEN** участник видит это ограничение и не получает заявления о проверке
  полного сценария на основании примера

### Requirement: Каталог разделяет Design System и Product

Каталог SHALL иметь два явно различимых содержательных блока: Design System
и Product. Design System SHALL показывать foundations из действующей общей темы,
семантические роли, используемые шкалы и общие компоненты, их варианты, состояния,
доступность и правила применения. Product SHALL содержать реальные бизнес-компоненты
и композиции приложения с полезными существующими историями, классифицированными
по ответственности без перемещения бизнес-реализаций в общий слой. Оба блока
MUST сохранять общую тему и изоляцию от application API, auth и данных пользователя.

#### Scenario: Участник открывает Design System

- **WHEN** выбран блок Design System
- **THEN** доступны наглядные foundations с актуальными значениями токенов,
  общие empty/error и loading компоненты, а также принятые конфигурации примитивов
  с правилами использования и применимыми интерактивными состояниями

#### Scenario: Участник открывает Product

- **WHEN** выбран блок Product
- **THEN** доступны существующие примеры списка счетов, карточек позиций, событий,
  обновления сохранённых сумм и skeleton страницы с их вариантами и ограничениями

#### Scenario: Оценивается готовность каталога

- **WHEN** каталог представлен как поставленный результат
- **THEN** существуют общий фундамент и оба содержательных блока, проверены
  отображение и применимые взаимодействия, явно описаны границы покрытия;
  сборка и наличие stories сами по себе не доказывают полноту или продуктовый пилот