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

package/bundle/components/List.md

@@ -0,0 +1,247 @@
+---
+component: List
+category: Data Display
+figma-node: ""
+figma-file: ""
+related: [ListMaster, Table, TreeView, Checkbox, LoaderScreen]
+tokens: []
+stories: stories/List/List.stories.tsx
+version: "1.0"
+---
+
+# List
+
+## Назначение
+
+Семейство компонентов для списков (`<ul>` / `<li>`) с набором слотов
+для строк: контент, правый контролы-блок, хвосты слева/справа, чекбокс-
+выбор, вложенный DropdownButton, drag-and-drop. Поддерживает loading-overlay
+на уровне списка.
+
+Используй когда: нужен табличный список с повторяющимися строками и
+фиксированной визуальной структурой. Для таблиц с колонками — `Table`,
+для древовидных — `TreeView`, для master-detail интерфейсов — `ListMaster`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/List/
+├── List.tsx                                       # <ul>, loading-overlay
+├── ListSortable.tsx                               # DnD обёртка (dnd-kit)
+├── index.ts                                       # Barrel всех слотов
+├── components/
+│   ├── ListItem.tsx                               # <li> + Provider ListItemContext
+│   ├── ListItemContext.ts                         # { selected, setSelected }
+│   ├── ListItemContent.tsx                        # Основной контент строки
+│   ├── ListItemControls.tsx                       # Правый блок кнопок
+│   ├── ListItemControlsButton.tsx                 # Стилизованная кнопка в Controls
+│   ├── ListItemControlsButtonDropdown.tsx         # Кнопка с выпадающим меню
+│   ├── ListItemSelectable.tsx                     # Обёртка с Checkbox, пишет selected в Context
+│   ├── ListItemTable.tsx                          # Табличный вид строки
+│   ├── ListItemTailLeft.tsx                       # Левый хвост (иконка, аватар)
+│   ├── ListItemTailRight.tsx                      # Правый хвост
+│   ├── ListItemLoading.tsx                        # Placeholder-строка при loading
+│   ├── ListEmptyState.tsx                         # Пустое состояние
+│   ├── ListSortableItem.tsx                       # <li> с useSortable (DnD)
+│   ├── ListSortableItemControls.tsx               # DnD-handle control (drag)
+│   └── ListSortableItemTarget.tsx                 # Цель сортировки
+└── styles/*.module.less
+```
+
+---
+
+## Варианты и props
+
+### List — `IListProps extends HTMLAttributes<HTMLUListElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `loading` | `boolean` | — | Накладывает `LoaderScreen type="middle"` поверх списка. |
+| `...ulAttributes` | — | — | Стандартные `<ul>`-атрибуты. |
+
+### ListItem — `IListItemProps extends LiHTMLAttributes<HTMLLIElement>`
+
+Создаёт собственный `ListItemContext` с `{ selected, setSelected }`. Подкомпоненты (`ListItemSelectable`) пишут в него.
+
+### ListItemSelectable — `IListItemSelectableProps extends Omit<HTMLDivAttributes, "onSelect">`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `selected` | `boolean` | Да | Управляемое состояние выбора. |
+| `onSelect` | `(selected: boolean) => void` | Да | Callback при изменении. |
+
+- Внутри — `<Checkbox>` + `useEffect(() => setSelected(selected))` — синхронизирует с `ListItemContext`, чтобы сиблинги (например, стили строки) могли реагировать на выбор.
+- `<span className={styles.checkboxLabelClickArea} />` — растягивающаяся область клика (не только на чекбокс).
+
+### ListItemContent — базовый слот для текста/описания строки.
+
+### ListItemControls / ListItemControlsButton / …ButtonDropdown
+
+| Компонент | Назначение |
+|---|---|
+| `ListItemControls` | Контейнер для кнопок справа. |
+| `ListItemControlsButton` | Стилизованная кнопка-иконка. |
+| `ListItemControlsButtonDropdown` | Кнопка + вложенное выпадающее меню. |
+
+### ListItemTailLeft / ListItemTailRight — хвосты (иконки, аватары, статусы) по краям строки.
+
+### ListItemTable
+
+Табличный вид строки: внутренняя сетка для выравнивания колонок между строками.
+
+### ListItemLoading — скелетон-строка, показывается во время загрузки.
+
+### ListEmptyState — рендерится, когда `items.length === 0`, параметры для заголовка/описания/иконки.
+
+### ListSortable<T extends { id: string }> — `IListSortableProps<T>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `items` | `T[]` | Да | Массив элементов, у каждого должно быть поле `id`. |
+| `onItemsChange` | `(items: T[]) => void` | Да | Callback после перестановки. |
+| `...IListProps` | — | — | Проброс на `<List>`. |
+
+- Обёртка над `@dnd-kit/core` + `@dnd-kit/sortable`.
+- Modifiers: `restrictToParentElement` + `restrictToVerticalAxis` — нельзя перетащить в другой родитель или по горизонтали.
+- Внутри использует `AdvancedMouseSensor` / `AdvancedTouchSensor` — расширенные sensor'ы.
+
+### ListSortableItem — `IListSortableItemProps extends Omit<LiHTMLAttributes, "children">`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `id` | `string` | Да | Уникальный идентификатор, должен совпадать с `items[i].id`. |
+| `disabled` | `boolean` | Нет | Блокирует drag. |
+| `children` | `ReactNode \| (provideProps) => ReactNode` | — | **Render-props или обычные children**. Provide-props: `{ dragging, disabled, listeners, setActivatorNodeRef }`. |
+
+- Использует `useSortable` из dnd-kit, применяет `transform` стиль.
+- Render-props позволяют **селективно назначать drag handle** (через `listeners` + `setActivatorNodeRef`), а не делать перетаскиваемым всю строку.
+- `ListSortableItem.Target` (Object.assign) — подкомпонент `ListSortableItemTarget`.
+
+---
+
+## Ключевые особенности реализации
+
+### `AdvancedMouseSensor` / `AdvancedTouchSensor` — `data-draggable="false"` escape hatch
+
+```ts
+while (element !== null) {
+    if (element.dataset?.draggable === "false") return false;
+    element = element.parentElement;
+}
+```
+
+- Любой потомок с `data-draggable="false"` **блокирует инициализацию drag'а**. Используется для кнопок/ссылок внутри строки — иначе клик по ним случайно запускает перетаскивание.
+- `MouseSensor`: игнорирует правую кнопку (`button === 2`).
+- `TouchSensor`: игнорирует мультитач (`touches.length > 1`).
+
+### `ListItemContext` — связь выбора и стилей сиблингов
+
+```tsx
+<ListItemContext.Provider value={{ selected, setSelected }}>
+    <li>{children}</li>
+</ListItemContext.Provider>
+```
+
+- `ListItemSelectable` пишет `selected` в контекст через `useEffect`.
+- Другие подкомпоненты (например, `ListItemContent`) могут подписаться и изменить стиль.
+- **Паттерн "выбор известен всей строке"** — без prop-drilling.
+
+### `loading` на уровне `List`
+
+```tsx
+<ul>
+  {children}
+  {loading ? <LoaderScreen type="middle" /> : null}
+</ul>
+```
+
+LoaderScreen рендерится **внутри `<ul>`**, но позиционируется абсолютно (overlay). Структурно `<ul>` содержит `<li>` и невалидный для семантики элемент — это сознательный trade-off в пользу простоты позиционирования.
+
+### `data-tx={process.env.npm_package_version}` на `<ul>` и `<li>`
+
+Версия библиотеки в DOM для отладки. Сохранять при изменениях.
+
+### ListSortable — vertical-axis only
+
+```ts
+modifiers: [restrictToParentElement, restrictToVerticalAxis]
+```
+
+- Список только вертикальный. Для горизонтальных списков — нужен отдельный компонент (сейчас не реализован).
+
+### ListSortableItem render-props
+
+```tsx
+<ListSortableItem id="1">
+    {({ listeners, setActivatorNodeRef }) => (
+        <>
+            <ListSortableItem.Target ref={setActivatorNodeRef} {...listeners}>
+                ≡
+            </ListSortableItem.Target>
+            {/* остальной контент — не перетаскиваемый */}
+        </>
+    )}
+</ListSortableItem>
+```
+
+Стандартный паттерн dnd-kit. `setActivatorNodeRef` задаёт элемент-триггер перетаскивания (handle), `listeners` — события.
+
+---
+
+## Инварианты
+
+- **`<ul>` + `<li>`** семантика — не заменять на `<div>`.
+- **`ListItemContext` shape** (`selected`, `setSelected`) — публичная точка расширения для сторонних кастомных подкомпонентов.
+- **`data-draggable="false"`** — атрибут-escape-hatch для ListSortable. Потребители в product-коде могут опираться на него, не менять семантику.
+- **`ListSortable` требует `items[].id: string`** — id как в React key, так и в dnd-kit. Переход на number/symbol — breaking.
+- **`arrayMove` от dnd-kit** — не собственная реализация. При смене DnD-библиотеки переписать.
+- **`IListSortableItemProps.children` — `ReactNode` или функция** — публичный render-props API.
+- **`LoaderScreen` внутри `<ul>`** — визуальное решение, не менять без согласования.
+- **ForwardRef** на всех компонентах; `ListSortable` — generic через `as <T>(props) => ...` cast.
+- **`Object.assign` на `ListSortableItem` → `Target`** — сохранить.
+
+---
+
+## Accessibility
+
+- Семантика списка `<ul>`/`<li>` — правильная. Screen reader'ы объявляют "list, N items".
+- `ListItemSelectable` — `<Checkbox>` внутри: нативная клавиатурная навигация, label через расширяющую clickable-область.
+- `ListItemControlsButton` / `ListItemControlsButtonDropdown` — проверь, что `aria-label` проставлен (иконки без текста).
+- **DnD не доступен с клавиатуры** из коробки (dnd-kit поддерживает `KeyboardSensor`, но здесь не подключён). Known debt.
+- Loader'овый overlay скрывает контент — добавь `aria-busy="true"` на `<ul>` через `...rest` на время загрузки.
+
+---
+
+## Дизайн-токены
+
+Нет прямых — визуал строки зависит от подкомпонентов (`ListItemSelectable`, `ListItemControls` используют собственные стили в `styles/*.module.less`).
+
+---
+
+## Связанные компоненты
+
+- `ListMaster` — master-detail layout на базе List.
+- `Table` — табличный вид с колонками.
+- `TreeView` — древовидный список.
+- `Checkbox` — используется в `ListItemSelectable`.
+- `LoaderScreen` — overlay для loading.
+- `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/modifiers` — DnD-инфраструктура.
+
+---
+
+## Stories
+
+- `stories/List/List.stories.tsx`
+- `stories/List/ListItem.stories.tsx`
+- `stories/List/ListItemControls.stories.tsx`
+- Примеры: `stories/List/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/ListMaster.md

@@ -0,0 +1,204 @@
+---
+component: ListMaster
+category: Data Display
+figma-node: ""
+figma-file: ""
+related: [List, ChipGroup, Checkbox]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# ListMaster
+
+## Назначение
+
+Тонкий layout-контейнер для экрана "список + фильтры + контролы выбора":
+оборачивает Header (sticky, со sticky-компенсацией scroll'а), Body (контент),
+ChipGroup (горизонтальные фильтры-чипы), Footer (sticky), SelectionControls
+(пакетные действия над выбранными элементами). Всё через compound-api
+`ListMaster.Header` / `.Body` / `.Footer` / `.ChipGroup` / `.SelectionControls`.
+
+Используй когда: нужен стандартный экран списка с фильтрами сверху и
+sticky-действиями снизу. Для самого списка — отдельно `List` / `Table`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/ListMaster/
+├── ListMaster.tsx                              # <div>, compound через Object.assign
+├── index.ts                                    # Barrel
+├── components/
+│   ├── ListMasterHeader.tsx                    # sticky + scroll-компенсация при mount/unmount
+│   ├── ListMasterBody.tsx                      # прозрачный <div>-wrapper
+│   ├── ListMasterFooter.tsx                    # sticky
+│   ├── ListMasterFooterControls.tsx
+│   ├── ListMasterFooterDescription.tsx
+│   ├── ListMasterChipGroup.tsx                 # обёртка над <ChipGroup oneLine>
+│   └── SelectionControls.tsx                   # блок пакетных действий
+└── styles/
+    ├── ListMasterHeader.module.less
+    ├── ListMasterFooter.module.less
+    ├── ListMasterChipGroup.module.less
+    └── SelectionControls.module.less
+```
+
+---
+
+## Compound-структура
+
+```tsx
+<ListMaster>
+    <ListMaster.Header sticky>
+        {/* Заголовок страницы, поиск, крупные фильтры */}
+    </ListMaster.Header>
+
+    <ListMaster.ChipGroup>
+        <Chip>Фильтр 1</Chip>
+        <Chip>Фильтр 2</Chip>
+    </ListMaster.ChipGroup>
+
+    <ListMaster.SelectionControls>
+        {/* Кнопки массовых действий: "Удалить", "Экспортировать" */}
+    </ListMaster.SelectionControls>
+
+    <ListMaster.Body>
+        <List>{/* ListItem'ы */}</List>
+    </ListMaster.Body>
+
+    <ListMaster.Footer sticky>
+        <ListMaster.FooterDescription>{/* "Показано 10 из 100" */}</ListMaster.FooterDescription>
+        <ListMaster.FooterControls>{/* Pagination */}</ListMaster.FooterControls>
+    </ListMaster.Footer>
+</ListMaster>
+```
+
+---
+
+## Варианты и props
+
+### ListMaster — `IListMasterProps extends HTMLAttributes<HTMLDivElement>`
+
+Без собственных props'ов. Просто `<div>` + `data-tx` + compound-подкомпоненты.
+
+### ListMaster.Header — `IListMasterHeaderProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `sticky` | `boolean` | `true` | Добавляет класс `.sticky` (CSS `position: sticky`). |
+
+**Scroll-компенсация при mount/unmount** — см. ниже.
+
+### ListMaster.Footer — `IListMasterFooterProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `sticky` | `boolean` | `true` | Аналогично Header. Но без scroll-компенсации. |
+
+### ListMaster.FooterControls / FooterDescription
+
+Простые `<div>`-слоты с семантическими именами для Footer.
+
+### ListMaster.ChipGroup
+
+Обёртка над `<ChipGroup oneLine>` (из компонента `ChipGroup`) с доп. стилем (horizontal padding). **`oneLine` зашит** — нельзя отключить через props.
+
+### ListMaster.Body
+
+Прозрачный forwardRef-wrapper, без стилей.
+
+### ListMaster.SelectionControls
+
+`<div>` с классом `.selectionControls`. Рендерится, когда нужно показать действия над выбранными элементами (например, по флагу контроллера).
+
+---
+
+## Ключевые особенности реализации
+
+### Scroll-компенсация в `ListMasterHeader`
+
+```tsx
+useEffect(() => {
+    containerHeightRef.current = containerRef.current.getBoundingClientRect().height;
+    window.scrollTo({ top: window.scrollY + containerHeightRef.current });
+    return () => window.scrollTo({ top: Math.max(window.scrollY - containerHeightRef.current, 0) });
+}, []);
+```
+
+- **При монтировании Header** (который обычно появляется при выборе элементов — `SelectionControls` mode) — страница "проскроллена" на высоту header'а, чтобы чекбоксы не "прыгнули" вниз.
+- **При размонтировании** — обратный scroll.
+- **Критичный side effect**: меняет `window.scrollY`. Если Header рендерится и пропадает часто — поведение видно. Этот UX-паттерн специфичен для случаев "выбрал строку → появился контрол-бар".
+
+### `data-tx` на нескольких слотах
+
+`ListMaster`, `ListMasterBody`, `SelectionControls` имеют `data-tx={process.env.npm_package_version}`. Header/Footer/ChipGroup — **нет**. Неконсистентно, но это исторический паттерн — не добавляй/убирай без согласования.
+
+### `ListMasterChipGroup` зашивает `oneLine`
+
+```tsx
+<ChipGroup className={...} oneLine {...rest} ref={ref}>
+```
+
+Если потребителю нужен многострочный ChipGroup в ListMaster — использовать `<ChipGroup>` напрямую, не через `.ChipGroup` слот.
+
+### Compound через `FC & { ...slots }` + присваивания
+
+```tsx
+export interface IListMasterFC extends FC<IListMasterProps> { Body, ChipGroup, ... }
+export const ListMaster: IListMasterFC = (...) => <div>...</div>;
+ListMaster.Body = ListMasterBody;
+// ...
+```
+
+**Не `Object.assign`** — явное присваивание после определения. Паттерн-вариант, используй тот же при добавлении слотов.
+
+---
+
+## Инварианты
+
+- **`sticky=true` по умолчанию** на Header/Footer — публичный контракт.
+- **Scroll-компенсация в Header** — UX-решение, не удалять без обсуждения (ломает visual continuity в scenario "выбор элементов").
+- **`ListMasterChipGroup` зашитый `oneLine`** — контракт. Для многострочного — потребитель использует `ChipGroup` напрямую.
+- **ForwardRef** на всех слотах.
+- **Compound: `ListMaster.{Body,ChipGroup,Footer,FooterControls,FooterDescription,Header,SelectionControls}`** — публичный API.
+- **Отсутствуют собственные токены** — визуал наследуется от `ChipGroup` и общих CSS-переменных.
+- **Нет stories/тестов** — compound тонкий, покрытие лежит на демо-приложении. При добавлении новых слотов **обязательно** написать story.
+
+---
+
+## Accessibility
+
+- `<div>`-контейнеры, без ARIA-ролей. Семантика — на совести потребителя (добавь `role="region"` + `aria-label` через `...rest` для скринридеров).
+- Sticky Header не ломает фокусируемость (CSS, не portal).
+- **Scroll-переход в Header при mount** — может сбивать скринридер на слабых устройствах (меняется позиция scroll'а). Не отключается через prop.
+
+---
+
+## Дизайн-токены
+
+Нет собственных.
+
+---
+
+## Связанные компоненты
+
+- `List` / `Table` / `TreeView` — то, что обычно внутри `<ListMaster.Body>`.
+- `ChipGroup` — используется в `.ChipGroup`.
+- `Checkbox` — часто в `.SelectionControls`.
+- `Pagination` — типично в `.FooterControls`.
+
+---
+
+## Stories
+
+Нет. Кандидат на добавление при следующей работе с компонентом.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Loader.md

@@ -0,0 +1,161 @@
+---
+component: Loader
+category: Feedback
+figma-node: ""
+figma-file: ""
+related: [LoaderScreen, Skeleton]
+tokens: []
+stories: stories/Loaders/LoaderMiddle/LoaderMiddle.stories.tsx
+version: "1.0"
+---
+
+# Loader
+
+## Назначение
+
+Две точечные анимации для индикации загрузки:
+- **`LoaderSmall`** — три точки, встраивается в кнопки/инпуты, поддерживает темы (`BRAND`/`NEUTRAL`) и размеры (`SM`/`MD`/`LG`).
+- **`LoaderMiddle`** — точки с линией, для центрирования в блоке (карточки, empty-state'ы).
+
+Для полноэкранной/мозаичной загрузки — `LoaderScreen`. Для skeleton-stub — `Skeleton`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Loader/
+├── index.ts                                    # Barrel: LoaderSmall, enum (ELoaderSmallTheme/Size), LoaderMiddle
+├── LoaderSmall/
+│   ├── LoaderSmall.tsx                         # FC, <span role="status">
+│   ├── enum.ts                                 # ELoaderSmallTheme, ELoaderSmallSize (unused? см. ниже)
+│   ├── styles/LoaderSmall.module.less
+│   └── __tests__/LoaderSmall.test.tsx
+└── LoaderMiddle/
+    ├── LoaderMiddle.tsx                        # FC, без props
+    ├── styles/LoaderMiddle.module.less
+    └── __tests__/LoaderMiddle.test.tsx
+```
+
+---
+
+## Варианты и props
+
+### LoaderSmall — `ILoaderSmallProps extends HTMLAttributes<HTMLSpanElement>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `theme` | `ELoaderSmallTheme` (`BRAND` / `NEUTRAL`) | Да | Цветовая тема точек. |
+| `size` | `EComponentSize` (`SM`/`MD`/`LG`) | Да | Размер. |
+| `className`, `...HTMLSpanAttributes` | — | — | Стандартные. |
+
+**Важно:** используется общий `EComponentSize`, а НЕ `ELoaderSmallSize` (хотя последний определён в `enum.ts` и экспортирован). **`ELoaderSmallSize` — unused в самом компоненте**. Считать legacy; рефакторинг — убрать из экспорта или переключить компонент на него.
+
+### LoaderMiddle — без props
+
+```ts
+export const LoaderMiddle: React.FC = () => (...);
+```
+
+Чистая визуальная анимация. Не принимает `className`/других атрибутов — если нужна кастомизация позиционирования, оборачивай снаружи.
+
+### ELoaderSmallTheme
+
+```ts
+enum ELoaderSmallTheme { BRAND = "brand", NEUTRAL = "neutral" }
+```
+
+### ELoaderSmallSize (экспортируется, но не используется компонентом)
+
+```ts
+enum ELoaderSmallSize { SM = "sm", MD = "md", LG = "lg" }
+```
+
+---
+
+## Ключевые особенности реализации
+
+### `role="status"` + `aria-label="loading"` — хардкод
+
+Оба лоадера используют:
+```tsx
+<span role="status" aria-label="loading" ...>
+```
+
+- **Хардкод английского текста** `"loading"` — технический долг для мультиязычной версии.
+- `role="status"` + непустой accessible name — скринридер анонсирует появление loader'а (live region).
+- **Не менять `role="status"`** без согласования a11y-regression.
+
+### LoaderMiddle — 4 точки + статическая линия
+
+```tsx
+<span className={styles.line} />
+<span className={clsx(styles.dot, styles.dot1)} />
+... dot2, dot3, dot4
+```
+
+4 точки с разной задержкой анимации — передают последовательную "волну". Линия — визуальный baseline.
+
+### LoaderSmall — 3 точки
+
+```tsx
+<span .dot .dot1 />
+<span .dot .dot2 />
+<span .dot .dot3 />
+```
+
+Темы (цвет) задаются через класс на корне, цвет точек — через CSS-переменные или текущий `color` (не проверено, зависит от less-файла).
+
+### `createSizeToClassNameMap(styles)` — утилита общая
+
+Мапит `EComponentSize.SM` → `styles.sm`, и т.д. Используется в других компонентах библиотеки — паттерн сохранять.
+
+---
+
+## Инварианты
+
+- **`LoaderSmall.theme` и `LoaderSmall.size` обязательны** — не делать опциональными без default'а.
+- **`ELoaderSmallTheme`** — публичный API.
+- **`ELoaderSmallSize`** — экспортирован, но не используется — **если трогаешь**, проверь потребителей (возможно, кто-то уже импортирует) прежде чем удалять.
+- **`LoaderSmall` использует `EComponentSize`**, а не `ELoaderSmallSize` — не менять без breaking-change-плана.
+- **`LoaderMiddle` без props** — расширение API требует RFC.
+- **`role="status"` + `aria-label="loading"`** — ARIA-контракт. Не менять на `"Загрузка"` без i18n-решения для всей библиотеки.
+- **`<span>` контейнер** у LoaderSmall (inline) vs **`<div>`** у LoaderMiddle (block) — семантическое различие, не унифицировать.
+
+---
+
+## Accessibility
+
+- `role="status"` создаёт **polite live region** — screen reader анонсирует появление без прерывания. Для одновременного показа двух лоадеров скринридер может анонсировать дважды.
+- `aria-label="loading"` — **захардкожен en**. Для i18n-проекта потребитель должен переопределить через `aria-label={t("loading")}` (prop принимается через `...restProps` только у LoaderSmall).
+- `LoaderMiddle` не принимает `aria-label` через props — текст "loading" фиксирован. Known debt.
+- Нет `aria-busy` на родительском контейнере — потребитель должен добавить на секцию, находящуюся в процессе загрузки.
+
+---
+
+## Дизайн-токены
+
+Нет публичных CSS-переменных. Цвета приходят от теории (BRAND/NEUTRAL) напрямую через LESS.
+
+---
+
+## Связанные компоненты
+
+- `LoaderScreen` — оверлей с лоадером для больших областей/полноэкранного режима (использует `LoaderMiddle` или `LoaderSmall` внутри).
+- `Skeleton` — альтернатива при загрузке контента с известной структурой.
+- `Button` — LoaderSmall встраивается в кнопку при `isLoading`.
+
+---
+
+## Stories
+
+- `stories/Loaders/LoaderMiddle/LoaderMiddle.stories.tsx`
+- `stories/Loaders/LoaderSmall/LoaderSmall.stories.tsx`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |