120 lines
9.1 KiB
Markdown
120 lines
9.1 KiB
Markdown
## Context
|
||
|
||
Текущий shared/theme задаёт blue, font family и colorRoles в TypeScript;
|
||
остальные опубликованные шкалы получает из DEFAULT_THEME Mantine 9.5.1.
|
||
Приложение и Storybook уже используют один provider contract; 9 групп / 30
|
||
stories существуют. Переносимость требует источника, который читается обычным
|
||
JSON parser без runtime этих библиотек.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:** JSON ownership общих токенов и semantic descriptions, узкий Mantine
|
||
adapter, валидация source contract, прежние эффективные размеры/цвета/поведение.
|
||
|
||
**Non-Goals:** новый token engine, внешние integrations или публикация пакета,
|
||
автоматическая совместимость с DTCG импортерами, dark theme, новые компоненты,
|
||
редизайн, перенос локальных product literals, изменение API/backend и архивов.
|
||
|
||
## Decisions
|
||
|
||
- `shared/theme/tokens.json` — единственный редактируемый источник опубликованных
|
||
токенов: formatVersion, description, palette/base colors, default shades,
|
||
semantic roles с description, typography, spacing/radius, shadows, breakpoints.
|
||
JSON самодостаточен: нет DEFAULT_THEME imports, CSS variables и executable code.
|
||
- Формат WealthLedger v1 документируется явно. Hex colors, числовые weights и
|
||
unitless line heights, размерные группы с unit px, breakpoints с unit em;
|
||
shadow состоит из упорядоченных слоёв offsetX/offsetY/blur/spread в px,
|
||
color и opacity. Font families — строки CSS font stacks. Semantic role
|
||
ссылается на palette/base color по имени и optional shade; null shade палитры
|
||
означает primaryShade.light для поддерживаемой светлой схемы. Base colors
|
||
используют null shade. Описания ролей также принадлежат JSON.
|
||
- В source закрепляются blue, gray, dark, red, green, yellow, grape и orange
|
||
(используется Product), white/black, все опубликованные typography/layout scales.
|
||
Их текущие значения принимаются один раз из baseline. Необъявленные Mantine
|
||
palettes и UI behavior defaults остаются библиотечными и не считаются токенами
|
||
переносимого контракта. JSON не генерируется обратно из Mantine.
|
||
- `theme.ts` адаптирует проверенные данные: native rem(px) сохраняет scale,
|
||
breakpoints преобразуются в em без scale, shadows — в CSS с теми же слоями.
|
||
Primary role сохраняет native filled reference; resolver выдаёт прежние
|
||
--wl-color-* aliases. App/preview, shared styles и компоненты не меняются.
|
||
- Установленный Zod валидирует shape, units/ranges, palette cardinality и role
|
||
references при чтении source; некорректные tokens не получают fallback.
|
||
Это ограниченная схема текущего формата, без цепочек aliases, resolver graph,
|
||
plugin architecture или динамической загрузки внешних tokens.
|
||
- Foundations читает effective theme и JSON descriptions; показывает источник
|
||
и границу portable contract, сохраняя story IDs и оба блока. Frontend импортирует
|
||
theme/tokens через public API; внешний потребитель читает raw JSON напрямую,
|
||
не исполняя barrel с CSS и Mantine.
|
||
|
||
## UI/UX Applicability and Package
|
||
|
||
**Applicability and scope:** new/changed только для пояснений Foundations и
|
||
добавления уже используемой orange palette в обзор. Приложение, общие компоненты,
|
||
Product states/interactions и responsive поведение сохраняются без нового макета.
|
||
|
||
**Package revision:** 1, полностью inline Markdown, exports не нужны.
|
||
|
||
**Screens, states and interactions:** Colors содержит те же semantic role cards,
|
||
данные/описания из JSON и palette swatches, включая orange. Typography и Layout
|
||
сохраняют образцы, поясняют JSON ownership вместо DEFAULT_THEME ownership.
|
||
Button, StateView, LoadingSkeleton и Product используют прежние реализации.
|
||
|
||
**Responsive behavior:** существующие grids/stack сохраняются; длинные source
|
||
пояснения переносятся на 375px. Изменение Mantine scale продолжает масштабировать
|
||
spacing/radius/type/shadow dimensions; responsive thresholds остаются em.
|
||
|
||
**Reused source and differences:** implementation baseline; historical Design
|
||
package не переиспользуется как external authority, archived artifacts не меняются.
|
||
|
||
## Delivery Map
|
||
|
||
| Area | Status | Architectural outcome or N/A reason |
|
||
| --- | --- | --- |
|
||
| frontend | affected | Самодостаточный tokens.json, schema и Mantine adapter, актуальный Foundations |
|
||
| backend | N/A | API/auth/storage и денежные вычисления не затронуты |
|
||
| specs | affected | Уточнённый source/ownership contract и фактическое evidence |
|
||
| docs | affected | As-built JSON format, ownership, usage и integration limits |
|
||
|
||
### Contract Gate Decision
|
||
|
||
| Gate | Status | Reason |
|
||
| --- | --- | --- |
|
||
| runtime-openapi | N/A | Frontend/backend API contract не меняется |
|
||
|
||
## Solution Assessment
|
||
|
||
Обычный JSON читается стандартными парсерами без operating dependencies;
|
||
Mantine rem/createTheme/getThemeColor и установленный Zod покрывают adaptation
|
||
и validation. Полный DTCG или Style Dictionary уместен при выбранном потребителе
|
||
и требованиях к transforms, но сейчас добавляет форматные преобразования и
|
||
tooling без подтверждённой совместимости целевого инструмента. Собственный
|
||
контракт ограничен данными и прямым adapter, без универсального движка. При
|
||
выборе внешнего потребителя оценить его importer и трансформацию в требуемый формат.
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- JSON теперь владеет принятыми шкалами: обновление Mantine не заменяет их
|
||
автоматически; локальные library defaults вне portable contract могут измениться.
|
||
- Числовые px в adapter используют rem, а не простые rem strings, чтобы сохранить
|
||
--mantine-scale. Breakpoints не масштабируются. Structured shadows могут дать
|
||
другой строковый порядок CSS при одинаковом computed value.
|
||
- Публичный format v1 требует явного изменения контракта при несовместимом изменении;
|
||
существующая browser интеграция не доказывает импорт конкретным внешним инструментом.
|
||
|
||
## Migration Plan
|
||
|
||
Сохранить baseline; перенести данные в JSON, включить schema и adapter; обновить
|
||
Foundations и документацию. Выполнить checks и независимый read-only review,
|
||
затем canonical completion. Прямое разрешение владельца в беседе сохраняет
|
||
workflow без session records и повторных промежуточных approval stops.
|
||
|
||
### Rollback Contract
|
||
|
||
| Field | Decision |
|
||
| --- | --- |
|
||
| Status | required |
|
||
| Trigger | Нарушено представление или потребление нового source contract |
|
||
| Actions | Вернуть delivery diff frontend/docs и соответствующую spec delta; не править исторические архивы. При появлении реального внешнего потребителя сохранить v1 JSON до его согласованной миграции. |
|
||
| Data safety | User data/auth не меняются; экспортированный v1 источник сохраняется для уже подключённых потребителей |
|
||
| Verification | Прежняя тема и обе сборки проходят gates; browser образцы совпадают с baseline |
|