specs/openspec/specs/frontend-ui-catalog/spec.md

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 сами по себе не доказывают полноту или продуктовый пилот