169 lines
12 KiB
Markdown
169 lines
12 KiB
Markdown
# 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.
|
||
- [ ] Существующие продуктовые страницы визуально не мигрированы в рамках этой фичи.
|