docs: describe portable design token contract

development/design-system.md

@@ -2,24 +2,35 @@
 
 Общий фундамент находится в
 [`frontend/src/shared/theme`](../../frontend/src/shared/theme/index.ts).
-Его public API экспортирует `theme`, `cssVariablesResolver`, `colorRoles` и
+Его public API экспортирует `theme`, `cssVariablesResolver`, `colorRoles`, `designTokens` и
 подключает базовые CSS. App владеет MantineProvider; Storybook подключает свой
 изолированный provider к тому же API. Тема и значения не копируются в preview.
 Оба runtime используют светлую схему; dark theme не заявлена как поддерживаемая.
 
 ## Тема и токены
 
-[`theme.ts`](../../frontend/src/shared/theme/theme.ts) сохраняет фирменную синюю
+[`tokens.json`](../../frontend/src/shared/theme/tokens.json) — единственный
-палитру 0–9, системный sans-serif и default radius md. Именованные шкалы
+редактируемый источник опубликованных токенов WealthLedger. Он содержит восемь
-fontSizes, fontWeights, lineHeights, headings, spacing, radius, shadows,
+палитр по десять оттенков: blue, gray, dark, red, green, yellow, grape и orange;
-breakpoints и monospace явно принимаются из `DEFAULT_THEME` Mantine 9.5.1.
+базовые white/black, оттенки по умолчанию, семантические роли с описаниями,
-Числовой дубликат шкал не хранится. Font family заголовков совпадает с общей.
+типографику, интервалы, радиусы, тени и breakpoints. Существующие значения
+приняты из темы приложения и Mantine 9.5.1; теперь ими владеет JSON. Default
+radius остаётся md, font family заголовков совпадает с общей.
+
+[`theme.ts`](../../frontend/src/shared/theme/theme.ts) проверяет source через
+установленный Zod и [`tokens.schema.ts`](../../frontend/src/shared/theme/tokens.schema.ts),
+затем адаптирует данные в Mantine. Схема проверяет структуру, единицы и диапазоны,
+число оттенков и ссылки ролей; ошибочные данные не подменяются defaults.
+Размеры px преобразуются native `rem`, сохраняя `--mantine-scale`, тени собираются
+из слоёв с `rgba`, а breakpoints остаются em без масштабирования. Неопубликованные
+палитры и настройки поведения компонентов остаются defaults Mantine.
 
 Используйте props Mantine (`gap="md"`, `p="xl"`, `radius="md"`, `shadow="xs"`)
 или `--mantine-spacing-*`, `--mantine-radius-*` и другие native CSS variables.
 [Foundations](http://localhost:6006/?path=/story/design-system-foundations--colors)
-читает эффективную тему, показывает фактические значения и образцы. Обновление
+читает эффективную тему и описания из JSON, показывает фактические значения
-Mantine требует повторной проверки шкал и внешнего вида приложения.
+и образцы. Обновление Mantine не заменяет принятые шкалы автоматически и требует
+повторной проверки адаптера и внешнего вида приложения.
 
 `colorRoles` связывает смысл и native Mantine reference; resolver создаёт
 `--wl-color-<role>`, ссылающийся на Mantine variable, без повторного hex-значения.
@@ -42,13 +53,54 @@ Mantine требует повторной проверки шкал и внеш
 постепенного использования; существующие локальные Mantine references не
 переписаны массово. Цвет не заменяет подпись статуса. Палитра не гарантирует
 доступный контраст произвольных сочетаний: для текста и фона проверяйте контекст.
-Grape остаётся дополнительной палитрой графиков; предметные значения задаёт Product.
+Grape и orange используются Product; предметные значения задают их FSD-владельцы.
 
 Особые card gradients/shadows, размеры страницы и финансовые цвета CSS остаются
 у своих FSD-владельцев. Это сохранение существующего UI, а не завершённый редизайн
 или миграция всех literals в tokens. Новую общую шкалу стоит вводить только при
 реальном повторном использовании, если native Mantine scale не подходит.
 
+## Переносимый JSON
+
+Файл использует собственный формат WealthLedger `formatVersion: 1`, без runtime
+imports, CSS variables или исполняемого кода. Это контракт данных, а не заявление
+о совместимости с DTCG или importer конкретной системы.
+
+| Данные | Представление |
+| --- | --- |
+| Цвета | Hex; palette — массив оттенков 0–9; base — именованные white/black. |
+| Семантическая роль | `color`, `shade`, `description`; ссылка на palette или base. Для palette `shade: null` означает `primaryShade.light`, для base оттенок не нужен. |
+| Типографика | CSS font stacks; размеры и headings в px, веса числовые, line heights без единиц. |
+| Интервалы и радиусы | Именованные `values` xs–xl с `unit: "px"`; `radius.default` выбирает имя шкалы. |
+| Тени | Упорядоченные слои: offsetX/offsetY/blur/spread в px, ссылка `color` на base и opacity 0–1. |
+| Breakpoints | Именованные `values` xs–xl с `unit: "em"`, не зависят от масштаба UI. |
+
+Имена палитр `dimmed` и `bright` зарезервированы адаптером Mantine;
+`white` и `black` принадлежат base colors. Вес шрифта ограничен диапазоном 1–1000.
+
+Внешний потребитель читает raw JSON напрямую. Например, из workspace root,
+без Node, React или Mantine:
+
+```python
+import json
+from pathlib import Path
+
+tokens = json.loads(Path("frontend/src/shared/theme/tokens.json").read_text())
+assert tokens["formatVersion"] == 1
+colors = tokens["color"]
+role = colors["roles"]["primary"]
+shade = role["shade"]
+if shade is None:
+    shade = colors["primaryShade"]["light"]
+primary_hex = colors["palettes"][role["color"]][shade]
+```
+
+`shared/theme/index.ts` предназначен для frontend: он подключает CSS и Mantine
+runtime. При интеграции с другой системой сопоставьте единицы, font stacks,
+слои теней и semantic references с её форматом; парсер JSON сам этого не делает.
+Несовместимое изменение требует новой версии контракта. Внешняя интеграция,
+генератор артефактов и публикация пакета пока не реализованы.
+
 ## Общие компоненты
 
 Public API — [`shared/ui`](../../frontend/src/shared/ui/index.ts). Минимальный

development/ui-catalog.md

@@ -32,7 +32,7 @@ npm run preview:catalog
 
 | Блок / группа | Что показывает |
 | --- | --- |
-| `Design System/Foundations` | Цвета и семантические роли, типографику, интервалы, радиусы, тени и breakpoints из действующей темы. |
+| `Design System/Foundations` | Восемь палитр и семантические роли, типографику, интервалы, радиусы, тени и breakpoints из общей темы, адаптированной из tokens.json. |
 | `Design System/Components/StateView` | Четыре empty/error варианта с действием и без. |
 | `Design System/Components/LoadingSkeleton` | Общую доступную busy-область с нейтральными structural shapes. |
 | `Design System/Components/Button` | Прямой Mantine Button: primary, default, subtle, loading, disabled; локальное действие и keyboard interaction. |
@@ -50,10 +50,11 @@ npm run preview:catalog
 
 Каталог не перечисляет весь Mantine или все компоненты приложения. AppShell
 с product navigation не объявлен компонентом общего набора. Отсутствие компонента
-в каталоге не запрещает его использование. Foundations показывает используемые
+в каталоге не запрещает его использование. Foundations показывает опубликованные
-шкалы, включая встроенные Mantine defaults; локальные размеры и особые тени
+шкалы из `shared/theme/tokens.json`, описания ролей и эффективные Mantine значения.
-не объявляются глобальными токенами. [Дизайн-система](design-system.md) описывает
+Локальные размеры и особые тени не объявляются глобальными токенами;
-ownership и правила расширения.
+неопубликованные defaults остаются у Mantine. [Дизайн-система](design-system.md)
+описывает JSON-формат, внешнее чтение, ownership и правила расширения.
 
 Выберите историю в дереве, чтобы открыть её состояние в Canvas. Docs описывает
 назначение, ограничения и свойства группы, а также её примеры. Controls меняют
@@ -71,7 +72,8 @@ Preview и приложение используют один public API `shared
 CSSVariablesResolver и базовые styles вместе с Mantine CSS. Preview использует
 русскую i18n и фиксированную светлую схему без чтения сохранённой темы.
 Stories находятся рядом с существующими presentation components и импортируют
-их реализации. Токены и их семантические роли принадлежат shared/theme. Error StateView сохраняет alert semantics,
+их реализации. Токены и описания их семантических ролей принадлежат
+`shared/theme/tokens.json`; preview не хранит их копию. Error StateView сохраняет alert semantics,
 skeleton — busy-область с декоративными фигурами без фокуса. Проверяйте доступность
 действий и ссылок с клавиатуры вместе с визуальным состоянием.