moex-vibe/docs/features/design-system-foundation/spec.md

Design System Foundation

Статус

Draft — ожидает ревью пользователя.

Цель

Создать внутреннюю дизайн-систему MoexVibe поверх MUI, которая задаёт единый визуальный язык, контролируемый набор UI-компонентов и правила их применения. Первая версия должна обслуживать web- приложение MoexVibe и сохранять нейтральную к платформе модель токенов для будущих адаптеров, включая Android.

Принципы

• MUI является компонентным и accessibility-движком, но не определяет визуальную идентичность MoexVibe.
• Визуальное направление: спокойный нейтральный финансовый интерфейс со сбалансированной плотностью.
• Текущие стили приложения не являются источником дизайн-решений. Их миграция выполняется после foundation отдельными фичами.
• Дизайн-система не содержит бизнес-логику, API-клиенты, маршрутизацию и доменные компоненты.
• Docusaurus остаётся единственной опубликованной человекочитаемой документацией проекта.

Артефакты

Workspace-пакет

В monorepo должен появиться внутренний пакет @moex-vibe/design-system со следующими границами:

• platform-neutral токены без зависимостей от React и MUI;
• MUI-адаптер, создающий тему и CSS variables из токенов;
• Core UI и повторяемые product patterns;
• стабильные subpath exports для токенов, темы и компонентов.

Продуктовый frontend использует компоненты дизайн-системы. Прямые импорты MUI разрешены только для компоновки (Box, Stack, Grid и системные layout utilities). Интерактивные и визуально значимые компоненты должны поступать из @moex-vibe/design-system.

Storybook

Storybook является локальным и CI-стендом дизайн-системы. Он показывает варианты, состояния, адаптивное поведение и accessibility-контракты компонентов, но не считается опубликованной документацией для пользователей проекта.

Docusaurus

В apps/docs должен появиться раздел «Дизайн-система» со страницами:

• обзор и принципы;
• foundations: цвет, типографика, spacing, размеры, радиусы, elevation и motion;
• модель токенов и правила их изменения;
• каталог компонентов и product patterns;
• accessibility;
• contribution и governance.

Каждая карточка компонента описывает: назначение и запреты, anatomy, разрешённые варианты, состояния, keyboard behavior, accessibility, content rules, responsive behavior, корректные примеры и антипаттерны.

Модель токенов

Source of truth первой версии — типизированные TypeScript-объекты. Их схема и имена не должны зависеть от MUI, React или CSS. Формат должен оставаться JSON-совместимым, чтобы позднее добавить экспорт в DTCG/Android resources без изменения семантических имён.

Токены состоят из трёх уровней с однонаправленными зависимостями:

1. Primitive/reference — сырые палитры, шкалы spacing и размеров, типографика, радиусы, тени и motion. Только на этом уровне допустимы абсолютные визуальные значения.
2. Semantic/system — роли: canvas, surface, text, border, action, feedback и финансовая семантика positive/negative/neutral. Будущая тёмная тема переопределяет этот уровень, не меняя компоненты.
3. Component — устойчивые решения конкретных компонентов и вариантов. Они ссылаются на semantic tokens и создаются только для повторяемых или тематизируемых решений, а не для каждого CSS- свойства MUI.

Приложение не должно использовать primitive tokens или произвольные визуальные значения напрямую. Цвет не может быть единственным способом сообщить финансовое состояние.

Тема и визуальные основы

• Первая версия включает только светлую тему. API темы должен допускать добавление новых color schemes без изменения API компонентов.
• MUI theme использует CSS variables и получает palette, typography, spacing, shape, elevation, motion, defaults, variants и style overrides из токенов.
• Основная плотность интерфейса — сбалансированная. Компактный вариант допускается как явный вариант data-heavy компонентов, но не как глобальный режим v1.
• Все состояния focus-visible должны быть заметны; компоненты поддерживают keyboard navigation и prefers-reduced-motion там, где используется анимация.
• Целевой уровень доступности — WCAG 2.2 AA для применимых web-компонентов.

Компонентная модель

Core UI v1

• Typography: Text, Heading, Link.
• Actions: Button, IconButton.
• Inputs: TextField, Select, Checkbox.
• Surfaces and labels: Surface, Card, Chip, Badge.
• Feedback: Alert, Dialog, Skeleton, Progress.

Core UI ограничивает разрешённые variants и состояния MUI, сохраняет доступность и не содержит доменной логики.

Product patterns v1

• Data display: DataTable, Metric, Money, PriceChange.
• Forms and filtering: FormField, FilterBar.
• Page states: EmptyState, ErrorState, LoadingState.

Product pattern попадает в пакет, если он не знает бизнес-домен и имеет минимум два подтверждённых места использования. Исключение — базовые интерактивные Core UI primitives, необходимые для целостного API.

Доменные компоненты, включая broker-, portfolio- и screener-specific композиции, остаются в соответствующих FSD-слоях frontend.

Governance

• Изменение значения primitive token не должно молча менять смысл semantic token.
• Новый token требует описания роли и проверки существующих эквивалентов.
• Новый variant или компонент требует documented use case; API «на всякий случай» не добавляется.
• Breaking changes внутреннего пакета фиксируются в changelog и миграционной заметке, даже пока пакет не публикуется во внешний npm registry.
• Архитектура пакета и граница прямого использования MUI фиксируются отдельным ADR.

Проверки качества

• Unit-тесты проверяют token contracts, уникальность имён, допустимые ссылки и отсутствие циклов.
• Type tests проверяют публичные exports и разрешённые component variants.
• Interaction tests проверяют keyboard и пользовательские состояния интерактивных компонентов.
• Storybook содержит stories для default, hover/focus reference, disabled, loading, error и responsive состояний, когда они применимы.
• Автоматические accessibility-проверки выполняются для stories и не допускают серьёзных нарушений.
• Visual regression покрывает репрезентативные состояния Core UI и product patterns.
• CI собирает workspace-пакет, Storybook, frontend и Docusaurus; затронутые lint и tests проходят.

Вне scope

• Тёмная тема и UI-переключатель темы.
• Android-адаптер, DTCG/JSON export и синхронизация с Figma.
• Публикация пакета во внешний npm registry.
• Backend-driven UI.
• Массовая миграция существующих страниц и удаление legacy CSS.
• Редизайн доменных экранов, графиков и визуализаций данных.

Последовательность внедрения

1. Эта фича создаёт Design System Foundation и не переписывает продуктовые экраны.
2. Отдельная фича мигрирует один репрезентативный pilot-экран и возвращает подтверждённые изменения в tokens/component API.
3. Остальные области мигрируются отдельными вертикальными срезами; legacy styles удаляются только после миграции всех их потребителей.

Acceptance Criteria

• @moex-vibe/design-system подключён как внутренний workspace-пакет с документированными public exports.
• Реализованы три уровня platform-neutral TypeScript tokens и автоматические проверки их контрактов.
• Light MUI theme полностью строится из токенов и предоставляет CSS variables.
• Реализован и задокументирован каталог Core UI v1 и product patterns v1.
• Прямое использование MUI ограничено documented allowlist для layout utilities.
• Storybook локально запускается, собирается в CI и содержит обязательные состояния компонентов.
• Accessibility и visual regression checks проходят для согласованного набора stories.
• В Docusaurus опубликован полный раздел дизайн-системы и правила выбора компонентов.
• Создан ADR о границах пакета, MUI-адаптере и будущих platform adapters.
• Frontend, docs и design-system package проходят build, lint и tests.
• Существующие продуктовые страницы визуально не мигрированы в рамках этой фичи.