@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.46.0-beta

package/bundle/components/IslandAccordion.md

@@ -1,10 +1,12 @@
 ---
 component: IslandAccordion
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [Island, IslandWidget, ExpandAnimation, Step, Button]
-tokens: []
+related: [Island, IslandWidget, ExpandAnimation, Step, ButtonIcon]
+tokens:
+  - IslandAccordion.Type1_Header_Background_Hover
+  - IslandAccordion.Type2_Header_Background_Hover
+  - IslandAccordion.Type3_Header_Background_Hover
+  - IslandAccordion.Shadow_Focus
 stories: stories/IslandAccordion/IslandAccordion.stories.tsx
 version: "1.0"
 ---
@@ -13,213 +15,255 @@ version: "1.0"
 
 ## Назначение
 
-Аккордеон — список раскрывающихся `Island`-карточек. Каждая `Item` хранит
-собственное открытое состояние (либо управляется извне через `opened`),
-анимация раскрытия делегирована `ExpandAnimation`. Поддерживает step-индикатор
-(через `Step`), кнопку удаления (`onRemove`), статусы и размеры (из `EComponentSize`)
-и типы (из `EIslandType`) — оба прокидываются детям через контекст.
+Список раскрывающихся карточек: `<ul>`, каждый элемент которого — `<li>` с карточкой `Island`,
+кнопкой-заголовком и анимированно раскрываемым содержимым. Элемент дополнительно умеет
+показывать номер шага со статусом (`Step`) и кнопку удаления.
 
-Используй когда: нужен последовательный список шагов/секций с раскрытием
-(wizard, FAQ-with-steps). Без step-индикатора — тоже валидный кейс.
-Не используй когда: нужен "плоский" аккордеон без визуала карточек —
-возьми кастомное решение или составь из `ExpandAnimation` напрямую.
+Используй когда: набор логически сгруппированных блоков нужно уместить в ограниченном
+пространстве и дать пользователю раскрывать их по одному — шаги оформления заявки, разделы
+формы, FAQ.
 
----
-
-## Файловая структура
-
-```text
-src/components/IslandAccordion/
-├── IslandAccordion.tsx              # <ul>, Provider контекста (size/type), Object.assign → Item
-├── IslandAccordionContext.ts        # IIslandAccordionContext = { size, type }
-├── index.ts                         # Barrel
-├── components/
-│   ├── IslandAccordionItem.tsx      # <li>, Island.Header с кнопкой + ExpandAnimation + Step/Remove
-│   ├── IslandAccordionContent.tsx   # Тонкая обёртка над Island.Body
-│   ├── IslandAccordionFooter.tsx    # Тонкая обёртка над Island.Footer
-│   └── index.ts
-└── styles/IslandAccordion.module.less
-```
+Не используй когда:
+- Нужна одна нераскрывающаяся карточка — возьми `Island`.
+- Нужен виджет, который сворачивается только в адаптиве, а не по клику пользователя — возьми
+  `IslandWidget`.
+- Нужны вкладки (виден ровно один раздел, заголовки в ряд) — возьми `Tabs`.
+- Нужна анимация раскрытия сама по себе, без карточки и заголовка — возьми `ExpandAnimation`.
+- Нужно дерево с раскрывающимися узлами — возьми `CollapsibleTree`.
 
 ---
 
-## Compound-структура
+## Состав
 
 ```tsx
-<IslandAccordion size={EComponentSize.MD} type={EIslandType.TYPE_1}>
-    <IslandAccordion.Item
-        id="step-1"
-        title="Шаг первый"
-        num={1}
-        status={EStepStatus.COMPLETED}
-        opened={isFirstOpen}
-        onToggle={(next, id) => setFirstOpen(next)}
-        onRemove={(id) => removeStep(id)}
-    >
-        <IslandAccordionContent>
-            {/* ... произвольный контент шага ... */}
-        </IslandAccordionContent>
-        <IslandAccordionFooter>
-            <Button>Следующий шаг</Button>
-        </IslandAccordionFooter>
-    </IslandAccordion.Item>
-</IslandAccordion>
+<IslandAccordion size type>          // <ul>, задаёт size и type через контекст
+    <IslandAccordion.Item id title>  // <li> + Island + кнопка-заголовок + ExpandAnimation
+        <IslandAccordion.Item.Content>  // Island.Body внутри ExpandAnimation
+        <IslandAccordion.Item.Footer>   // Island.Footer внутри ExpandAnimation
 ```
 
+Из barrel экспортируются и «плоские» имена: `IslandAccordionItem`, `IslandAccordionContent`,
+`IslandAccordionFooter` — вместе с точечными псевдонимами это один и тот же компонент.
+
+`Content` и `Footer` необязательны: содержимым `Item` может быть произвольный узел, он попадёт
+внутрь `ExpandAnimation` как есть. Но тогда на него не подействуют внутренние отступы аккордеона
+(они заданы на `.body` / `.footer`).
+
 ---
 
 ## Варианты и props
 
-### IslandAccordion — `IIslandAccordionProps extends HTMLAttributes<HTMLUListElement>, Pick<IIslandProps, "type">`
-
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `size` | `EComponentSize` | `MD` | Передаётся детям через контекст. |
-| `type` | `EIslandType` | `TYPE_1` | Передаётся детям через контекст. |
-| `...ulAttributes` | — | — | Обычные `<ul>`-атрибуты. |
+### IslandAccordion
 
-### IslandAccordion.Item — `IIslandAccordionItemProps extends Omit<HTMLAttributes<HTMLLIElement>, "title">`
+Обязательных props нет.
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `title` | `ReactNode` | — | Заголовок. Обязателен. |
-| `id` | `string` | — | Уникальный id (обязателен, используется как ключ и для ARIA). |
-| `num` | `number` | — | Цифра в кружке Step. Применяется только вместе со `status`. |
-| `status` | `EStepStatus` | — | Статус шага; рендерит `Step` при наличии `num`. |
-| `stepHint` | `string` | — | Подсказка рядом с цифрой. Игнорируется в `disabled`. |
-| `opened` | `boolean` | — (uncontrolled) | Управляемое состояние раскрытия. Если не передан — item uncontrolled, хранит своё состояние через `useState`. |
-| `disabled` | `boolean` | `false` | Блокирует клик по заголовку и удаление. |
-| `onToggle` | `(newOpened, id) => void` | — | Срабатывает даже в disabled? Нет — ранний return при `disabled`. |
-| `onRemove` | `(id) => void` | — | Рендерит крестик справа; при клике вызывает `onRemove(id)`. |
-| `transitionProps` | `IExpandAnimationProps["transitionProps"]` | — | Проброс в `ExpandAnimation`. |
-
-### IslandAccordion.Item.Content / Footer
-
-Тонкие обёртки над `Island.Body` / `Island.Footer` с добавлением нужных
-отступов (`styles.body`, `styles.footer`).
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер всех элементов: паддинги, скругление, отступ между элементами, размер заголовка |
+| `type` | `EIslandType` | `EIslandType.TYPE_1` | Визуальный тип карточки `Island` у элементов; влияет и на цвет hover заголовка |
 
----
+Расширяет `React.HTMLAttributes<HTMLUListElement>` — `className`, `style`, `aria-*`, `data-*`
+и обработчики попадают на корневой `<ul>`.
 
-## Ключевые особенности реализации
+Обе props раздаются элементам **через контекст**, а не через клонирование детей, поэтому между
+`IslandAccordion` и его `Item` можно вставлять произвольные обёртки. Обратная сторона: `Item`,
+отрендеренный вне `IslandAccordion`, берёт значения по умолчанию из
+`initialIslandAccordionContext` (`MD` + `TYPE_1`) и не ломается.
 
-### Controlled / uncontrolled по `opened`
+### IslandAccordion.Item
 
-- Если `opened !== undefined` — controlled; `useEffect` синхронизирует
-  внутренний `isOpen` с `opened` при изменении.
-- Если `opened === undefined` — uncontrolled; `handleHeaderClick` переключает
-  локальный `isOpen` через `setIsOpen(newOpened)`.
-- В обоих случаях вызывается `onToggle(newOpened, id)`.
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `title` | `React.ReactNode` | — | **Обязательный.** Содержимое заголовка. Оборачивается в `Title` с `tag="div"` |
+| `id` | `string` | — | **Обязательный.** Проставляется на корневой `<li>` и передаётся в `onToggle` / `onRemove` |
+| `num` | `number` | `undefined` | Номер в кружке слева от заголовка. Рендерится только вместе с `status` |
+| `status` | `EStepStatus` | `undefined` | Статус шага (цвет кружка). Без него кружок не рендерится, даже если задан `num` |
+| `stepHint` | `string` | `undefined` | Подсказка (`Tooltip` от `Step`) по наведению на кружок. Игнорируется при `disabled` |
+| `opened` | `boolean` | `undefined` | Раскрыт ли элемент. Передан — элемент управляемый, не передан — раскрывается сам |
+| `disabled` | `boolean` | `false` | Блокирует раскрытие и удаление, гасит подсказку шага, оставляет содержимое свёрнутым |
+| `onToggle` | `(newOpened: boolean, id: string) => void` | `undefined` | Клик по заголовку. Первым аргументом — состояние, в которое элемент переходит |
+| `onRemove` | `(id: string) => void` | `undefined` | Клик по кнопке удаления. Сама кнопка рендерится, **только** если колбэк передан |
+| `transitionProps` | `IExpandAnimationProps["transitionProps"]` | `undefined` | Props `Transition` (react-transition-group), пробрасываются в `ExpandAnimation` |
 
-### Размеры через маппинги
+Расширяет `Omit<React.HTMLAttributes<HTMLLIElement>, "title">` — `title` переопределён на
+`ReactNode`, поэтому HTML-атрибут `title` на `<li>` через него не задать.
 
-```ts
-SIZE_TO_TITLE_SIZE_MAP = { SM: H3, MD: H3, LG: H2 }   // Title внутри заголовка
-```
+### Управляемый и неуправляемый режим
 
-Размер `size` также влияет на общий layout через CSS-классы (`.sm`, `.md`, `.lg`).
+Один и тот же prop `opened` переключает режим:
 
-### Типы через локальный map
+- **`opened` не передан** — элемент хранит раскрытие сам. Клик по заголовку меняет его и вызывает
+  `onToggle`.
+- **`opened` передан** — раскрытие задаёт потребитель. Клик по заголовку **только** вызывает
+  `onToggle(!текущее, id)`; собственное состояние элемент не меняет и ждёт нового `opened`. Если
+  потребитель не обновит prop, элемент не раскроется.
 
-```ts
-TYPE_TO_CLASS_NAME_MAP = { TYPE_1: styles.type1, TYPE_2: styles.type2, TYPE_3: styles.type3 }
-```
+Синхронизация `opened` → внутреннее состояние идёт **в фазе рендера** (паттерн React «adjusting
+state when a prop changes»), а не в `useEffect`, поэтому промежуточный кадр со старым состоянием
+не отрисовывается. Если `opened` из заданного становится `undefined`, элемент сохраняет последнее
+синхронизированное значение и дальше управляет им сам.
 
-Дублирует `Island.utils.mapTypeToClassName`, но использует **локальные** стили
-аккордеона (в `IslandAccordion.module.less`), а не Island'овские.
+«Открыт ровно один элемент» встроенным поведением **не является**: аккордеон не знает о состоянии
+соседей. Потребитель держит id открытого элемента у себя и раздаёт `opened={id === openId}` —
+см. story `OnlyOneOpenAtATime`.
 
-### Чип `hoverable` на свёрнутом заголовке
+### Удаление
 
-```tsx
-className={clsx(styles.header, { hoverable: !isOpen })}
-```
+`onRemove` только уведомляет — элемент себя не удаляет. Убрать его из списка должен потребитель
+(см. story `Removable`).
 
-Когда item закрыт — иконка chevron реагирует на hover (меняет цвет через
-правила из `@sberbusiness/icons-next/styles/icons.css`). Когда открыт —
-класс не ставится, иконка статична.
+### Размеры
 
-### ARIA-связка через `uniqueId`
+| `size` | Паддинги заголовка / тела | `border-radius` | Отступ между элементами | Размер `Title` |
+|---|---|---|---|---|
+| `SM` | 16px | 16px | 16px | `H3` |
+| `MD` | 24px | 24px | 16px | `H3` |
+| `LG` | 32px | 32px | 24px | `H2` |
 
-- `instanceId` генерируется через `useRef(uniqueId()).current` — НЕ SSR-safe.
-  Для SSR-сценариев потребителю нужно передавать стабильный `id`.
-- `aria-expanded`, `aria-controls` (кнопка → контент), `role="region"`,
-  `aria-labelledby` (контент → кнопка) проставляются.
-- Контент рендерится внутри `ExpandAnimation` с этими ARIA-атрибутами;
-  даже в свёрнутом состоянии `ExpandAnimation` может оставлять элемент в DOM
-  (зависит от реализации) — не полагайся на "нет DOM = нет фокусируемых".
+В раскрытом состоянии нижний паддинг заголовка уменьшается (12 / 16 / 24px), чтобы заголовок и
+тело не расходились.
 
-### Кнопка удаления — снаружи карточки
+**Адаптив** (`max-width: @screen-sm-max`) устроен в двух местах и они должны сходиться:
+- LESS схлопывает `MD` до метрик `SM`, а `LG` — до метрик `MD`;
+- `useMobileView()` в TSX принудительно ставит `Title` размер `H3` при любом `size`.
 
-```tsx
-{onRemove && (
-    <span className={styles.remove}>
-        <ButtonIcon onClick={handleRemoveClick} disabled={disabled} title="Удалить">
-            <CrossStrokeSrvIcon24 paletteIndex={5} />
-        </ButtonIcon>
-    </span>
-)}
-```
+---
 
-Это **хардкод русского текста `title="Удалить"`** — нарушение правил
-мультиязычности (`aria-label`/`title` не должны быть на конкретном языке).
-**Technical debt.** Кандидат на рефакторинг: вынести в prop `removeTitle`
-или полностью убрать, оставив потребителю.
+## Дизайн-токены
 
-### `// eslint-disable-next-line react-hooks/refs`
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию —
+`src/components/DesignTokens/components/IslandAccordion.ts`.
 
-```ts
-const instanceId = useRef(uniqueId()).current;
+```text
+IslandAccordion.Type1_Header_Background_Hover
+IslandAccordion.Type2_Header_Background_Hover
+IslandAccordion.Type3_Header_Background_Hover
+IslandAccordion.Shadow_Focus
 ```
 
-Паттерн создаёт id один раз на монтировании. ESLint ругается, но это
-осознанный legacy-подход; в новом коде лучше `React.useId()`.
+Hover-фон заголовка применяется только к **свёрнутому** элементу (`&.type1:not(.opened) .header:hover`).
+`Shadow_Focus` — внутренняя рамка на `.header:focus-visible`. Фон и тень самой карточки берутся из
+токенов `Island` (`Island.Type1_Background` и т.д.), собственных у аккордеона нет. Скругления и
+отступы токенами не описаны — они заданы литералами в `styles/IslandAccordion.module.less`.
 
 ---
 
 ## Инварианты
 
-- **`IslandAccordionContext` shape** (`size`, `type`) — при изменении подхватят все items; передать извне только `type` и `size` — контекст public.
-- **`Object.assign` на `IslandAccordion` → `Item`**, на `Item` → `Content`/`Footer`. Двухуровневый compound.
-- **`<ul>` / `<li>`** — семантика списка, её нельзя заменить на `<div>` без согласования (ломает скринридеры и существующую стилизацию).
-- **`onRemove` title="Удалить"** — захардкоженный текст. Не дублировать паттерн в других компонентах; при переводе библиотеки — первая точка исправления.
-- **`forwardRef`** на корне и на `Item`; `Content`/`Footer` — `React.FC`.
-- **`opened` управляемое/неуправляемое поведение** — не нарушать (ломает интеграции).
-- **`id` обязателен** на Item — используется как React key и в ARIA.
-- **`uniqueId` из lodash** — не SSR-safe; потребители для SSR должны передавать `id` явно.
+- **`forwardRef`** у `IslandAccordion` (→ `<ul>`) и `IslandAccordionItem` (→ `<li>`) — не убирать.
+  У `IslandAccordionContent` и `IslandAccordionFooter` его нет: они объявлены как `React.FC`.
+  Добавление `forwardRef` этим двум — изменение публичного контракта.
+- **Корневые элементы `<ul>` и `<li>`** — на них держатся роли `list` / `listitem` и селекторы
+  отступов между элементами (`.item + .item.md`). Смена тега ломает и семантику, и вёрстку.
+- **`id` у `Item` обязателен и уникален в пределах страницы** — он идёт прямо в DOM-атрибут `id`
+  корневого `<li>`, а не только в колбэки. Дубли дадут невалидный DOM.
+- **Публичный API:** `IslandAccordion`, `IslandAccordionItem`, `IslandAccordionContent`,
+  `IslandAccordionFooter` и их интерфейсы props экспортируются из
+  `src/components/IslandAccordion/index.ts`. `IslandAccordionContext`,
+  `IIslandAccordionContext` и `initialIslandAccordionContext` в barrel **не** реэкспортируются —
+  это внутренний слой, менять его можно свободно.
+- **`margin-top: 0 !important` у `.footer`** гасит правило отступов `Island`
+  (`.island.{size} .islandBody + .islandFooter`), у которого специфичность в четыре класса.
+  Убрать `!important` без переписывания селектора нельзя — подвал разъедется. Подробности —
+  в комментарии в LESS и в `Island-ai.md` → «Ограничения».
+- **`.body` / `.footer` скрыты через `visibility: hidden`**, пока у элемента нет класса `.opened` —
+  «чтобы focus не попадал во внутренние элементы в закрытом состоянии» (комментарий в LESS).
+  `ExpandAnimation` независимо ставит `visibility: hidden` инлайном в фазе `exited`; классы
+  аккордеона переключаются синхронно с состоянием, инлайн-стиль — по завершении анимации.
+  Удаление любого из двух механизмов меняет момент, начиная с которого содержимое перестаёт
+  ловить фокус.
+- **Глобальный класс `hoverable`** на кнопке-заголовке приходит из `@sberbusiness/icons-next` и
+  задаёт цвет каретки при наведении. Он не из `styles` — при чистке «мёртвых» классов не удалять.
+- **Кружок шага рендерится только при `status` И `num`.** Условие намеренно записано тернарником
+  с явными проверками (`num !== undefined && num !== 0`), а не через `&&`: выражение `status && num`
+  при `num === 0` вернуло бы `0`, и React отрисовал бы текст «0». Намеренна здесь только форма записи.
+  Сам пропуск кружка при `num === 0` — **унаследованная особенность, а не желаемый контракт**:
+  ноль выглядит валидным номером шага, но исторически не рендерится. Поведение зафиксировано тестом
+  как есть; менять его — отдельная задача с записью в release notes, потому что это изменение
+  наблюдаемого поведения.
 
 ---
 
 ## Accessibility
 
-- **`<button>`-заголовок** — полная клавиатурная навигация (Tab, Enter, Space).
-- `aria-expanded` на заголовке, `aria-controls` → id контента.
-- `role="region"` + `aria-labelledby` на контенте — скринридер объявляет секцию при входе.
-- `disabled` — нативный HTML-атрибут на `<button>` + класс `.disabled` для CSS.
-- **Иконка chevron** — `aria-hidden="true"`, правильно (вся семантика на кнопке).
-- **Кнопка удаления** — title="Удалить" (см. debt выше). Для корректной мультиязычности потребитель должен переопределить через передаваемые пропы в будущем или не использовать `onRemove`.
+- Заголовок — нативный `<button type="button">` внутри `Island.Header`. Клавиатура работает
+  штатно (`Enter` / `Space`), собственных обработчиков клавиш компонент не ставит.
+- Связка заголовка и содержимого: у кнопки `id` и `aria-controls`, у раскрывающейся области
+  `role="region"` и `aria-labelledby`. Оба id генерируются автоматически
+  (`IslandAccordionItem-<n>-header` / `-body`) — потребителю их задавать не нужно и нельзя.
+- `aria-expanded` на кнопке отражает **запрошенное** состояние. При `disabled` содержимое остаётся
+  свёрнутым (`expanded={isOpen && !disabled}`), а `aria-expanded` может показывать `true`, если
+  передан `opened` — это известное расхождение.
+- Каретка помечена `aria-hidden="true"` — она декоративная.
+- Навигации стрелками между элементами нет (в WAI-ARIA Accordion Pattern она опциональна). Между
+  заголовками ходят `Tab`.
+- Список не получает `aria-label` автоматически. Если на странице несколько списков, передай его
+  сам в `IslandAccordion`.
+- Фокус при раскрытии никуда не переносится — он остаётся на заголовке.
+- **Кнопка удаления имеет захардкоженный `title="Удалить"`** — отступление от правила
+  мультиязычности `docs/ai/codestyle.md`. Задать его снаружи сейчас нельзя; починка требует нового
+  prop, то есть изменения публичного API.
 
 ---
 
-## Дизайн-токены
+## Связанные компоненты
 
-Нет прямых — цвет/тень приходят от `Island` (`--triplex-next-Island-*`).
-Chevron-цвета — из `@sberbusiness/icons-next` (palette 5).
+### Части IslandAccordion (своего AI.md не имеют)
 
----
+- `IslandAccordionItem` (он же `IslandAccordion.Item`) — раскрывающийся элемент. Вся логика
+  состояния, статуса и удаления живёт здесь.
+- `IslandAccordionContent` (он же `IslandAccordion.Item.Content`) — обёртка над `Island.Body`,
+  добавляющая класс с отступами аккордеона. Собственных props, кроме `children`, нет:
+  `className` и `...rest` она не принимает.
+- `IslandAccordionFooter` (он же `IslandAccordion.Item.Footer`) — обёртка над `Island.Footer`.
+  `IIslandAccordionFooterProps extends IIslandFooterProps`, `className` мерджится с базовым.
 
-## Связанные компоненты
+### Альтернативы (в `related`)
+
+- `Island` — та же карточка без раскрытия. `IslandAccordion` строится на нём и опирается на его
+  вёрстку: гасит отступ `Island.Footer` через `!important` и обнуляет паддинги `Island` в свою
+  пользу, поэтому правки селекторов отступов `Island` ломают аккордеон молча.
+- `IslandWidget` — виджет на `Island`, который сворачивается в адаптиве, а не по клику. Свои
+  Header / Body / Footer, частями `Island` не пользуется.
+
+### Контракты по рендеру (в `related`)
 
-- `Island` — корневая карточка каждого Item.
-- `ExpandAnimation` — раскрытие контента.
-- `Step` — номер+статус в заголовке.
-- `Typography.Title` — заголовок.
-- `ButtonIcon` — кнопка удаления.
+- `ExpandAnimation` — анимация раскрытия содержимого. Получает `role="region"`, `aria-labelledby`
+  и `transitionProps` от элемента. Именно он держит содержимое в DOM в свёрнутом состоянии
+  (`height: 0` + `visibility: hidden`), а не размонтирует его.
+- `Step` — кружок с номером и статусом слева от заголовка. `position` всегда `XFirst`,
+  `size` берётся из контекста аккордеона, `stepHint` уходит в `children` и превращается в `Tooltip`.
+- `ButtonIcon` — кнопка удаления справа от карточки (абсолютно спозиционирована **за** её
+  границами: `right: -36px` / `-40px`, поэтому у аккордеона с `onRemove` нужен внешний отступ справа).
+
+### Другие направления из «Не используй когда» (в `related` не входят)
+
+- `Tabs` — если виден ровно один раздел, а заголовки стоят в ряд.
+- `CollapsibleTree`, `CollapsibleTreeExtended` — если нужна древовидная структура.
 
 ---
 
 ## Stories
 
-`stories/IslandAccordion/IslandAccordion.stories.tsx`
-Примеры: `stories/IslandAccordion/examples/`
+Основные истории: `stories/IslandAccordion/IslandAccordion.stories.tsx`
+Файлы примеров: `stories/IslandAccordion/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный контроль `size`, `type`, `status`, `removable`, `disabled`, `title` |
+| `Default` | `DefaultExample.tsx` | Минимальный элемент: заголовок, `Content`, `Footer` с кнопками |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG: паддинги, скругление, размер заголовка |
+| `Disabled` | `DisabledExample.tsx` | `disabled`: заголовок не кликается, содержимое свёрнуто |
+| `Removable` | `RemovableExample.tsx` | `onRemove`: кнопка удаления и удаление элемента силами потребителя |
+| `WithStatus` | `WithStatusExample.tsx` | Все значения `EStepStatus` в кружке шага |
+| `WithStepHint` | `WithStepHintExample.tsx` | `stepHint`: подсказка `Tooltip` по наведению на кружок |
+| `OnlyOneOpenAtATime` | `OnlyOneOpenAtATimeExample.tsx` | Управляемый режим: одновременно раскрыт не больше одного элемента |
+| `VisualTests` | — | Скриншот-регрессия: раскрытый и свёрнутый элементы рядом |
+
+Скриншот-регрессия снимается со stories `Default`, `Sizes`, `Disabled`, `Removable`,
+`WithStatus`, `VisualTests`. `Playground`, `WithStepHint` и `OnlyOneOpenAtATime` помечены
+`testRunner: { skip: true }` — они интерактивные и дают нестабильный кадр.
 
 ---
 
@@ -227,4 +271,251 @@ Chevron-цвета — из `@sberbusiness/icons-next` (palette 5).
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-09 | Создан документ. AI-рефакторинг: JSDoc на props, компонентах и контексте; синхронизация `opened` перенесена из `useEffect` в фазу рендера (промежуточный кадр со старым состоянием больше не отрисовывается); автогенерируемые id заголовка и содержимого получили вид `IslandAccordionItem-<n>-header` / `-body`; при `num={0}` со статусом больше не отрисовывается текст «0»; добавлены unit-тесты на `IslandAccordionItem`, контекст, части и публичный контракт `IslandAccordion`. Публичный API не изменён. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/IslandAccordion/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <IslandAccordion>
+        <IslandAccordion.Item id="island-accordion-default" num={1} title="Title">
+            <IslandAccordion.Item.Content>Content</IslandAccordion.Item.Content>
+            <IslandAccordion.Item.Footer>
+                <Button theme={EButtonTheme.LINK} size={EComponentSize.MD}>
+                    Button link text
+                </Button>
+                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                    Button text
+                </Button>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                    Button text
+                </Button>
+            </IslandAccordion.Item.Footer>
+        </IslandAccordion.Item>
+    </IslandAccordion>
+);
+```
+
+### Sizes
+
+`stories/IslandAccordion/examples/SizesExample.tsx`
+
+```tsx
+import React from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size, index) => (
+            <div key={size}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+                <IslandAccordion size={size}>
+                    <IslandAccordion.Item id={`island-accordion-sizes-${size}`} num={index + 1} title="Title">
+                        <IslandAccordion.Item.Content>Content</IslandAccordion.Item.Content>
+                        <IslandAccordion.Item.Footer>
+                            <Button theme={EButtonTheme.LINK} size={size}>
+                                Button link text
+                            </Button>
+                            <Button theme={EButtonTheme.SECONDARY} size={size}>
+                                Button text
+                            </Button>
+                            <Button theme={EButtonTheme.GENERAL} size={size}>
+                                Button text
+                            </Button>
+                        </IslandAccordion.Item.Footer>
+                    </IslandAccordion.Item>
+                </IslandAccordion>
+            </div>
+        ))}
+    </div>
+);
+```
+
+### Disabled
+
+`stories/IslandAccordion/examples/DisabledExample.tsx`
+
+```tsx
+import React from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const DisabledExample = () => (
+    <IslandAccordion>
+        <IslandAccordion.Item id="island-accordion-disabled" num={1} title="Title" disabled>
+            <IslandAccordion.Item.Content>Контент аккордеона</IslandAccordion.Item.Content>
+            <IslandAccordion.Item.Footer>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                    Button Name
+                </Button>
+            </IslandAccordion.Item.Footer>
+        </IslandAccordion.Item>
+    </IslandAccordion>
+);
+```
+
+### Removable
+
+`stories/IslandAccordion/examples/RemovableExample.tsx`
+
+```tsx
+import React from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const RemovableExample = () => {
+    const handleRemove = (id: string) => document.getElementById(id)?.remove();
+
+    return (
+        <IslandAccordion>
+            <IslandAccordion.Item id="island-accordion-removable" num={1} title="Title" onRemove={handleRemove}>
+                <IslandAccordion.Item.Content>Контент аккордеона</IslandAccordion.Item.Content>
+                <IslandAccordion.Item.Footer>
+                    <Button theme={EButtonTheme.LINK} size={EComponentSize.MD}>
+                        Button link text
+                    </Button>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                </IslandAccordion.Item.Footer>
+            </IslandAccordion.Item>
+        </IslandAccordion>
+    );
+};
+```
+
+### WithStatus
+
+`stories/IslandAccordion/examples/WithStatusExample.tsx`
+
+```tsx
+import React from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize, EStepStatus } from "@sberbusiness/triplex-next";
+
+const ITEMS = [
+    { id: "accordion-status-0", status: EStepStatus.DEFAULT },
+    { id: "accordion-status-1", status: EStepStatus.DONE },
+    { id: "accordion-status-2", status: EStepStatus.ACTIVE },
+    { id: "accordion-status-3", status: EStepStatus.ERROR },
+    { id: "accordion-status-4", status: EStepStatus.DISABLED },
+    { id: "accordion-status-5", status: EStepStatus.WARNING },
+];
+
+export const WithStatusExample = () => (
+    <IslandAccordion>
+        {ITEMS.map(({ id, status }, index) => (
+            <IslandAccordion.Item key={id} id={id} num={index + 1} status={status} title="Title">
+                <IslandAccordion.Item.Content>Content</IslandAccordion.Item.Content>
+                <IslandAccordion.Item.Footer>
+                    <Button theme={EButtonTheme.LINK} size={EComponentSize.MD}>
+                        Button link text
+                    </Button>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                </IslandAccordion.Item.Footer>
+            </IslandAccordion.Item>
+        ))}
+    </IslandAccordion>
+);
+```
+
+### WithStepHint
+
+`stories/IslandAccordion/examples/WithStepHintExample.tsx`
+
+```tsx
+import React from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize, EStepStatus } from "@sberbusiness/triplex-next";
+
+export const WithStepHintExample = () => (
+    <IslandAccordion>
+        <IslandAccordion.Item
+            id="island-accordion-step-hint"
+            num={1}
+            status={EStepStatus.DONE}
+            title="Title"
+            stepHint="Текст подсказки."
+        >
+            <IslandAccordion.Item.Content>Content</IslandAccordion.Item.Content>
+            <IslandAccordion.Item.Footer>
+                <Button theme={EButtonTheme.LINK} size={EComponentSize.MD}>
+                    Button link text
+                </Button>
+                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                    Button text
+                </Button>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                    Button text
+                </Button>
+            </IslandAccordion.Item.Footer>
+        </IslandAccordion.Item>
+    </IslandAccordion>
+);
+```
+
+### OnlyOneOpenAtATime
+
+`stories/IslandAccordion/examples/OnlyOneOpenAtATimeExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { IslandAccordion, Button, EButtonTheme, EComponentSize, EStepStatus } from "@sberbusiness/triplex-next";
+
+const ITEMS = [
+    { id: "accordion-single-0", status: EStepStatus.DEFAULT },
+    { id: "accordion-single-1", status: EStepStatus.DONE },
+    { id: "accordion-single-2", status: EStepStatus.ACTIVE },
+];
+
+export const OnlyOneOpenAtATimeExample = () => {
+    const [openItemId, setOpenItemId] = useState<string>();
+
+    const handleToggle = (open: boolean, id: string) => setOpenItemId(open ? id : undefined);
+
+    return (
+        <IslandAccordion>
+            {ITEMS.map(({ id, status }, index) => (
+                <IslandAccordion.Item
+                    key={id}
+                    id={id}
+                    num={index + 1}
+                    status={status}
+                    title="Title"
+                    opened={id === openItemId}
+                    onToggle={handleToggle}
+                >
+                    <IslandAccordion.Item.Content>Content</IslandAccordion.Item.Content>
+                    <IslandAccordion.Item.Footer>
+                        <Button theme={EButtonTheme.LINK} size={EComponentSize.MD}>
+                            Button link text
+                        </Button>
+                        <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                            Button text
+                        </Button>
+                        <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                            Button text
+                        </Button>
+                    </IslandAccordion.Item.Footer>
+                </IslandAccordion.Item>
+            ))}
+        </IslandAccordion>
+    );
+};
+```
+