docs: describe portable design token contract

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 показывает используемые
-шкалы, включая встроенные Mantine defaults; локальные размеры и особые тени
-не объявляются глобальными токенами. [Дизайн-система](design-system.md) описывает
-ownership и правила расширения.
+в каталоге не запрещает его использование. Foundations показывает опубликованные
+шкалы из `shared/theme/tokens.json`, описания ролей и эффективные Mantine значения.
+Локальные размеры и особые тени не объявляются глобальными токенами;
+неопубликованные 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-область с декоративными фигурами без фокуса. Проверяйте доступность
 действий и ссылок с клавиатуры вместе с визуальным состоянием.