prime-ui-kit 0.9.0 → 0.9.2

package/src/components/tooltip/examples/placement.tsx

@@ -0,0 +1,30 @@
+/** Every side, and start / end alignment along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. */
+import { Button, Tooltip } from "prime-ui-kit";
+
+const PLACEMENTS = [
+  { side: "top", align: "center" },
+  { side: "bottom", align: "center" },
+  { side: "left", align: "center" },
+  { side: "right", align: "center" },
+  { side: "bottom", align: "start" },
+  { side: "bottom", align: "end" },
+] as const;
+
+export default function TooltipPlacementExample() {
+  return (
+    <Tooltip.Provider>
+      {PLACEMENTS.map(({ side, align }) => (
+        <Tooltip.Root key={`${side}-${align}`}>
+          <Tooltip.Trigger>
+            <Button.Root variant="soft" tone="neutral">
+              {side} · {align}
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content side={side} align={align}>
+            Выгрузка займёт около минуты
+          </Tooltip.Content>
+        </Tooltip.Root>
+      ))}
+    </Tooltip.Provider>
+  );
+}

package/src/components/tooltip/examples/sizes.tsx

@@ -1,24 +1,21 @@
-/** Tooltip.Content at every size tier xs → xl next to buttons of the same size. Pick the tier of the control the tooltip describes. */
+/** Every size tier next to buttons of the same tier; take the tier of the control it describes — `size`. */
 import { Button, Tooltip } from "prime-ui-kit";
-import styles from "./examples.module.css";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TooltipSizesExample() {
   return (
-    <Tooltip.Provider delayDuration={200}>
-      <div className={styles.row}>
-        {SIZES.map((size) => (
-          <Tooltip.Root key={size}>
-            <Tooltip.Trigger>
-              <Button.Root variant="soft" tone="neutral" size={size}>
-                Размер {size}
-              </Button.Root>
-            </Tooltip.Trigger>
-            <Tooltip.Content size={size}>Подсказка размера {size}</Tooltip.Content>
-          </Tooltip.Root>
-        ))}
-      </div>
+    <Tooltip.Provider>
+      {SIZES.map((size) => (
+        <Tooltip.Root key={size}>
+          <Tooltip.Trigger>
+            <Button.Root variant="soft" tone="neutral" size={size}>
+              {size}
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content size={size}>Черновик сохранится на сервере</Tooltip.Content>
+        </Tooltip.Root>
+      ))}
     </Tooltip.Provider>
   );
 }

package/src/components/tooltip/examples/toolbar.tsx

@@ -0,0 +1,35 @@
+/** A formatting toolbar in one group: after the first tooltip the neighbours open at once, each with its name and shortcut — `Tooltip.Provider`. */
+import { Button, Icon, Kbd, Tooltip } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TOOLS = [
+  { icon: "format.bold", label: "Жирный", keys: "⌘B" },
+  { icon: "format.italic", label: "Курсив", keys: "⌘I" },
+  { icon: "format.underline", label: "Подчёркнутый", keys: "⌘U" },
+  { icon: "format.list", label: "Список", keys: "⌘⇧8" },
+  { icon: "format.link", label: "Ссылка", keys: "⌘K" },
+] as const;
+
+export default function TooltipToolbarExample() {
+  return (
+    <Tooltip.Provider>
+      <div className={styles.toolbar} role="toolbar" aria-label="Форматирование">
+        {TOOLS.map(({ icon, label, keys }) => (
+          <Tooltip.Root key={label}>
+            <Tooltip.Trigger>
+              <Button.Root variant="ghost" tone="neutral" size="s" aria-label={label}>
+                <Button.Icon>
+                  <Icon name={icon} />
+                </Button.Icon>
+              </Button.Root>
+            </Tooltip.Trigger>
+            <Tooltip.Content size="s" side="bottom">
+              {label} <Kbd>{keys}</Kbd>
+            </Tooltip.Content>
+          </Tooltip.Root>
+        ))}
+      </div>
+    </Tooltip.Provider>
+  );
+}

package/src/components/typography/COMPONENT.md

@@ -1,6 +1,7 @@
 # Typography
 
 **Category:** foundations
+**Kind:** primitive
 
 > Text roles of the Golos Text type scale applied to any text element, with reading-width guidance.
 
@@ -11,145 +12,113 @@
 - Single-line names in fixed-width places (`truncate` + `title`).
 
 ## 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).
+- Field labels, hints and errors → 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.
+- Text inside controls (Button, Tabs, Badge…) — they set their own type.
 
 ## Import
 ```tsx
 import { Typography } from "prime-ui-kit";
 ```
 
+## Anatomy
+```
+Typography       the element from `as` (default <p>); variant, tone, weight, tracking, italic, truncate
+```
+
 ## API
 
-### Typography.Root
-`forwardRef` → `HTMLElement` (the element chosen by `as`). + native HTML attributes (`HTMLAttributes<HTMLElement>`: `id`, `title`, `aria-*` …).
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Typography
+`ref` → the element. Any text element styled by one text role (`--prime-text-<role>-*`); state goes to `data-*`.
 
 | 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. |
+| `variant` | `"caption" \| "body-s" \| "body-m" \| "body-l" \| "title-s" \| "title-m" \| "title-l" \| "heading-s" \| "heading-m" \| "heading-l" \| "display-s" \| "display-m" \| "display-l" \| "code"` | — (required) | Text role: size, line height, weight and tracking. |
+| `tone` | `"default" \| "secondary" \| "muted" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Text color by meaning; `default` is primary text. |
+| `as` | `"p" \| "span" \| "div" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "small" \| "blockquote" \| "article" \| "section" \| "header" \| "footer" \| "aside" \| "nav" \| "main"` | `"p"` | The element, by the page outline; the role keeps the look. |
+| `weight` | `"regular" \| "medium" \| "semibold"` | — | Overrides the role's weight. |
+| `tracking` | `"normal" \| "tight" \| "tighter" \| "wide"` | — | Overrides the role's tracking with a `--prime-font-tracking-*` step. |
+| `italic` | `boolean` | `false` | Italic, for quotes and titles of works. |
 | `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. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className`, `id`, `title` and the other attributes of the element. |
 
 ## 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
+### variant (text role)
 | 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 |
+| `display-l` · `display-m` · `display-s` | 60/68 · 48/56 · 36/44, 600 | hero numbers, promo | |
+| `heading-l` · `heading-m` · `heading-s` | 30/36 · 24/32 · 20/28, 600 | page titles and subtitles | |
+| `title-l` · `title-m` · `title-s` | 18/24 · 16/24 · 14/20, 600 | block, dialog and card titles | |
+| `body-l` · `body-m` · `body-s` | 16/24 · 14/20 · 13/20, 400 | reading text, interface text, dense secondary text | |
+| `caption` | 12/16, 400 | hints, meta, table heads | |
+| `code` | 13/20, mono | identifiers, inline code | |
 
 ### 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
+| `default` | primary text | most text | yes |
+| `secondary` · `muted` | the two quieter steps | descriptions, meta | |
+| `accent` · `success` · `warning` · `danger` | semantic `*-text` colors | a value with a meaning (with a word, not color alone) | |
+
+### 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.
+| `italic` | italic | quotes, titles of works | `false` |
+| `truncate` | one line with an ellipsis | names in fixed-width cells | `false` |
 
-**Hierarchy:** one `heading-m` (or `heading-l`) per page; sections `heading-s` or `title-m`; cards `title-s`; everything else `body-*` and `caption`.
+`weight` (`regular` · `medium` · `semibold`) and `tracking` (`normal` 0 · `tight` −0.01em · `tighter` −0.02em · `wide` +0.01em, from `--prime-font-tracking-*`) override the role.
 
 ## 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"`.
+| State | Driven by | DOM |
+|---|---|---|
+| role / overrides | `variant`, `weight`, `tracking`, `tone` | `data-variant`, `data-weight`, `data-tracking`, `data-tone` (not for `default`) |
+| italic / truncate | flags | `data-italic`, `data-truncate` |
+
+Text has no interactive states.
 
 ## 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.
+- No outer margins: spacing comes from the parent's `gap`.
+- Reading text: cap the column at `--prime-layout-reading-max-width` (60–75 characters).
+- `truncate` needs a block element and a shrinking parent (`min-width: 0` in flex rows).
 
 ## 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 |
+### Keyboard
+No keyboard interaction.
 
-```tsx
-import { Typography } from "prime-ui-kit";
+### ARIA
+- The heading level comes from `as` by the page outline, the look from `variant`: never skip levels for size.
+- `tone` never carries meaning alone — name the status in words.
+- With `truncate` pass the full text in `title` when it matters.
 
-export function PageTitle() {
-  return (
-    <Typography.Root as="h1" variant="heading-m">
-      Заказы
-    </Typography.Root>
-  );
-}
-```
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A block heading, its text and a meta line, each set by a text role and a semantic tag — `variant`, `as`, `tone`. |
+| [variants.tsx](examples/variants.tsx) | Every text role from display to caption and code, then every text color on body text — `variant`, `tone`. |
+| [weights.tsx](examples/weights.tsx) | One role with its weight, tracking or italic overridden — `weight`, `tracking`, `italic`. |
+| [inline-emphasis.tsx](examples/inline-emphasis.tsx) | Values emphasized inside running text by nested spans with another weight — `as`, `weight`. |
+| [semantic-tag.tsx](examples/semantic-tag.tsx) | The tag follows the page outline and the role sets the look, so a section title can be an `h2` at title size — `as`. |
+| [truncate.tsx](examples/truncate.tsx) | A long product name clamped to one line with an ellipsis; the full text stays in the tooltip — `truncate`, `title`. |
+| [article.tsx](examples/article.tsx) | A help article from landmarks, headings and a quote at the reading width — `as`, `variant`. |
 
 ## Mistakes
-- `<Typography.Root variant="h1">` → `variant="heading-m"` (or another role) plus `as="h1"`.
+- `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`.
+- `truncate` on an inline span in a flex row that does not shrink → use a block element and `min-width: 0`.
 - Raw `font-size` in `className` → pick a role.
 
 ## Related
-- [LinkButton](../link-button/COMPONENT.md)
-- [CodeBlock](../code-block/COMPONENT.md)
-- [Label](../label/COMPONENT.md)
-- [PageContent](../page-content/COMPONENT.md)
+- **Built from:** —
+- **See also:** [LinkButton](../link-button/COMPONENT.md), [CodeBlock](../code-block/COMPONENT.md), [Label](../label/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)

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

@@ -1,4 +1,4 @@
-/** An article built from landmarks (`article`, `section`, `header`), `h1`–`h2` headings and a `blockquote`, all styled by `variant`. Use for long-form reading content. */
+/** A help article from landmarks, headings and a quote at the reading width — `as`, `variant`. */
 import { Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -7,43 +7,30 @@ 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>
+        <Typography as="h1" variant="heading-m">
+          Как выставить счёт
+        </Typography>
+        <Typography as="p" variant="body-m" tone="secondary">
+          Счёт создаётся из заказа или вручную в разделе «Финансы».
+        </Typography>
       </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 aria-labelledby="article-steps">
+        <Typography id="article-steps" as="h2" variant="heading-s">
+          Из заказа
+        </Typography>
+        <Typography as="p" variant="body-m">
+          Откройте заказ, нажмите «Выставить счёт» и проверьте реквизиты покупателя. Счёт уйдёт на
+          почту из карточки клиента.
+        </Typography>
       </section>
+      <blockquote>
+        <Typography as="p" variant="body-l">
+          Счёт без реквизитов покупателя бухгалтерия не примет.
+        </Typography>
+        <Typography as="footer" variant="caption" tone="secondary">
+          — Регламент финансового отдела
+        </Typography>
+      </blockquote>
     </article>
   );
 }

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

@@ -1,75 +1,41 @@
-/* Layout for the Typography examples: semantic tokens only. */
+/* Layout of the Typography scenarios: semantic tokens only. */
 
-/* Full-width column of samples (stretches inside a centered host). */
-.scaleList {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-4);
-  width: 100%;
-  max-width: 100%;
-  box-sizing: border-box;
-}
-
-.scaleRow {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-2);
-}
-
-.article {
+/* A short text block at a form width. */
+.block {
   display: grid;
-  gap: var(--prime-space-4);
-  max-width: var(--prime-layout-reading-max-width);
+  gap: var(--prime-space-2);
+  max-width: var(--prime-modal-width-s);
+  margin: 0;
   text-align: start;
 }
 
-.article blockquote {
-  margin: 0;
-  padding-inline-start: var(--prime-space-3);
-  border-inline-start: var(--prime-space-1) solid var(--prime-color-fill-strong);
+/* inline-emphasis.tsx: a paragraph keeps inline flow, its spans must not become grid rows. */
+p.block {
+  display: block;
 }
 
-.page {
+/* weights.tsx */
+.stack {
   display: grid;
   gap: var(--prime-space-3);
-  max-width: var(--prime-modal-width-s);
   text-align: start;
 }
 
-.form {
+/* article.tsx: long-form text at the reading width. */
+.article {
   display: grid;
-  gap: var(--prime-space-5);
-}
-
-.actions {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--prime-space-2);
-}
-
-.columns {
-  display: flex;
-  flex-wrap: wrap;
   gap: var(--prime-space-4);
-  width: 100%;
-  max-width: 100%;
-  box-sizing: border-box;
-}
-
-/* 200px basis, 280px cap. */
-.narrowColumn {
-  flex: 1 1 calc(var(--prime-space-10) * 5);
-  min-width: 0;
-  max-width: calc(var(--prime-space-10) * 7);
+  max-width: var(--prime-layout-reading-max-width);
+  text-align: start;
 }
 
-/* 320px basis. */
-.wideColumn {
-  flex: 2 1 calc(var(--prime-space-10) * 8);
-  min-width: 0;
+.article blockquote {
+  margin: 0;
+  padding-inline-start: var(--prime-space-3);
+  border-inline-start: var(--prime-space-1) solid var(--prime-color-fill-strong);
 }
 
-/* 240px — narrow enough to show the ellipsis. */
+/* truncate.tsx: 240px, narrow enough to show the ellipsis. */
 .truncateBox {
   width: min(100%, calc(var(--prime-space-24) * 2.5));
 }

package/src/components/typography/examples/inline-emphasis.tsx

@@ -0,0 +1,20 @@
+/** Values emphasized inside running text by nested spans with another weight — `as`, `weight`. */
+import { LinkButton, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TypographyInlineEmphasisExample() {
+  return (
+    <Typography as="p" variant="body-m" className={styles.block}>
+      Заказ № 4821 —{" "}
+      <Typography as="span" variant="body-m" weight="semibold">
+        отправлен
+      </Typography>
+      , сумма{" "}
+      <Typography as="span" variant="body-m" weight="medium">
+        12 400 ₽
+      </Typography>
+      . Доставка: <LinkButton href="#address">уточнить адрес</LinkButton>.
+    </Typography>
+  );
+}

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

@@ -0,0 +1,20 @@
+/** A block heading, its text and a meta line, each set by a text role and a semantic tag — `variant`, `as`, `tone`. */
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TypographyOverviewExample() {
+  return (
+    <div className={styles.block}>
+      <Typography as="h3" variant="title-m">
+        Счёт № 4821 оплачен
+      </Typography>
+      <Typography as="p" variant="body-m" tone="secondary">
+        Деньги поступили на расчётный счёт. Закрывающие документы придут на почту бухгалтерии.
+      </Typography>
+      <Typography as="span" variant="caption" tone="muted">
+        12 марта, 14:20
+      </Typography>
+    </div>
+  );
+}

package/src/components/typography/examples/semantic-tag.tsx

@@ -0,0 +1,17 @@
+/** The tag follows the page outline and the role sets the look, so a section title can be an `h2` at title size — `as`. */
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TypographySemanticTagExample() {
+  return (
+    <section className={styles.block} aria-labelledby="billing-title">
+      <Typography as="h2" id="billing-title" variant="title-s">
+        Реквизиты для оплаты
+      </Typography>
+      <Typography as="p" variant="body-m" tone="secondary">
+        ООО «Прайм», ИНН 7701234567, расчётный счёт в АО «Банк Север».
+      </Typography>
+    </section>
+  );
+}

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

@@ -1,19 +1,19 @@
-/** `truncate` clamps a block to one line with an ellipsis; `title` keeps the full text available. Use for names and titles in fixed-width cells, cards and list rows. */
+/** A long product name clamped to one line with an ellipsis; the full text stays in the tooltip — `truncate`, `title`. */
 import { Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const name = "Эргономичное кресло с подголовником и поддержкой поясницы";
+const NAME = "Эргономичное кресло с подголовником и поддержкой поясницы";
 
 export default function TypographyTruncateExample() {
   return (
     <div className={styles.truncateBox}>
-      <Typography.Root variant="title-s" truncate title={name}>
-        {name}
-      </Typography.Root>
-      <Typography.Root variant="body-s" tone="muted">
+      <Typography variant="title-s" truncate title={NAME}>
+        {NAME}
+      </Typography>
+      <Typography variant="body-s" tone="muted">
         Артикул 48 213
-      </Typography.Root>
+      </Typography>
     </div>
   );
 }