@sberbusiness/triplex-next-mcp-server 1.43.0-beta → 1.45.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

@@ -1,10 +1,9 @@
 ---
 component: Tag
-category: Data Display
-figma-node: ""
-figma-file: ""
-related: [TagColor, TagGroup, ButtonIcon]
-tokens: []
+category: Tag
+related: [TagGroup, TagColor, ButtonIcon, Text]
+tokens:
+  - Tag.Background
 stories: stories/Tag/Tag.stories.tsx
 version: "1.0"
 ---
@@ -13,118 +12,153 @@ version: "1.0"
 
 ## Назначение
 
-Тег для отображения выбранного значения параметра (фильтра/категории).
-Структура: `<span>` с `Text` контентом + опциональная кнопка редактирования
-(`ButtonIcon` с edit-иконкой) + всегда кнопка удаления (`ButtonIcon` с
-cross-иконкой). Иконки масштабируются по `size` (16/20/24).
+Тег — компактная плашка с выбранным значением параметра и кнопками управления им: удалением
+и, опционально, редактированием. Типичное место — строка применённых фильтров или список выбранных
+в форме значений, где пользователь должен видеть выбор и уметь его снять.
 
-Используй когда: нужно показать выбранное значение со встроенной возможностью
-удалить или редактировать. Для цветной маркировки (categorical labels) —
-`TagColor`. Для управления коллекцией тегов — `TagGroup`.
+Используй когда: значение выбрано пользователем и его нужно показать вместе с возможностью убрать
+или изменить.
+Не используй когда: нужна неинтерактивная цветная метка статуса — это `TagColor`, у него нет кнопок,
+но есть `status`. Нужен интерактивный элемент выбора фильтра (открывает выпадающий список,
+хранит выбор) — это семейство `Chip`.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/Tag/
-├── Tag.tsx          # forwardRef<HTMLSpanElement, ITagProps>
-├── types.ts         # ITagProps
-├── styles/Tag.module.less
-├── __tests__/
-└── index.ts
-```
+### Обязательные props
 
----
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Идентификатор тега. Рендерится атрибутом `id` на корневом `<span>` и уходит аргументом в `onEdit` и `onRemove` — по нему потребитель понимает, какой тег группы изменили. Значение должно быть уникальным в пределах документа |
+| `size` | `EComponentSize` | Размер: SM (высота 20px) / MD (28px) / LG (32px). Задаёт высоту, внутренние отступы, размер текста (`ETextSize.B4` / `B3` / `B2`) и размер иконок (16 / 20 / 24) |
 
-## Публичный API
+### Опциональные props
 
-### `ITagProps`
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Контент тега. Рендерится внутри `Text`, длинный текст обрезается многоточием |
+| `disabled` | `boolean` | `false` | Текст переключается на `EFontType.DISABLED`, обе кнопки получают `disabled` — но своё значение в `editButtonProps` / `removeButtonProps` его перекрывает |
+| `onEdit` | `(id: string) => void` | — | Колбэк редактирования. **Управляет наличием кнопки редактирования** — без него кнопка не рендерится |
+| `onRemove` | `(id: string) => void` | — | Колбэк удаления. На наличие кнопки удаления НЕ влияет — она рендерится всегда |
+| `editButtonProps` | `IButtonIconProps` | — | Props кнопки редактирования. Здесь потребитель задаёт `aria-label` |
+| `removeButtonProps` | `IButtonIconProps` | — | Props кнопки удаления. Здесь потребитель задаёт `aria-label` |
 
-```ts
-extends HTMLAttributes<HTMLSpanElement>
-```
+Остальные props — стандартные атрибуты `span` (`ITagProps extends React.HTMLAttributes<HTMLSpanElement>`),
+уходят на корневой элемент через `...restProps`.
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `id` | `string` | — | Уникальный id; передаётся в `onEdit(id)` / `onRemove(id)`. |
-| `size` | `EComponentSize` | — | **Обязателен** (нет default'а). Маппится на размер иконки и текста. |
-| `disabled?` | `boolean` | — | Disabled-состояние; влияет на цвет текста (`EFontType.DISABLED`) и `disabled` обеих кнопок. |
-| `onEdit?` | `(id: string) => void` | — | Если передан — рендерится edit-кнопка. |
-| `onRemove?` | `(id: string) => void` | — | Колбэк удаления; **remove-кнопка рендерится всегда**. |
-| `editButtonProps?` | `IButtonIconProps` | — | HTML/aria-атрибуты для edit-кнопки (объединяется с `onClick`). |
-| `removeButtonProps?` | `IButtonIconProps` | — | HTML/aria-атрибуты для remove-кнопки. |
-| `children` | `ReactNode` | — | Содержимое (текст тега). |
-| `...HTMLAttributes<HTMLSpanElement>` | — | — | На корневой `<span>`. |
-
-### Размер → иконка/текст
-
-| `size` | Edit/Remove иконка | Text size |
-|---|---|---|
-| `SM` | `*StrokeSrvIcon16` | `B4` |
-| `MD` | `*StrokeSrvIcon20` | `B3` |
-| `LG` | `*StrokeSrvIcon24` | `B2` |
+### Асимметрия кнопок
 
-Иконки — `paletteIndex={5}` (приглушённая палитра).
+Две кнопки живут по разным правилам, и это легко перепутать:
 
----
+- кнопка **редактирования** рендерится только при переданном `onEdit`;
+- кнопка **удаления** рендерится всегда, даже без `onRemove` — тогда клик по ней просто ничего
+  не делает.
 
-## Поведение
+### Порядок обработчиков клика
 
-### Edit-кнопка
+`onClick` внутри `editButtonProps` / `removeButtonProps` не заменяет `onEdit` / `onRemove`,
+а вызывается **после** него: компонент вынимает `onClick` из этих props и вешает на кнопку
+собственный обработчик, который сначала зовёт колбэк тега, потом пользовательский `onClick`.
 
-- Рендерится **только** если передан `onEdit`.
-- `onClick` объединяет `onEdit(id)` + `editButtonProps.onClick(event)`.
+---
 
-### Remove-кнопка
+## Дизайн-токены
 
-- Рендерится **всегда** (даже без `onRemove`).
-- `onClick` вызывает `onRemove?.(id)` (опционально) + `removeButtonProps.onClick(event)`.
-- Если `onRemove` не передан — кнопка остаётся видимой, но клик ничего не делает (кроме `removeButtonProps.onClick`).
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Tag.ts`.
 
-### Disabled
+```text
+Tag.Background
+```
 
-- `Text type = DISABLED`.
-- `ButtonIcon disabled` — обе кнопки.
+Единственный собственный токен — фон плашки. Цвет текста задаёт `Text` через токены типографики
+(`Typography-Primary_Color` / `Typography-Disabled_Color`), цвет иконок — палитра
+`@sberbusiness/icons-next` (`paletteIndex={5}`), кольцо фокуса кнопок — `ButtonIcon`
+(`Button-Icon_Shadow_Focus`).
+
+Размерные значения (высоты 20/28/32px, отступы, `border-radius: 4px`, `gap: 2px`) заданы литералами
+в `styles/Tag.module.less` — они специфичны для компонента.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef<HTMLSpanElement>`** — не убирать.
-- **`size` обязателен** — нет default'а; передавать всегда.
-- **Remove-кнопка всегда в DOM** — даже без `onRemove`. Если нужно скрыть — `display:none` через `removeButtonProps.style` (или собственная обёртка); поведение `Tag` это не поддерживает напрямую.
-- **`onEdit` определяет видимость edit-кнопки** — единственный механизм. `editButtonProps` без `onEdit` не отрендерит кнопку.
-- **`id` прокидывается ТОЛЬКО в колбэки** (`onEdit`/`onRemove`), не в DOM. Если нужен HTML id — через `restProps`.
-- **Иконки `paletteIndex={5}`** — намеренно. Менять только координированно с дизайн-системой.
-- **`Text` size маппится через `sizeToTextSizeMap`**, иконки — через `sizeTo{Edit,Remove}IconMap`. Все три должны обновляться синхронно при добавлении нового размера.
-- **Корень — `<span>`**, не `<div>` — чтобы тег был inline-friendly.
+- `forwardRef<HTMLSpanElement>` — не убирать. Ref всегда указывает на корневой `<span>`.
+- Корневой элемент — `<span>` (тег инлайновый, встаёт в строку текста и в `TagGroup`).
+  Менять на `div` нельзя.
+- `displayName` — `"Tag"`. Не менять.
+- `id` рендерится атрибутом на корневом `<span>` и одновременно служит бизнес-идентификатором
+  в `onEdit` / `onRemove`. Prop обязательный, поэтому идентификатор попадает в DOM у всех
+  потребителей: значение должно быть уникальным в пределах документа. Если бизнес-идентификатор
+  уже используется другим элементом страницы (типовой случай — тег выбранного значения и опция
+  списка в `MultiselectField`), тегу нужен свой префикс.
+- Кнопка удаления рендерится безусловно, вне зависимости от `onRemove` — менять на условный
+  рендер нельзя без согласования, это изменит вёрстку у потребителей, не передающих `onRemove`.
+- Порядок в DOM: текст → кнопка редактирования → кнопка удаления. Он же задаёт порядок фокуса,
+  на него опираются скриншот-тесты.
+- Собственный `onClick` тега на кнопках всегда вызывается раньше пользовательского
+  `onClick` из `*ButtonProps`.
+- Компонент не хардкодит текстовые строки: `aria-label` / `title` кнопок задаёт потребитель.
+  Библиотека мультиязычная.
+- Экспорты `Tag` и `ITagProps` идут в barrel `src/components/Tag/index.ts` — сохранять.
+- Ширина ограничена контейнером (`max-width: 100%`), текст обрезается многоточием
+  (`.content` с `overflow: hidden`, `text-overflow: ellipsis`, `min-width: 0`) — часть
+  визуального контракта, покрыта stories `WithOverflow` и `VisualTests`.
 
 ---
 
 ## Accessibility
 
-- Корневой `<span>` без явной ARIA-роли — потребитель должен задать смысл через `aria-label` или родительский контекст (`TagGroup`).
-- Edit/Remove кнопки — `<button>` через `ButtonIcon`; добавлять `aria-label` через `editButtonProps`/`removeButtonProps` (например, `aria-label="Удалить тег Москва"`).
-- `disabled` отключает кнопки (`aria-disabled` + `disabled` атрибут от `ButtonIcon`).
-- Иконки декоративные — содержание описывается через `aria-label` кнопки.
+- Собственной ARIA-роли у тега нет: корневой `<span>` — контейнер. Роль группы задаёт `TagGroup`
+  (`role="group"`).
+- Кнопки — `ButtonIcon` без текстового контента, поэтому **доступное имя обязан задать
+  потребитель**: `editButtonProps={{ "aria-label": "..." }}` и
+  `removeButtonProps={{ "aria-label": "..." }}`. Без них кнопки остаются безымянными
+  для скринридера. Компонент не подставляет умолчание намеренно — строки на конкретном языке
+  внутри библиотеки запрещены.
+- Клавиатура: собственных обработчиков у тега нет, работает нативная семантика `<button>`
+  (Tab / Enter / Space). Порядок фокуса совпадает с порядком в DOM: сначала редактирование,
+  затем удаление.
+- Кольцо фокуса рисует `ButtonIcon` через `:focus-visible`, то есть только при переходе
+  с клавиатуры.
+- При `disabled` обе кнопки получают нативный `disabled` и выпадают из порядка фокуса,
+  колбэки не вызываются. `disabled` спредится до `editButtonProps` / `removeButtonProps`,
+  поэтому собственное значение в них перекрывает состояние тега — в отличие от `onClick`,
+  который тег вынимает из props принудительно.
 
 ---
 
 ## Связанные компоненты
 
-- `TagColor` — категориальные цветные теги (без edit/remove).
-- `TagGroup` — контейнер для коллекции тегов (с overflow).
-- `ButtonIcon` — кнопки edit/remove.
-- `Typography.Text` — текст внутри.
-- `@sberbusiness/icons-next` — `EditStrokeSrvIcon{16,20,24}`, `CrossStrokeSrvIcon{16,20,24}`.
+- `TagGroup` — контейнер группы тегов (`role="group"`), задаёт раскладку и переносы;
+  собственный `size` передаётся ему отдельно, теги внутри свой `size` получают сами.
+- `TagColor` — визуально похожая плашка, но неинтерактивная: без кнопок, зато со `status`
+  (`DEFAULT` / `SUCCESS` / `INFO` / `WARNING` / `ERROR`). Берётся, когда нужна метка состояния,
+  а не снимаемое значение.
+- `ButtonIcon` — рендерится внутри как кнопка редактирования и удаления; от него тег получает
+  форму, состояние `disabled` и стили фокуса. Все props из `editButtonProps` / `removeButtonProps`
+  уходят именно на него.
+- `Text` — рендерит контент тега; тег выбирает `size` (`ETextSize`) и `type` (`EFontType`)
+  по своим `size` и `disabled`.
 
 ---
 
 ## Stories
 
 Основные истории: `stories/Tag/Tag.stories.tsx`
-Примеры: `stories/Tag/examples/`
+Файлы примеров: `stories/Tag/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `children`, `size`, `disabled` и наличия кнопки редактирования |
+| `Default` | `Default.tsx` | Минимальный тег: контент и кнопка удаления |
+| `Editable` | `Editable.tsx` | Тег с кнопкой редактирования — появляется вместе с `onEdit` |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Disabled` | `Disabled.tsx` | Отключенное состояние: приглушённый текст и заблокированные кнопки |
+| `WithCustomButtonProps` | `WithCustomButtonProps.tsx` | `editButtonProps` / `removeButtonProps`: `title`, `aria-label` и собственный `onClick` |
+| `WithOverflow` | `WithOverflow.tsx` | Обрезка длинного контента многоточием по ширине контейнера |
+| `VisualTests` | `VisualTests.tsx` | Матрица размеров и состояний плюс кольцо фокуса кнопки — для скриншот-тестов |
 
 ---
 
@@ -132,4 +166,155 @@ extends HTMLAttributes<HTMLSpanElement>
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-27 | `id` пробрасывается атрибутом на корневой `<span>` — раньше деструктурировался из props и в DOM не попадал (ломающее изменение). |
+| 2026-08-26 | Создан документ. AI-рефакторинг (`displayName`, снят лишний `useCallback` с render-функций, константы приведены к UPPER_SNAKE_CASE, JSDoc на props), расширены unit-тесты, stories переведены на modern pattern. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Tag/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <Tag id="default-tag" size={EComponentSize.LG} onRemove={() => {}} removeButtonProps={{ "aria-label": "Удалить" }}>
+        Selected value
+    </Tag>
+);
+```
+
+### Editable
+
+`stories/Tag/examples/Editable.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Editable = () => (
+    <Tag
+        id="editable-tag"
+        size={EComponentSize.LG}
+        onEdit={() => {}}
+        onRemove={() => {}}
+        editButtonProps={{ "aria-label": "Редактировать" }}
+        removeButtonProps={{ "aria-label": "Удалить" }}
+    >
+        Selected value
+    </Tag>
+);
+```
+
+### Sizes
+
+`stories/Tag/examples/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <Tag
+                    id={`${size}-tag`}
+                    size={size}
+                    onEdit={() => {}}
+                    onRemove={() => {}}
+                    editButtonProps={{ "aria-label": "Редактировать" }}
+                    removeButtonProps={{ "aria-label": "Удалить" }}
+                >
+                    Selected value
+                </Tag>
+            </div>
+        ))}
+    </div>
+);
+```
+
+### Disabled
+
+`stories/Tag/examples/Disabled.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Disabled = () => (
+    <Tag
+        id="disabled-tag"
+        size={EComponentSize.LG}
+        disabled
+        onEdit={() => {}}
+        onRemove={() => {}}
+        editButtonProps={{ "aria-label": "Редактировать" }}
+        removeButtonProps={{ "aria-label": "Удалить" }}
+    >
+        Selected value
+    </Tag>
+);
+```
+
+### WithCustomButtonProps
+
+`stories/Tag/examples/WithCustomButtonProps.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const WithCustomButtonProps = () => (
+    <Tag
+        id="custom-props-tag"
+        size={EComponentSize.LG}
+        onEdit={() => {}}
+        onRemove={() => {}}
+        editButtonProps={{
+            title: "Редактировать тег",
+            "aria-label": "Редактировать тег",
+            onClick: () => {},
+        }}
+        removeButtonProps={{
+            title: "Удалить тег",
+            "aria-label": "Удалить тег",
+            onClick: () => {},
+        }}
+    >
+        Selected value
+    </Tag>
+);
+```
+
+### WithOverflow
+
+`stories/Tag/examples/WithOverflow.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const WithOverflow = () => (
+    <div style={{ maxWidth: 440 }}>
+        <Tag
+            id="long-tag"
+            size={EComponentSize.LG}
+            onEdit={() => {}}
+            onRemove={() => {}}
+            editButtonProps={{ "aria-label": "Редактировать" }}
+            removeButtonProps={{ "aria-label": "Удалить" }}
+        >
+            Very long tag text that should be truncated with ellipsis
+        </Tag>
+    </div>
+);
+```
+

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` |
 
 ---