docs: describe direct local token adaptation

development/design-system.md

@@ -17,13 +17,15 @@
 приняты из темы приложения и Mantine 9.5.1; теперь ими владеет JSON. Default
 radius остаётся md, font family заголовков совпадает с общей.
 
-[`theme.ts`](../../frontend/src/shared/theme/theme.ts) проверяет source через
+[`theme.ts`](../../frontend/src/shared/theme/theme.ts) напрямую адаптирует JSON
-установленный Zod и [`tokens.schema.ts`](../../frontend/src/shared/theme/tokens.schema.ts),
+в Mantine. Файл — доверенная конфигурация репозитория; приложение не загружает
-затем адаптирует данные в Mantine. Схема проверяет структуру, единицы и диапазоны,
+внешние или пользовательские токены и не проверяет JSON runtime-схемой.
-число оттенков и ссылки ролей; ошибочные данные не подменяются defaults.
 Размеры px преобразуются native `rem`, сохраняя `--mantine-scale`, тени собираются
 из слоёв с `rgba`, а breakpoints остаются em без масштабирования. Неопубликованные
 палитры и настройки поведения компонентов остаются defaults Mantine.
+Небольшой [`theme.test.ts`](../../frontend/src/shared/theme/theme.test.ts)
+проверяет преобразования адаптера; корректность изменений локального JSON
+проверяется при review, сборке и проверке внешнего вида.
 
 Используйте props Mantine (`gap="md"`, `p="xl"`, `radius="md"`, `shadow="xs"`)
 или `--mantine-spacing-*`, `--mantine-radius-*` и другие native CSS variables.
@@ -75,8 +77,9 @@ imports, CSS variables или исполняемого кода. Это конт
 | Тени | Упорядоченные слои: offsetX/offsetY/blur/spread в px, ссылка `color` на base и opacity 0–1. |
 | Breakpoints | Именованные `values` xs–xl с `unit: "em"`, не зависят от масштаба UI. |
 
-Имена палитр `dimmed` и `bright` зарезервированы адаптером Mantine;
+Не используйте для палитр специальные имена Mantine `dimmed` и `bright`;
-`white` и `black` принадлежат base colors. Вес шрифта ограничен диапазоном 1–1000.
+`white` и `black` принадлежат base colors. Задавайте вес шрифта в диапазоне
+CSS 1–1000. Это правила редактирования формата, а не runtime-проверки.
 
 Внешний потребитель читает raw JSON напрямую. Например, из workspace root,
 без Node, React или Mantine:

development/ui-catalog.md

@@ -73,7 +73,8 @@ CSSVariablesResolver и базовые styles вместе с Mantine CSS. Previ
 русскую i18n и фиксированную светлую схему без чтения сохранённой темы.
 Stories находятся рядом с существующими presentation components и импортируют
 их реализации. Токены и описания их семантических ролей принадлежат
-`shared/theme/tokens.json`; preview не хранит их копию. Error StateView сохраняет alert semantics,
+`shared/theme/tokens.json`; `theme.ts` напрямую адаптирует этот локальный файл
+в Mantine, preview не хранит копию токенов. Error StateView сохраняет alert semantics,
 skeleton — busy-область с декоративными фигурами без фокуса. Проверяйте доступность
 действий и ссылок с клавиатуры вместе с визуальным состоянием.