# Design System Foundation ## Статус Approved — утверждена пользователем 2026-06-21. ## Цель Создать внутреннюю дизайн-систему 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. - [ ] Существующие продуктовые страницы визуально не мигрированы в рамках этой фичи.