specs: define shared design system correction
This commit is contained in:
@@ -0,0 +1,127 @@
|
||||
## Context
|
||||
|
||||
Baseline: app/theme задаёт blue 0–9, primaryColor blue, defaultRadius md и
|
||||
системный sans-serif; прочие шкалы разрешаются Mantine 9.5.1. App/styles задаёт
|
||||
фон gray.2 и текст dark.7. StateView и LoadingSkeleton уже используются в shared/ui.
|
||||
Каталог содержит 6 групп / 21 историю; preview импортирует тему из app.
|
||||
Локальные card gradients, размеры, shadows и бизнес-цвета остаются у владельцев.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:** shared-владение темы и базовых стилей, явные шкалы и семантические
|
||||
роли без копий значений, полезный общий набор и два блока Storybook.
|
||||
|
||||
**Non-Goals:** редизайн приложения, перенос всех CSS literals в tokens,
|
||||
новые зависимости, смена Mantine, перенос AppShell/навигации, бизнес-реализаций
|
||||
или auth в дизайн-систему, продуктовый пилот и правка исторических artifacts.
|
||||
|
||||
## Decisions
|
||||
|
||||
- `shared/theme` — FSD segment с public API `index.ts`: тема Mantine,
|
||||
CSSVariablesResolver и семантические color roles. Базовые CSS импортируются
|
||||
public entrypoint темы. App владеет MantineProvider; preview подключает свой
|
||||
изолированный MantineProvider с тем же public API. Дублирующий app/theme удаляется.
|
||||
- Blue palette и font family сохраняют исходные bytes. Шкалы spacing, radius,
|
||||
fontSizes, lineHeights, headings, shadows, breakpoints и mono font явно
|
||||
принимаются из DEFAULT_THEME, без повторения числовых значений. Primary shade
|
||||
и focus behavior также сохраняют defaults. Это используемый Mantine contract,
|
||||
а не отдельный token engine.
|
||||
- Семантические CSS aliases `--wl-color-*` ссылаются на Mantine CSS variables:
|
||||
canvas gray.2, surface white (body светлой схемы), subtle gray.0, text dark.7, muted gray.6 (dimmed),
|
||||
border gray.3, primary filled, info blue.6, positive green.6, negative red.6,
|
||||
warning yellow.6. Цвет не заменяет текстовый статус; warning не предназначен
|
||||
для мелкого текста на белом. Глобальный фон/текст используют соответствующие
|
||||
aliases; локальные роли можно принимать постепенно без массовой миграции.
|
||||
- Общий набор — существующие StateView (empty/error, optional action) и
|
||||
LoadingSkeleton (busy/status wrapper с caller-owned decorative shapes).
|
||||
Они уже решают реальные задачи, не требуют новых wrappers. AppShell содержит
|
||||
маршруты и не входит в заявленный общий каталог. Mantine Button показывается
|
||||
напрямую в принятых конфигурациях primary/default/subtle/loading/disabled;
|
||||
никаких WLButton и изменения глобальных defaults ради витрины.
|
||||
- CSF stories остаются colocated. StateView и новые foundations/loading/buttons
|
||||
относятся к Design System; пять существующих бизнес-групп — Product.
|
||||
Theme foundations читают effective theme через useMantineTheme, labels роли
|
||||
ссылаются на тот же alias map; значения не копируются в stories.
|
||||
|
||||
## UI/UX Applicability and Package
|
||||
|
||||
**Applicability and scope:** new/changed для каталога; приложение сохраняет
|
||||
существующий UI, новый макет приложения не нужен.
|
||||
|
||||
**Package revision:** 1; пакет полностью inline Markdown, exports не нужны.
|
||||
|
||||
**Screens, states and interactions:**
|
||||
|
||||
| Блок / экран | Содержание и поведение |
|
||||
| --- | --- |
|
||||
| Design System / Foundations / Colors | Подписанные роли, образец цвета, фактическое значение; blue 0–9 и используемые neutral/status palettes. Цвет всегда сопровождается текстом. |
|
||||
| Design System / Foundations / Typography | Семейства sans/mono, heading и body шкалы с размерами, весом, line-height и примерами. |
|
||||
| Design System / Foundations / Layout | Spacing, radius, shadows, breakpoints из effective theme, default radius и правила применения. |
|
||||
| Design System / Components / StateView | Сохраняются все 4 истории: empty/error с действием и без, error role alert, keyboard button и локальный callback. |
|
||||
| Design System / Components / LoadingSkeleton | Нейтральные structural shapes; status/busy label, no focusable shapes. Форма страницы остаётся у page. |
|
||||
| Design System / Components / Button | Реальный Mantine Button; primary/default/subtle, loading/disabled, доступное имя, keyboard focus и наблюдаемый local action. |
|
||||
| Product | Все 17 исходных бизнес-историй: список счетов, позиции, события, обновление сохранённых сумм и loading страницы. Синтетические fixtures, локальные Actions и MemoryRouter, без API/auth runtime. |
|
||||
|
||||
Docs каждой группы задаёт назначение, правила применения и границы. Manager
|
||||
явно сортирует Design System перед Product. Controls меняют поддерживаемые args,
|
||||
reset/remount сохраняют штатную семантику Storybook.
|
||||
|
||||
**Responsive behavior:** foundations используют переносящиеся grids/stack,
|
||||
длинные значения и labels не расширяют viewport 375px. Button variants переносятся;
|
||||
StateView сохраняет доступную кнопку. Product сохраняет существующее responsive
|
||||
поведение; проверяется узкий и desktop iframe, без нового breakpoint contract.
|
||||
|
||||
**Reused source and differences:** исходные реализации текущей baseline,
|
||||
без ссылки на изменяемую витрину как authority и без reuse исторического пакета.
|
||||
|
||||
## Delivery Map
|
||||
|
||||
| Area | Status | Architectural outcome or N/A reason |
|
||||
| --- | --- | --- |
|
||||
| frontend | affected | Shared theme и базовые styles, общий набор, два блока каталога |
|
||||
| backend | N/A | API, auth и хранение данных не меняются |
|
||||
| specs | affected | Новый corrective contract и evidence в canonical store |
|
||||
| docs | affected | As-built foundation ownership, coverage и использование каталога |
|
||||
|
||||
### Contract Gate Decision
|
||||
|
||||
| Gate | Status | Reason |
|
||||
| --- | --- | --- |
|
||||
| runtime-openapi | N/A | Ни одна сторона API contract не меняется |
|
||||
|
||||
## Solution Assessment
|
||||
|
||||
Mantine 9.5.1 уже предоставляет зрелые тему, типы, CSS variables, scales,
|
||||
компоненты и focus/loading/disabled semantics. Его native theme сохраняет
|
||||
совместимость и не увеличивает operating cost. Storybook 10.6.0 уже установлен,
|
||||
CSF/autodocs достаточно для двух блоков. Отдельный token framework либо новая
|
||||
UI-библиотека дублировали бы ownership, увеличили зависимости и стоимость
|
||||
миграции без нужного поведения. Выбран текущий stack; custom code ограничен
|
||||
семантическим map и демонстрацией effective scales, без runtime интеграций.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- DEFAULT_THEME — источник встроенных шкал: обновление Mantine требует проверки
|
||||
foundations и приложения, а не скрытого сохранения старой копии defaults.
|
||||
- Перенос CSS может повлиять на cascade; сохраняются content/order и сравниваются
|
||||
computed styles и снимки до/после. Не заявляется exhaustiveness визуальной проверки.
|
||||
- Новые story IDs меняют прямые ссылки; документация использует новые пути.
|
||||
- Изоляция подтверждается существующим transitive runtime graph guard;
|
||||
browser проверяет доступность и взаимодействия, не API recovery.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Зафиксировать baseline, перенести ownership темы и styles, подключить оба
|
||||
provider, оформить общий набор и foundations, классифицировать Product,
|
||||
обновить документацию. После проверок — независимый read-only review и canonical
|
||||
completion mechanics только при актуальном PASS. Исторические archives и чужие
|
||||
changes/state исключены из записи. Прямое разрешение владельца в запросе
|
||||
заменяет промежуточные session/approval stops для этого bounded corrective scope;
|
||||
независимость review сохраняется.
|
||||
|
||||
### Rollback Contract
|
||||
|
||||
| Field | Decision |
|
||||
| --- | --- |
|
||||
| Status | N/A |
|
||||
| Reason | Обратимый перенос frontend-владения и каталог, без данных, auth или public API изменений; возврат delivery diff восстанавливает исходную структуру |
|
||||
Reference in New Issue
Block a user