@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/Badge.md

@@ -0,0 +1,277 @@
+---
+component: Badge
+category: Badges
+figma-node: ""
+figma-file: ""
+related: [Avatar, Chip, Tag, MarkerStatus]
+tokens:
+  - --triplex-next-Badge-Background
+stories: stories/Badge/Badge.stories.tsx
+version: "1.0"
+---
+
+# Badge
+
+## Назначение
+
+Индикатор статуса или уведомления в виде горизонтальной "таблетки" с опциональным
+префиксом, контентом и постфиксом. Имеет три размера (SM / MD / LG), которые
+соответствуют общей шкале компонентов библиотеки (`EComponentSize`).
+
+Сопутствующий `Badge.Dot` — точечный вариант (круг) для минималистичных
+индикаторов (например, "есть непрочитанное"). Badge и BadgeDot — два независимых
+компонента под одним barrel-экспортом.
+
+Используй `Badge` когда: нужна краткая метка статуса/счётчика с текстом или
+иконкой ("NEW", "12", "Beta").
+Используй `Badge.Dot` когда: нужен просто цветной кружок без текста.
+Не используй когда: нужен удаляемый тег с текстом (используй `Chip` или `Tag`);
+нужен большой статус-блок с описанием (используй `MarkerStatus`).
+
+---
+
+## Файловая структура
+
+```text
+src/components/Badge/
+├── Badge.tsx                              # React.forwardRef, compound: Badge + Badge.Dot
+├── BadgeDot.tsx                           # React.forwardRef, отдельный компонент (не subcomponent)
+├── types.ts                               # IBadgeProps, IBadgeDotProps, IBadgeContentProps
+├── index.ts                               # Barrel: types + Badge (+ Badge.Dot через compound)
+├── styles/
+│   ├── Badge.module.less                  # Root .badge (SM/MD/LG: height + border-radius)
+│   └── BadgeDot.module.less               # Root .badgeDot (SM/MD/LG: width+height, border-radius 50%)
+├── components/                            # Внутренние subcomponents (не экспортируются)
+│   ├── BadgeContent.tsx                   # React.FC с паддингами по size
+│   ├── BadgePrefix.tsx                    # React.FC, display: contents (не создаёт DOM-слоя)
+│   ├── BadgePostfix.tsx                   # React.FC, display: contents
+│   └── styles/
+│       ├── BadgeContent.module.less       # Паддинги SM=4px / MD=6px / LG=8px + noPaddingLeft/Right
+│       ├── BadgePrefix.module.less        # display: contents
+│       └── BadgePostfix.module.less       # display: contents
+└── tests/Badge.test.tsx
+```
+
+Особенности:
+- **`Badge` + `Badge.Dot` через `Object.assign`** — compound-паттерн, как у
+  `AlertProcess`. BadgeDot также экспортирован из `index.ts` (через `./Badge`),
+  но рекомендуемый путь — через `Badge.Dot`.
+- **`prefix`/`postfix` через `display: contents`** — обёртки не добавляют визуального
+  слоя, являются только семантическими якорями для DOM-тестов.
+- **`components/` папка** — прямо не экспортируется, subcomponents видны только Badge.
+
+---
+
+## Варианты и props
+
+### `IBadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "prefix" | "postfix">`
+
+**Важно:** `prefix` и `postfix` НЕ стандартные HTML-атрибуты — они переопределены
+через `Omit` и изменяют семантику.
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` (`SM`, `MD`, `LG`) | Да | Определяет высоту (16/20/24px), border-radius и внутренние паддинги. |
+| `children` | `React.ReactNode` | Нет | Основной контент (текст/иконка/число). Если не передан — рендерится только prefix+postfix. |
+| `prefix` | `React.ReactNode` | Нет | Обычно иконка слева. При наличии — у BadgeContent убирается `padding-left`. |
+| `postfix` | `React.ReactNode` | Нет | Обычно иконка или мини-кнопка справа. При наличии — у BadgeContent убирается `padding-right`. |
+| `className` | `string` | Нет | Объединяется с `styles.badge + sizeClass`. |
+| `...HTMLSpanAttributes` | — | — | Всё остальное, кроме `prefix`/`postfix`. |
+
+### `IBadgeDotProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children">`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | Да | Диаметр точки: SM=6px, MD=8px, LG=10px. |
+| `children` | `never` | — | Явно запрещено через `never` — точка без контента. |
+| `className` | `string` | Нет | Объединяется с `styles.badgeDot + sizeClass`. |
+| `...HTMLSpanAttributes` | — | — | Стандартные атрибуты `<span>`. |
+
+### Размеры
+
+**Badge (горизонтальная плашка):**
+
+| size | Height | Border-radius | Content padding-x |
+|---|---|---|---|
+| `SM` | 16px | 4px | 4px |
+| `MD` | 20px | 6px | 6px |
+| `LG` | 24px | 8px | 8px |
+
+**Badge.Dot (круг):**
+
+| size | Diameter |
+|---|---|
+| `SM` | 6px |
+| `MD` | 8px |
+| `LG` | 10px |
+
+---
+
+## Ключевые особенности реализации
+
+### `createSizeToClassNameMap` вместо локального маппинга
+
+```ts
+const SIZE_TO_CLASS_NAME_MAP = createSizeToClassNameMap(styles);
+```
+
+Утилита `src/utils/classNameMaps.ts` возвращает `{ [SM]: styles.sm, [MD]: styles.md, [LG]: styles.lg }`.
+Используется во всех Badge-файлах (`Badge.tsx`, `BadgeDot.tsx`, `BadgeContent.tsx`).
+Это единый паттерн — не дублировать маппинг локально.
+
+Если понадобится новый размер (XS, XL) — обновлять **и** `EComponentSize`, **и**
+`createSizeToClassNameMap`, **и** LESS-файлы. Помни: `createSizeToClassNameMap`
+типизирован как `Record<EComponentSize, string>` — TypeScript заставит добавить
+ключ.
+
+### `Omit<HTMLAttributes, "prefix" | "postfix">` — реальная проблема
+
+HTML-атрибут `prefix` (устаревший, для RDFa) существует на некоторых тегах.
+TypeScript не распознаёт его на `<span>`, но React.HTMLAttributes включает его
+через dom-типы. Без `Omit` prop `prefix` компонента конфликтует с HTML-атрибутом
+в типах. Не удалять Omit.
+
+### `BadgePrefix` / `BadgePostfix` — `display: contents`
+
+```less
+.badgePrefix { display: contents; }
+.badgePostfix { display: contents; }
+```
+
+Обёртка не создаёт box — её children рендерятся так, как будто `<span>`
+вообще нет, но в DOM он есть. Это позволяет:
+- Применять семантический класс для тестов.
+- Не нарушать flex-лейаут родителя.
+- Не добавлять лишних паддингов.
+
+**`display: contents` имеет a11y-баг в Safari <14** — он убирает роль элемента
+для screen reader. Для `<span>` без семантической роли это не проблема, но помни
+при расширении (не добавлять `role="button"` на BadgePrefix без тестирования).
+
+### `BadgeContent` убирает паддинги при наличии prefix/postfix
+
+```tsx
+<BadgeContent
+    size={size}
+    noPaddingLeft={Boolean(prefix)}
+    noPaddingRight={Boolean(postfix)}
+>
+```
+
+Это делает `prefix/postfix` "приклеенными" к контенту без двойного отступа. Если
+пишешь новый subcomponent внутри Badge — следуй этому паттерну (не добавляй
+горизонтальные паддинги на subcomponent-уровне, только на BadgeContent).
+
+### Compound `Badge.Dot`
+
+```ts
+export const Badge = Object.assign(
+    React.forwardRef<HTMLSpanElement, IBadgeProps>(...),
+    { Dot: BadgeDot },
+);
+```
+
+Тот же паттерн, что у `AlertProcess.Spoiler`. Одновременно `BadgeDot` экспортируется
+из `index.ts` через `./Badge` напрямую, но **рекомендуемое использование** —
+через `Badge.Dot` (единый API).
+
+### Один цветовой токен на оба
+
+`--triplex-next-Badge-Background` используется и для Badge, и для BadgeDot. Нет
+отдельного токена для `BadgeDot-Background` — оба разделяют цвет. Если нужны
+разные цвета (например, зелёная точка при сером Badge) — потребитель
+переопределяет через `style`/`className`.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен на Badge и BadgeDot. Не убирать.
+- **`size` обязателен** — без default value, чтобы потребитель явно выбирал масштаб.
+- **`EComponentSize`** — общий enum из `src/enums/EComponentSize`, не делай
+  локальный аналог. Badge входит в семейство компонентов, использующих единый
+  SM/MD/LG.
+- **`BadgeDot.children: never`** — не превращать в обычный slot. Компонент
+  намеренно пустой.
+- **`Omit<HTMLAttributes, "prefix" | "postfix">`** — не убирать, конфликт типов.
+- **`display: contents` в BadgePrefix/BadgePostfix** — не менять на `inline-flex`.
+  Меняет лейаут и ломает `noPaddingLeft/Right` логику в BadgeContent.
+- **`Badge.Dot` через Object.assign** — не убирать, потребители импортируют
+  через compound.
+- **Background-токен един** для Badge и BadgeDot — не разделять без согласования
+  с дизайнером.
+- **`white-space: nowrap`** на Badge — не убирать, иначе длинный контент ломается
+  на несколько строк и разваливает высоту.
+- **BadgeContent/Prefix/Postfix — внутренние** — не экспортировать через barrel.
+  Потребители используют только `prefix`/`postfix` props.
+
+---
+
+## Accessibility
+
+- **Никаких ARIA-ролей по умолчанию** — Badge семантически нейтрален. Если
+  Badge отображает число непрочитанных сообщений — потребитель обязан обеспечить
+  озвучку: `aria-label="5 непрочитанных сообщений"` или `role="status"`.
+- **Для статусного Badge** (например, "Online") — потребитель должен добавить
+  `role="status"` и `aria-label` / `title`, иначе screen reader прочитает только
+  визуальный текст, без контекста.
+- **BadgeDot** — чистая визуальная точка без текста. **Обязан** получать
+  `aria-label` от потребителя, иначе не воспринимается screen reader'ом. Или,
+  если это чисто декоративный индикатор рядом с другим текстом — `aria-hidden="true"`.
+- **`display: contents`** на prefix/postfix — в современных браузерах не ломает
+  a11y, но в Safari <14 может. Если поддержка старого Safari критична, делай
+  тесты.
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-Badge-Background       # Фон Badge и BadgeDot (единый токен)
+```
+
+Цвет текста внутри Badge определяется `color: inherit` от родителя (нет явного
+токена) — потребитель задаёт цвет через `Typography`-компоненты или `style`.
+
+Высоты, радиусы, паддинги, размеры точки — жёсткие значения в LESS, не токенизированы.
+Кандидат на рефакторинг при общей токенизации размеров.
+
+---
+
+## Связанные компоненты
+
+- `Avatar` (`src/components/Avatar`) — часто комбинируется с Badge: Badge на углу
+  Avatar как индикатор статуса. Позиционирование — задача потребителя.
+- `Chip` (`src/components/Chip`) — "большой Badge" с возможностью закрытия и
+  интерактивностью. Разная семантика: Badge = индикатор, Chip = тег.
+- `Tag` / `TagColor` / `TagGroup` (`src/components/Tag`) — ещё больший уровень:
+  стилизованные метки категорий с цветами.
+- `MarkerStatus` (`src/components/MarkerStatus`) — крупный блок статуса с иконкой
+  и текстом (тип сообщения).
+- `EComponentSize` (`src/enums/EComponentSize`) — общий enum трёх размеров.
+- `createSizeToClassNameMap` (`src/utils/classNameMaps.ts`) — утилита
+  размер → class.
+
+---
+
+## Stories
+
+`stories/Badge/Badge.stories.tsx`
+Файлы примеров: `stories/Badge/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` |
+| `Default` | `DefaultExample.tsx` | Базовое использование |
+| `Sizes` | `SizesExample.tsx` | Все три размера Badge |
+| `WithPrefixAndPostfix` | `WithPrefixAndPostfixExample.tsx` | Badge с иконкой слева и/или справа |
+| `DotSizes` | `DotSizesExample.tsx` | Три размера Badge.Dot |
+| `Example` | `ProductionExample.tsx` | Реальные кейсы композиции |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Body.md

@@ -0,0 +1,167 @@
+---
+component: Body
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Page, Header, Footer]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Body
+
+## Назначение
+
+Минимальный layout-контейнер для содержимого страницы. Создаёт двухуровневую
+структуру `<div>` (root + inner) с `display: flex` и `flex-grow: 1` на inner,
+что позволяет контенту растягиваться на всю доступную высоту.
+
+В текущей архитектуре `Body` — примитив, используемый внутри `BodyPage`
+(экспортируется как `Page.Body` в stories). Как самостоятельный публичный
+компонент применяется редко — чаще через `Page.Body` с дополнительными
+props (`type`, `verticalMargin`).
+
+Используй когда: собираешь кастомный layout страницы и хочешь переиспользовать
+flex-обёртку без привязки к Page.
+Не используй когда: строишь страницу по стандартному паттерну — бери `Page.Body`,
+там уже есть Island, verticalMargin и поддержка типов.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Body/
+├── Body.tsx                      # React.forwardRef, thin wrapper
+├── index.ts                      # Barrel
+├── styles/Body.module.less       # .body (flex) + .bodyInner (flex-grow: 1)
+└── __tests__/Body.test.tsx
+```
+
+Особенности:
+- Нет LESS-токенов — компонент чисто структурный.
+- **Нет собственных stories** — документируется косвенно через `Page.Body`
+  (stories/Page/BodyPage.stories.tsx).
+- **Импорт через публичный путь, а не через `../Body`**: в `BodyPage.tsx` путь
+  `@sberbusiness/triplex-next/components/Body/Body` — это сохранено намеренно,
+  paths-alias для работы в монорепозитории потребителей.
+
+---
+
+## Варианты и props
+
+### `IBodyProps extends React.HTMLAttributes<HTMLDivElement>`
+
+Интерфейс пустой — используется наследование от HTMLAttributes как есть.
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `React.ReactNode` | Контент, рендерится внутри inner-div. |
+| `className` | `string` | Объединяется с `.body` через `clsx`. |
+| `...HTMLDivAttributes` | — | Всё стандартное для `<div>`. |
+
+---
+
+## Ключевые особенности реализации
+
+### Двухуровневая обёртка
+
+```tsx
+<div className={clsx(styles.body, className)} {...rest} data-tx={...} ref={ref}>
+    <div className={styles.bodyInner}>{children}</div>
+</div>
+```
+
+Root — `display: flex; position: relative`. Inner — `flex-grow: 1; width: 100%;
+position: relative`. Двойной уровень нужен, чтобы:
+- Root мог получать `className` и event handler'ы от потребителя без поломки
+  flex-layout.
+- Inner гарантированно занимал всю ширину/высоту, что критично для корректного
+  позиционирования абсолютных потомков (position: relative на обоих уровнях).
+
+### ref идёт на root
+
+`forwardRef` прокидывает ref на **внешний div**, не на inner. Это сохраняет
+стабильный контракт (ref → тот же DOM-элемент, что получает className и spread
+props).
+
+### `data-tx` только на root
+
+Версия пакета ставится только на внешний div — второй раз на inner не нужен.
+
+### Пустой интерфейс `IBodyProps`
+
+```tsx
+export interface IBodyProps extends React.HTMLAttributes<HTMLDivElement> {}
+```
+
+ESLint может предлагать заменить на type-alias `type IBodyProps = React.HTMLAttributes<HTMLDivElement>`,
+но `interface` сохранён для возможности расширения в будущем (например, если
+потребуется добавить `verticalMargin` на уровень Body, а не BodyPage). Не
+переписывать на type.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен. Ref идёт на root div.
+- **`data-tx={process.env.npm_package_version}`** — не удалять (версия для
+  отладки).
+- **Двухуровневая структура (`.body` → `.bodyInner`)** — не схлопывать в один
+  div. От этого зависит lafyut-контракт потребителей, особенно `BodyPage`
+  (он оборачивает Body в Island для типа FIRST).
+- **`position: relative` на обоих уровнях** — не убирать. Потребители могут
+  полагаться на то, что абсолютно спозиционированные элементы привязаны к
+  этим контейнерам.
+- **`flex-grow: 1` на inner** — не убирать. Обеспечивает поведение "body
+  занимает всё доступное место по высоте".
+- **`IBodyProps` как interface (не type)** — сохранить для будущего расширения.
+- **Нет своих дизайн-токенов** — не добавлять без согласования (компонент
+  намеренно стилистически нейтрален, цвет/шрифт/отступы задаёт потребитель
+  или родитель).
+
+---
+
+## Accessibility
+
+- **Нет собственной ARIA-роли** — `<div>` семантически нейтрален. Если нужна
+  semantic main-область — потребитель передаёт `role="main"` через `...rest`
+  или использует `<main>` как обёртку снаружи.
+- **Не перехватывает фокус, не манипулирует tabindex** — полностью прозрачен
+  для навигации.
+
+---
+
+## Дизайн-токены
+
+Нет — компонент структурный, без визуального оформления.
+
+---
+
+## Связанные компоненты
+
+- `Page` (`src/components/Page`) — страничный layout. Содержит Header / Body /
+  Footer как compound-пропсы.
+- `BodyPage` / `Page.Body` (`src/components/Page/components/BodyPage.tsx`) —
+  расширенный Body с поддержкой `type` (FIRST/SECOND), `verticalMargin`,
+  опциональной обёрткой в Island. В большинстве сценариев потребитель использует
+  Page.Body, а не Body напрямую.
+- `Header` / `Page.Header`, `Footer` / `Page.Footer` — соседние компоненты страницы.
+- `Island` (`src/components/Island`) — используется внутри `Page.Body` типа FIRST,
+  даёт body карточное оформление.
+
+---
+
+## Stories
+
+Отдельных stories нет. Поведение Body показано через `Page.Body` в
+`stories/Page/BodyPage.stories.tsx` с вариациями `type` и `verticalMargin`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Button.md

@@ -0,0 +1,230 @@
+---
+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
+  - --triplex-next-Button-General_Color_Default
+  - --triplex-next-Button-General_Background_Hover
+  - --triplex-next-Button-General_Color_Hover
+  - --triplex-next-Button-General_Background_Active
+  - --triplex-next-Button-General_Color_Active
+  - --triplex-next-Button-General_Shadow_Focus
+  - --triplex-next-Button-General_Background_Disabled
+  - --triplex-next-Button-General_Color_Disabled
+  - --triplex-next-Button-Secondary_Background_Default
+  - --triplex-next-Button-Secondary_Color_Default
+  - --triplex-next-Button-Secondary_Background_Hover
+  - --triplex-next-Button-Secondary_Color_Hover
+  - --triplex-next-Button-Secondary_Background_Active
+  - --triplex-next-Button-Secondary_Color_Active
+  - --triplex-next-Button-Secondary_Shadow_Focus
+  - --triplex-next-Button-Secondary_Background_Disabled
+  - --triplex-next-Button-Secondary_Color_Disabled
+  - --triplex-next-Button-SecondaryLight_Background_Default
+  - --triplex-next-Button-SecondaryLight_Color_Default
+  - --triplex-next-Button-SecondaryLight_Background_Hover
+  - --triplex-next-Button-SecondaryLight_Color_Hover
+  - --triplex-next-Button-SecondaryLight_Background_Active
+  - --triplex-next-Button-SecondaryLight_Color_Active
+  - --triplex-next-Button-SecondaryLight_Shadow_Focus
+  - --triplex-next-Button-SecondaryLight_Background_Disabled
+  - --triplex-next-Button-SecondaryLight_Color_Disabled
+  - --triplex-next-Button-Danger_Background_Default
+  - --triplex-next-Button-Danger_Color_Default
+  - --triplex-next-Button-Danger_Background_Hover
+  - --triplex-next-Button-Danger_Color_Hover
+  - --triplex-next-Button-Danger_Background_Active
+  - --triplex-next-Button-Danger_Color_Active
+  - --triplex-next-Button-Danger_Shadow_Focus
+  - --triplex-next-Button-Danger_Background_Disabled
+  - --triplex-next-Button-Danger_Color_Disabled
+  - --triplex-next-Button-Link_Color_Default
+  - --triplex-next-Button-Link_Color_Hover
+  - --triplex-next-Button-Link_Color_Active
+  - --triplex-next-Button-Link_Shadow_Focus
+  - --triplex-next-Button-Link_Color_Disabled
+  - --triplex-next-Button-Icon_Shadow_Focus
+stories: stories/Buttons/Button.stories.tsx
+version: "1.0"
+---
+
+# Button
+
+## Назначение
+
+Основной интерактивный элемент для запуска действий. Существует в пяти визуальных темах
+и трёх размерах. Поддерживает состояния загрузки, иконки и полноширинный режим.
+
+Используй `Button` когда: нужна кнопка с текстом (с иконкой или без).
+Используй `ButtonIcon` когда: нужна кнопка только с иконкой без текста.
+Используй `ButtonDropdown` когда: нужен выбор из нескольких действий.
+
+---
+
+## Файловая структура
+
+```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` |
+
+### Размеры (`EComponentSize`)
+
+| Значение | Высота | Padding | Border-radius | Font-size |
+|---|---|---|---|---|
+| `SM` | 28px | 0 12px | 6px | 12px |
+| `MD` | 40px | 0 20px | 8px | 14px |
+| `LG` | 56px | 0 24px | 10px | 16px |
+
+### Props компонента `Button`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `theme` | `EButtonTheme` | Да | Визуальный стиль |
+| `size` | `EComponentSize` | Да | Размер |
+| `block` | `boolean` | Нет | Полноширинный режим (только не-LINK темы) |
+| `loading` | `boolean` | Нет | Состояние загрузки: скрывает контент, показывает спиннер (только не-LINK темы) |
+| `icon` | `React.ReactElement` | Нет | Иконка слева от текста; если без `children` — кнопка становится квадратной |
+| `children` | `React.ReactNode` | Нет | Текст кнопки |
+| `...HTMLButtonAttributes` | — | — | Все стандартные атрибуты `<button>` |
+
+### Props компонента `ButtonIcon`
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `shape` | `EButtonIconShape` | `SQUIRCLE` | Форма: `SQUIRCLE` (4px radius) или `CIRCLE` (50%) |
+| `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` — виден только при клавиатурной навигации.
+
+---
+
+## Дизайн-токены
+
+Паттерн: `--triplex-next-Button-{Theme}_{Property}_{State}`
+
+Каждая тема (кроме LINK) имеет полный набор:
+- `_Background_Default/Hover/Active/Disabled`
+- `_Color_Default/Hover/Active/Disabled`
+- `_Shadow_Focus`
+
+Тема LINK — только `_Color_*` и `_Shadow_Focus` (нет фона).
+
+При добавлении нового визуального состояния нужен новый токен в `src/generated/themesCssVariables.css`.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен на `Button`, `ButtonBase`, `ButtonIcon`, `ButtonDropdown`. Не убирать.
+- **`TButtonProps` union type** — должен включать все тематические интерфейсы. При добавлении новой темы — добавь интерфейс в union.
+- **`EButtonTheme` значения** — не переименовывать. Это публичное API.
+- **`EComponentSize`** — общий enum из `src/enums/EComponentSize`, не делай локальный аналог.
+- **Размеры (28px/40px/56px)** — не менять без согласования с дизайнером, другие компоненты ориентируются на эти размеры.
+
+---
+
+## Связанные компоненты
+
+- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — иконочная кнопка, часть того же компонента
+- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) — кнопка с выпадающим меню опций
+- `ButtonDropdownExtended` — контейнер для кастомного dropdown с render-функциями
+- `Loader` (`src/components/Loader`) — используется внутри Button для состояния загрузки
+- `Dropdown` (`src/components/Dropdown`) — используется внутри ButtonDropdown
+
+---
+
+## Stories
+
+`stories/Buttons/Button.stories.tsx`
+Файлы примеров: `stories/Buttons/examples/Button/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль всех props |
+| `Default` | `DefaultExample.tsx` | Базовое использование |
+| `States` | `StatesExample.tsx` | Expanded, loading, disabled |
+| `Sizes` | `SizesExample.tsx` | SM / MD / LG для всех тем |
+| `Themes` | `ThemesExample.tsx` | Все пять тем |
+| `WithIcon` | `WithIconExample.tsx` | Icon-only и text+icon |
+| `BlockMode` | `BlockModeExample.tsx` | Полноширинный режим |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-03-31 | Создан документ (пилот AI-Ready) |