prime-ui-kit 0.7.11 → 0.9.0

package/src/components/typography/COMPONENT.md

@@ -1,127 +1,155 @@
 # Typography
 
-**Default choice for page copy:** start from **`body-default`** in `variant` unless the scenario clearly needs another reading role.
+**Category:** foundations
 
-## About
+> Text roles of the Golos Text type scale applied to any text element, with reading-width guidance.
 
-Styled text with **semantic reading roles** (`variant`) wired to `typography.role` in tokens, plus optional axes: `weight`, `tracking`, italic, and `tone` for secondary color. Renders as the HTML tag you pick with **`as`**.
+## When to use
+- Page titles, section headings, card titles, body text, captions and inline code outside of components that style their own text.
+- Long-form reading content (articles, help pages) with semantic tags via `as`.
+- Emphasis inside running text: nested `as="span"` with another `weight`, `tracking` or `tone`.
+- Single-line names in fixed-width places (`truncate` + `title`).
 
-**When to use**
+## When not to use
+- Field labels, hints and errors → use the field's own `label` / `hint` / `error` or [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md).
+- Links → use [LinkButton](../link-button/COMPONENT.md).
+- Multi-line code → use [CodeBlock](../code-block/COMPONENT.md); keyboard keys → [Kbd](../kbd/COMPONENT.md).
+- Status labels → use [Badge](../badge/COMPONENT.md).
+- Text inside controls (Button, Tabs, Badge …) — they set their own type. Inside Button a nested Typography inherits the button's size, weight and color.
 
-- Body copy, headings, captions, and metrics where you want kit tokens instead of ad-hoc `font-size`.
-- `tone="muted"` for secondary explanations, hints, and legal lines.
-- Nested **`Typography.Root`** nodes with different `as` / `weight` inside one block (see `./examples/composition.tsx`, `./examples/05-inline-emphasis.tsx`).
-- `as="h1"`–`as="h6"` for heading levels that match the theme; keep a sensible outline order on the page.
-- `as` values that are landmarks (`main`, `article`, `section`, `header`, `footer`, …) when you need both semantics and typography on the same node — otherwise wrap landmarks in normal elements and put **`Typography.Root`** inside.
-
-**When not to use**
-
-- As a substitute for **button** or **link** chrome — use [Button](../button/COMPONENT.md) / [LinkButton](../link-button/COMPONENT.md).
-- Expecting a separate `line-height` control per instance — line height is part of the role in CSS.
-- Interactive controls (fields, switches, etc.) still use their own components and sizes; **Typography** does not restyle them.
-
-## Reference mapping: MD3, Apple (SF), Polaris
-
-Rough **hierarchy** alignment only — not pixel-perfect parity. Font size column assumes **`1rem = 16px`** on `:root` (rounded).
-
-| `variant` | Token step | ≈ px @16 | Close MD3 | Close Apple (SF) | Polaris `Text` |
-| --------- | ---------- | -------- | --------- | ---------------- | -------------- |
-| `display` | `9xl` | 57 | Display Large | Large Title | `heading3xl` |
-| `headline` | `6xl` | 32 | Headline Large | Title 1 | `heading2xl` |
-| `heading-page` | `4xl` | 28 | Headline Medium | Title 2 | `headingXl` |
-| `heading-section` | `2xl` | 24 | Headline Small | Title 3 | `headingLg` |
-| `heading-subsection` | `xl` | 22 | Title Large | Headline | `headingMd` |
-| `heading-group` | `xs` | 14 | Title Small | Subheadline / Footnote | `headingSm`, `headingXs` |
-| `body-large` | `s` | 16 | Body Large | Body / Callout | `bodyLg` |
-| `body-default` | `xs` | 14 | Body Medium | Subheadline | `bodyMd` |
-| `body-small` | `2xs` | 12 | Body Small | Footnote | `bodySm` |
-| `body-compact` | `xs` size, tighter line | 14 | Label Large (dense) | — | `bodyXs` |
-| `caption` | `2xs` | 12 | Label Medium | Caption 1 | `bodySm` (with `tone`) |
-| `caption-micro` | `labelMicro` | 11 | Label Small | Caption 2 | smallest semantic step |
-
-Steps **`7xl`** / **`8xl`** exist in the scale but are **not** wired to `typography.role` — use tokens directly if you need them, not **`Typography`**.
-
-## Composition
+## Import
+```tsx
+import { Typography } from "prime-ui-kit";
+```
 
-- Single primitive: **`Typography.Root`**. Put text or inline markup in **`children`**.
-- **`as`** defaults to **`p`**; allowed: paragraph, inline, block, **`h1`–`h6`**, **`small`**, **`blockquote`**, landmarks (`article`, `section`, `header`, `footer`, `aside`, `nav`, `main`).
+## API
 
-### Canonical example
+### Typography.Root
+`forwardRef` → `HTMLElement` (the element chosen by `as`). + native HTML attributes (`HTMLAttributes<HTMLElement>`: `id`, `title`, `aria-*` …).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `TypographyRole` (see Variants) | — (required) | Text role: size, line height, weight, tracking from `--prime-text-<role>-*`. |
+| `as` | `"p" \| "span" \| "div" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "small" \| "blockquote" \| "article" \| "section" \| "header" \| "footer" \| "aside" \| "nav" \| "main"` | `"p"` | Rendered element. |
+| `weight` | `"regular" \| "medium" \| "semibold"` | role weight | Overrides the role's weight. |
+| `tracking` | `"normal" \| "tight" \| "tighter" \| "wide"` | role tracking | Overrides the role's letter spacing. |
+| `tone` | `"default" \| "secondary" \| "muted" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Text color. |
+| `truncate` | `boolean` | `false` | One line with an ellipsis; set `title` when the full text matters. |
+| `italic` | `boolean` | `false` | Italic style. |
+| `children` | `ReactNode` | — | Text or nested markup. |
+| `className` | `string` | — | Extra class. |
+
+## Variants
+
+### variant (role)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `display-l` | 60/68, 600, −0.03em | hero headline | |
+| `display-m` | 48/56, 600, −0.03em | large metric | |
+| `display-s` | 36/44, 600, −0.02em | metric, promo | |
+| `heading-l` | 30/36, 600, −0.02em | large page title | |
+| `heading-m` | 24/32, 600, −0.02em | page title | |
+| `heading-s` | 20/28, 600, −0.01em | page sub-heading | |
+| `title-l` | 18/24, 600, −0.01em | large block title | |
+| `title-m` | 16/24, 600, −0.01em | modal and section title | |
+| `title-s` | 14/20, 600 | card and group title | |
+| `body-l` | 16/24, 400 | reading text | |
+| `body-m` | 14/20, 400 | default UI text | |
+| `body-s` | 13/20, 400 | secondary text, dense UI | |
+| `caption` | 12/16, 400, +0.01em | hints, meta, table head | |
+| `code` | 13/20, mono (JetBrains Mono), 400 | inline code, IDs | |
+
+Titles, headings and display roles use `text-wrap: balance`; body and caption use `text-wrap: pretty`. Weights are only 400 / 500 / 600.
+
+### weight
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `regular` | 400 | plain text in a title role | role |
+| `medium` | 500 | emphasis in body text, values | role |
+| `semibold` | 600 | strong emphasis in body text | role |
+
+### tracking
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `normal` | 0 | reset a role's tracking | role |
+| `tight` | −0.01em | numbers, compact titles | role |
+| `tighter` | −0.02em | large text set in a smaller role | role |
+| `wide` | +0.01em | small uppercase-like labels | role |
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `default` | primary text | main text | yes |
+| `secondary` | secondary text | descriptions, intros | |
+| `muted` | muted text | meta, captions | |
+| `accent` | accent text | highlighted value | |
+| `success` | success text | positive result | |
+| `warning` | warning text | warning message | |
+| `danger` | danger text | error, destructive context | |
+
+### Visual flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `italic` | italic style | quotes, titles of works | off |
+| `truncate` | single line, overflow hidden, ellipsis, `min-width: 0` | names in table cells, cards, list rows | off |
+
+**Combinations**
+- Recommended: `heading-m` page title + `body-m tone="secondary"` intro; `title-s` card title + `body-s tone="muted"` meta; nested `as="span" weight="medium"` for values in text.
+- Avoid: `weight` overrides that turn body text into a fake heading (use a title role); `tone="danger"` for non-error text; `truncate` on long reading text.
+
+**Hierarchy:** one `heading-m` (or `heading-l`) per page; sections `heading-s` or `title-m`; cards `title-s`; everything else `body-*` and `caption`.
+
+## States
+Text has no interactive states. DOM attributes: `data-variant`, `data-weight` and `data-tracking` (only when set), `data-tone` (only when not `default`), `data-italic="true"`, `data-truncate="true"`.
+
+## Layout & spacing
+- The root has `margin: 0`; space text with `gap` on the parent: heading → intro `var(--prime-space-2)`–`var(--prime-space-3)`, paragraph → paragraph `var(--prime-space-4)`, section → section `var(--prime-space-10)`–`var(--prime-space-12)`.
+- Reading text: cap the column at `--prime-layout-reading-max-width` (≈ 65ch).
+- Text takes the parent width; long words break (`overflow-wrap: break-word`).
+- Numbers in tables and counters: add `font-variant-numeric: tabular-nums` on the host.
+
+## Accessibility
+- Pick `as` by meaning, `variant` by look: a page title is `as="h1"`, even if it uses `heading-m`. Do not skip heading levels.
+- Landmarks (`article`, `section`, `nav`, `main`…) via `as`; label sections with `aria-labelledby`.
+- Use only one `as="main"` per page.
+- `truncate` hides text visually — add `title` (or a Tooltip) when the full text matters.
+- No `labels` keys.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [variant-catalog.tsx](examples/variant-catalog.tsx) | Every role with its size and purpose | choosing a role |
+| [article.tsx](examples/article.tsx) | Landmarks, `h1`–`h2`, blockquote | long-form reading content |
+| [reading-and-form.tsx](examples/reading-and-form.tsx) | Page heading + intro above an Input/Button form | form pages |
+| [variants.tsx](examples/variants.tsx) | `weight`, `tracking`, `tone="secondary"` on `body-m` | overriding a role |
+| [tones.tsx](examples/tones.tsx) | Every `tone` | text color by meaning |
+| [truncate.tsx](examples/truncate.tsx) | One-line name with `title` | fixed-width cells and cards |
+| [states.tsx](examples/states.tsx) | `italic` on the same role and weight | quotes, titles of works |
+| [composition.tsx](examples/composition.tsx) | Nested spans and a link in one paragraph | emphasis in running text |
+| [full-width.tsx](examples/full-width.tsx) | Same text in narrow and wide columns | multi-column layouts |
+| [as-prop.tsx](examples/as-prop.tsx) | `as="p"`, `"div"`, inline `"span"` | choosing the element |
 
 ```tsx
 import { Typography } from "prime-ui-kit";
 
-export function Example() {
+export function PageTitle() {
   return (
-    <>
-      <Typography.Root as="h1" variant="heading-page">
-        Release notes
-      </Typography.Root>
-      <Typography.Root as="p" variant="body-default" tone="muted">
-        Summary of changes for the current shipping cycle.
-      </Typography.Root>
-      <Typography.Root as="p" variant="body-default">
-        Copy uses reading roles; controls use their own size scale — keep both axes explicit in layouts.
-      </Typography.Root>
-    </>
+    <Typography.Root as="h1" variant="heading-m">
+      Заказы
+    </Typography.Root>
   );
 }
 ```
 
-### Playground-aligned examples
-
-Order matches **`playground/sections/TypographySection.tsx`** and the runnable snippets in **`playground/snippets/typography/`**; the same scenarios ship under **`./examples/`** for `prime-ui-kit` consumers (import from **`prime-ui-kit`**).
-
-| Playground snippet | Package example |
-| --- | --- |
-| [`variant-catalog.tsx`](../../../playground/snippets/typography/variant-catalog.tsx) | [`./examples/variant-catalog.tsx`](./examples/variant-catalog.tsx) |
-| [`article-landmarks.tsx`](../../../playground/snippets/typography/article-landmarks.tsx) | [`./examples/01-article.tsx`](./examples/01-article.tsx) (same structure; English copy) |
-| [`reading-and-form.tsx`](../../../playground/snippets/typography/reading-and-form.tsx) | [`./examples/reading-and-form.tsx`](./examples/reading-and-form.tsx) |
-| [`variants.tsx`](../../../playground/snippets/typography/variants.tsx) | [`./examples/variants.tsx`](./examples/variants.tsx) |
-| [`states.tsx`](../../../playground/snippets/typography/states.tsx) | [`./examples/states.tsx`](./examples/states.tsx) |
-| [`composition.tsx`](../../../playground/snippets/typography/composition.tsx) | [`./examples/composition.tsx`](./examples/composition.tsx) |
-| [`full-width.tsx`](../../../playground/snippets/typography/full-width.tsx) | [`./examples/full-width.tsx`](./examples/full-width.tsx) |
-| [`as-prop.tsx`](../../../playground/snippets/typography/as-prop.tsx) | [`./examples/as-prop.tsx`](./examples/as-prop.tsx) |
-
-### Additional examples
-
-- [`./examples/02-form-labels-contrast.tsx`](./examples/02-form-labels-contrast.tsx) — **`Input`** label / optional / hint slots built with **`Typography.Root`** (richer than the playground form frame).
-- [`./examples/03-marketing-hero.tsx`](./examples/03-marketing-hero.tsx) — Hero stack: caption, display, headline, muted body.
-- [`./examples/04-reading-scale.tsx`](./examples/04-reading-scale.tsx) — Compact English ladder of every **`variant`** (no **`Divider`** captions; use **`variant-catalog`** for the full labeled catalog).
-- [`./examples/05-inline-emphasis.tsx`](./examples/05-inline-emphasis.tsx) — Nested spans on **`body-default`** (English; playground **`composition`** adds a link and `as="div"` wrapper).
-
-**LLM note:** Use **`./examples/*.tsx`** for copy-paste scenarios; **`playground/snippets/typography/*.tsx`** stay the source shown in the dev playground (`?raw`). This page keeps the contract (rules + API tables) authoritative.
-
-## Rules
-
-- **`variant` is required**; default-looking props omit extra **`data-*`** (`weight="regular"`, `tracking="normal"`, `tone="default"`, no italic).
-- DOM: **`data-variant`** uses kebab-case (e.g. `heading-page`).
-- Standard HTML attributes (`id`, `aria-*`, …) pass through **`...rest`**.
-- Root uses **`text-wrap: balance`** on short blocks; override from a parent if needed.
-- No built-in disabled / loading / error states — combine with surrounding UI.
-
-## API
-
-### Typography.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| as | see `TypographyAs` | `"p"` | No | HTML element |
-| variant | see `TypographyVariant` | — | Yes | Reading role |
-| weight | `"regular"` \| `"medium"` \| `"semibold"` | `"regular"` | No | Font weight |
-| tracking | `"normal"` \| `"tight"` \| `"tighter"` \| `"wide"` | `"normal"` | No | Letter spacing |
-| italic | `boolean` | `false` | No | Italic |
-| tone | `"default"` \| `"muted"` | `"default"` | No | Primary vs secondary text color |
-| children | `React.ReactNode` | — | No | Content |
-| className | `string` | — | No | Extra class |
-| ref | `React.Ref<HTMLElement>` | — | No | Element ref |
-| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | Other element props |
+## Mistakes
+- `<Typography.Root variant="h1">` → `variant="heading-m"` (or another role) plus `as="h1"`.
+- Missing `variant` → it is required.
+- `tone="error"` → `tone="danger"`; `color="gray"` → `tone="muted"`.
+- `truncate` on `as="span"` inside a flex row that does not shrink → use a block element (`p`/`div`) and give flex parents `min-width: 0`.
+- Raw `font-size` in `className` → pick a role.
 
 ## Related
-
-- [Label](../label/COMPONENT.md)
-- [Hint](../hint/COMPONENT.md)
-- [Input](../input/COMPONENT.md)
 - [LinkButton](../link-button/COMPONENT.md)
-- [Banner](../banner/COMPONENT.md)
-- [Notification](../notification/COMPONENT.md)
+- [CodeBlock](../code-block/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [PageContent](../page-content/COMPONENT.md)

package/src/components/typography/examples/article.tsx

@@ -0,0 +1,49 @@
+/** An article built from landmarks (`article`, `section`, `header`), `h1`–`h2` headings and a `blockquote`, all styled by `variant`. Use for long-form reading content. */
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TypographyArticleExample() {
+  return (
+    <article className={styles.article}>
+      <header>
+        <Typography.Root as="h1" variant="heading-m">
+          Краткий гид по осям
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-m" tone="secondary">
+          Иерархия текста страницы задаётся только{" "}
+          <Typography.Root as="span" variant="code" tone="secondary">
+            variant
+          </Typography.Root>{" "}
+          и тегами.
+        </Typography.Root>
+      </header>
+      <section aria-labelledby="section-roles">
+        <Typography.Root id="section-roles" as="h2" variant="heading-s">
+          Семантические роли
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-m">
+          Роль задаёт пару «кегль + межстрочный интервал» из темы; не смешивайте с произвольными{" "}
+          <Typography.Root as="span" variant="code">
+            rem
+          </Typography.Root>{" "}
+          для основного текста.
+        </Typography.Root>
+      </section>
+      <section aria-labelledby="section-quote">
+        <Typography.Root id="section-quote" as="h2" variant="heading-s">
+          Цитата
+        </Typography.Root>
+        <blockquote>
+          <Typography.Root as="p" variant="body-l">
+            Две оси — меньше коллизий: заголовок страницы и подпись к полю больше не спорят об одном
+            «размере».
+          </Typography.Root>
+          <Typography.Root as="footer" variant="caption" tone="secondary">
+            — Руководство по дизайн-системе
+          </Typography.Root>
+        </blockquote>
+      </section>
+    </article>
+  );
+}

package/src/components/typography/examples/as-prop.tsx

@@ -1,21 +1,21 @@
+/** The `as` prop: `p` and `div` as block wrappers, `span` as an inline fragment inside a paragraph. Use `as` to keep the right HTML element while the role sets the look. */
 import { Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** Проп `as`: `p`, `div`, вложенный `span`. Зеркало `playground/snippets/typography/as-prop.tsx`. */
-export default function TypographyExampleAsProp() {
+export default function TypographyAsPropExample() {
   return (
-    <div className={styles.typographyScaleList}>
-      <Typography.Root as="p" variant="body-default">
+    <div className={styles.scaleList}>
+      <Typography.Root as="p" variant="body-m">
         as=&quot;p&quot; — отдельный абзац с нулевыми внешними отступами по умолчанию у компонента.
       </Typography.Root>
-      <Typography.Root as="div" variant="body-default">
+      <Typography.Root as="div" variant="body-m">
         as=&quot;div&quot; — блочный контейнер, если нужна обёртка без семантики абзаца (например
         внутри карточки).
       </Typography.Root>
-      <Typography.Root as="p" variant="body-default">
+      <Typography.Root as="p" variant="body-m">
         В одной строке можно вставить{" "}
-        <Typography.Root as="span" variant="body-default" weight="semibold">
+        <Typography.Root as="span" variant="body-m" weight="semibold">
           span с акцентом
         </Typography.Root>{" "}
         без нового абзаца.

package/src/components/typography/examples/composition.tsx

@@ -1,28 +1,22 @@
-import { Typography } from "prime-ui-kit";
+/** Nested `Typography.Root` spans with other `weight` / `tracking` and a LinkButton inside one paragraph. Use to emphasize values inside running text. */
+import { LinkButton, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/**
- * Вложенные `Typography.Root` и ссылка внутри блока.
- * Зеркало `playground/snippets/typography/composition.tsx`.
- */
-export default function TypographyExampleComposition() {
+export default function TypographyCompositionExample() {
   return (
-    <div className={styles.typographyScaleList}>
-      <Typography.Root variant="body-default" as="div">
+    <div className={styles.scaleList}>
+      <Typography.Root variant="body-m" as="div">
         Сводка по заказу № 4821: статус{" "}
-        <Typography.Root as="span" variant="body-default" weight="semibold">
+        <Typography.Root as="span" variant="body-m" weight="semibold">
           отправлен
         </Typography.Root>
         . Сумма{" "}
-        <Typography.Root as="span" variant="body-default" weight="medium" tracking="tight">
+        <Typography.Root as="span" variant="body-m" weight="medium" tracking="tight">
           12 400 ₽
         </Typography.Root>
-        , доставка до{" "}
-        <a href="#typography-example-composition" className={styles.inlineLinkInherit}>
-          уточнить адрес
-        </a>
-        . Подробности — в разделе «История покупок».
+        , доставка до <LinkButton.Root href="#address">уточнить адрес</LinkButton.Root>. Подробности
+        — в разделе «История покупок».
       </Typography.Root>
     </div>
   );

package/src/components/typography/examples/examples.module.css

@@ -1,95 +1,75 @@
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-}
-
-.stackTight {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-s);
-}
-
-.formFields {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-l);
-}
-
-.hero {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-l);
-  max-width: 40rem;
-}
+/* Layout for the Typography examples: semantic tokens only. */
 
+/* Full-width column of samples (stretches inside a centered host). */
 .scaleList {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-}
-
-/* Layout parity with playground/snippets/typography (PlaygroundExampleFrame preview). */
-.typographyScaleList {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-x4);
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: 100%;
+  box-sizing: border-box;
 }
 
-.typographyScaleRow {
+.scaleRow {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-x2);
+  gap: var(--prime-space-2);
 }
 
-.articleLandmarks {
+.article {
   display: grid;
-  gap: var(--prime-sys-spacing-x4);
-  max-width: 40rem;
+  gap: var(--prime-space-4);
+  max-width: var(--prime-layout-reading-max-width);
   text-align: start;
 }
 
-.articleLandmarks blockquote {
+.article blockquote {
   margin: 0;
-  padding-inline-start: var(--prime-sys-spacing-x3);
-  border-inline-start: 3px solid var(--prime-sys-color-border-subtle);
+  padding-inline-start: var(--prime-space-3);
+  border-inline-start: var(--prime-space-1) solid var(--prime-color-fill-strong);
 }
 
-.readingAndForm {
+.page {
   display: grid;
-  gap: var(--prime-sys-spacing-x3);
-  max-width: 22rem;
+  gap: var(--prime-space-3);
+  max-width: var(--prime-modal-width-s);
   text-align: start;
 }
 
-.readingAndFormFields {
+.form {
   display: grid;
-  gap: var(--prime-sys-spacing-x3);
+  gap: var(--prime-space-5);
 }
 
-.readingAndFormActions {
+.actions {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--prime-sys-spacing-x2);
+  gap: var(--prime-space-2);
 }
 
-.fullWidthColumns {
+.columns {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--prime-sys-spacing-l);
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: 100%;
+  box-sizing: border-box;
 }
 
-.fullWidthNarrow {
-  flex: 1 1 12.5rem;
+/* 200px basis, 280px cap. */
+.narrowColumn {
+  flex: 1 1 calc(var(--prime-space-10) * 5);
   min-width: 0;
-  max-width: 17.5rem;
+  max-width: calc(var(--prime-space-10) * 7);
 }
 
-.fullWidthWide {
-  flex: 2 1 20rem;
+/* 320px basis. */
+.wideColumn {
+  flex: 2 1 calc(var(--prime-space-10) * 8);
   min-width: 0;
 }
 
-.inlineLinkInherit {
-  color: inherit;
+/* 240px — narrow enough to show the ellipsis. */
+.truncateBox {
+  width: min(100%, calc(var(--prime-space-24) * 2.5));
 }

package/src/components/typography/examples/full-width.tsx

@@ -1,30 +1,27 @@
+/** The same caption and body text in a narrow and a wide column: text takes the parent width and wraps naturally. Use to check text in multi-column layouts. */
 import { Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/**
- * Две колонки разной ширины, одинаковые `variant` и `tone`.
- * Зеркало `playground/snippets/typography/full-width.tsx`.
- */
-export default function TypographyExampleFullWidth() {
+export default function TypographyFullWidthExample() {
   return (
-    <div className={styles.fullWidthColumns}>
-      <div className={styles.fullWidthNarrow}>
-        <Typography.Root variant="body-small" tone="muted">
+    <div className={styles.columns}>
+      <div className={styles.narrowColumn}>
+        <Typography.Root variant="body-s" tone="secondary">
           Узкая колонка
         </Typography.Root>
-        <Typography.Root variant="body-default">
+        <Typography.Root variant="body-m">
           Длинное предложение в узком контейнере демонстрирует переносы и выравнивание без
           отдельного пропа ширины.
         </Typography.Root>
       </div>
-      <div className={styles.fullWidthWide}>
-        <Typography.Root variant="body-small" tone="muted">
+      <div className={styles.wideColumn}>
+        <Typography.Root variant="body-s" tone="secondary">
           Широкая колонка
         </Typography.Root>
-        <Typography.Root variant="body-default">
+        <Typography.Root variant="body-m">
           Тот же размер и стиль в более широком блоке: меньше переносов, читаемость остаётся за счёт
-          связки кегля и межстрочного интервала из токенов для `size="m"`.
+          связки кегля и межстрочного интервала из токенов роли body-m.
         </Typography.Root>
       </div>
     </div>

package/src/components/typography/examples/reading-and-form.tsx

@@ -1,40 +1,35 @@
+/** A page heading and intro text set with Typography above a form built from Input and Button. Use for form pages: text roles come from Typography, fields from form components. */
 import { Button, Input, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/**
- * Заголовок и вводный текст — `Typography`; поля и кнопки — `Input` / `Button`.
- * Зеркало `playground/snippets/typography/reading-and-form.tsx`.
- */
-export default function TypographyExampleReadingAndForm() {
+export default function TypographyReadingAndFormExample() {
   return (
-    <main className={styles.readingAndForm}>
-      <Typography.Root as="h1" variant="heading-page">
+    <section className={styles.page} aria-labelledby="access-request-title">
+      <Typography.Root id="access-request-title" as="h1" variant="heading-m">
         Заявка на доступ
       </Typography.Root>
-      <Typography.Root as="p" variant="body-default" tone="muted">
+      <Typography.Root as="p" variant="body-m" tone="secondary">
         Заполните форму: роли текста задаются здесь, оформление полей — компонентами формы.
       </Typography.Root>
-      <div className={styles.readingAndFormFields}>
+      <div className={styles.form}>
         <Input.Root label="Email">
           <Input.Wrapper>
             <Input.Field type="email" placeholder="you@example.com" autoComplete="email" />
           </Input.Wrapper>
         </Input.Root>
-        <Input.Root label="Комментарий" hint="Необязательно">
+        <Input.Root label="Комментарий" optional>
           <Input.Wrapper>
             <Input.Field placeholder="Контекст" />
           </Input.Wrapper>
         </Input.Root>
-        <div className={styles.readingAndFormActions}>
-          <Button.Root type="button" variant="primary">
-            Отправить
-          </Button.Root>
-          <Button.Root type="button" variant="neutral" mode="stroke">
+        <div className={styles.actions}>
+          <Button.Root type="button">Отправить</Button.Root>
+          <Button.Root variant="outline" tone="neutral" type="button">
             Отмена
           </Button.Root>
         </div>
       </div>
-    </main>
+    </section>
   );
 }

package/src/components/typography/examples/states.tsx

@@ -1,26 +1,22 @@
+/** Text has no interactive states; this shows the one boolean style axis, `italic`, on the same variant and weight. Use italic for quotes and titles of works. */
 import { Divider, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** Курсив `italic` при том же `variant` и `weight`. Зеркало `playground/snippets/typography/states.tsx`. */
-export default function TypographyExampleStates() {
+export default function TypographyStatesExample() {
   return (
-    <div className={styles.typographyScaleList}>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" weight="medium">
-          Заголовок карточки без курсива — обычный акцент.
+    <div className={styles.scaleList}>
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" weight="medium">
+          Обычный текст без курсива.
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          italic не задан (false)
-        </Divider.Root>
+        <Divider.Root align="start">italic не задан (false)</Divider.Root>
       </div>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" weight="medium" italic>
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" weight="medium" italic>
           Тот же размер и вес с курсивом — цитата или название научной работы.
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          italic — курсив через data-атрибут и токены
-        </Divider.Root>
+        <Divider.Root align="start">italic — курсив через data-атрибут и токены</Divider.Root>
       </div>
     </div>
   );