@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/content/empty-and-loading.md

@@ -0,0 +1,149 @@
+---
+component: EmptyAndLoading
+exports: [EmptyState, ErrorState, Skeleton]
+category: content
+status: stable
+source: src/components/content/EmptyState.tsx, src/components/content/ErrorState.tsx, src/components/content/Skeleton.tsx
+story: src/components/content/EmptyState.stories.tsx, src/components/content/ErrorState.stories.tsx, src/components/content/Skeleton.stories.tsx
+---
+
+# EmptyState, ErrorState и Skeleton
+
+## Кратко для AI
+
+Три состояния экрана, у которых нет содержимого, и они не взаимозаменяемы:
+`Skeleton` показывают, пока результат неизвестен; `EmptyState`, когда запрос
+удался и вернул пусто; `ErrorState`, когда запрос не удался. Не показывайте «Ничего не найдено»,
+пока запрос ещё выполняется, и не показывайте его же вместо отказа: пустой
+список — это результат, отказ — событие.
+
+## Когда использовать
+
+- `EmptyState` — после успешной загрузки пустого списка, отсутствия результатов
+  или первого запуска без объектов.
+- `ErrorState` — запрос завершился отказом: сбой сети, ответ 5xx, недоступный бэкенд.
+  Почти всегда вместе с действием «Попробовать снова».
+- `Skeleton` — пока результат неизвестен и место будущих данных уже понятно.
+  Подбирайте его форму по будущему содержимому: строка, аватар, кнопка, превью.
+
+## Когда не использовать
+
+- Не используйте `EmptyState` для сетевой ошибки — для неё есть `ErrorState`.
+- Не используйте `ErrorState` для сообщения внутри уже отрисованного экрана:
+  там уместнее `Alert` (он живёт в потоке содержимого), а `ErrorState` встаёт
+  **вместо** содержимого.
+- Не используйте `ErrorState` для ошибки валидации поля — это `FormField`.
+- Не используйте `Skeleton` как постоянный декоративный блок или индикатор
+  прогресса. Для неопределённой короткой работы используйте `Spinner`, а для
+  известного хода — `Progress`.
+- Не добавляйте в `EmptyState` бизнес-логику: `action` принимает готовый узел,
+  обычно `Button`, а не callback.
+
+## Минимальный пример
+
+```tsx
+import { Button, EmptyState, Skeleton } from "@olddevs/ui";
+
+{
+  isLoading ? (
+    <Skeleton width={240} height={16} borderRadius={4} />
+  ) : items.length === 0 ? (
+    <EmptyState
+      title="Ничего не найдено"
+      description="Попробуйте изменить запрос или сбросить фильтры."
+      action={
+        <Button variant="soft" onPress={resetFilters}>
+          Сбросить фильтры
+        </Button>
+      }
+    />
+  ) : (
+    <Results items={items} />
+  );
+}
+```
+
+## Public API
+
+### `EmptyState`
+
+| Prop          | По умолчанию | Значение                                                          |
+| ------------- | ------------ | ----------------------------------------------------------------- |
+| `title`       | —            | Обязательное краткое описание пустого состояния.                  |
+| `description` | —            | Дополнительное объяснение или следующий шаг.                      |
+| `icon`        | —            | Готовый декоративный узел; компонент скрывает его от скринридера. |
+| `action`      | —            | Готовый узел действия, например `Button`.                         |
+| `size`        | `md`         | `sm` — пикер или dropdown; `md` — страница либо секция.           |
+
+### `ErrorState`
+
+| Prop          | По умолчанию | Значение                                                                                                                       |
+| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `title`       | из каталога  | Общая формулировка отказа; умолчание (`errorState.title`) — «Ошибка загрузки» в `locales/ru`, «Failed to load» без провайдера. |
+| `description` | —            | Что именно не удалось: «Не удалось загрузить коллекции».                                                                       |
+| `action`      | —            | Готовый узел, обычно `Button` с «Попробовать снова».                                                                           |
+| `icon`        | `ErrorIcon`  | Своя иконка; `null` убирает её вовсе.                                                                                          |
+| `size`        | `md`         | `sm` — панель или пикер; `md` — вместо содержимого страницы.                                                                   |
+
+Геометрия у `EmptyState` и `ErrorState` общая и живёт в `src/lib/state.ts`;
+различаются они тоном и ролью в дереве доступности.
+
+### `Skeleton`
+
+| Prop                 | По умолчанию  | Значение                                                                   |
+| -------------------- | ------------- | -------------------------------------------------------------------------- |
+| `width`, `height`    | —             | Число — пиксели, строка — CSS-значение.                                    |
+| `borderRadius`       | `var(--r-md)` | Число или CSS-значение. Например, `"50%"` для аватара.                     |
+| `className`, `style` | —             | Стандартные атрибуты `div`; `style` объединяется с вычисленными размерами. |
+
+## Доступность и состояние
+
+`EmptyState` передаёт текст как обычное видимое содержимое: пустой список —
+это результат, и объявлять его немедленно незачем. Иконка всегда декоративна.
+
+`ErrorState`, наоборот, получает `role="alert"`: отказ обязан быть объявлен, иначе
+пользователь скринридера остаётся с тишиной вместо ответа. Отсюда правило
+применения: не держите `ErrorState` в разметке постоянно, скрывая его через
+CSS: он должен появляться в момент отказа, иначе объявление не сработает.
+`Skeleton` не сообщает завершение загрузки сам: владелец состояния должен
+переключить его на фактические данные или статус для скринридера.
+
+## Антипаттерны
+
+```tsx
+// Плохо: пользователю сообщают об отсутствии, хотя запрос ещё идёт.
+return <EmptyState title="Ничего не найдено" />;
+
+// Хорошо: сначала форма будущих данных.
+return isLoading ? (
+  <Skeleton width="100%" height={120} />
+) : (
+  <EmptyState title="Ничего не найдено" />
+);
+```
+
+```tsx
+// Плохо: отказ подан как пустой результат — пользователь думает, что данных нет.
+if (isError) return <EmptyState title="Ничего не найдено" />;
+
+// Хорошо: отказ назван отказом и предлагает повтор.
+if (isError)
+  return (
+    <ErrorState
+      description="Не удалось загрузить коллекции."
+      action={
+        <Button icon={<RefreshIcon />} onClick={refetch}>
+          Попробовать снова
+        </Button>
+      }
+    />
+  );
+```
+
+## Связанные исходники и Storybook
+
+- Исходники: `src/components/content/EmptyState.tsx`, `src/components/content/ErrorState.tsx`,
+  `src/components/content/Skeleton.tsx`.
+- Stories: `src/components/content/EmptyState.stories.tsx`, `src/components/content/ErrorState.stories.tsx`,
+  `src/components/content/Skeleton.stories.tsx`.
+- Тесты: `tests/error-state.test.tsx`.

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

@@ -0,0 +1,148 @@
+---
+component: Grid
+exports: [Grid, GridProps, GridColumns, GridMinItemWidth, GridGap]
+category: content
+status: stable
+source: src/components/content/Grid.tsx
+story: src/components/content/Grid.stories.tsx
+sourceHash: 964d8a4c81d8
+---
+
+# Grid
+
+## Summary for AI
+
+A responsive grid of equal columns built on Tailwind utilities. Columns are set
+by a number (a responsive ladder), by an object keyed by the kit's breakpoints
+(`base`/`sm`/`md`/`lg`/`xl`), or by a minimum cell width for auto-fill. It has
+no behavior: no roles, no keyboard, no state — only layout.
+
+## When to use
+
+- A set of uniform blocks: pricing cards, metric tiles, document previews — a
+  dozen or two, without virtualization.
+- The number of columns has to change with the screen width together with
+  `AppShell` and `FormLayout`, not on your own breakpoints.
+- A component "for the future" (ADR-0048): there was no requesting screen at release, and
+  the API was taken from analogues — Mantine `SimpleGrid`, Chakra `SimpleGrid`,
+  MUI `Grid`, Ant `Row`/`Col`, Cloudscape `ColumnLayout`. Your screen is the first
+  test of this API, not a breach of the contract.
+
+## When not to use
+
+- Hundreds of cells or keyboard selection of cells — that is `VirtualGrid`: it has
+  its own scrolling, the `listbox`/`option` roles and arrow keys across the grid.
+- Form fields in one or two columns — that is `FormLayout`: it also sets
+  label placement for the fields.
+- Cells of different widths, column merging (`span`), masonry — not here: the grid
+  has only equal columns. A complex screen layout stays with the consumer's
+  classes.
+- A stack or a row of elements with a gap is `flex` with `gap` on the consumer's
+  side; the package does not export `Stack` and `Inline`.
+
+## Minimal example
+
+```tsx
+import { Card, Grid } from "@olddevs/ui";
+
+<Grid columns={3}>
+  <Card>Basic</Card>
+  <Card>Team</Card>
+  <Card>Company</Card>
+</Grid>;
+```
+
+## Public API
+
+| Prop             | Default | Meaning                                                                                                                     |
+| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `columns`        | `1`     | A number `1`–`6` — a responsive ladder (below); an object `{ base, sm, md, lg, xl }` — the exact number from each width up. |
+| `minItemWidth`   | —       | `120`, `160`, `200`, `240`, `280`, `320` — the minimum cell width in pixels; as many columns as fit.                        |
+| `gap`            | `md`    | The gap as a scale step: `none` 0, `xs` 8, `sm` 12, `md` 16, `lg` 24, `xl` 32 pixels.                                       |
+| `as`             | `div`   | The tag: `div`, `ul` or `ol`. For a list, the children are `<li>`.                                                          |
+| `div` attributes | —       | `className`, `id`, `aria-*`, `data-*` reach the element; `ref` goes to it too (`forwardRef`).                               |
+
+`columns` and `minItemWidth` are **mutually exclusive**, and the type says so:
+there are either as many columns as you specify or as many as fit. TypeScript
+does not accept both at once. A JS consumer can still pass both — then
+`minItemWidth` wins and `columns` is ignored, and in development mode the console
+reports it once ([warning rules](../../conventions.md#предупреждения-в-режиме-разработки)).
+
+The values are closed sets, not arbitrary numbers: every class is written out in
+full in the source, otherwise Tailwind would not see it and the grid would
+silently be left without columns.
+
+### A number is a responsive ladder
+
+A single number does not mean "this many columns at any width". It means "this
+many on a wide screen": the number in `columns` is a **ladder, not a fixed
+number**. This is the owner's decision, and there is no need to change it in
+favor of "number = exactly that many columns". Exactly N columns at any width is
+the object `{ base: N }`.
+
+| Screen width        | `columns={1}` | `columns={2}` | `columns={3}`…`{6}` |
+| ------------------- | ------------- | ------------- | ------------------- |
+| up to 640           | 1             | 1             | 1                   |
+| from `sm` (640)     | 1             | 2             | 2                   |
+| from `lg` (1024) up | 1             | 2             | 3…6                 |
+
+The jump to the full number sits at `lg`, not `md`: from `md`, `AppShell` shows
+the side navigation, and it takes 240 pixels from the content. `FormLayout` with
+`columns={2}` likewise gives one column on a phone.
+
+### An object is an exact number per breakpoint
+
+```tsx
+<Grid columns={{ base: 1, sm: 2, md: 3, xl: 6 }}>{tiles}</Grid>
+<Grid columns={{ base: 3 }}>{tiles}</Grid> // three columns at any width
+```
+
+Breakpoints are mobile-first, as in Tailwind: a value applies from the given width
+and up until the next key overrides it. The breakpoints are the standard ones:
+`sm` 640, `md` 768, `lg` 1024, `xl` 1280 pixels; `base` starts at zero. This is
+the width of the **screen**, not of the container: the grid changes layout at the same
+widths as the shell. The kit has no container queries yet.
+
+### Minimum cell width
+
+```tsx
+<Grid minItemWidth={200}>{previews}</Grid>
+```
+
+The grid fills each row automatically: `repeat(auto-fill, minmax(min(100%, 200px), 1fr))`.
+Empty tracks are kept (`auto-fill`, not `auto-fit`), so three cells on a wide
+screen do not stretch across the whole row — they are the same size as the cells
+of a full row. In a container narrower than 200 pixels, a cell shrinks to the
+container's width instead of overflowing the edge.
+
+## Accessibility
+
+- By default the grid is a `div` and announces nothing: layout is not meaning.
+- Render a set that is a list with `as="ul"` (or `ol` if the order matters) and
+  `<li>` inside — the screen reader announces a list and the number of items. Name
+  the list with `aria-label` if there is no heading next to it.
+- The reading and tab order is the order of the children in the markup. The grid
+  does not change it and must not: visually reordering the cells would no longer match
+  the keyboard order.
+
+## Anti-patterns
+
+- Building a column class at runtime (`` `grid-cols-${n}` ``) — it is not in
+  the CSS. That is what `columns` is for.
+- Setting `columns={4}` and expecting four columns on a phone. For an unchanging
+  grid use `columns={{ base: 4 }}`.
+- Passing `columns` and `minItemWidth` together.
+- Putting children other than `<li>` into `as="ul"` — a screen reader
+  announces a list without items as empty.
+- Using `Grid` for hundreds of cells: all of them end up in the DOM — that is a
+  job for `VirtualGrid`.
+
+## Related sources and Storybook
+
+- Source: `src/components/content/Grid.tsx`; the "value per breakpoint → classes"
+  map is the internal `src/lib/responsive.ts` (not public API).
+- Tests: `tests/grid.test.tsx`; every class of the map in the built CSS —
+  `tests/class-coverage.test.ts`. jsdom cannot see the column count at different
+  window widths: it was checked by hand in a browser on the showcase stories.
+- Showcase: `src/components/content/Grid.stories.tsx`. The level is periphery
+  (ADR-0014): no snapshots.

package/docs/components/content/grid.md

@@ -0,0 +1,142 @@
+---
+component: Grid
+exports: [Grid, GridProps, GridColumns, GridMinItemWidth, GridGap]
+category: content
+status: stable
+source: src/components/content/Grid.tsx
+story: src/components/content/Grid.stories.tsx
+---
+
+# Grid
+
+## Кратко для AI
+
+Адаптивная сетка равных колонок на утилитах Tailwind. Колонки задаются
+числом (адаптивная лестница), объектом по брейкпойнтам кита
+(`base`/`sm`/`md`/`lg`/`xl`) или наименьшей шириной ячейки для автозаполнения.
+Поведения нет: ни ролей, ни клавиатуры, ни состояния — только раскладка.
+
+## Когда использовать
+
+- Набор однородных блоков: карточки тарифов, плитки показателей, превью
+  документов — десяток-другой, без виртуализации.
+- Число колонок должно меняться по ширине экрана вместе с `AppShell` и
+  `FormLayout`, а не на своих брейкпойнтах.
+- Компонент «на будущее» (ADR-0048): экрана-заказчика при выпуске не было, API взят по
+  аналогам — Mantine `SimpleGrid`, Chakra `SimpleGrid`, MUI `Grid`, Ant `Row`/`Col`,
+  Cloudscape `ColumnLayout`. Ваш экран — первая проверка этого API, а не
+  нарушение контракта.
+
+## Когда не использовать
+
+- Сотни ячеек или выбор ячеек с клавиатуры — это `VirtualGrid`: у него своя
+  прокрутка, роли `listbox`/`option` и стрелки по сетке.
+- Поля формы в одну-две колонки — это `FormLayout`: он ещё и передаёт полям
+  место подписи.
+- Ячейки разной ширины, объединение колонок (`span`), masonry — не здесь: сетка
+  только равных колонок. Сложная раскладка экрана остаётся классами
+  потребителя.
+- Стопка или строка элементов с зазором — это `flex` с `gap` у потребителя;
+  `Stack` и `Inline` пакет не экспортирует.
+
+## Минимальный пример
+
+```tsx
+import { Card, Grid } from "@olddevs/ui";
+
+<Grid columns={3}>
+  <Card>Базовый</Card>
+  <Card>Команда</Card>
+  <Card>Компания</Card>
+</Grid>;
+```
+
+## Public API
+
+| Проп           | По умолчанию | Значение                                                                                                             |
+| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `columns`      | `1`          | Число `1`–`6` — адаптивная лестница (ниже); объект `{ base, sm, md, lg, xl }` — точное число с каждой ширины.        |
+| `minItemWidth` | —            | `120`, `160`, `200`, `240`, `280`, `320` — наименьшая ширина ячейки в пикселях; колонок столько, сколько помещается. |
+| `gap`          | `md`         | Зазор ступенью шкалы: `none` 0, `xs` 8, `sm` 12, `md` 16, `lg` 24, `xl` 32 пикселя.                                  |
+| `as`           | `div`        | Тег: `div`, `ul` или `ol`. Для списка детьми идут `<li>`.                                                            |
+| атрибуты `div` | —            | `className`, `id`, `aria-*`, `data-*` доходят до элемента; `ref` — на него же (`forwardRef`).                        |
+
+`columns` и `minItemWidth` **взаимоисключающие**, и это сказано типом: колонок
+либо столько, сколько задано, либо столько, сколько помещается. Обе записи сразу
+TypeScript не пропустит. Потребитель на JS их всё же передаст — тогда побеждает
+`minItemWidth`, а `columns` игнорируется, и в режиме разработки консоль один раз
+пишет об этом ([правила предупреждений](../../conventions.md#предупреждения-в-режиме-разработки)).
+
+Значения — закрытые наборы, а не любые числа: каждый класс написан в исходнике
+целиком, иначе Tailwind его не увидит и сетка молча останется без колонок.
+
+### Число — адаптивная лестница
+
+Число в `columns` — **лестница**: оно задаёт число колонок на широком экране,
+на узких их меньше. Это решение владельца, и менять его в пользу «число = ровно столько
+колонок» не нужно. Ровно N колонок на любой ширине — объект `{ base: N }`.
+
+| Ширина экрана        | `columns={1}` | `columns={2}` | `columns={3}`…`{6}` |
+| -------------------- | ------------- | ------------- | ------------------- |
+| до 640               | 1             | 1             | 1                   |
+| с `sm` (640)         | 1             | 2             | 2                   |
+| с `lg` (1024) и шире | 1             | 2             | 3…6                 |
+
+Скачок к полному числу стоит на `lg`, а не на `md`: с `md` `AppShell`
+показывает боковую навигацию, и она забирает у содержимого 240 пикселей. По тому же принципу
+`FormLayout` с `columns={2}` даёт на телефоне одну колонку.
+
+### Объект — точное число по брейкпойнтам
+
+```tsx
+<Grid columns={{ base: 1, sm: 2, md: 3, xl: 6 }}>{tiles}</Grid>
+<Grid columns={{ base: 3 }}>{tiles}</Grid> // три колонки на любой ширине
+```
+
+Отсчёт mobile-first, как в Tailwind: значение действует с указанной ширины и
+выше, пока его не перекроет следующий ключ. Брейкпойнты штатные: `sm` 640,
+`md` 768, `lg` 1024, `xl` 1280 пикселей; `base` — с нуля. Это ширина **экрана**,
+а не контейнера: сетка перестраивается вместе с оболочкой. Container queries в ките
+пока нет.
+
+### Наименьшая ширина ячейки
+
+```tsx
+<Grid minItemWidth={200}>{previews}</Grid>
+```
+
+Строка заполняется сама: `repeat(auto-fill, minmax(min(100%, 200px), 1fr))`.
+Пустые дорожки остаются (`auto-fill`, не `auto-fit`), поэтому три ячейки на
+широком экране не растягиваются во всю строку — они равны ячейкам полной
+строки. Если ширина контейнера меньше 200 пикселей, ячейка сжимается до этой ширины
+и не выходит за край.
+
+## Доступность
+
+- По умолчанию сетка — `div` и ничего не объявляет: раскладка не смысл.
+- Набор, который и есть список, рисуйте `as="ul"` (или `ol`, если порядок
+  значим) с `<li>` внутри — скринридер объявит список и число элементов. Имя
+  списку — `aria-label`, если рядом нет заголовка.
+- Порядок чтения и табуляции — порядок детей в разметке. Сетка его не меняет и
+  не должна: визуальная перестановка ячеек разошлась бы с клавиатурой.
+
+## Антипаттерны
+
+- Склеивать класс колонок в рантайме (`` `grid-cols-${n}` ``) — в CSS его не
+  будет. Для этого и есть `columns`.
+- Ставить `columns={4}` и ждать четырёх колонок на телефоне. Нужна неизменная
+  сетка — `columns={{ base: 4 }}`.
+- Передавать `columns` и `minItemWidth` вместе.
+- Класть в `as="ul"` детей не `<li>` — список без элементов скринридер объявит
+  пустым.
+- Брать `Grid` под сотни ячеек: все они будут в DOM — это работа `VirtualGrid`.
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/components/content/Grid.tsx`; словарь «значение по брейкпойнтам →
+  классы» — внутренний `src/lib/responsive.ts` (не public API).
+- Тесты: `tests/grid.test.tsx`; каждый класс словаря в собранном CSS —
+  `tests/class-coverage.test.ts`. Число колонок на разной ширине окна jsdom не
+  видит: оно проверено вручную в браузере на историях витрины.
+- Витрина: `src/components/content/Grid.stories.tsx`. Уровень — периферия (ADR-0014):
+  снимков нет.

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

@@ -0,0 +1,115 @@
+---
+component: Image
+exports: [Image]
+category: content
+status: stable
+source: src/components/content/Image.tsx
+story: src/components/content/Image.stories.tsx
+sourceHash: a353dbfb16fc
+---
+
+# Image
+
+## Summary for AI
+
+`Image` handles all three states of a picture: loading, loaded and failed to load. It is built on a plain `<img>`; `next/image` is deliberately not used (ADR-0011).
+
+## When to use
+
+- Anywhere the markup would have an `<img>`: tiles, previews, object images, list rows.
+- When the URL comes from data and may turn out broken or empty — that is, almost always.
+
+## When not to use
+
+- For an icon — that is `@olddevs/ui/icons`, which has vector icons; pick an icon name by the meaning of the action (see [icons](../../icons.md)).
+- For a user's photo — there is `Avatar`: it has `src` and `alt`, a circle of fixed size and a fallback to initials, and the same `Image` handles loading inside it.
+- For an empty box that holds future content — that is `AspectRatio` or `Skeleton`.
+
+## Minimal example
+
+```tsx
+import { Image } from "@olddevs/ui";
+
+<Image src={document.previewUrl} alt="" ratio={16 / 9} className="w-full rounded-xl" />;
+```
+
+## Public API
+
+The component renders a box (`span`) and an image inside it. The box gets the size, corner radius and border; the image gets the fit.
+
+| Prop           | Default | Meaning                                                                                                                 |
+| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `src`          | —       | The image URL. `null`, `undefined` and an empty string mean "nothing to show" → fallback.                               |
+| `alt`          | —       | Required. `""` is a legitimate value: "the image is decorative".                                                        |
+| `fit`          | `cover` | `cover` fills the box, `contain` fits the whole image inside. Has no effect with `sizing="intrinsic"`.                  |
+| `sizing`       | `fill`  | `fill` — the size is set by the surrounding layout, `intrinsic` — the image sets the size (below, "Who sets the size"). |
+| `ratio`        | —       | The box aspect ratio as a number (`16 / 9`). Without it, the layout sets the height.                                    |
+| `fallback`     | icon    | A custom node instead of the icon; `null` leaves an empty box.                                                          |
+| `skeleton`     | `true`  | A skeleton under the image while it loads.                                                                              |
+| `eager`        | `false` | Turns off lazy loading — for an above-the-fold image.                                                                   |
+| `className`    | —       | Box classes: size, corner radius, border.                                                                               |
+| `imgClassName` | —       | Classes of the image itself. Rarely needed.                                                                             |
+| `imgStyle`     | —       | Inline style of the image itself; needed where the visual element is the image, not the box.                            |
+
+The other `<img>` attributes (including `onLoad`, `onError`, `draggable`, `onDoubleClick`) go to the image; handlers you pass are called together with the internal ones, not instead of them.
+
+There is no separate `radius` prop: the box accepts `className`, and the source app has seven different image radii — a three-step scale would get in the way here. It is the same reason `Skeleton` accepts numbers.
+
+## Who sets the size
+
+`fill` (the default) — the size is set by the surrounding layout: a tile in a grid, an avatar, a preview of fixed height. The image gets `h-full w-full` and fills the box according to `fit`.
+
+`intrinsic` — the image has the size, and the box wraps it. This is how the full-image viewer works: it has no height of its own, only a maximum height, and it must go on the **image**:
+
+```tsx
+<Image
+  src={photoUrl}
+  alt={title}
+  sizing="intrinsic"
+  eager
+  imgClassName="max-h-[45vh] max-w-full rounded-lg"
+/>
+```
+
+A maximum height on the box (`className`) would crop the image instead of shrinking it. And `fill` in this layout collapses everything to zero: `h-full` is a percentage of a box that has no size. Lazy loading then does not start at all, because there is nothing to show.
+
+There is no skeleton in `intrinsic` mode and there cannot be: before loading, the box wraps nothing. The calling code has to reserve the space for the image.
+
+## States
+
+- **Loading** — the skeleton sits **under** the image, not instead of it: the browser starts loading only when the `<img>` is in the tree.
+- **Loaded** — the skeleton is removed.
+- **Failed to load** — the image is replaced with the fallback; the state resets when `src` changes, otherwise a node reused by a virtualized grid for a different image would keep the fallback forever.
+
+## Accessibility
+
+`alt` is required, and it is required not for the text but for the choice: `alt=""` is a decision ("the image is decorative"), while a missing attribute is an oversight after which a screen reader reads the file name aloud.
+
+The skeleton is always decorative. The fallback inherits the decision from `alt`: when it is empty, the fallback is decorative; when it is not, the fallback takes the label itself (`role="img"` with the same name) — otherwise a load failure would turn a named object into an empty place that a screen reader does not announce. The failure itself is not announced: it is not an event for the user, but a missing preview.
+
+## Anti-patterns
+
+```tsx
+// Bad: custom failure handling on top of a component that already does it.
+const [broken, setBroken] = useState(false);
+{
+  broken ? <Placeholder /> : <Image src={src} alt="" onError={() => setBroken(true)} />;
+}
+
+// Good:
+<Image src={src} alt="" fallback={<Placeholder />} />;
+```
+
+```tsx
+// Bad: an above-the-fold image is deferred by the browser and hurts LCP.
+<Image src={hero} alt="" />
+
+// Good:
+<Image src={hero} alt="" eager />
+```
+
+## Related sources and Storybook
+
+- Source: `src/components/content/Image.tsx`
+- Stories: `src/components/content/Image.stories.tsx`
+- Tests: `tests/image.test.tsx`