diff --git a/docs/features/design-system-foundation/spec.md b/docs/features/design-system-foundation/spec.md new file mode 100644 index 0000000..9091099 --- /dev/null +++ b/docs/features/design-system-foundation/spec.md @@ -0,0 +1,168 @@ +# 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. +- [ ] Существующие продуктовые страницы визуально не мигрированы в рамках этой фичи.