@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.46.0-beta

package/bundle/components/TabsExtended.md

@@ -3,16 +3,16 @@ component: TabsExtended
 category: Tabs
 related: [Tabs, TabsLine, Badge, Text]
 tokens:
-  - --triplex-next-Tabs-Type1_Background
-  - --triplex-next-Tabs-Type2_Background
-  - --triplex-next-Tabs-Type1_Tab_Background_Default
-  - --triplex-next-Tabs-Type2_Tab_Background_Default
-  - --triplex-next-Tabs-Type1_Tab_Background_Hover
-  - --triplex-next-Tabs-Type2_Tab_Background_Hover
-  - --triplex-next-Tabs-Type1_Tab_Background_Selected
-  - --triplex-next-Tabs-Type2_Tab_Background_Selected
-  - --triplex-next-Tabs-Tab_BorderColor_Default
-  - --triplex-next-Tabs-Tab_BorderColor_Focus
+  - Tabs.Type1_Background
+  - Tabs.Type2_Background
+  - Tabs.Type1_Tab_Background_Default
+  - Tabs.Type2_Tab_Background_Default
+  - Tabs.Type1_Tab_Background_Hover
+  - Tabs.Type2_Tab_Background_Hover
+  - Tabs.Type1_Tab_Background_Selected
+  - Tabs.Type2_Tab_Background_Selected
+  - Tabs.Tab_BorderColor_Default
+  - Tabs.Tab_BorderColor_Focus
 stories: stories/TabsExtended/TabsExtended.stories.tsx
 version: "1.0"
 ---
@@ -88,22 +88,25 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Tabs.ts`.
+
 Компонент использует токены семейства `Tabs` — они общие с `Tabs`:
 
 ```text
---triplex-next-Tabs-Type1_Background
---triplex-next-Tabs-Type2_Background
---triplex-next-Tabs-Type1_Tab_Background_Default
---triplex-next-Tabs-Type2_Tab_Background_Default
---triplex-next-Tabs-Type1_Tab_Background_Hover
---triplex-next-Tabs-Type2_Tab_Background_Hover
---triplex-next-Tabs-Type1_Tab_Background_Selected
---triplex-next-Tabs-Type2_Tab_Background_Selected
---triplex-next-Tabs-Tab_BorderColor_Default
---triplex-next-Tabs-Tab_BorderColor_Focus
+Tabs.Type1_Background
+Tabs.Type2_Background
+Tabs.Type1_Tab_Background_Default
+Tabs.Type2_Tab_Background_Default
+Tabs.Type1_Tab_Background_Hover
+Tabs.Type2_Tab_Background_Hover
+Tabs.Type1_Tab_Background_Selected
+Tabs.Type2_Tab_Background_Selected
+Tabs.Tab_BorderColor_Default
+Tabs.Tab_BorderColor_Focus
 ```
 
-Собственного префикса `--triplex-next-TabsExtended-*` у компонента нет: переименование токенов `Tabs` ломает оба компонента сразу.
+Собственной группы токенов `TabsExtended` нет: переименование токенов группы `Tabs` ломает оба компонента сразу.
 
 ---
 

package/bundle/components/Tag.md

@@ -2,7 +2,8 @@
 component: Tag
 category: Tag
 related: [TagGroup, TagColor, ButtonIcon, Text]
-tokens: [--triplex-next-Tag-Background]
+tokens:
+  - Tag.Background
 stories: stories/Tag/Tag.stories.tsx
 version: "1.0"
 ---
@@ -64,8 +65,11 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Tag.ts`.
+
 ```text
---triplex-next-Tag-Background
+Tag.Background
 ```
 
 Единственный собственный токен — фон плашки. Цвет текста задаёт `Text` через токены типографики

package/bundle/components/Text.md

@@ -3,28 +3,28 @@ component: Text
 category: Typography
 related: [Title, Caption, CodeText]
 tokens:
-  - --triplex-next-Typography-Primary_Color
-  - --triplex-next-Typography-PrimaryInvert_Color
-  - --triplex-next-Typography-Complementary_Color
-  - --triplex-next-Typography-ComplementaryInvert_Color
-  - --triplex-next-Typography-Secondary_Color
-  - --triplex-next-Typography-SecondaryInvert_Color
-  - --triplex-next-Typography-Tertiary_Color
-  - --triplex-next-Typography-TertiaryInvert_Color
-  - --triplex-next-Typography-Disabled_Color
-  - --triplex-next-Typography-DisabledInvert_Color
-  - --triplex-next-Typography-Brand_Color
-  - --triplex-next-Typography-BrandInvert_Color
-  - --triplex-next-Typography-Info_Color
-  - --triplex-next-Typography-InfoInvert_Color
-  - --triplex-next-Typography-Success_Color
-  - --triplex-next-Typography-SuccessInvert_Color
-  - --triplex-next-Typography-Warning_Color
-  - --triplex-next-Typography-WarningInvert_Color
-  - --triplex-next-Typography-Error_Color
-  - --triplex-next-Typography-ErrorInvert_Color
-  - --triplex-next-Typography-System_Color
-  - --triplex-next-Typography-SystemInvert_Color
+  - Typography.Primary_Color
+  - Typography.PrimaryInvert_Color
+  - Typography.Complementary_Color
+  - Typography.ComplementaryInvert_Color
+  - Typography.Secondary_Color
+  - Typography.SecondaryInvert_Color
+  - Typography.Tertiary_Color
+  - Typography.TertiaryInvert_Color
+  - Typography.Disabled_Color
+  - Typography.DisabledInvert_Color
+  - Typography.Brand_Color
+  - Typography.BrandInvert_Color
+  - Typography.Info_Color
+  - Typography.InfoInvert_Color
+  - Typography.Success_Color
+  - Typography.SuccessInvert_Color
+  - Typography.Warning_Color
+  - Typography.WarningInvert_Color
+  - Typography.Error_Color
+  - Typography.ErrorInvert_Color
+  - Typography.System_Color
+  - Typography.SystemInvert_Color
 stories: stories/Typography/Text.stories.tsx
 version: "1.0"
 ---
@@ -74,11 +74,14 @@ version: "1.0"
 
 ## Дизайн-токены
 
-Цвета — только через CSS-переменные группы Typography (общие для всего семейства, см. frontmatter):
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Typography.ts`.
+
+Цвета — только через токены группы `Typography` (общие для всего семейства, см. frontmatter):
 
 ```text
---triplex-next-Typography-{Type}_Color
---triplex-next-Typography-{Type}Invert_Color
+Typography.{Type}_Color
+Typography.{Type}Invert_Color
 ```
 
 где `{Type}` ∈ Primary, Complementary, Secondary, Tertiary, Disabled, Brand, Info, Success, Warning, Error, System.

package/bundle/components/TextField.md

@@ -54,7 +54,7 @@ version: "1.0"
 
 ## Дизайн-токены
 
-Собственных CSS-токенов и стилей нет. Внешний вид полностью наследуется от семейства `FormField` (токены `--triplex-next-FormField-*` описаны в стилях `src/components/FormField/styles/`).
+Собственных токенов и стилей нет. Внешний вид полностью наследуется от семейства `FormField` (группа токенов `FormField`, стили — `src/components/FormField/styles/`).
 
 ---
 
@@ -62,7 +62,7 @@ version: "1.0"
 
 - `forwardRef` на `TextField` и `TextFieldBase` — не убирать. Внешний `ref` указывает на корневой `<div>` `FormField`; ref на сам input — только через `inputProps.ref`.
 - Публичный API (`ITextFieldProps`: `inputProps` + `label`/`prefix`/`postfix`/`description`/`counter` + унаследованные `size`/`status`/`active`) — изменение имён/типов/значений enum — breaking change.
-- Barrel `index.ts` экспортирует `TextField` и `MaskedField` — состав экспортов не менять. `TextFieldBase` намеренно НЕ экспортируется — приватная база.
+- `TextFieldBase` намеренно НЕ экспортируется — приватная база.
 - Известное ограничение контракта: `inputProps.ref` типизирован как `React.RefObject<HTMLInputElement>` (не `React.Ref`), callback-ref формально не проходит по типам. Исправление — breaking change, требует отдельной задачи.
 - Уникальный `id` для связки label↔input генерируется через `lodash uniqueId` в `FormFieldInput` — не заменять на `useId` (React 17 совместимость через release-0).
 - `description || counter` рендерятся в общем блоке `FormFieldDescription` — не разносить по отдельным блокам (изменит DOM и скриншоты).
@@ -80,8 +80,7 @@ version: "1.0"
 
 ## Связанные компоненты
 
-- `TextFieldBase` (внутренний, не в barrel) — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`. На нём построены `TextField` и `MaskedField`. Описан здесь, отдельного AI.md не имеет.
-- `MaskedField` — сосед по папке: то же самое, но с `FormFieldMaskedInput` (ввод по маске) через prop `maskedInputProps`. Документируется отдельно.
+- `TextFieldBase` (внутренний, не в barrel) — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`. Описан здесь, отдельного AI.md не имеет.
 - `FormField` / `FormFieldInput` и слоты семейства — низкоуровневые строительные блоки; используются напрямую, когда нужна нестандартная композиция.
 - `FormGroup` — контейнер вертикальной раскладки поля и описания.
 - `FormFieldClear` — кнопка очистки, передаётся в `postfix`.

package/bundle/components/ThemeProvider.md

@@ -65,7 +65,55 @@ version: "1.0"
 ```
 
 Версия в имени переменной — версия пакета с точками, заменёнными на дефисы
-(см. `DesignTokenUtils.getCSSVariableByTokenGroup`).
+(см. `DesignTokenUtils.getCSSVariableByTokenGroup`). Из-за версии эти имена нельзя
+использовать в коде потребителя — они меняются каждый релиз. Публичный способ
+поменять оформление — prop `tokens`.
+
+### Как переопределять токены
+
+Путь токена — `{Группа}.{Токен}`. Объект `tokens` плоский: группы лежат на верхнем
+уровне, вложенности `core` / `components` в API нет.
+
+```tsx
+import {useRef} from "react";
+import {ThemeProvider, ETriplexNextTheme} from "@sberbusiness/triplex-next";
+
+// tokens сравнивается по ссылке — объект вынесен из рендера, иначе <style> пересобирается
+// на каждый рендер.
+const TOKENS = {
+    // core-токен: палитра, меняется сразу для всех компонентов, которые на неё ссылаются
+    ColorBrand: {50: {value: "#1D6BF3"}},
+    // компонентный токен: значением или ссылкой на core-токен
+    Calendar: {
+        Background: {value: "#FFFFFF"},
+        View_Item_Background_Selected_Default: {ref: "ColorBrand.50"},
+    },
+};
+
+const App = () => {
+    const scopeRef = useRef<HTMLDivElement>(null);
+
+    return (
+        <ThemeProvider theme={ETriplexNextTheme.LIGHT} tokens={TOKENS} scopeRef={scopeRef}>
+            <div ref={scopeRef}>…</div>
+        </ThemeProvider>
+    );
+};
+```
+
+Правила:
+
+- значение задаётся либо `{value: "<css>"}`, либо `{ref: "<Группа>.<Токен>"}`;
+- `ref` указывает **только на core-токен**: тип ссылок генерируется из `DesignTokensCore`
+  (`scripts/generateRefTokensTypes.ts`), ссылка на компонентный токен не скомпилируется;
+- одним объектом можно переопределить сколько угодно групп — и core, и компонентные;
+- переопределения мерджатся поверх токенов темы (`defaultsDeep`), тема при этом
+  продолжает действовать: то, что не переопределено, берётся из неё;
+- действуют внутри `scopeRef`; вложенные `ThemeProvider` переопределяют друг друга.
+
+Где смотреть значения по умолчанию: `src/components/DesignTokens/DesignTokensCore.ts`
+(палитра) и `src/components/DesignTokens/components/{Группа}.ts` (пара «светлая /
+тёмная тема» для каждого компонентного токена).
 
 ---
 
@@ -145,6 +193,7 @@ version: "1.0"
 |---|---|
 | 2026-08-05 | Создан документ. AI-рефакторинг: JSDoc на props и экспортах, ключ тега стилей вынесен в хелпер, упрощён эффект `ThemeProviderView`, добавлены unit-тесты `ThemeProviderView` и `useToken`, stories переведены на modern pattern |
 | 2026-08-05 | `related` сокращён до `useToken`. Удалён неактуальный комментарий про относительный импорт в `ThemeProviderView` |
+| 2026-08-31 | Добавлен раздел «Как переопределять токены»: путь `{Группа}.{Токен}`, плоская форма prop `tokens`, `value` / `ref` |
 
 ---
 

package/bundle/components/Title.md

@@ -3,28 +3,28 @@ component: Title
 category: Typography
 related: [Text, Caption, CodeText]
 tokens:
-  - --triplex-next-Typography-Primary_Color
-  - --triplex-next-Typography-PrimaryInvert_Color
-  - --triplex-next-Typography-Complementary_Color
-  - --triplex-next-Typography-ComplementaryInvert_Color
-  - --triplex-next-Typography-Secondary_Color
-  - --triplex-next-Typography-SecondaryInvert_Color
-  - --triplex-next-Typography-Tertiary_Color
-  - --triplex-next-Typography-TertiaryInvert_Color
-  - --triplex-next-Typography-Disabled_Color
-  - --triplex-next-Typography-DisabledInvert_Color
-  - --triplex-next-Typography-Brand_Color
-  - --triplex-next-Typography-BrandInvert_Color
-  - --triplex-next-Typography-Info_Color
-  - --triplex-next-Typography-InfoInvert_Color
-  - --triplex-next-Typography-Success_Color
-  - --triplex-next-Typography-SuccessInvert_Color
-  - --triplex-next-Typography-Warning_Color
-  - --triplex-next-Typography-WarningInvert_Color
-  - --triplex-next-Typography-Error_Color
-  - --triplex-next-Typography-ErrorInvert_Color
-  - --triplex-next-Typography-System_Color
-  - --triplex-next-Typography-SystemInvert_Color
+  - Typography.Primary_Color
+  - Typography.PrimaryInvert_Color
+  - Typography.Complementary_Color
+  - Typography.ComplementaryInvert_Color
+  - Typography.Secondary_Color
+  - Typography.SecondaryInvert_Color
+  - Typography.Tertiary_Color
+  - Typography.TertiaryInvert_Color
+  - Typography.Disabled_Color
+  - Typography.DisabledInvert_Color
+  - Typography.Brand_Color
+  - Typography.BrandInvert_Color
+  - Typography.Info_Color
+  - Typography.InfoInvert_Color
+  - Typography.Success_Color
+  - Typography.SuccessInvert_Color
+  - Typography.Warning_Color
+  - Typography.WarningInvert_Color
+  - Typography.Error_Color
+  - Typography.ErrorInvert_Color
+  - Typography.System_Color
+  - Typography.SystemInvert_Color
 stories: stories/Typography/Title.stories.tsx
 version: "1.0"
 ---
@@ -73,7 +73,10 @@ version: "1.0"
 
 ## Дизайн-токены
 
-Цвета — общие CSS-переменные семейства Typography (см. frontmatter): `--triplex-next-Typography-{Type}_Color` и `--triplex-next-Typography-{Type}Invert_Color`.
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Typography.ts`.
+
+Цвета — общие токены группы `Typography` (см. frontmatter): `Typography.{Type}_Color` и `Typography.{Type}Invert_Color`.
 
 Размеры шрифта и line-height — фиксированные пиксельные значения в `styles/Title.module.less` (токенов для них нет).
 

package/bundle/components/Tooltip.md

@@ -3,16 +3,16 @@ component: Tooltip
 category: Tooltip
 related: [HelpBox, SMSField, Dropdown, DropdownMobile, Portal, MobileView, ThemeProvider, ButtonIcon]
 tokens:
-  - --triplex-next-Tooltip-Background
-  - --triplex-next-Tooltip-Color
-  - --triplex-next-Tooltip-Link_Desktop_Color_Default
-  - --triplex-next-Tooltip-Link_Desktop_Color_Hover
-  - --triplex-next-Tooltip-Link_Desktop_Color_Active
-  - --triplex-next-Tooltip-Link_Desktop_Shadow_Focus
-  - --triplex-next-Tooltip-Link_Mobile_Color_Default
-  - --triplex-next-Tooltip-Link_Mobile_Color_Hover
-  - --triplex-next-Tooltip-Link_Mobile_Color_Active
-  - --triplex-next-Tooltip-Link_Mobile_Shadow_Focus
+  - Tooltip.Background
+  - Tooltip.Color
+  - Tooltip.Link_Desktop_Color_Default
+  - Tooltip.Link_Desktop_Color_Hover
+  - Tooltip.Link_Desktop_Color_Active
+  - Tooltip.Link_Desktop_Shadow_Focus
+  - Tooltip.Link_Mobile_Color_Default
+  - Tooltip.Link_Mobile_Color_Hover
+  - Tooltip.Link_Mobile_Color_Active
+  - Tooltip.Link_Mobile_Shadow_Focus
 stories: stories/Tooltip/Tooltip.stories.tsx
 version: "1.0"
 ---
@@ -85,20 +85,23 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Tooltip.ts`.
+
 ```text
---triplex-next-Tooltip-Background
---triplex-next-Tooltip-Color
---triplex-next-Tooltip-Link_Desktop_Color_Default
---triplex-next-Tooltip-Link_Desktop_Color_Hover
---triplex-next-Tooltip-Link_Desktop_Color_Active
---triplex-next-Tooltip-Link_Desktop_Shadow_Focus
---triplex-next-Tooltip-Link_Mobile_Color_Default
---triplex-next-Tooltip-Link_Mobile_Color_Hover
---triplex-next-Tooltip-Link_Mobile_Color_Active
---triplex-next-Tooltip-Link_Mobile_Shadow_Focus
+Tooltip.Background
+Tooltip.Color
+Tooltip.Link_Desktop_Color_Default
+Tooltip.Link_Desktop_Color_Hover
+Tooltip.Link_Desktop_Color_Active
+Tooltip.Link_Desktop_Shadow_Focus
+Tooltip.Link_Mobile_Color_Default
+Tooltip.Link_Mobile_Color_Hover
+Tooltip.Link_Mobile_Color_Active
+Tooltip.Link_Mobile_Shadow_Focus
 ```
 
-Мобильная версия дополнительно наследует токены `DropdownMobile` (`--triplex-next-DropdownMobile-*`), так как построена на его субкомпонентах.
+Мобильная версия дополнительно наследует токены группы `DropdownMobile`, так как построена на его субкомпонентах.
 
 ---
 

package/bundle/components/TopOverlay.md

@@ -3,7 +3,7 @@ component: TopOverlay
 category: TopOverlay
 related: [LightBox, Overlay]
 tokens:
-  - --triplex-next-TopOverlay-Background
+  - TopOverlay.Background
 stories: stories/TopOverlay/TopOverlay.stories.tsx
 version: "1.0"
 ---
@@ -89,13 +89,16 @@ LESS: `top: var(--triplex-next-runtime-TopOverlay-Top, 0)` — inline-стили
 
 ## Дизайн-токены
 
-```css
---triplex-next-TopOverlay-Background
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/TopOverlay.ts`.
+
+```text
+TopOverlay.Background
 ```
 
 Токен задаёт цвет маски. Панель намеренно рисуется без фона и тени
 (`background: none`, `box-shadow: none`) — фон даёт контент, который в неё кладут
-(обычно `Confirm`), поэтому токен `--triplex-next-Overlay-Panel_Background`
+(обычно `Confirm`), поэтому токен `Overlay.Panel_Background`
 здесь не действует.
 
 Runtime CSS-переменная (задаётся компонентом через `style`, **не** дизайн-токен,

package/bundle/guides/codestyle.md

@@ -135,6 +135,9 @@ import { Button } from "../Button";
 - Имена классов — **camelCase**: `styles.secondaryLight`, `styles.iconOnly`.
 - Никаких **inline styles** в компонентах (в stories допустимо для лейаута примеров).
 - **Цвета** — только через CSS-переменные токенов (`var(--triplex-next-...)`). Никаких hex/rgb.
+  В стилях это правильная запись: CSS-переменные — внутренний слой токенов. А в документации
+  (`*-ai.md`, тексты Storybook) токен указывается путём `{Группа}.{Токен}` — см.
+  `docs/ai/CONTEXT.md` → «Дизайн-токены».
 - Runtime CSS-переменные, которые компонент задаёт сам (например через `style` для динамической высоты,
   transform или координат), называй с префиксом `--triplex-next-runtime-...`.
   Они не являются дизайн-токенами и не должны попадать в `src/components/DesignTokens` или generated-файлы.

package/bundle/guides/context.md

@@ -70,27 +70,99 @@ src/components/Button/
 
 ---
 
-## Дизайн-токены (CSS-переменные)
+## Дизайн-токены
 
-Паттерн именования:
-```
---triplex-next-{Component}-{Variant}_{Property}_{State}
-```
+У токенов два слоя. Не путай их: в документации для потребителя описывается
+только первый.
+
+### Публичный слой — токены в TypeScript
 
-Примеры:
+Источник значений: `src/components/DesignTokens/DesignTokensCore.ts` (палитра,
+10 групп) и `src/components/DesignTokens/components/{Group}.ts` (токены
+компонентов, 56 групп). Путь токена — `{Группа}.{Токен}`:
+
+```text
+ColorBrand.50
+Button.General_Background_Default
+Calendar.View_Item_Background_Selected_Hover
 ```
---triplex-next-Button-General_Background_Default
---triplex-next-Button-General_Color_Hover
---triplex-next-Button-Secondary_Shadow_Focus
---triplex-next-Button-Danger_Background_Disabled
+
+Ровно в этом виде токен переопределяется потребителем через `ThemeProvider`:
+
+```tsx
+// tokens сравнивается по ссылке — объект выносится из рендера.
+const TOKENS = {
+    ColorBrand: {50: {value: "blue"}},
+    Calendar: {Background: {ref: "ColorNeutral.100"}},
+};
+
+<ThemeProvider tokens={TOKENS} scopeRef={scopeRef}>…</ThemeProvider>
 ```
 
+Правила слоя:
+
+- объект токенов **плоский** — группы лежат на верхнем уровне
+  (`TDesignTokens = TDesignTokensCore & TDesignTokensComponents`). Вложенности
+  `core` / `components` в API нет, она есть только в раскладке исходников;
+- значение токена — либо `{value: "<css>"}`, либо `{ref: "<Группа>.<Токен>"}`;
+- `ref` указывает **только на core-токены**: тип `designTokensRefs` генерируется
+  из `DesignTokensCore` (`scripts/generateRefTokensTypes.ts`), ссылка на
+  компонентный токен не скомпилируется;
+- у компонентного токена всегда пара значений — `[светлая, тёмная]` тема;
+- имена core-групп и групп компонентов не должны пересекаться: в одном плоском
+  неймспейсе они схлопнутся. Проверяется гардом в `scripts/syncAiMdTokens.ts`.
+
 **Состояния:** `Default`, `Hover`, `Active`, `Focus`, `Disabled`
 **Свойства:** `Background`, `Color`, `Shadow`, `Border`
 
-Токены генерируются в `src/generated/themesCssVariables.css`. Не редактируй этот файл вручную.
+Если добавляешь новое визуальное состояние — нужен новый токен. Имя токена
+согласуй с дизайнером.
+
+### Внутренний слой — CSS-переменные
+
+В LESS токен читается как css-переменная:
+
+```less
+background: var(--triplex-next-Button-General_Background_Default);
+```
+
+Это внутренняя реализация, а не публичное имя: на сборке
+`scripts/replaceDesignTokenVersion.js` дописывает к переменной версию пакета,
+и в опубликованном коде она выглядит как
+`--triplex-next-{Группа}-{Токен}-{версия}`. Имя меняется каждый релиз, поэтому
+потребитель не может на него опереться.
+
+Отсюда правило: **в стилях библиотеки пиши `var(--triplex-next-...)`, а в
+документации (`*-ai.md`, описания в Storybook) указывай путь токена
+`{Группа}.{Токен}`.** Переименование css-переменной остаётся breaking change —
+её видят потребители, дотянувшиеся до внутреннего слоя.
+
+Полный набор переменных генерируется в `src/generated/themesCssVariables.css`.
+Не редактируй этот файл вручную.
+
+### Токены в AI-документации
+
+Frontmatter `{Component}-ai.md` перечисляет пути токенов:
+
+```yaml
+tokens:
+  - Calendar.Background
+  - Calendar.View_Header_Color
+```
+
+Этот список читает MCP-сервер (`get_tokens`), поэтому формат обязателен.
+Проверяется и нормализуется скриптом:
+
+```bash
+npm run syncAiMdTokens            # нормализовать блоки tokens:
+npm run syncAiMdTokens -- --check # проверить, ничего не записывая
+npm run syncAiMdTokens -- --check src/components/Badge/Badge-ai.md # только эти файлы
+```
 
-Если добавляешь новое визуальное состояние — нужен новый токен. Имя токена согласуй с дизайнером.
+Скрипт не определяет состав токенов за автора (в одной директории живёт
+несколько компонентов с разными наборами) — он нормализует и проверяет то, что
+перечислено, а расхождения с LESS показывает предупреждениями. Файл, по которому
+нашлись ошибки, скрипт не переписывает — чинит автор.
 
 ---