docs(design-system): add foundation specification
This commit is contained in:
parent
1b6fd39be3
commit
e8dcb27a03
168
docs/features/design-system-foundation/spec.md
Normal file
168
docs/features/design-system-foundation/spec.md
Normal file
@ -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.
|
||||||
|
- [ ] Существующие продуктовые страницы визуально не мигрированы в рамках этой фичи.
|
||||||
Loading…
x
Reference in New Issue
Block a user