frontend-design-system Specification

Purpose

Определяет единый визуальный фундамент WealthLedger и переиспользуемые общие компоненты, чтобы приложение и каталог сохраняли согласованное представление.

Requirements

Requirement: Приложение и каталог используют единый визуальный фундамент

Приложение и каталог SHALL использовать один источник темы и токенов: цвета с семантическими ролями, типографику, интервалы, радиусы, тени и применимые адаптивные параметры. Общий фундамент MUST быть независим от бизнес-сущностей и уровня приложения; подключение провайдеров принадлежит приложению и runtime каталога. Объявленные общие токены SHALL иметь единый переносимый машиночитаемый источник значений, единиц, семантических ссылок и описаний, доступный без приложения или UI-библиотеки. Адаптер приложения SHALL потреблять этот источник без ручного дублирования значений. Перенос владения опубликованными шкалами из UI-библиотеки в токены MUST сохранять их эффективные значения; не включённые в контракт библиотечные defaults MAY оставаться у библиотеки. Выделение фундамента MUST сохранять текущий внешний вид, светлую схему и поведение приложения без массовой замены локальных значений оформления. Источник SHALL поставляться вместе с приложением как доверенная конфигурация; загрузка внешних или пользовательских токенов и отдельная runtime-валидация произвольных документов не поддерживаются.

Scenario: Компонент отображается в приложении и каталоге

WHEN один компонент с одинаковыми props отображается в обоих runtime
THEN он получает одинаковые тему, токены и общие визуальные правила

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

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

Scenario: Владение темой перенесено

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

Scenario: Токены использует другая система

WHEN потребитель читает исходный файл обычным парсером данных
THEN объявленные цвета, роли, типографика, интервалы, радиусы, тени и адаптивные пороги доступны с определёнными единицами и ссылками без React, Mantine, CSS runtime или запуска приложения; интеграция конкретного инструмента не заявляется автоматически

Scenario: Изменён исходный токен

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

Scenario: Исходные токены некорректны

WHEN разработчик вносит некорректное значение в локальный источник
THEN отдельный runtime-валидатор не применяется; корректность изменения проверяется при review и проверке представления, автоматическое отклонение любого некорректного документа не гарантируется

Requirement: Общие компоненты независимы от предметной области

Дизайн-система SHALL предоставлять минимальный набор реально используемых общих компонентов с описанием назначения, вариантов, состояний и доступности. Они MUST NOT знать о счетах, позициях, API или authentication. Существующие компоненты SHALL переиспользоваться, если удовлетворяют этой границе; новые обёртки MUST NOT вводиться только ради имени или покрытия каждого примитива. Принятые конфигурации библиотечных компонентов MAY демонстрироваться напрямую.

Scenario: Требуется общее состояние интерфейса

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

Scenario: Композиция имеет бизнес-смысл

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

7.0 KiB Raw Blame History