@sberbusiness/triplex-next-mcp-server 0.24.0-beta1 → 0.36.0-beta0

package/bundle/components/ButtonDropdown.md

@@ -1,8 +1,6 @@
 ---
 component: ButtonDropdown
 category: Buttons
-figma-node: ""
-figma-file: ""
 related: [Button, ButtonDropdownExtended, Dropdown]
 tokens: []
 stories: stories/Buttons/ButtonDropdown.stories.tsx
@@ -13,25 +11,10 @@ version: "1.0"
 
 ## Назначение
 
-Кнопка-триггер с выпадающим списком действий.
-Поддерживает два визуальных режима: обычная кнопка (`EButtonTheme`) и dots-вариант (`EButtonDotsTheme`).
+Кнопка-триггер с выпадающим списком действий. Поддерживает два визуальных режима: обычная кнопка (`EButtonTheme`) и dots-вариант (`EButtonDotsTheme`).
 
 Используй когда: нужно сгруппировать несколько действий под один триггер и дать выбор опции из списка.
-Не используй когда: нужна одиночная кнопка без списка - используй `Button`.
-
----
-
-## Файловая структура
-
-```text
-src/components/Button/
-├── ButtonDropdown.tsx                  # Основной компонент (forwardRef, рендер button + dropdown)
-├── ButtonDropdownExtended.tsx          # Базовый контейнер с контролем opened/close и outside click
-├── styles/
-│   ├── ButtonDropdown.module.less      # Стили caret, active-состояния, block-режима
-│   └── ButtonDropdownExtended.module.less
-└── index.ts                            # Публичный экспорт ButtonDropdown
-```
+Не используй когда: нужна одиночная кнопка без списка — используй `Button`.
 
 ---
 
@@ -49,18 +32,13 @@ src/components/Button/
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `children` | `React.ReactNode` | `undefined` | Текст/контент кнопки (используется также в mobile header) |
-| `selected` | `IButtonDropdownOption` | `undefined` | Предвыбранная опция для подсветки в списке |
+| `children` | `React.ReactNode` | — | Текст/контент кнопки (используется также в mobile header) |
+| `selected` | `IButtonDropdownOption` | — | Предвыбранная опция для подсветки в списке |
 | `disabled` | `boolean` | `false` | Блокирует кнопку и открытие списка |
-| `buttonAttributes` | `React.ButtonHTMLAttributes<HTMLButtonElement>` | `undefined` | Дополнительные HTML-атрибуты нативной кнопки |
-| `block` | `boolean` | `false` | Доступен только для non-dots тем |
+| `buttonAttributes` | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | Дополнительные HTML-атрибуты нативной кнопки (включая `aria-label`) |
+| `block` | `boolean` | `false` | Полноширинный режим (только для non-dots тем) |
 | `className` | `string` | — | Дополнительный CSS-класс контейнера |
-| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Атрибуты корневого `div` компонента |
-
-### Ограничения по темам
-
-- Для `EButtonDotsTheme` prop `block` запрещен типизацией (`never`).
-- Dots-режим использует иконку `Dotshorizontal*` вместо текстового контента кнопки.
+| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Атрибуты корневого `<div>` компонента |
 
 ### Структура опции (`IButtonDropdownOption`)
 
@@ -69,50 +47,19 @@ src/components/Button/
 | `id` | `string` | Уникальный идентификатор опции |
 | `label` | `React.ReactNode` | Видимый контент пункта меню |
 | `onSelect` | `() => void` | Callback выбора опции |
-| `...rest` | `IDropdownListItemProps` (без ряда запрещенных полей) | Остальные настройки `DropdownList.Item` |
-
----
-
-## Ключевые особенности реализации
-
-### Композиция через `ButtonDropdownExtended`
+| `...rest` | `IDropdownListItemProps` (без ряда запрещённых полей) | Остальные настройки `DropdownList.Item` |
 
-- `ButtonDropdown` делегирует управление opened-state и close-on-outside в `ButtonDropdownExtended`.
-- Передает две render-функции: `renderButton` и `renderDropdown`.
-
-### Desktop + mobile dropdown
-
-- Desktop: рендерится `DropdownList` с `DropdownList.Item`.
-- Mobile: через `mobileViewProps` рендерится `DropdownMobileHeader` + `DropdownMobileList`.
-- После выбора любого пункта вызывается `option.onSelect?.()` и dropdown закрывается.
-
-### Управление клавиатурой
-
-- На кнопке перехватываются `Space`, `ArrowUp`, `ArrowDown` с `preventDefault`.
-- `ArrowUp/ArrowDown` открывают dropdown, если он закрыт.
-- В `ButtonDropdownExtended` dropdown закрывается по `Escape` и (из-за `closeOnTab`) по `Tab`.
-
-### ARIA-связка trigger/list
-
-- Кнопка получает `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`.
-- `aria-controls` и `DropdownList` связываются через `instanceId` (`uniqueId()`).
-- `aria-activedescendant` синхронизируется через `DropdownListContext`.
-
----
-
-## Accessibility
+### Ограничения по темам
 
-- Триггер строится на `Button` (нативный `button`), базовая keyboard-навигация сохраняется.
-- Компонент не хардкодит aria-тексты: при необходимости `aria-label` нужно передавать через `buttonAttributes`.
-- На mobile-заголовке dropdown отображается `children` триггера; если в продукте нужен локализованный отдельный заголовок, его нужно задавать на уровне композиции (через `ButtonDropdownExtended`).
-- Для корректной доступности меню потребитель должен передавать понятные `label` для `options`.
+- Для `EButtonDotsTheme` prop `block` запрещён типизацией (`never`).
+- Dots-режим использует иконку `Dotshorizontal*` вместо текстового контента кнопки.
+- Desktop рендерит `DropdownList` с `DropdownList.Item`; mobile через `mobileViewProps` рендерит `DropdownMobileHeader` + `DropdownMobileList`.
 
 ---
 
 ## Дизайн-токены
 
-`ButtonDropdown` не использует собственных CSS color-токенов в `ButtonDropdown.module.less`.
-Визуальные токены берутся из `Button` и `Dropdown`, которые рендерятся внутри.
+`ButtonDropdown` не использует собственных CSS color-токенов. Визуальные токены берутся из `Button` и `Dropdown`, которые рендерятся внутри.
 
 ---
 
@@ -126,17 +73,27 @@ src/components/Button/
 
 ---
 
+## Accessibility
+
+- Триггер строится на `Button` (нативный `<button>`), базовая keyboard-навигация сохраняется.
+- Кнопка получает `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`. Связка trigger/list осуществляется через `instanceId` (`uniqueId()`); `aria-activedescendant` синхронизируется через `DropdownListContext`.
+- На кнопке перехватываются `Space`, `ArrowUp`, `ArrowDown` с `preventDefault`. `ArrowUp` / `ArrowDown` открывают dropdown, если он закрыт. Dropdown закрывается по `Escape` и (из-за `closeOnTab`) по `Tab`.
+- Компонент **не хардкодит** aria-тексты: при необходимости `aria-label` нужно передавать через `buttonAttributes`. Для корректной доступности меню потребитель должен передавать понятные `label` для `options`.
+- На mobile-заголовке dropdown отображается `children` триггера; если в продукте нужен локализованный отдельный заголовок, его нужно задавать на уровне композиции (через `ButtonDropdownExtended`).
+
+---
+
 ## Связанные компоненты
 
-- `Button` (`src/components/Button/Button.tsx`) - базовый триггер, на котором построен `ButtonDropdown`.
-- `ButtonDropdownExtended` (`src/components/Button/ButtonDropdownExtended.tsx`) - управляет открытием/закрытием dropdown.
-- `Dropdown` (`src/components/Dropdown`) - контейнер и пункты списка для desktop/mobile представления.
+- `Button` (`src/components/Button/Button.tsx`) — базовый триггер, на котором построен `ButtonDropdown`.
+- `ButtonDropdownExtended` (`src/components/Button/ButtonDropdownExtended.tsx`) — управляет открытием/закрытием dropdown через render-функции `renderButton` и `renderDropdown`.
+- `Dropdown` (`src/components/Dropdown`) — контейнер и пункты списка для desktop/mobile представления.
 
 ---
 
 ## Stories
 
-`stories/Buttons/ButtonDropdown.stories.tsx`
+Основные истории: `stories/Buttons/ButtonDropdown.stories.tsx`
 Файлы примеров: `stories/Buttons/examples/ButtonDropdown/`
 
 | Story | Example file | Что демонстрирует |
@@ -157,3 +114,304 @@ src/components/Button/
 | Дата | Изменение |
 |---|---|
 | 2026-04-15 | Создан документ AI-ready для `ButtonDropdown`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», их содержимое перенесено в `Ограничения по темам` и `Accessibility`, добавлена колонка `Example file`. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Buttons/examples/ButtonDropdown/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { ButtonDropdown, EButtonTheme, EComponentSize, IButtonDropdownOption } from "@sberbusiness/triplex-next";
+
+const OPTIONS: IButtonDropdownOption[] = [
+    { id: "opt-1", label: "Действие 1", onSelect: () => undefined },
+    { id: "opt-2", label: "Действие 2", onSelect: () => undefined },
+    { id: "opt-3", label: "Действие 3", onSelect: () => undefined },
+];
+
+export const DefaultExample = () => (
+    <div style={{ width: 280 }}>
+        <ButtonDropdown theme={EButtonTheme.GENERAL} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Buttons/examples/ButtonDropdown/SizesExample.tsx`
+
+```tsx
+import React from "react";
+import {
+    ButtonDropdown,
+    EButtonDotsTheme,
+    EButtonTheme,
+    EComponentSize,
+    IButtonDropdownOption,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS: IButtonDropdownOption[] = [
+    { id: "opt-1", label: "Действие 1", onSelect: () => undefined },
+    { id: "opt-2", label: "Действие 2", onSelect: () => undefined },
+    { id: "opt-3", label: "Действие 3", onSelect: () => undefined },
+];
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>SM</div>
+            <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 16 }}>
+                <ButtonDropdown size={EComponentSize.SM} theme={EButtonTheme.GENERAL} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.SM} theme={EButtonTheme.SECONDARY} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.SM} theme={EButtonTheme.SECONDARY_LIGHT} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.SM} theme={EButtonTheme.DANGER} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.SM} theme={EButtonDotsTheme.DOTS_SECONDARY} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown
+                    size={EComponentSize.SM}
+                    theme={EButtonDotsTheme.DOTS_SECONDARY_LIGHT}
+                    options={OPTIONS}
+                >
+                    Button text
+                </ButtonDropdown>
+            </div>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>MD</div>
+            <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 16 }}>
+                <ButtonDropdown size={EComponentSize.MD} theme={EButtonTheme.GENERAL} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.MD} theme={EButtonTheme.SECONDARY} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.MD} theme={EButtonTheme.SECONDARY_LIGHT} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.MD} theme={EButtonTheme.DANGER} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.MD} theme={EButtonDotsTheme.DOTS_SECONDARY} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown
+                    size={EComponentSize.MD}
+                    theme={EButtonDotsTheme.DOTS_SECONDARY_LIGHT}
+                    options={OPTIONS}
+                >
+                    Button text
+                </ButtonDropdown>
+            </div>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>LG</div>
+            <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 16 }}>
+                <ButtonDropdown size={EComponentSize.LG} theme={EButtonTheme.GENERAL} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.LG} theme={EButtonTheme.SECONDARY} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.LG} theme={EButtonTheme.SECONDARY_LIGHT} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.LG} theme={EButtonTheme.DANGER} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown size={EComponentSize.LG} theme={EButtonDotsTheme.DOTS_SECONDARY} options={OPTIONS}>
+                    Button text
+                </ButtonDropdown>
+                <ButtonDropdown
+                    size={EComponentSize.LG}
+                    theme={EButtonDotsTheme.DOTS_SECONDARY_LIGHT}
+                    options={OPTIONS}
+                >
+                    Button text
+                </ButtonDropdown>
+            </div>
+        </div>
+    </div>
+);
+```
+
+### Themes
+
+`stories/Buttons/examples/ButtonDropdown/ThemesExample.tsx`
+
+```tsx
+import React from "react";
+import {
+    ButtonDropdown,
+    EButtonDotsTheme,
+    EButtonTheme,
+    EComponentSize,
+    IButtonDropdownOption,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS: IButtonDropdownOption[] = [
+    { id: "opt-1", label: "Действие 1", onSelect: () => undefined },
+    { id: "opt-2", label: "Действие 2", onSelect: () => undefined },
+    { id: "opt-3", label: "Действие 3", onSelect: () => undefined },
+];
+
+export const ThemesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 16 }}>
+            <ButtonDropdown theme={EButtonTheme.GENERAL} size={EComponentSize.MD} options={OPTIONS}>
+                General
+            </ButtonDropdown>
+            <ButtonDropdown theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} options={OPTIONS}>
+                Secondary
+            </ButtonDropdown>
+            <ButtonDropdown theme={EButtonTheme.SECONDARY_LIGHT} size={EComponentSize.MD} options={OPTIONS}>
+                Secondary Light
+            </ButtonDropdown>
+            <ButtonDropdown theme={EButtonTheme.DANGER} size={EComponentSize.MD} options={OPTIONS}>
+                Danger
+            </ButtonDropdown>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>DOTS_SECONDARY</div>
+            <ButtonDropdown theme={EButtonDotsTheme.DOTS_SECONDARY} size={EComponentSize.MD} options={OPTIONS}>
+                Dots Secondary
+            </ButtonDropdown>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>DOTS_SECONDARY_LIGHT</div>
+            <ButtonDropdown theme={EButtonDotsTheme.DOTS_SECONDARY_LIGHT} size={EComponentSize.MD} options={OPTIONS}>
+                Dots Secondary Light
+            </ButtonDropdown>
+        </div>
+    </div>
+);
+```
+
+### BlockMode
+
+`stories/Buttons/examples/ButtonDropdown/BlockModeExample.tsx`
+
+```tsx
+import React from "react";
+import { ButtonDropdown, EButtonTheme, EComponentSize, Gap, IButtonDropdownOption } from "@sberbusiness/triplex-next";
+
+const OPTIONS: IButtonDropdownOption[] = [
+    { id: "opt-1", label: "Действие 1", onSelect: () => undefined },
+    { id: "opt-2", label: "Действие 2", onSelect: () => undefined },
+    { id: "opt-3", label: "Действие 3", onSelect: () => undefined },
+];
+
+export const BlockModeExample = () => (
+    <div style={{ maxWidth: 280 }}>
+        <ButtonDropdown block theme={EButtonTheme.GENERAL} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <Gap size={16} />
+        <ButtonDropdown block theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <Gap size={16} />
+        <ButtonDropdown block theme={EButtonTheme.SECONDARY_LIGHT} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <Gap size={16} />
+        <ButtonDropdown block theme={EButtonTheme.DANGER} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+    </div>
+);
+```
+
+### Disabled
+
+`stories/Buttons/examples/ButtonDropdown/DisabledExample.tsx`
+
+```tsx
+import React from "react";
+import {
+    ButtonDropdown,
+    EButtonDotsTheme,
+    EButtonTheme,
+    EComponentSize,
+    IButtonDropdownOption,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS: IButtonDropdownOption[] = [
+    { id: "opt-1", label: "Действие 1", onSelect: () => undefined },
+    { id: "opt-2", label: "Действие 2", onSelect: () => undefined },
+    { id: "opt-3", label: "Действие 3", onSelect: () => undefined },
+];
+
+export const DisabledExample = () => (
+    <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 16 }}>
+        <ButtonDropdown disabled theme={EButtonTheme.GENERAL} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <ButtonDropdown disabled theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <ButtonDropdown disabled theme={EButtonTheme.SECONDARY_LIGHT} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <ButtonDropdown disabled theme={EButtonTheme.DANGER} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <ButtonDropdown disabled theme={EButtonDotsTheme.DOTS_SECONDARY} size={EComponentSize.MD} options={OPTIONS}>
+            Button text
+        </ButtonDropdown>
+        <ButtonDropdown
+            disabled
+            theme={EButtonDotsTheme.DOTS_SECONDARY_LIGHT}
+            size={EComponentSize.MD}
+            options={OPTIONS}
+        >
+            Button text
+        </ButtonDropdown>
+    </div>
+);
+```
+
+### WithSelectedOption
+
+`stories/Buttons/examples/ButtonDropdown/WithSelectedOptionExample.tsx`
+
+```tsx
+import React, { useMemo, useState } from "react";
+import { ButtonDropdown, EButtonTheme, EComponentSize, IButtonDropdownOption } from "@sberbusiness/triplex-next";
+
+const createOptions = (onItemSelect?: (id: string) => void): IButtonDropdownOption[] => [
+    { id: "opt-1", label: "Действие 1", onSelect: () => onItemSelect?.("opt-1") },
+    { id: "opt-2", label: "Действие 2", onSelect: () => onItemSelect?.("opt-2") },
+    { id: "opt-3", label: "Действие 3", onSelect: () => onItemSelect?.("opt-3") },
+];
+
+export const WithSelectedOptionExample = () => {
+    const [selectedId, setSelectedId] = useState<string | undefined>("opt-2");
+    const options = useMemo(() => createOptions(setSelectedId), []);
+    const selected = options.find((o) => o.id === selectedId);
+
+    return (
+        <div style={{ maxWidth: 280 }}>
+            <ButtonDropdown theme={EButtonTheme.GENERAL} size={EComponentSize.MD} options={options} selected={selected}>
+                Button text
+            </ButtonDropdown>
+        </div>
+    );
+};
+```
+

package/bundle/components/ButtonIcon.md

@@ -1,8 +1,6 @@
 ---
 component: ButtonIcon
 category: Buttons
-figma-node: ""
-figma-file: ""
 related: [Button]
 tokens:
   - --triplex-next-Button-Icon_Shadow_Focus
@@ -17,19 +15,7 @@ version: "1.0"
 Кнопка только с иконкой без текстового контента. Используется как компактный trigger для локальных действий (например, открыть меню, удалить, закрыть).
 
 Используй когда: действие можно однозначно распознать по иконке и есть корректный `aria-label`.
-Не используй когда: нужен текстовый CTA или несколько визуальных тем с размерами как у `Button` - используй `Button`.
-
----
-
-## Файловая структура
-
-```text
-src/components/Button/
-├── ButtonIcon.tsx                     # Компонент (forwardRef, native button)
-├── enums.ts                           # EButtonIconShape (SQUIRCLE / CIRCLE)
-└── styles/
-    └── ButtonIcon.module.less         # Геометрия, focus-visible, базовые состояния
-```
+Не используй когда: нужен текстовый CTA или несколько визуальных тем с размерами как у `Button` — используй `Button`.
 
 ---
 
@@ -51,29 +37,8 @@ src/components/Button/
 ### Ограничения использования
 
 - Размер `ButtonIcon` задаётся размером переданной иконки; у компонента нет собственного prop `size`.
-- Корневой DOM-элемент всегда `button`, `type` по умолчанию принудительно установлен в `button`.
-
----
-
-## Ключевые особенности реализации
-
-### Маппинг формы через enum
-
-- `shape` маппится в CSS-класс через `Record<EButtonIconShape, string>`.
-- При расширении `EButtonIconShape` нужно добавить класс в маппинг и в `ButtonIcon.module.less`.
-
-### Визуальные состояния
-
-- `active` и `disabled` добавляются как глобальные CSS-классы (`active`, `disabled`) для совместимости с иконками.
-- Дополнительно всегда добавляется класс `hoverable`.
-
----
-
-## Accessibility
-
-- Компонент рендерит нативный `<button>`, поэтому базовая keyboard-навигация доступна из коробки.
-- Компонент **не хардкодит** `aria-label` (библиотека мультиязычная). Для иконки без текста потребитель обязан передать `aria-label` через `...rest`.
-- Фокусное состояние реализовано через `:focus-visible` и токен `--triplex-next-Button-Icon_Shadow_Focus`.
+- Корневой DOM-элемент всегда `<button>`, `type` по умолчанию принудительно установлен в `button`.
+- При расширении `EButtonIconShape` необходимо добавить класс в маппинг `Record<EButtonIconShape, string>` и в `ButtonIcon.module.less`.
 
 ---
 
@@ -94,16 +59,24 @@ src/components/Button/
 
 ---
 
+## Accessibility
+
+- Компонент рендерит нативный `<button>`, поэтому базовая keyboard-навигация доступна из коробки.
+- Компонент **не хардкодит** `aria-label` (библиотека мультиязычная). Для иконки без текста потребитель **обязан** передать `aria-label` через `...rest`.
+- Фокусное состояние реализовано через `:focus-visible` и токен `--triplex-next-Button-Icon_Shadow_Focus`.
+
+---
+
 ## Связанные компоненты
 
-- `Button` (`src/components/Button/Button.tsx`) - текстовая/универсальная кнопка, используемая вместо `ButtonIcon` когда нужен label.
-- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) - использует иконочный паттерн для dots-варианта trigger.
+- `Button` (`src/components/Button/Button.tsx`) — текстовая/универсальная кнопка, используемая вместо `ButtonIcon` когда нужен label.
+- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) — использует иконочный паттерн для dots-варианта trigger.
 
 ---
 
 ## Stories
 
-`stories/Buttons/ButtonIcon.stories.tsx`
+Основные истории: `stories/Buttons/ButtonIcon.stories.tsx`
 Файлы примеров: `stories/Buttons/examples/ButtonIcon/`
 
 | Story | Example file | Что демонстрирует |
@@ -111,7 +84,7 @@ src/components/Button/
 | `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `shape`, `active`, `disabled` |
 | `Default` | `DefaultExample.tsx` | Базовый сценарий использования |
 | `Sizes` | `SizesExample.tsx` | Разные размеры через размер иконки (16/20/24/32) |
-| `Disabled` | `DisabledExample.tsx` | Неактивное состояние |
+| `States` | `StatesExample.tsx` | Состояния `active` и `disabled` |
 
 ---
 
@@ -120,3 +93,86 @@ src/components/Button/
 | Дата | Изменение |
 |---|---|
 | 2026-04-15 | Создан документ AI-ready для `ButtonIcon`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убрана секция «Файловая структура», содержимое «Ключевых особенностей реализации» перенесено в `Ограничения использования`, добавлена колонка `Example file`. |
+| 2026-07-08 | Актуализирована таблица Stories: story `Disabled` заменена на `States` (`StatesExample.tsx`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Buttons/examples/ButtonIcon/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { DefaulticonStrokePrdIcon32 } from "@sberbusiness/icons-next";
+import { ButtonIcon, EButtonIconShape } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <ButtonIcon shape={EButtonIconShape.SQUIRCLE}>
+        <DefaulticonStrokePrdIcon32 paletteIndex={5} />
+    </ButtonIcon>
+);
+```
+
+### Sizes
+
+`stories/Buttons/examples/ButtonIcon/SizesExample.tsx`
+
+```tsx
+import React from "react";
+import {
+    DefaulticonStrokePrdIcon16,
+    DefaulticonStrokePrdIcon20,
+    DefaulticonStrokePrdIcon24,
+    DefaulticonStrokePrdIcon32,
+} from "@sberbusiness/icons-next";
+import { ButtonIcon, EButtonIconShape } from "@sberbusiness/triplex-next";
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
+        <ButtonIcon shape={EButtonIconShape.SQUIRCLE}>
+            <DefaulticonStrokePrdIcon16 paletteIndex={5} />
+        </ButtonIcon>
+        <ButtonIcon shape={EButtonIconShape.SQUIRCLE}>
+            <DefaulticonStrokePrdIcon20 paletteIndex={5} />
+        </ButtonIcon>
+        <ButtonIcon shape={EButtonIconShape.SQUIRCLE}>
+            <DefaulticonStrokePrdIcon24 paletteIndex={5} />
+        </ButtonIcon>
+        <ButtonIcon shape={EButtonIconShape.SQUIRCLE}>
+            <DefaulticonStrokePrdIcon32 paletteIndex={5} />
+        </ButtonIcon>
+    </div>
+);
+```
+
+### States
+
+`stories/Buttons/examples/ButtonIcon/StatesExample.tsx`
+
+```tsx
+import React from "react";
+import { DefaulticonStrokePrdIcon32 } from "@sberbusiness/icons-next";
+import { ButtonIcon, EButtonIconShape } from "@sberbusiness/triplex-next";
+
+export const StatesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "start", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Active</div>
+            <ButtonIcon shape={EButtonIconShape.SQUIRCLE} active>
+                <DefaulticonStrokePrdIcon32 paletteIndex={5} />
+            </ButtonIcon>
+        </div>
+
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "start", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Disabled</div>
+            <ButtonIcon shape={EButtonIconShape.SQUIRCLE} disabled>
+                <DefaulticonStrokePrdIcon32 paletteIndex={5} />
+            </ButtonIcon>
+        </div>
+    </div>
+);
+```
+