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) сохраняет фирменную синюю
-палитру 0–9, системный sans-serif и default radius md. Именованные шкалы
-fontSizes, fontWeights, lineHeights, headings, spacing, radius, shadows,
-breakpoints и monospace явно принимаются из `DEFAULT_THEME` Mantine 9.5.1.
-Числовой дубликат шкал не хранится. Font family заголовков совпадает с общей.
+[`tokens.json`](../../frontend/src/shared/theme/tokens.json) — единственный
+редактируемый источник опубликованных токенов WealthLedger. Он содержит восемь
+палитр по десять оттенков: blue, gray, dark, red, green, yellow, grape и orange;
+базовые white/black, оттенки по умолчанию, семантические роли с описаниями,
+типографику, интервалы, радиусы, тени и 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)
-читает эффективную тему, показывает фактические значения и образцы. Обновление
-Mantine требует повторной проверки шкал и внешнего вида приложения.
+читает эффективную тему и описания из JSON, показывает фактические значения
+и образцы. Обновление 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). Минимальный