## 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 |