@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/content/avatar.md

@@ -0,0 +1,119 @@
+---
+component: Avatar
+exports: [Avatar, AvatarGroup]
+category: content
+status: stable
+source: src/components/content/Avatar.tsx, src/components/content/AvatarGroup.tsx
+story: src/components/content/Avatar.stories.tsx, src/components/content/AvatarGroup.stories.tsx
+---
+
+# Avatar и AvatarGroup
+
+## Кратко для AI
+
+`Avatar` показывает фотографию по `src` или, если её нет или она не загрузилась,
+инициалы и стабильный градиент, вычисленные из имени. `AvatarGroup` компактно
+показывает участников (строки или `{ name, src? }`) и объявляет весь список
+одним доступным именем. Это представление человека/участников, а не бейдж
+статуса или кнопка профиля.
+
+## Когда использовать
+
+- `Avatar` — когда нужно компактно представить пользователя: с фотографией по
+  `src` или одними инициалами.
+- `AvatarGroup` — когда важна именно группа и можно показать только первых участников с
+  остатком `+N`; например, участников кампании. Фотографии передаются
+  объектами `{ name, src }`.
+- Фотография у `Avatar` добавлена «на будущее» (ADR-0048): заказчика при выпуске не
+  было, API взят по аналогам: у всех двенадцати сверенных китов у аватара есть
+  фотография с возвратом к инициалам. Ваш экран первым проверит этот API; если
+  ему понадобится другой, это не нарушение контракта.
+
+## Когда не использовать
+
+- Не подменяйте инициалы запасной картинкой: возврат к инициалам при
+  отсутствии или ошибке загрузки встроен, отдельного `fallback` у `Avatar` нет.
+- Не используйте для произвольных изображений (логотип, превью документа) — это
+  `Image`: у аватара круг фиксированного размера и доступное имя, выведенное из имени человека.
+- Не передавайте в `AvatarGroup` неполные инициалы вместо имён: доступное имя
+  группы строится из `names`.
+- Не применяйте группу как интерактивный список участников. Для выбора или
+  открытия профиля нужен отдельный контрол.
+
+## Минимальный пример
+
+```tsx
+import { Avatar, AvatarGroup } from "@olddevs/ui";
+
+<Avatar name="Анна Смирнова" />
+<Avatar name="Анна Смирнова" src="/avatars/anna.jpg" />
+<AvatarGroup names={["Анна Смирнова", "Иван Петров", "Олег Кузнецов"]} />
+<AvatarGroup names={[{ name: "Анна Смирнова", src: "/avatars/anna.jpg" }, "Иван Петров"]} />
+```
+
+## Public API
+
+### `Avatar`
+
+| Prop                          | По умолчанию | Значение                                                                                                                                        |
+| ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                        | `"IV"`       | Имя или логин; первые два символа становятся инициалами, первый символ задаёт стабильный оттенок.                                               |
+| `size`                        | `md`         | `md` — компактный размер для списков и шапок; `lg` — крупный для карточки профиля.                                                              |
+| `src`                         | —            | Адрес фотографии. Пока грузится — круг с оттенком имени; нет или ошибка — инициалы на том же круге. Пустое значение равносильно отсутствию.     |
+| `alt`                         | `name`       | Альтернативный текст фотографии. `""` — декоративная (имя рядом уже написано). Без `name` и без `alt` фото декоративно. Без `src` не действует. |
+| `className` и атрибуты `span` | —            | Передаются корневому `span`; `children` намеренно не поддерживается.                                                                            |
+
+### `AvatarGroup`
+
+| Prop         | По умолчанию              | Значение                                                                            |
+| ------------ | ------------------------- | ----------------------------------------------------------------------------------- |
+| `names`      | —                         | Обязательный полный список: строка-имя или `{ name, src? }`; формы можно смешивать. |
+| `max`        | `3`                       | Число видимых аватаров; остаток выводится как `+N`.                                 |
+| `size`       | `md`                      | Размер всех видимых аватаров: `md` или `lg`.                                        |
+| `aria-label` | все `names` через запятую | Переопределяет единое доступное имя группы.                                         |
+| `className`  | —                         | Класс корневой группы.                                                              |
+
+## Фотография и возврат к инициалам
+
+Фото рендерится через `Image` кита (ADR-0011): загрузка и отказ обрабатываются в
+одном месте. Подложка с оттенком из имени лежит на корне круга, поэтому между
+«грузится», «загрузилось» и «не загрузилось» размер не меняется и круг не
+мигает: сначала виден круг цвета имени, затем фото или инициалы. Под загруженным
+фото подложка убирается, так что прозрачный PNG не окрашивается оттенком имени.
+`Skeleton` у аватара нет. Фото вписано по `cover`, не искажается, круг и размеры `md`/`lg`
+не меняются. Смена `src` после ошибки пробует новый адрес. Без `src` разметка, вид и
+озвучивание не меняются.
+
+## Доступность
+
+`AvatarGroup` рендерится как один `role="img"` с полным списком имён.
+Внутренние круги и `+N` скрыты от скринридера, поэтому он не читает бесполезные
+двухбуквенные инициалы и не повторяет имя у фотографии: список объявляет группа.
+Не удаляйте `names` ради визуального сокращения.
+
+Одиночный `Avatar` с фотографией — `img` с именем из `alt` (по умолчанию `name`);
+если фото не загрузилось, инициалы сохраняют то же имя. Без `src` аватар не
+несёт роли, его текст — инициалы. Рядом с написанным именем человека ставьте
+`alt=""`, чтобы имя не прозвучало дважды.
+
+## Антипаттерны
+
+```tsx
+// Плохо: скринридер получит не имена, а сокращения.
+<AvatarGroup names={["АС", "ИП"]} />
+
+// Хорошо: храните понятные людям имена.
+<AvatarGroup names={["Анна Смирнова", "Иван Петров"]} max={2} />
+
+// Плохо: имя рядом уже написано, фото прозвучит вторым разом.
+<><Avatar name="Анна Смирнова" src={url} /> Анна Смирнова</>
+
+// Хорошо: фото декоративно.
+<><Avatar name="Анна Смирнова" src={url} alt="" /> Анна Смирнова</>
+```
+
+## Связанные исходники и Storybook
+
+- Исходники: `src/components/content/Avatar.tsx`, `src/components/content/AvatarGroup.tsx`.
+- Stories: `src/components/content/Avatar.stories.tsx`, `src/components/content/AvatarGroup.stories.tsx`.
+- Доступное имя группы проверяется в `tests/data.test.tsx`; фото, возврат к инициалам и неизменность разметки без `src` — в `tests/avatar.test.tsx`.

package/docs/components/content/card.en.md

@@ -0,0 +1,123 @@
+---
+component: Card
+exports: [Card]
+category: content
+status: stable
+source: src/components/content/Card.tsx
+story: src/components/content/Card.stories.tsx
+sourceHash: 13efde973162
+---
+
+# Card
+
+## Summary for AI
+
+`Card` is a visual panel with a background, border, shadow, inner padding and
+rounded corners. It does not set structure or a heading: set the heading and structure with
+nested components (`Heading`, `Text`) at the screen level. If the card is clickable, use
+`asChild` with a real button or link inside, not a `div` with `onClick`.
+
+## When to use
+
+- For a self-contained block of data, settings, a metric or a list item that
+  needs to stand apart from the background.
+- When one of the two sizes is enough: `md` for a regular panel,
+  `sm` for a compact one.
+
+## When not to use
+
+- Do not put `onClick` on the card itself without `asChild`: you get a `div`
+  that the keyboard cannot reach and that a screen reader does not announce as
+  clickable. For a clickable card, use `asChild`.
+- Do not create props for arbitrary `padding` and `radius`; only the two sizes
+  `size="sm" | "md"` are available.
+- Do not use it for a loading placeholder; use `Skeleton` for that, not a
+  panel with content.
+
+## Minimal example
+
+```tsx
+import { Card, Heading, Text } from "@olddevs/ui";
+
+<Card>
+  <Heading level={3}>Publication</Heading>
+  <Text level={2}>Scheduled for 6:00 PM</Text>
+</Card>;
+```
+
+## Public API
+
+`CardProps` accepts the standard `div` attributes, including `className`, and
+three props of its own:
+
+| Prop          | Default | Meaning                                                                                                                                                  |
+| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size`        | `md`    | `sm` sets compact padding and corner radius; `md` sets a regular panel. Size and radius change together.                                                 |
+| `asChild`     | `false` | Apply the card's look to its only child (`button`, `a`, `next/link`) and turn on the clickable styling: cursor, border highlight, focus ring.            |
+| `interactive` | `false` | A container card with a stretched link inside: cursor, border highlight, positioning context (`position: relative`) and a focus ring driven by the link. |
+
+`asChild` turns on not only the slot but also the styling of a clickable
+element: cursor, border highlight on hover and the focus ring. Otherwise every
+consumer would have to add it by hand — the very divergence the card exists to
+eliminate. A container card without `asChild` stays an ordinary container: no cursor and no highlight.
+
+```tsx
+<Card asChild size="md">
+  <button type="button" onClick={open}>
+    <Heading level={3}>Cityscapes</Heading>
+    <Text level={3}>142 photos</Text>
+  </button>
+</Card>
+```
+
+The choice between `button` and `a` is the same as for `Button`: going to
+another screen is a link (it can be opened in a new tab, its URL copied), an
+action that does not leave the screen is a button.
+
+If the card has a secondary action inside — a "More" menu, an "Add to favorites" button —
+`asChild` does not fit: you cannot nest a button in a button. Then use
+`interactive` plus a stretched link:
+
+```tsx
+<Card interactive>
+  <a href={href} className="after:absolute after:inset-0">
+    Cityscapes
+  </a>
+  <div className="relative z-10">
+    <MenuTrigger>…</MenuTrigger>
+  </div>
+</Card>
+```
+
+The focus ring outlines the card only when the link itself has focus: focus on
+the menu would outline the whole card and promise a click in the wrong place.
+
+## Accessibility and composition
+
+Without `asChild`, `Card` gets neither a role nor focus: if the panel is a
+separate region, set the semantics with nested markup, for example `Heading`
+for the title.
+
+With `asChild`, the role, focus and keyboard belong to the child, and the
+card's accessible name is its content. A consequence: you cannot nest a button
+inside a clickable card — nested interactivity is unreachable from the
+keyboard. Put the actions menu next to the card, not inside its button.
+
+## Anti-patterns
+
+```tsx
+// Bad: a div becomes a pseudo-button without a keyboard contract.
+<Card onClick={openCampaign}>…</Card>
+
+// Good: interactivity belongs to the link, and the card hands it its look.
+<Card asChild>
+  <Link href={`/campaigns/${id}`} variant="standalone">
+    …
+  </Link>
+</Card>
+```
+
+## Related sources and Storybook
+
+- Source: `src/components/content/Card.tsx`.
+- Story: `src/components/content/Card.stories.tsx`.

package/docs/components/content/card.md

@@ -0,0 +1,122 @@
+---
+component: Card
+exports: [Card]
+category: content
+status: stable
+source: src/components/content/Card.tsx
+story: src/components/content/Card.stories.tsx
+---
+
+# Card
+
+## Кратко для AI
+
+`Card` — визуальная панель с фоном, границей, тенью, внутренним отступом и
+скруглением. Структуру и заголовок она не задаёт: заголовок и структуру задавайте
+вложенными компонентами (`Heading`, `Text`) на уровне экрана. Если по карточке нажимают — это `asChild` с
+настоящей кнопкой или ссылкой внутри, а не `div` с `onClick`.
+
+## Когда использовать
+
+- Для самостоятельного блока данных, настроек, метрики или элемента списка,
+  которому нужно отделение от фона.
+- Когда достаточно одного из двух размеров: `md` для обычной
+  панели, `sm` для компактной.
+
+## Когда не использовать
+
+- Не вешайте `onClick` на саму карточку без `asChild`: получится `div`, до
+  которого не добраться с клавиатуры и о котором скринридер не сообщит, что
+  сюда можно нажать. Для нажимаемой карточки есть `asChild`.
+- Не создавайте пропсы произвольных `padding` и `radius`; доступны только
+  два размера `size="sm" | "md"`.
+- Не используйте для заглушки на время загрузки — для этого `Skeleton`, а
+  не панель с содержимым.
+
+## Минимальный пример
+
+```tsx
+import { Card, Heading, Text } from "@olddevs/ui";
+
+<Card>
+  <Heading level={3}>Публикация</Heading>
+  <Text level={2}>Запланирована на 18:00</Text>
+</Card>;
+```
+
+## Public API
+
+`CardProps` принимает стандартные атрибуты `div`, включая `className`, и три
+собственных prop:
+
+| Prop          | По умолчанию | Значение                                                                                                                                             |
+| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size`        | `md`         | `sm` даёт компактные отступ и скругление; `md` — обычную панель. Размер и радиус меняются вместе.                                                    |
+| `asChild`     | `false`      | Передать оформление единственному потомку (`button`, `a`, `next/link`) и включить оформление нажимаемого: курсор, рамку, кольцо фокуса.              |
+| `interactive` | `false`      | Карточка-контейнер с растянутой ссылкой внутри: курсор, подсветка рамки, контекст позиционирования (`position: relative`) и кольцо фокуса по ссылке. |
+
+`asChild` включает не только слот, но и оформление нажимаемого: курсор,
+подсветку рамки на наведении и кольцо фокуса. Иначе каждый потребитель дописывал
+бы это руками — то самое расхождение, ради устранения которого карточка и лежит
+в пакете. Карточка-контейнер без `asChild` остаётся обычным контейнером: без курсора и подсветки.
+
+```tsx
+<Card asChild size="md">
+  <button type="button" onClick={open}>
+    <Heading level={3}>Городские пейзажи</Heading>
+    <Text level={3}>142 фото</Text>
+  </button>
+</Card>
+```
+
+Выбор между `button` и `a` тот же, что у `Button`: переход на другой экран —
+ссылка (её открывают в новой вкладке, копируют адрес), действие без перехода на другой экран —
+кнопка.
+
+Если внутри карточки есть вторичное действие — меню «Ещё», кнопка «В избранное» —
+`asChild` не подходит: кнопку в кнопку вкладывать нельзя. Тогда `interactive`
+плюс растянутая ссылка:
+
+```tsx
+<Card interactive>
+  <a href={href} className="after:absolute after:inset-0">
+    Городские пейзажи
+  </a>
+  <div className="relative z-10">
+    <MenuTrigger>…</MenuTrigger>
+  </div>
+</Card>
+```
+
+Кольцо фокуса обводит карточку только по фокусу самой ссылки: фокус на меню
+обвёл бы карточку целиком и обещал бы нажатие не туда.
+
+## Доступность и композиция
+
+Без `asChild` `Card` не получает ни роли, ни фокуса: если панель — отдельная
+область, задайте семантику вложенной разметкой, например `Heading` для
+заголовка.
+
+С `asChild` роль, фокус и клавиатура принадлежат потомку, и доступное имя
+карточки — это его содержимое. Поэтому кнопку внутри нажимаемой
+карточки вкладывать нельзя — вложенная интерактивность недостижима с
+клавиатуры. Меню действий кладите рядом с карточкой, а не внутрь её кнопки.
+
+## Антипаттерны
+
+```tsx
+// Плохо: div становится псевдокнопкой без клавиатурного контракта.
+<Card onClick={openCampaign}>…</Card>
+
+// Хорошо: интерактивность принадлежит ссылке, а карточка отдаёт ей свой вид.
+<Card asChild>
+  <Link href={`/campaigns/${id}`} variant="standalone">
+    …
+  </Link>
+</Card>
+```
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/components/content/Card.tsx`.
+- Story: `src/components/content/Card.stories.tsx`.

package/docs/components/content/carousel.en.md

@@ -0,0 +1,236 @@
+---
+component: Carousel
+exports: [Carousel, CarouselProps, CarouselSlidesPerView]
+category: content
+status: stable
+source: src/components/content/Carousel.tsx
+story: src/components/content/Carousel.stories.tsx
+sourceHash: 25011370f63a
+---
+
+# Carousel
+
+## Summary for AI
+
+A strip of slides on native scrolling with CSS scroll-snap: the "previous" and
+"next" buttons, the mouse wheel, the trackpad, swipe and the arrow keys all move
+it; after a gesture the slide settles exactly in place. The region name is
+required — exactly one of `aria-label` and `aria-labelledby`. The number of
+slides in view is `slidesPerView` (a number or an object keyed by the kit's
+breakpoints), and the current slide is `index` / `defaultIndex` / `onIndexChange`.
+Slides never change on their own: no autoplay, no infinite strip.
+
+## When to use
+
+- A gallery, a selection or a set of cards that should fill one row of the
+  screen instead of growing downward: previews, recommendations, onboarding steps.
+- You need to show several slides at once and change their number with the screen
+  width (`slidesPerView={{ base: 1, md: 2, xl: 4 }}`).
+- You need to tie the strip to the rest of the screen: a caption, thumbnails, a
+  counter — through `index` and `onIndexChange`.
+- A component "for the future" (ADR-0048): there was no requesting screen at release, and
+  the API was modeled on comparable kits — shadcn/ui `Carousel`, Mantine `Carousel`,
+  Chakra `Carousel`, Ant `Carousel`, Fluent 2 `Carousel`. Your screen is the first
+  to test this API: if it needs a different API, that is not a violation of the contract.
+
+## When not to use
+
+- Automatically changing slides, an infinite strip, dot indicators — they do
+  not exist and never will: the kit takes on neither a pause button nor the
+  accessibility traps of autoplay (motion that cannot be stopped, text that
+  cannot be read in time).
+- A ready-made lightbox component: there is none and never will be, but a
+  viewer that pages through slides in a dialog is assembled from `Dialog` and `Carousel` — see
+  ["Viewing with a carousel in a `Dialog`"](#viewing-with-a-carousel-in-a-dialog).
+- For tabs with a single visible panel, use `Tabs`: they have different
+  semantics (`tablist`), not a strip.
+- Paged browsing of records with arrow buttons and keys is a separate task (`DetailPager`
+  in the candidate registry), not a carousel.
+- If a set can reasonably be shown in full as a grid, use `Grid`: hiding half of the content behind
+  scrolling is a price paid only when the grid does not fit.
+- For a long list of rows, use a `Table` or a list; a horizontal strip is the
+  wrong way to present it.
+
+## Minimal example
+
+```tsx
+import { Carousel } from "@olddevs/ui";
+
+<Carousel aria-label="Recommendations" slidesPerView={{ base: 1, md: 3 }}>
+  <ProductCard id="a" />
+  <ProductCard id="b" />
+  <ProductCard id="c" />
+  <ProductCard id="d" />
+</Carousel>;
+```
+
+## Public API
+
+| Prop                 | Default | Meaning                                                                                                                   |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `aria-label`         | —       | The region name as a string. Exactly one of `aria-label` and `aria-labelledby` is required; both at once is a type error. |
+| `aria-labelledby`    | —       | The region name taken from a visible heading above the strip — the heading's `id`.                                        |
+| `slidesPerView`      | `1`     | `1`, `2`, `3` or `4` slides in view; an object `{ base, sm, md, lg, xl }` — a separate number starting at each width.     |
+| `index`              | —       | The current slide, controlled mode: the leftmost visible one, zero-based.                                                 |
+| `defaultIndex`       | `0`     | The initial slide in uncontrolled mode. It is shown without animation.                                                    |
+| `onIndexChange`      | —       | `(index: number) => void` — the strip has stopped on a different slide.                                                   |
+| `children`           | —       | The slides: each direct child is one slide.                                                                               |
+| `section` attributes | —       | `className`, `id` and `data-*` are passed to the region; `ref` goes to the `<section>` (`forwardRef`).                    |
+
+**A slide is a direct child.** A fragment is one child, so slides inside it do not
+become separate slides; `null`, `false` and empty strings do not become slides.
+
+**There is no gap between slides.** A slide's width is a fraction of the row, and
+a gap would make it depend on the number of slides in view. The space between
+cards is the inner padding of the slide's content (`p-2` on the card root).
+
+### The index is the leftmost visible slide
+
+With `slidesPerView={3}` and five slides, indexes 0–2 are reachable: the strip does
+not scroll past its end, and the last view holds the slides with indexes 2–4. An index that cannot
+be reached (`index={4}` in this example) is replaced by the nearest
+reachable one.
+
+### `onIndexChange` fires after scrolling stops
+
+The callback is called when scrolling has stopped (100 ms after the last scroll
+event), not on every frame. So in controlled mode, changing `index` externally
+does not create an echo: the strip travels to the assigned slide, passes the
+intermediate ones silently, and the callback is not called on arrival — the slide
+is already the right one.
+
+This is controlled mode in the usual sense: `index` assigns the slide, and the
+callback asks the parent to change it. A parent that keeps the old index gets the
+strip back on it — smoothly, after scrolling stops. A slide you assigned yourself
+(`index`, `defaultIndex`) does not call the callback.
+
+### Buttons and edges
+
+The buttons are the kit's `Button`, icon only; their names come from the message
+catalog ("Previous slide", "Next slide"). They are disabled at the edges; if the
+whole strip fits in view, both are disabled. A pressed button that becomes
+disabled passes focus to its neighbor — a keyboard user does not end up at the
+start of the page. If you press several times in a row, each press counts from the slide the strip is
+already scrolling to.
+
+### Smoothness and `prefers-reduced-motion`
+
+The buttons scroll with `behavior: "smooth"`, but instantly under
+`prefers-reduced-motion: reduce`. The preference is read at the moment of scrolling. Settling
+on a slide after a gesture is the browser's built-in snapping, and the browser
+itself drives its animation.
+
+## Viewing with a carousel in a `Dialog`
+
+A lightbox is not a component but a composition: `Dialog` supplies the modal surface,
+focus and focus return, `Carousel` supplies the paging. It needs no new
+exports. Opening a particular slide is handled by the calling code: it remembers the index
+and the list of slides at the moment of opening, `Dialog` shows them, and
+`Carousel` starts at the right place through `defaultIndex`.
+
+```tsx
+import { Carousel, Dialog, Image } from "@olddevs/ui";
+
+const [view, setView] = useState<{ start: number; files: MediaFile[] } | null>(null);
+const [index, setIndex] = useState(0);
+
+const open = (start: number) => {
+  setIndex(start);
+  // The list is frozen on opening: an upload that lands later must not shift
+  // the slides under the user's finger.
+  setView({ start, files });
+};
+
+<Dialog
+  open={view !== null}
+  onClose={() => setView(null)}
+  title={view?.files[index]?.name ?? "Preview"}
+  subtitle={view ? `${index + 1} of ${view.files.length}` : undefined}
+  className="w-full max-w-[720px]"
+>
+  {view && (
+    <Carousel aria-label="Files" defaultIndex={view.start} onIndexChange={setIndex}>
+      {view.files.map((file) => (
+        <Image key={file.id} src={file.url} alt={file.name} ratio={16 / 9} fit="contain" />
+      ))}
+    </Carousel>
+  )}
+</Dialog>;
+```
+
+What matters here:
+
+- **`defaultIndex`, not `index`.** The dialog mounts its content on opening, so
+  the strip starts at `view.start` each time, without animation. A controlled
+  `index` is needed only if the slide can also be changed from elsewhere (thumbnails,
+  buttons in the header).
+- **The title and the counter follow `onIndexChange`.** The callback fires after
+  the strip stops, not on every frame — the title changes once the slide has
+  settled. The dialog's name stays the `title` of `Dialog`, while the slide
+  name "N of M" is announced by the strip itself.
+- **`{view && …}` inside the dialog.** While `view` is empty there is no strip
+  at all: the next opening creates it anew and does not inherit the previous
+  scroll position.
+- **A slide whose content has its own label.** The image's `alt` is the file
+  name: the slide name "N of M" does not replace it.
+- Focus: opening the dialog moves focus into it; `Escape` closes the dialog and returns
+  focus to where it was opened from. The arrow keys page through the slides when the strip is focused;
+  the strip's buttons are separate tab stops.
+
+It is convenient to open the dialog from the `onAction` of a
+[`VirtualGrid`](virtual-grid.md): a click or Enter on a cell calls `open`
+without selecting it.
+
+## Accessibility
+
+This component follows the WAI-ARIA APG Carousel pattern, without autoplay and so without a pause
+button.
+
+- The region is a `<section>` with `aria-roledescription` "carousel" (in the
+  Russian locale "карусель") and a name from `aria-label` or `aria-labelledby`.
+  Without a name the screen reader announces an unnamed region, which is why the
+  type requires the name. The carousel has no `label` prop: in the kit `label` is
+  only a visible label
+  ([conventions.md](../../conventions.md#доступное-имя)).
+- A slide is `role="group"` with `aria-roledescription` "slide" and the name "N of
+  M" from the catalog: the screen reader reads "slide, 2 of 5". The
+  `aria-roledescription` words are text that screen readers speak, so they live in the message
+  catalog and are not an ARIA token.
+- Slides outside the view are **not hidden** from the screen reader: without
+  autoplay the strip is read in full, and when focus lands on a slide that is out of view, the browser scrolls the strip to
+  that slide on its own.
+- Keyboard: Tab reaches the "previous" button, the strip and the "next" button; disabled buttons at the edges are skipped. On
+  a focused strip, the arrow keys scroll it natively, with snapping. If
+  the slides contain links and buttons, Tab through them scrolls the strip to
+  that slide.
+- The strip gets `tabIndex={0}`: a scrollable block with no place in the tab order
+  is the axe violation `scrollable-region-focusable`.
+- Give slides meaningful captions ("Photo 2: sunset") through the content — the
+  slide name "N of M" does not replace them.
+- In RTL, the scrolling and the arrows on the buttons are mirrored.
+
+## Anti-patterns
+
+- Putting interactive forms in slides when they cannot be completed without paging:
+  what is hidden past the edge is not visible and cannot be found by eye.
+- Setting `slidesPerView` to a number outside the set 1–4 (`slidesPerView={5}`) or
+  assembling the width class yourself — the set is closed, and a class for each
+  value is written out in the source.
+- Building a lightbox not from `Dialog` but on `ModalOverlay` or your own
+  scrim: the dialog name, the focus trap and the focus return are lost.
+- Changing `index` from a timer to "liven up" the strip: auto-advance is what the
+  component deliberately does not do, and the user does not have time to read.
+- Deriving the number of slides from `index` when `slidesPerView > 1`: the index
+  is the leftmost visible slide, not a "page".
+
+## Related sources and Storybook
+
+- Source: `src/components/content/Carousel.tsx`; the "value per breakpoint →
+  classes" map is the internal `src/lib/responsive.ts` (not public API).
+- Tests: `tests/carousel.test.tsx` (names, buttons, edges, `onIndexChange`, modes;
+  scrolling is stubbed because jsdom does not compute layout); snapping to a
+  slide, the gesture and the slide width at breakpoints are checked by hand in
+  the showcase in a browser; every width class in the built CSS —
+  `tests/class-coverage.test.ts`.
+- Story: `src/components/content/Carousel.stories.tsx`. The tier is core
+  (ADR-0014): its own accessibility model and its own scrolling behavior.