@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/content/tag-group.md

@@ -0,0 +1,151 @@
+---
+component: TagGroup
+exports: [TagGroup, Tag, TagGroupProps, TagProps, TagKey]
+category: content
+status: stable
+source: src/components/content/TagGroup.tsx
+story: src/components/content/TagGroup.stories.tsx
+---
+
+# TagGroup и Tag
+
+## Кратко для AI
+
+Набор меток **для показа**: категории записи, проекты, ярлыки. Метке задают
+оттенок палитры (`hue` — точка рядом с подписью), превращают её в ссылку (`href`)
+и разрешают удаление одним обработчиком (`onRemove`). Построен на `TagGroup` из
+`react-aria-components`: стрелки между метками, Delete и Backspace, фокус после
+удаления — от неё. Выбора нет.
+
+## Когда использовать
+
+- Показать категории, проекты или ярлыки записи рядом с её содержимым.
+- Метка — ссылка на список записей этой категории.
+- Форма редактирования, где метки убирает пользователь, а добавляет их другой элемент.
+- Оттенок из палитры меток (`LABEL_HUES`) нужен рядом с подписью.
+
+## Когда не использовать
+
+- Метку выбирают или переключают, как фильтр — это `Chip` или `Segmented`.
+  `selectionMode` у `TagGroup` не пробрасывается намеренно.
+- Метка говорит о состоянии объекта (активен, ошибка, черновик) — это `StatusBadge`
+  или `Badge`: у метки смысл вкладывает человек, у статуса — система.
+- Пользователь вводит новые метки текстом — это `TagInput`. Вид метки у них общий.
+- Нужен только цветной образец без подписи — это `SwatchGroup`.
+
+## Минимальный пример
+
+```tsx
+import { Tag, TagGroup } from "@olddevs/ui";
+
+<TagGroup label="Категории">
+  <Tag id="design" hue="teal">
+    Дизайн
+  </Tag>
+  <Tag id="docs" href="/posts?category=docs">
+    Документация
+  </Tag>
+</TagGroup>;
+```
+
+Удаление и пустая группа:
+
+```tsx
+const [tags, setTags] = useState(["design", "docs"]);
+
+<TagGroup
+  aria-label="Категории записи"
+  onRemove={(keys) => setTags((current) => current.filter((tag) => !keys.has(tag)))}
+  empty="Категорий нет"
+>
+  {tags.map((tag) => (
+    <Tag key={tag} id={tag}>
+      {NAMES[tag]}
+    </Tag>
+  ))}
+</TagGroup>;
+```
+
+## Public API
+
+`TagGroup`:
+
+| Проп              | Умолчание | Назначение                                                                                                                                                                                                                                             |
+| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`           | —         | Видимая подпись группы. **Имя берётся ровно из одного источника**: `label`, `aria-label` или `aria-labelledby` — TypeScript не пропустит группу без имени (в том числе с `label`, равной `undefined`, `null` или `false`) и с двумя источниками сразу. |
+| `aria-label`      | —         | Имя группы без видимой подписи.                                                                                                                                                                                                                        |
+| `aria-labelledby` | —         | Имя от заголовка в другом месте страницы — `id` заголовка.                                                                                                                                                                                             |
+| `onRemove`        | —         | `(keys: Set<TagKey>) => void`. Задан — у меток есть кнопки удаления и работают Delete/Backspace.                                                                                                                                                       |
+| `empty`           | —         | Что показать, когда меток нет. Без него пустая группа выглядит сбоем.                                                                                                                                                                                  |
+| `className`       | —         | Класс корня; `ref` — на корень группы.                                                                                                                                                                                                                 |
+
+`Tag`:
+
+| Проп        | Умолчание | Назначение                                                               |
+| ----------- | --------- | ------------------------------------------------------------------------ |
+| `id`        | —         | Ключ метки: его получает `onRemove`. Для удаляемых наборов задавайте.    |
+| `hue`       | —         | Оттенок из `LABEL_HUES`: точка рядом с подписью. Не задан — точки нет.   |
+| `href`      | —         | Метка становится ссылкой. Ещё `target` и `rel`.                          |
+| `textValue` | —         | Текст метки для имени. Обязателен, если содержимое не строка и не число. |
+| `children`  | —         | Подпись метки.                                                           |
+
+Метки переносятся на новую строку целиком: внутри метки перенос не делается. Состояние (набор меток)
+группа не хранит: метку убирает потребитель, перерисовав группу.
+
+## Оттенок — точка рядом с подписью
+
+`hue` рисует кружок 10 пикселей слева от подписи. Заливки под текстом нет, и это
+решение палитры меток: восемь оттенков, которые читаются под текстом во всех
+трёх темах, потребовали бы вдвое больше цветов, а потребитель в заявке прямо
+допустил пару «точка и подпись рядом». Класс заливки снаружи не принимается —
+оттенок берётся из закрытого словаря.
+
+Точка скринридеру не видна (`aria-hidden`): оттенок слова не заменяет. Смысл метки
+несёт текст — иначе её не различит человек с нарушением цветового зрения.
+
+## Метка-ссылка
+
+`href` делает метку ссылкой: Enter и щелчок открывают адрес. react-aria не рисует
+`<a>` — она хранит адрес в `data-href` и открывает его при нажатии, чтобы метка
+оставалась строкой группы со стрелками и удалением. Цена: нет контекстного меню
+«открыть в новой вкладке». Для клиентской маршрутизации оберните приложение в
+`RouterProvider` из `react-aria-components`.
+
+## Доступность и клавиатура
+
+| Клавиша                | Что делает                                        |
+| ---------------------- | ------------------------------------------------- |
+| `←` / `→`              | Между метками                                     |
+| `Delete` / `Backspace` | Удаляют метку под фокусом (если задан `onRemove`) |
+| `Enter`                | Открывает ссылку у метки с `href`                 |
+
+- После удаления фокус остаётся в группе, на соседней метке.
+- Роль группы — `grid`, метки — `row`; имя группы обязательно. Видимая подпись
+  вместе с `aria-label` запрещена типом: атрибут перекрыл бы текст на экране, и на
+  слух группа называлась бы иначе
+  ([правило имени](../../conventions.md#доступное-имя)).
+- **Имя кнопки удаления — из каталога сообщений, с подписью метки внутри**
+  («Удалить: Дизайн», `Remove: Design`; ключ `tagGroup.remove`). Подпись вписана
+  в строку, потому что порядок слов принадлежит языку; поэтому у кнопки пустой
+  `aria-labelledby` — иначе react-aria дописала бы подпись метки второй раз.
+- Кнопка удаления — это `Button` из react-aria со `slot="remove"`, а не
+  `<button>`: поведение приходит через контекст react-aria.
+
+## Антипаттерны
+
+- Заливать метку цветом оттенка под текстом: контраст в трёх темах не обещан.
+- Делать метки выбираемыми: для этого `Chip` и `Segmented`.
+- Передавать нетекстовое содержимое без `textValue`: у метки и у кнопки удаления
+  не будет имени.
+- Сообщать оттенком смысл («красная — ошибка»): оттенки палитры не тоны, статус —
+  `StatusBadge`.
+- Собирать кнопку удаления руками: теряются Delete/Backspace и возврат фокуса.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/content/TagGroup.tsx`, общий вид метки — `src/lib/tag.ts`
+  (им же пользуется `TagInput`)
+- Палитра оттенков: `LABEL_HUES`, `LABEL_BG_CLASS` — [`docs/palette.md`](../../palette.md)
+- Тесты: `tests/tag-group.test.tsx`
+- Витрина: `src/components/content/TagGroup.stories.tsx`
+- Соседи: [TagInput](../inputs/tag-input.md), [SwatchGroup](../inputs/swatch-group.md), [Chip](../actions/chip.md)

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

@@ -0,0 +1,77 @@
+---
+component: Timeline
+exports: [Timeline]
+category: content
+status: stable
+source: src/components/content/Timeline.tsx
+story: src/components/content/Timeline.stories.tsx
+sourceHash: ce8736050ae0
+---
+
+# Timeline
+
+## Summary for AI
+
+`Timeline` is a list of process steps: what has already happened and how it ended. Each step has its own state, and any of them can fail.
+
+## When to use
+
+- When you need to monitor a running or finished process: a task pipeline, a publication history, import steps.
+- When a step can end in failure and this must be shown next to it, not as an overall status at the top.
+
+## When not to use
+
+- For a multi-screen wizard — that is `Stepper`: it has a linear `current`, the steps ahead have not happened yet and cannot fail, and a click leads back.
+- For a single state of an object — that is `StatusBadge`.
+- For a message about the failure of the whole operation — that is `Alert` or `ErrorState`.
+
+The difference from `Stepper` is not stylistic, and it is the reason the task-step pipeline in the source app did not move to `Stepper` and stayed hand-written:
+
+|              | `Stepper`                              | `Timeline`                       |
+| ------------ | -------------------------------------- | -------------------------------- |
+| state        | one for the whole timeline (`current`) | its own for each step            |
+| step failure | cannot be expressed                    | `status: "failed"`               |
+| interactive  | yes, a click on a completed step       | no, it only displays the process |
+
+## Minimal example
+
+```tsx
+import { Timeline } from "@olddevs/ui";
+
+<Timeline
+  aria-label="Task steps"
+  items={steps.map((s) => ({
+    id: s.id,
+    label: s.step_name,
+    status: s.status,
+    statusLabel: STATUS_LABEL[s.status],
+    details: s.details,
+  }))}
+/>;
+```
+
+## Public API
+
+| Prop         | Meaning                                                     |
+| ------------ | ----------------------------------------------------------- |
+| `items`      | An array of steps. If empty, the component renders nothing. |
+| `aria-label` | The accessible name of the timeline.                        |
+| `className`  | Wrapper classes.                                            |
+
+A step: `id`, `label`, `status` (`pending` · `running` · `success` · `failed`), optional `statusLabel`, `details`, `time`.
+
+**The state label is a prop, not derived from `status`.** The words "done" and "error" belong to the domain: an import task and a payment word them differently. The "status → label" mapping lives with the consumer, next to the domain — the same as with `StatusBadge`.
+
+## Accessibility
+
+The markup is an ordered list (`ol`): steps go in order, and a screen reader must announce both the order and the total count. A set of `div` elements announces neither. The running step is marked `aria-current="step"`; the dots and connecting lines are decorative and hidden.
+
+## Colors
+
+The colors come from the tone vocabulary (`TONE_TOKENS`) and are not defined anew: "error" means the same color here, in `Alert`, in `StatusBadge` and on the delete button. `pending` is deliberately neutral and muted — a step that has not started yet is not an event.
+
+## Related sources and Storybook
+
+- Source: `src/components/content/Timeline.tsx`
+- Stories: `src/components/content/Timeline.stories.tsx`
+- Tests: `tests/timeline.test.tsx`

package/docs/components/content/timeline.md

@@ -0,0 +1,76 @@
+---
+component: Timeline
+exports: [Timeline]
+category: content
+status: stable
+source: src/components/content/Timeline.tsx
+story: src/components/content/Timeline.stories.tsx
+---
+
+# Timeline
+
+## Кратко для AI
+
+`Timeline` — лента шагов процесса: что уже произошло и чем закончилось. У каждого шага своё состояние, и любой может провалиться.
+
+## Когда использовать
+
+- Когда нужно наблюдать за идущим или завершившимся процессом: конвейер задачи, история публикации, шаги импорта.
+- Когда шаг может закончиться отказом, и это надо показать рядом с ним, а не общим статусом сверху.
+
+## Когда не использовать
+
+- Для мастера из нескольких экранов — это `Stepper`: там линейный `current`, шаги впереди ещё не случались, провалиться не могут, а назад ведёт клик.
+- Для одного состояния объекта — это `StatusBadge`.
+- Для сообщения о сбое всей операции — это `Alert` или `ErrorState`.
+
+Разница со `Stepper` не стилевая, и именно из-за неё конвейер шагов задачи в приложении-источнике не перешёл на `Stepper`, а остался рукописным:
+
+|              | `Stepper`                     | `Timeline`          |
+| ------------ | ----------------------------- | ------------------- |
+| состояние    | одно на всю ленту (`current`) | своё у каждого шага |
+| отказ шага   | не выражается                 | `status: "failed"`  |
+| интерактивен | да, клик по пройденному шагу  | нет, это наблюдение |
+
+## Минимальный пример
+
+```tsx
+import { Timeline } from "@olddevs/ui";
+
+<Timeline
+  aria-label="Шаги задачи"
+  items={steps.map((s) => ({
+    id: s.id,
+    label: s.step_name,
+    status: s.status,
+    statusLabel: STATUS_LABEL[s.status],
+    details: s.details,
+  }))}
+/>;
+```
+
+## Public API
+
+| Prop         | Значение                                            |
+| ------------ | --------------------------------------------------- |
+| `items`      | Массив шагов. Пустой — компонент не рисуется вовсе. |
+| `aria-label` | Имя ленты для скринридера.                          |
+| `className`  | Классы обёртки.                                     |
+
+Шаг: `id`, `label`, `status` (`pending` · `running` · `success` · `failed`), необязательные `statusLabel`, `details`, `time`.
+
+**Подпись состояния — проп, а не вывод из `status`.** Слова «выполнен» и «ошибка» принадлежат предметной области: у задачи импорта и у платежа они разные. Сопоставление «статус → подпись» живёт у потребителя, рядом с доменом — так же, как у `StatusBadge`.
+
+## Доступность
+
+Разметка — упорядоченный список (`ol`): шаги идут по порядку, и скринридер обязан сообщить и порядок, и общее число. Набор `div` не сообщает ни того, ни другого. Идущий шаг помечается `aria-current="step"`; точки и соединительные линии декоративны и скрыты.
+
+## Цвета
+
+Цвета берутся из словаря тонов (`TONE_TOKENS`), а не задаются заново: «ошибка» означает один и тот же цвет здесь, в `Alert`, в `StatusBadge` и на кнопке удаления. `pending` намеренно нейтральный и приглушённый — шаг, который ещё не начинался, не событие.
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/components/content/Timeline.tsx`
+- Stories: `src/components/content/Timeline.stories.tsx`
+- Тесты: `tests/timeline.test.tsx`

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

@@ -0,0 +1,152 @@
+---
+component: Typography
+exports: [Text, Heading, Link]
+category: content
+status: stable
+source: src/components/content/Text.tsx, src/components/content/Heading.tsx, src/components/content/Link.tsx
+story: src/components/content/Text.stories.tsx, src/components/content/Heading.stories.tsx, src/components/content/Link.stories.tsx
+sourceHash: 16bb83df1a1d
+---
+
+# Typography: `Text`, `Heading`, `Link`
+
+## Summary for AI
+
+Use `Heading` for document structure, `Text` for paragraphs and auxiliary
+lines, `Link` for navigation. Do not replace them with a `div` and hand-written
+Tailwind classes: these components already carry semantics, the visual scale and
+accessibility.
+
+## When to use
+
+- `Heading` — when the text starts a logical section. Always set `level`; it is
+  the level in the outline, not a way to pick a size.
+- `Text` — for text that is not a heading: a paragraph, caption, description,
+  or a secondary or auxiliary message.
+- `Link` — for navigating to a URL or a route. For an action without
+  navigation, use `Button`.
+- `numeric="tabular"` on `Text` and `Heading` — when a number changes in place
+  or sits in a column: a timer, counter, countdown, summary. With proportional
+  digits, a line with the same number of characters changes width and makes its
+  neighbors on the same row jump.
+
+## When not to use
+
+- Do not choose `Heading` just for a large font: keep the right level and pass
+  `size` if needed.
+- Do not use `Text level` as a heading level: on `Text` it only sets how muted
+  the color is. For a heading, use `Heading`.
+- Do not use `Link` to mutate data, open a dialog or submit a form; that is a
+  button action.
+- Do not use `Link external` instead of `target="_blank"`: the first adds an
+  icon but does not change how the link opens.
+- Do not set `numeric="tabular"` on all text: equal-width digits are wider
+  than proportional ones and read worse in an ordinary paragraph. The `numeric` prop is
+  for places where digits are compared with each other or change in place.
+- Do not use `numeric` instead of `font-mono` when you need a monospaced font
+  (code, a hash): the prop only changes the digit width; the typeface stays
+  unchanged.
+
+`font-mono` is the system monospace stack (`ui-monospace`, SF Mono, Menlo,
+Consolas, Liberation Mono): the kit does not load its own font files. The
+consumer sets a custom code font with the `--font-code` variable — the same
+way as `--font-inter` for the main one (for example, `variable: "--font-code"`
+in `next/font`).
+
+## Minimal examples
+
+```tsx
+import { Heading, Link, Text } from "@olddevs/ui";
+
+<Heading level={2}>Schedule</Heading>
+<Text level={2}>Choose a publication time.</Text>
+<Text as="span" size="sm" tone="danger">Save failed</Text>
+<Link href="/campaigns">Back to campaigns</Link>
+<Text as="span" numeric="tabular">12:00</Text>
+```
+
+```tsx
+<Link external href="https://example.com" target="_blank">
+  External documentation
+</Link>
+```
+
+## Public API
+
+### `Text`
+
+| Prop       | Purpose and constraints                                                                                     |
+| ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `size`     | Step `caption`, `xs`, `sm`, `md` (default) or `lg`. This is size, not semantics.                            |
+| `level`    | Muting `1`–`3`; `1` by default. Applies only with `tone="neutral"`.                                         |
+| `tone`     | Semantic color; with a non-neutral tone it replaces the color from `level` instead of mixing with it.       |
+| `weight`   | `regular` (default), `medium` or `bold`.                                                                    |
+| `numeric`  | `tabular` — equal-width digits. No default: ordinary text keeps proportional digits.                        |
+| `truncate` | `true` — one line with an ellipsis; a positive number — that many lines. `0` is safely treated as one line. |
+| `as`       | `p` (default), `span` or `div`; changes only the HTML tag, not the look.                                    |
+
+### `Heading`
+
+| Prop      | Purpose and constraints                                                                                                    |
+| --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `level`   | Required logical level `1`–`4`; by default renders the matching `h1`…`h4`. Do not skip levels in the page structure.       |
+| `size`    | Font size `md`, `lg`, `xl`, `2xl`, independent of the level. If not set, it comes from `level`.                            |
+| `as`      | An explicit tag `h1`…`h6` when the place in the markup needs a different tag; the level itself and its size do not change. |
+| `numeric` | `tabular` — equal-width digits, the same axis as on `Text`: for a large summary number that is recalculated in place.      |
+
+### `Link`
+
+| Prop              | Purpose and constraints                                                                                                                                                                                                                                                                                                                       |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`         | `inline` (default, always underlined), `standalone` or `quiet`. Use `inline` inside text; `quiet` — for secondary navigation.                                                                                                                                                                                                                 |
+| `tone`            | Semantic tone; `accent` by default. On `quiet` the tone shows on hover.                                                                                                                                                                                                                                                                       |
+| `external`        | Adds an external-link icon hidden from screen readers; does not set `target`.                                                                                                                                                                                                                                                                 |
+| `as`              | A tag or a router component, for example `next/link`. Props keep the type of the chosen component.                                                                                                                                                                                                                                            |
+| `target="_blank"` | The component adds `rel="noopener noreferrer"` if no `rel` is passed, and a hidden note about the new tab.                                                                                                                                                                                                                                    |
+| `href`            | Executable schemes are dropped: the link is rendered without an `href`. These are `javascript:`, `vbscript:` and executable `data:` types (`text/html`, `application/xhtml+xml`, `image/svg+xml`). Everything else passes as is — including the app's own schemes (`slack://`) and non-executable `data:` (an image, a CSV under `download`). |
+
+## Accessibility and semantics
+
+- `Heading level` builds the accessible outline. The visual size must not force
+  you to change the semantic level.
+- The `Link inline` variant is always underlined: color is not the only cue that
+  text inside a paragraph is a link.
+- On `Link target="_blank"`, the accessible name is extended with a note about
+  the new tab. The component keeps a `rel` you pass.
+- Do not substitute `VisuallyHidden` for visible text: hidden text supplements an
+  element that is already clear, but does not make up for a missing clear
+  label.
+
+## Anti-patterns
+
+```tsx
+// Bad: h4 chosen for a small font size after an h2.
+<Heading level={4}>Filters</Heading>
+
+// Good: the structure stays h3, the size is separate.
+<Heading level={3} size="md">Filters</Heading>
+
+// Bad: a utility put on a semantic element, bypassing the scale.
+<Text as="span">
+  <time dateTime={`PT${seconds}S`} className="tabular-nums">{formatDuration(seconds)}</time>
+</Text>
+
+// Good: the axis is on the component, `time` stays clean — the property is inherited.
+<Text as="span" numeric="tabular">
+  <time dateTime={`PT${seconds}S`}>{formatDuration(seconds)}</time>
+</Text>
+
+// Bad: a link runs an action.
+<Link onClick={deleteCampaign}>Delete</Link>
+
+// Good: an action is a button.
+<Button tone="danger" onPress={deleteCampaign}>Delete</Button>
+```
+
+## Related sources and Storybook
+
+- Sources: `src/components/content/Text.tsx`, `src/components/content/Heading.tsx`,
+  `src/components/content/Link.tsx`.
+- Stories: `src/components/content/Text.stories.tsx`, `src/components/content/Heading.stories.tsx`,
+  `src/components/content/Link.stories.tsx`.
+- Contracts are tested in `tests/typography.test.tsx` and `tests/link.test.tsx`.

package/docs/components/content/typography.md

@@ -0,0 +1,146 @@
+---
+component: Typography
+exports: [Text, Heading, Link]
+category: content
+status: stable
+source: src/components/content/Text.tsx, src/components/content/Heading.tsx, src/components/content/Link.tsx
+story: src/components/content/Text.stories.tsx, src/components/content/Heading.stories.tsx, src/components/content/Link.stories.tsx
+---
+
+# Typography: `Text`, `Heading`, `Link`
+
+## Кратко для AI
+
+Используйте `Heading` для структуры документа, `Text` для абзацев и служебных
+строк, `Link` для навигации. Не заменяйте их `div` и ручными Tailwind-классами:
+эти компоненты уже несут семантику, визуальную шкалу и доступность.
+
+## Когда использовать
+
+- `Heading` — когда текст начинает логический раздел. Всегда задавайте
+  `level`; это уровень в оглавлении, а не выбор размера.
+- `Text` — для текста, который не заголовок: абзаца, подписи,
+  описания, вторичного или служебного сообщения.
+- `Link` — для перехода к адресу или маршруту. Для действия без навигации
+  используйте `Button`.
+- `numeric="tabular"` у `Text` и `Heading` — когда число меняется на месте или
+  стоит колонкой: таймер, счётчик, обратный отсчёт, сводка. У пропорциональных
+  цифр строка с тем же числом знаков меняет ширину и сдвигает соседей в той же строке.
+
+## Когда не использовать
+
+- Не выбирайте `Heading` только ради крупного шрифта: сохраните правильный
+  уровень и при необходимости передайте `size`.
+- Не применяйте `Text level` как уровень заголовка: у `Text` это лишь
+  приглушённость цвета. Для заголовка нужен `Heading`.
+- Не используйте `Link` для мутации данных, открытия диалога или отправки
+  формы; это кнопочное действие.
+- Не ставьте `Link external` вместо `target="_blank"`: первый добавляет
+  иконку, но не меняет способ открытия.
+- Не задавайте `numeric="tabular"` всему тексту подряд: цифры равной ширины
+  шире пропорциональных и в обычном абзаце читаются хуже. Проп `numeric` нужен там, где
+  цифры сравниваются между собой или меняются на месте.
+- Не берите `numeric` вместо `font-mono`, когда нужен именно моноширинный
+  шрифт (код, хеш): проп меняет только ширину цифр, гарнитура не меняется.
+
+`font-mono` — системный моноширинный стек (`ui-monospace`, SF Mono, Menlo,
+Consolas, Liberation Mono): кит своих файлов шрифта не загружает. Свой шрифт кода
+потребитель подставляет переменной `--font-code` — так же, как `--font-inter`
+для основного (например, `variable: "--font-code"` у `next/font`).
+
+## Минимальные примеры
+
+```tsx
+import { Heading, Link, Text } from "@olddevs/ui";
+
+<Heading level={2}>Расписание</Heading>
+<Text level={2}>Выберите время публикации.</Text>
+<Text as="span" size="sm" tone="danger">Ошибка сохранения</Text>
+<Link href="/campaigns">К кампаниям</Link>
+<Text as="span" numeric="tabular">12:00</Text>
+```
+
+```tsx
+<Link external href="https://example.com" target="_blank">
+  Внешняя документация
+</Link>
+```
+
+## Public API
+
+### `Text`
+
+| Prop       | Назначение и ограничения                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `size`     | Ступень `caption`, `xs`, `sm`, `md` (по умолчанию) или `lg`. Это размер, не семантика.                             |
+| `level`    | Приглушённость `1`–`3`; по умолчанию `1`. Работает только с `tone="neutral"`.                                      |
+| `tone`     | Семантический цвет; при ненейтральном тоне он заменяет цвет от `level`, а не смешивается с ним.                    |
+| `weight`   | `regular` (по умолчанию), `medium` или `bold`.                                                                     |
+| `numeric`  | `tabular` — цифры равной ширины. Умолчания нет: обычный текст остаётся с пропорциональными.                        |
+| `truncate` | `true` — одна строка с многоточием; положительное число — столько строк. `0` безопасно трактуется как одна строка. |
+| `as`       | `p` (по умолчанию), `span` или `div`; меняет только HTML-тег, не вид.                                              |
+
+### `Heading`
+
+| Prop      | Назначение и ограничения                                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `level`   | Обязательный логический уровень `1`–`4`; по умолчанию рендерится соответствующий `h1`…`h4`. Не пропускайте уровни в структуре страницы. |
+| `size`    | Независимый от уровня кегль `md`, `lg`, `xl`, `2xl`. Если не задан, берётся из `level`.                                                 |
+| `as`      | Явный тег `h1`…`h6`, если место в разметке требует другого тега; сам уровень и его размер от этого не меняются.                         |
+| `numeric` | `tabular` — цифры равной ширины, та же ось, что у `Text`: для крупного числа сводки, которое пересчитывается на месте.                  |
+
+### `Link`
+
+| Prop              | Назначение и ограничения                                                                                                                                                                                                                                                                                                |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`         | `inline` (по умолчанию, всегда подчёркнут), `standalone` или `quiet`. Используйте `inline` внутри текста; `quiet` — для вторичной навигации.                                                                                                                                                                            |
+| `tone`            | Семантический тон; по умолчанию `accent`. У `quiet` тон проявляется при наведении.                                                                                                                                                                                                                                      |
+| `external`        | Добавляет скрытую от скринридера иконку внешней ссылки; не устанавливает `target`.                                                                                                                                                                                                                                      |
+| `as`              | Тег или компонент роутера, например `next/link`. Пропсы сохраняют тип выбранного компонента.                                                                                                                                                                                                                            |
+| `target="_blank"` | Компонент добавляет скрытое пояснение о новой вкладке и, если свой `rel` не передан, `rel="noopener noreferrer"`.                                                                                                                                                                                                       |
+| `href`            | Исполняемые схемы отбрасываются: ссылка рисуется без адреса. Это `javascript:`, `vbscript:` и исполняемые типы `data:` (`text/html`, `application/xhtml+xml`, `image/svg+xml`). Остальное проходит как есть — включая собственные схемы приложения (`slack://`) и неисполняемый `data:` (картинка, CSV под `download`). |
+
+## Доступность и семантика
+
+- `Heading level` формирует доступное оглавление. Визуальный размер не должен
+  заставлять менять семантический уровень.
+- Вариант `Link inline` постоянно подчёркнут: цвет — не единственный
+  признак ссылки внутри текста.
+- У `Link target="_blank"` доступное имя дополняется сообщением о новой
+  вкладке. Переданный `rel` компонент сохраняет.
+- Не подменяйте видимый текст компонентом `VisuallyHidden`: скрытый текст дополняет уже
+  понятный элемент, но не компенсирует отсутствующую понятную подпись.
+
+## Антипаттерны
+
+```tsx
+// Плохо: h4 выбран ради маленького кегля после h2.
+<Heading level={4}>Фильтры</Heading>
+
+// Хорошо: структура остаётся h3, размер отделён.
+<Heading level={3} size="md">Фильтры</Heading>
+
+// Плохо: утилита навешена на семантический элемент мимо шкалы.
+<Text as="span">
+  <time dateTime={`PT${seconds}S`} className="tabular-nums">{formatDuration(seconds)}</time>
+</Text>
+
+// Хорошо: ось у компонента, `time` остаётся чистым — свойство наследуется.
+<Text as="span" numeric="tabular">
+  <time dateTime={`PT${seconds}S`}>{formatDuration(seconds)}</time>
+</Text>
+
+// Плохо: ссылка запускает действие.
+<Link onClick={deleteCampaign}>Удалить</Link>
+
+// Хорошо: действие — кнопка.
+<Button tone="danger" onPress={deleteCampaign}>Удалить</Button>
+```
+
+## Связанные исходники и Storybook
+
+- Исходники: `src/components/content/Text.tsx`, `src/components/content/Heading.tsx`,
+  `src/components/content/Link.tsx`.
+- Stories: `src/components/content/Text.stories.tsx`, `src/components/content/Heading.stories.tsx`,
+  `src/components/content/Link.stories.tsx`.
+- Контракты проверяются в `tests/typography.test.tsx` и `tests/link.test.tsx`.