specs/openspec/changes/archive/2026-09-08-make-design-tokens-portable/design.md

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