specs/openspec/changes/archive/2026-09-08-complete-shared-design-system/design.md

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 восстанавливает исходную структуру