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

package/README.md

@@ -80,6 +80,9 @@ npm run inspect
 # Обновить bundle/ из последнего релиза triplex-next
 npm run fetch-bundle
 
+# Обновить только AI-ready компоненты из bundle, остальные данные сохранить
+npm run fetch-bundle -- --merge --file path/to/mcp-data.json
+
 # Обновить bundle/icons.json из @sberbusiness/icons-next
 npm run fetch-icons
 
@@ -111,6 +114,13 @@ bundle/
 содержимое в поддиректории выше. Транзиентный `mcp-data.json` удаляется
 после раскладки.
 
+По умолчанию дерево перезаписывается целиком. Флаг `--merge` включает
+инкрементальное обновление: компоненты, у которых в bundle есть данные
+(`raw !== null`), перезаписываются, остальные сохраняют текущую документацию
+и записи в `manifest.json`. Гайды и release notes из bundle перезаписываются,
+отсутствующие в bundle — сохраняются. Режим полезен, пока AI-документация
+в triplex-next выверяется покомпонентно.
+
 В triplex-next bundle собирается скриптом `scripts/generateMcpData.ts`
 (npm-команда `generateMcpData`) и автоматически прикладывается к релиз-ассетам
 через `.github/workflows/release.yml`.

package/bundle/components/BodyPage.md

@@ -0,0 +1,186 @@
+---
+component: BodyPage
+category: Page
+related: [Page, HeaderPage, FooterPage, Body, Island, LightBox]
+tokens: []
+stories: stories/Page/BodyPage/BodyPage.stories.tsx
+version: "1.0"
+---
+
+# BodyPage
+
+## Назначение
+
+Тело страницы `Page`. Доступен как статическое свойство `Page.Body`. Контейнер для основного
+контента страницы между `Page.Header` и `Page.Footer`.
+
+Используй когда: нужно разместить основной контент внутри `Page` — как в карточке (Island), так и без неё.
+Не используй когда: нужен заголовок или футер страницы — для этого есть `Page.Header` / `Page.Footer`.
+
+---
+
+## Варианты и props
+
+Публичный API — discriminated union по `type`: `IBodyPageTypeFirstProps | IBodyPageTypeSecondProps`.
+Оба интерфейса расширяют `IBodyProps` (≈ `React.HTMLAttributes<HTMLDivElement>`).
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `EBodyPageType` | `FIRST` — контент оборачивается в `Island` (карточка с белым фоном и тенью). `SECOND` — контент без карточки. |
+| `children` | `React.ReactNode` | Контент тела страницы. |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `verticalMargin` | `EBodyPageVerticalMargin` | `LARGE` | Вертикальные отступы: `LARGE` = 24px (16px на узких экранах), `SMALL` = 16px (8px на узких). В LightBox используется `SMALL`. |
+| `size` | `EComponentSize` | — | Размер острова (Island). **Доступен только для `type=FIRST`**; для `type=SECOND` типизирован как `never`. |
+
+### Ограничения по типам
+
+- `size` доступен только при `type=FIRST` (в `SECOND` контент не оборачивается в Island, поэтому `size?: never`).
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-переменных нет. Внешний вид карточки наследуется от `Island` (`EIslandType.TYPE_1`).
+Вертикальные отступы заданы фиксированными значениями в `styles/BodyPage.module.less`
+(24/16px и адаптив 16/8px на `@screen-sm-max`).
+
+---
+
+## Инварианты
+
+- `forwardRef<HTMLDivElement>` — не убирать. Ref всегда указывает на корневой элемент
+  (Island для FIRST, Body для SECOND).
+- `displayName = "BodyPage"` — не менять.
+- Discriminated union по `type` и значения `EBodyPageType` / `EBodyPageVerticalMargin` — часть
+  публичного API, менять нельзя.
+- Экспорты `BodyPage`, `IBodyPageTypeFirstProps`, `IBodyPageTypeSecondProps` идут в barrel
+  `src/components/Page/index.ts` — сохранять.
+- `verticalMargin` по умолчанию `LARGE` — менять дефолт нельзя без обсуждения.
+
+---
+
+## Accessibility
+
+Особого a11y-поведения нет — это структурный контейнер. Семантику и aria-атрибуты задаёт
+потребитель через проброшенные HTML-атрибуты (`...rest` уходит в `Body`).
+
+---
+
+## Связанные компоненты
+
+- `Page` — родитель; `BodyPage` доступен как `Page.Body`.
+- `HeaderPage` (`Page.Header`), `FooterPage` (`Page.Footer`) — соседи внутри `Page`.
+- `Body` — внутренний контейнер контента (рендерится в обоих типах).
+- `Island` — карточка-обёртка для `type=FIRST`.
+- `LightBox` — типичное место использования с `verticalMargin=SMALL`.
+
+---
+
+## Stories
+
+Основные истории: `stories/Page/BodyPage/BodyPage.stories.tsx`
+Файлы примеров: `stories/Page/BodyPage/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `type` и `verticalMargin` |
+| `Default` | `Default.tsx` | Минимальный пример (FIRST, контент в карточке) |
+| `Types` | `Types.tsx` | Сравнение типов FIRST и SECOND |
+| `VerticalMargins` | `VerticalMargins.tsx` | Отступы LARGE (24px) и SMALL (16px) |
+| `VisualTests` | `VisualTests.tsx` | Матрица type × verticalMargin для скриншот-регрессии |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-06-18 | Создан документ. AI-рефакторинг (clsx order, JSDoc), unit-тесты, миграция stories на modern pattern. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Page/BodyPage/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Page, EBodyPageType, Text, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <Page.Body type={EBodyPageType.FIRST}>
+        <Text tag="div" size={ETextSize.B2} type={EFontType.PRIMARY}>
+            BodyPage типа FIRST оборачивает контент в Island (карточку) с белым фоном и тенью.
+        </Text>
+    </Page.Body>
+);
+```
+
+### Types
+
+`stories/Page/BodyPage/examples/Types.tsx`
+
+```tsx
+import React from "react";
+import { Page, EBodyPageType, Text, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const Types = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>FIRST</div>
+            <Page.Body type={EBodyPageType.FIRST}>
+                <Text tag="div" size={ETextSize.B2} type={EFontType.PRIMARY}>
+                    Тип FIRST оборачивает контент в Island (карточку) с белым фоном и тенью.
+                </Text>
+            </Page.Body>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>SECOND</div>
+            <Page.Body type={EBodyPageType.SECOND}>
+                <Text tag="div" size={ETextSize.B2} type={EFontType.PRIMARY}>
+                    Тип SECOND отображает контент без карточки.
+                </Text>
+            </Page.Body>
+        </div>
+    </div>
+);
+```
+
+### VerticalMargins
+
+`stories/Page/BodyPage/examples/VerticalMargins.tsx`
+
+```tsx
+import React from "react";
+import { Page, EBodyPageType, EBodyPageVerticalMargin, Text, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const VerticalMargins = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>LARGE (24px)</div>
+            <Page.Body type={EBodyPageType.FIRST} verticalMargin={EBodyPageVerticalMargin.LARGE}>
+                <Text tag="div" size={ETextSize.B2} type={EFontType.PRIMARY}>
+                    Отступы сверху и снизу 24px (значение по умолчанию).
+                </Text>
+            </Page.Body>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>SMALL (16px)</div>
+            <Page.Body type={EBodyPageType.FIRST} verticalMargin={EBodyPageVerticalMargin.SMALL}>
+                <Text tag="div" size={ETextSize.B2} type={EFontType.PRIMARY}>
+                    Уменьшенные отступы сверху и снизу 16px. Используется в LightBox.
+                </Text>
+            </Page.Body>
+        </div>
+    </div>
+);
+```
+

package/bundle/components/Button.md

@@ -1,8 +1,6 @@
 ---
 component: Button
 category: Buttons
-figma-node: "1-328"
-figma-file: "https://www.figma.com/design/MeAqaaLV9acAgoBOkZC9C2/-W--LIB-DSN-01-Components-DCB-Next-v.1.3.0"
 related: [ButtonIcon, ButtonDropdown, ButtonDropdownExtended]
 tokens:
   - --triplex-next-Button-General_Background_Default
@@ -64,42 +62,17 @@ version: "1.0"
 
 ---
 
-## Файловая структура
-
-```text
-src/components/Button/
-├── Button.tsx                     # Основной компонент, union type TButtonProps
-├── ButtonBase.tsx                 # Базовый <button>, extends HTML attrs
-├── ButtonIcon.tsx                 # Иконочная кнопка (squircle / circle)
-├── ButtonDropdown.tsx             # Кнопка с выпадающим меню
-├── ButtonDropdownExtended.tsx     # Контейнер с кастомным dropdown
-├── enums.ts                       # EButtonTheme, EButtonDotsTheme, EButtonIconShape
-├── index.ts                       # Barrel exports
-└── styles/
-    ├── Button.module.less         # Размеры, block, loading, base layout
-    ├── ButtonGeneral.module.less  # Тема GENERAL
-    ├── ButtonSecondary.module.less
-    ├── ButtonSecondaryLight.module.less
-    ├── ButtonDanger.module.less
-    ├── ButtonLink.module.less     # Тема LINK — нет min-width, нет bg
-    ├── ButtonIcon.module.less     # Стили ButtonIcon
-    ├── ButtonDropdown.module.less
-    └── ButtonDropdownExtended.module.less
-```
-
----
-
 ## Варианты и props
 
 ### Темы (`EButtonTheme`)
 
-| Значение | Описание | Поддерживает loading/icon/block |
-|---|---|---|
-| `GENERAL` | Основной стиль (primary) | Да |
-| `SECONDARY` | Вторичный | Да |
-| `SECONDARY_LIGHT` | Вторичный светлый (для тёмных фонов) | Да |
-| `DANGER` | Деструктивное действие | Да |
-| `LINK` | Текстовая ссылка | Нет — `loading`, `icon`, `block` запрещены через `never` |
+| Значение | Описание |
+|---|---|
+| `GENERAL` | Основной стиль (primary) |
+| `SECONDARY` | Вторичный |
+| `SECONDARY_LIGHT` | Вторичный светлый (для тёмных фонов) |
+| `DANGER` | Деструктивное действие |
+| `LINK` | Текстовая ссылка |
 
 ### Размеры (`EComponentSize`)
 
@@ -109,17 +82,22 @@ src/components/Button/
 | `MD` | 40px | 0 20px | 8px | 14px |
 | `LG` | 56px | 0 24px | 10px | 16px |
 
-### Props компонента `Button`
+### Обязательные props (`Button`)
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `theme` | `EButtonTheme` | Визуальный стиль |
+| `size` | `EComponentSize` | Размер |
+
+### Опциональные props (`Button`)
 
-| Prop | Тип | Обязателен | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `theme` | `EButtonTheme` | Да | Визуальный стиль |
-| `size` | `EComponentSize` | Да | Размер |
-| `block` | `boolean` | Нет | Полноширинный режим (только не-LINK темы) |
-| `loading` | `boolean` | Нет | Состояние загрузки: скрывает контент, показывает спиннер (только не-LINK темы) |
-| `icon` | `React.ReactElement` | Нет | Иконка слева от текста; если без `children` — кнопка становится квадратной |
-| `children` | `React.ReactNode` | Нет | Текст кнопки |
-| `...HTMLButtonAttributes` | — | — | Все стандартные атрибуты `<button>` |
+| `block` | `boolean` | `false` | Полноширинный режим |
+| `loading` | `boolean` | `false` | Состояние загрузки: скрывает контент через `visibility: hidden`, показывает спиннер, ставит `tabIndex={-1}` |
+| `icon` | `React.ReactElement` | — | Иконка слева от текста; если без `children` — кнопка становится квадратной (icon-only) |
+| `children` | `React.ReactNode` | — | Текст кнопки |
+| `...HTMLButtonAttributes` | — | — | Все стандартные атрибуты `<button>`, включая `aria-expanded` (см. Accessibility) |
 
 ### Props компонента `ButtonIcon`
 
@@ -129,45 +107,11 @@ src/components/Button/
 | `active` | `boolean` | `false` | Визуальное активное состояние |
 | `...HTMLButtonAttributes` | — | — | Включая `disabled` |
 
----
-
-## Ключевые особенности реализации
-
-### Иконка без текста
-Если передан `icon` без `children` — добавляется класс `.icon`, который делает кнопку квадратной:
-```tsx
-// Button.tsx — логика определения icon-only режима
-const iconOnly = Boolean(icon) && !children;
-<button className={clsx(styles.button, { [styles.icon]: iconOnly })}>
-```
-
-### Состояние загрузки
-- `loading` скрывает контент через `visibility: hidden` (не `display: none`) — сохраняет размеры,
-- устанавливает `tabIndex={-1}` — кнопка недоступна с клавиатуры
-- Тема лоадера: `SECONDARY` и `SECONDARY_LIGHT` → `ELoaderSmallTheme.BRAND`, остальные → `ELoaderSmallTheme.NEUTRAL`
+### Ограничения по темам
 
-### `aria-expanded` управляет визуалом
-Состояние "раскрыто" (например, когда кнопка открывает dropdown) управляется через `aria-expanded`:
-```tsx
-<Button aria-expanded={true} ...> → добавляет CSS-классы .expanded и .active
-```
-Отдельного prop `expanded` нет — используй стандартный HTML-атрибут.
-
-### Тема LINK
-- Нет `min-width`
-- `background: transparent`
-- `padding` по вертикали отличается от других тем (меньше)
-- `block`, `loading`, `icon` — тип `never` в интерфейсе, TypeScript запрещает передачу
-
----
-
-## Accessibility
-
-- Нативный `<button>` — полная поддержка клавиатуры (Tab, Enter, Space) без дополнительных атрибутов.
-- **`ButtonIcon`**: иконочная кнопка без видимого текста — потребитель **обязан** передать `aria-label` через `...rest`. Библиотека мультиязычная, текст не хардкодится.
-- **`loading`**: устанавливает `tabIndex={-1}` — кнопка исключается из tab-порядка. Если нужна доступность состояния загрузки для скринридеров, потребитель добавляет `aria-busy="true"` через props.
-- **`aria-expanded`**: управляет визуальным состоянием "раскрыто" (добавляет CSS-классы `.expanded`, `.active`). Передаётся потребителем при использовании кнопки как триггера dropdown.
-- Фокус-стиль через `:focus-visible` — виден только при клавиатурной навигации.
+- `block`, `loading`, `icon` недоступны для темы `LINK` — тип `never` в интерфейсе, TypeScript запрещает передачу.
+- Тема `LINK` не имеет `min-width`, фона (`background: transparent`) и использует уменьшенный вертикальный `padding`.
+- Тема лоадера (`loading`) для `SECONDARY` и `SECONDARY_LIGHT` — `ELoaderSmallTheme.BRAND`, для остальных — `ELoaderSmallTheme.NEUTRAL`.
 
 ---
 
@@ -175,12 +119,12 @@ const iconOnly = Boolean(icon) && !children;
 
 Паттерн: `--triplex-next-Button-{Theme}_{Property}_{State}`
 
-Каждая тема (кроме LINK) имеет полный набор:
+Каждая тема (кроме `LINK`) имеет полный набор:
 - `_Background_Default/Hover/Active/Disabled`
 - `_Color_Default/Hover/Active/Disabled`
 - `_Shadow_Focus`
 
-Тема LINK — только `_Color_*` и `_Shadow_Focus` (нет фона).
+Тема `LINK` — только `_Color_*` и `_Shadow_Focus` (нет фона).
 
 При добавлении нового визуального состояния нужен новый токен в `src/generated/themesCssVariables.css`.
 
@@ -192,7 +136,17 @@ const iconOnly = Boolean(icon) && !children;
 - **`TButtonProps` union type** — должен включать все тематические интерфейсы. При добавлении новой темы — добавь интерфейс в union.
 - **`EButtonTheme` значения** — не переименовывать. Это публичное API.
 - **`EComponentSize`** — общий enum из `src/enums/EComponentSize`, не делай локальный аналог.
-- **Размеры (28px/40px/56px)** — не менять без согласования с дизайнером, другие компоненты ориентируются на эти размеры.
+- **Размеры (28px / 40px / 56px)** — не менять без согласования с дизайнером, другие компоненты ориентируются на эти размеры.
+
+---
+
+## Accessibility
+
+- Нативный `<button>` — полная поддержка клавиатуры (Tab, Enter, Space) без дополнительных атрибутов.
+- **`ButtonIcon`**: иконочная кнопка без видимого текста — потребитель **обязан** передать `aria-label` через `...rest`. Библиотека мультиязычная, текст не хардкодится.
+- **`loading`**: устанавливает `tabIndex={-1}` — кнопка исключается из tab-порядка. Если нужна доступность состояния загрузки для скринридеров, потребитель добавляет `aria-busy="true"` через props.
+- **`aria-expanded`**: управляет визуальным состоянием «раскрыто» (добавляет CSS-классы `.expanded`, `.active`). Передаётся потребителем при использовании кнопки как триггера dropdown. Отдельного prop `expanded` нет — используй стандартный HTML-атрибут.
+- Фокус-стиль через `:focus-visible` — виден только при клавиатурной навигации.
 
 ---
 
@@ -208,7 +162,7 @@ const iconOnly = Boolean(icon) && !children;
 
 ## Stories
 
-`stories/Buttons/Button.stories.tsx`
+Основные истории: `stories/Buttons/Button.stories.tsx`
 Файлы примеров: `stories/Buttons/examples/Button/`
 
 | Story | Example file | Что демонстрирует |
@@ -219,7 +173,9 @@ const iconOnly = Boolean(icon) && !children;
 | `Sizes` | `SizesExample.tsx` | SM / MD / LG для всех тем |
 | `Themes` | `ThemesExample.tsx` | Все пять тем |
 | `WithIcon` | `WithIconExample.tsx` | Icon-only и text+icon |
+| `WithNotificationIcon` | `WithNotificationIconExample.tsx` | Иконка с индикатором уведомления |
 | `BlockMode` | `BlockModeExample.tsx` | Полноширинный режим |
+| `TextWithIcon` | `TextWithIconExample.tsx` | Текст вместе с иконкой |
 
 ---
 
@@ -228,6 +184,7 @@ const iconOnly = Boolean(icon) && !children;
 | Дата | Изменение |
 |---|---|
 | 2026-03-31 | Создан документ (пилот AI-Ready) |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», переструктурированы props, добавлена колонка `Example file` в таблице Stories |
 
 ---
 
@@ -475,6 +432,27 @@ export const WithIconExample = () => (
 );
 ```
 
+### WithNotificationIcon
+
+`stories/Buttons/examples/Button/WithNotificationIconExample.tsx`
+
+```tsx
+import React from "react";
+import { Badge, Button, EButtonTheme, EComponentSize } from "@sberbusiness/triplex-next";
+import { BellStrokeNavIcon20 } from "@sberbusiness/icons-next";
+
+export const WithNotificationIconExample = () => (
+    <div style={{ position: "relative", display: "inline-flex" }}>
+        <Button
+            icon={<BellStrokeNavIcon20 paletteIndex={0} />}
+            size={EComponentSize.MD}
+            theme={EButtonTheme.SECONDARY}
+        />
+        <Badge.Dot size={EComponentSize.MD} style={{ position: "absolute", top: 4, right: 4 }} />
+    </div>
+);
+```
+
 ### BlockMode
 
 `stories/Buttons/examples/Button/BlockModeExample.tsx`
@@ -508,3 +486,30 @@ export const BlockModeExample = () => (
 );
 ```
 
+### TextWithIcon
+
+`stories/Buttons/examples/Button/TextWithIconExample.tsx`
+
+```tsx
+import React from "react";
+import { DefaulticonStrokePrdIcon16, DefaulticonStrokePrdIcon20 } from "@sberbusiness/icons-next";
+import { Button, EButtonTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const TextWithIconExample = () => (
+    <div style={{ display: "flex", alignItems: "flex-start", gap: 16 }}>
+        <Button theme={EButtonTheme.LINK} size={EComponentSize.SM}>
+            <DefaulticonStrokePrdIcon16 paletteIndex={5} />
+            <span style={{ marginLeft: 8 }}>Button text</span>
+        </Button>
+        <Button theme={EButtonTheme.LINK} size={EComponentSize.MD}>
+            <DefaulticonStrokePrdIcon20 paletteIndex={5} />
+            <span style={{ marginLeft: 8 }}>Button text</span>
+        </Button>
+        <Button theme={EButtonTheme.LINK} size={EComponentSize.LG}>
+            <DefaulticonStrokePrdIcon20 paletteIndex={5} />
+            <span style={{ marginLeft: 8 }}>Button text</span>
+        </Button>
+    </div>
+);
+```
+

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`
-
-- `ButtonDropdown` делегирует управление opened-state и close-on-outside в `ButtonDropdownExtended`.
-- Передает две render-функции: `renderButton` и `renderDropdown`.
-
-### Desktop + mobile dropdown
-
-- Desktop: рендерится `DropdownList` с `DropdownList.Item`.
-- Mobile: через `mobileViewProps` рендерится `DropdownMobileHeader` + `DropdownMobileList`.
-- После выбора любого пункта вызывается `option.onSelect?.()` и dropdown закрывается.
+| `...rest` | `IDropdownListItemProps` (без ряда запрещённых полей) | Остальные настройки `DropdownList.Item` |
 
-### Управление клавиатурой
-
-- На кнопке перехватываются `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,6 +114,7 @@ src/components/Button/
 | Дата | Изменение |
 |---|---|
 | 2026-04-15 | Создан документ AI-ready для `ButtonDropdown`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», их содержимое перенесено в `Ограничения по темам` и `Accessibility`, добавлена колонка `Example file`. |
 
 ---