prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/components/kanban/examples/states.tsx

@@ -0,0 +1,75 @@
+/** Loading draws skeleton cards in the card geometry and cross-fades the cards in; an empty column keeps its drop area; a read-only board drags nothing — `loading`, `disabled`. */
+import { Button, Icon, Kanban, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Order = { id: string; title: string; total: string };
+
+const COLUMNS = [
+  { id: "new", title: "Новые" },
+  { id: "packing", title: "Сборка" },
+  { id: "shipped", title: "Отгружены" },
+];
+
+const ORDERS: Order[] = [
+  { id: "ORD-5531", title: "ООО «Север» · 12 позиций", total: "48 300 ₽" },
+  { id: "ORD-5529", title: "ИП Лебедев · 3 позиции", total: "7 950 ₽" },
+  { id: "ORD-5524", title: "АО «Гранит» · 40 позиций", total: "212 000 ₽" },
+];
+
+const PLACEMENT = { new: ["ORD-5531", "ORD-5529"], packing: [], shipped: ["ORD-5524"] };
+
+const LOAD_MS = 1200;
+
+export default function KanbanStatesExample() {
+  const [loading, setLoading] = React.useState(true);
+  const [readOnly, setReadOnly] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!loading) return;
+    const timer = window.setTimeout(() => setLoading(false), LOAD_MS);
+    return () => window.clearTimeout(timer);
+  }, [loading]);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.toolbar}>
+        <Switch.Root checked={readOnly} onCheckedChange={setReadOnly}>
+          <Switch.Label>Только просмотр</Switch.Label>
+        </Switch.Root>
+        <div className={styles.spacer} />
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          loading={loading}
+          onClick={() => setLoading(true)}
+        >
+          <Button.Icon>
+            <Icon name="action.refresh" />
+          </Button.Icon>
+          Обновить
+        </Button.Root>
+      </div>
+      <Kanban.Root
+        aria-label="Заказы склада"
+        className={styles.board}
+        columns={COLUMNS}
+        items={ORDERS}
+        getId={(order) => order.id}
+        getLabel={(order) => order.id}
+        defaultValue={PLACEMENT}
+        loading={loading}
+        disabled={readOnly}
+        renderItem={(order) => (
+          <Kanban.Item>
+            <Kanban.ItemTitle>{order.id}</Kanban.ItemTitle>
+            <Kanban.ItemDescription>
+              {order.title} · {order.total}
+            </Kanban.ItemDescription>
+          </Kanban.Item>
+        )}
+      />
+    </div>
+  );
+}

package/dist/skill/reference/components/kanban/examples/structure.tsx

@@ -0,0 +1,76 @@
+/** Cards take only the parts they need: a title alone, a meta line, labels, a footer with counts and an assignee — `Kanban.ItemTitle`, `Kanban.ItemDescription`, `Kanban.ItemBadges`, `Kanban.ItemFooter`, `Kanban.ItemCount`. */
+import { Avatar, Badge, Icon, Kanban } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Card = {
+  id: string;
+  title: string;
+  meta?: string;
+  label?: string;
+  comments?: number;
+  attachments?: number;
+  assignee?: { initials: string; name: string };
+};
+
+const COLUMNS = [
+  { id: "inbox", title: "Входящие" },
+  { id: "planned", title: "Запланировано" },
+];
+
+const CARDS: Card[] = [
+  { id: "c1", title: "Уточнить реквизиты поставщика" },
+  { id: "c2", title: "Сверка остатков на складе", meta: "INV-3102 · до 15 окт" },
+  { id: "c3", title: "Новый тариф для партнёров", label: "Продажи" },
+  {
+    id: "c4",
+    title: "Акт сверки с ООО «Вектор»",
+    meta: "INV-3088 · до 11 окт",
+    label: "Финансы",
+    comments: 4,
+    attachments: 2,
+    assignee: { initials: "ОБ", name: "Ольга Белова" },
+  },
+];
+
+const PLACEMENT = { inbox: ["c1", "c2"], planned: ["c3", "c4"] };
+
+export default function KanbanStructureExample() {
+  return (
+    <Kanban.Root
+      aria-label="Задачи отдела закупок"
+      className={styles.board}
+      columns={COLUMNS}
+      items={CARDS}
+      getId={(card) => card.id}
+      getLabel={(card) => card.title}
+      defaultValue={PLACEMENT}
+      renderItem={(card) => (
+        <Kanban.Item>
+          <Kanban.ItemTitle>{card.title}</Kanban.ItemTitle>
+          {card.meta ? <Kanban.ItemDescription>{card.meta}</Kanban.ItemDescription> : null}
+          {card.label ? (
+            <Kanban.ItemBadges>
+              <Badge.Root color="blue">{card.label}</Badge.Root>
+            </Kanban.ItemBadges>
+          ) : null}
+          {card.assignee ? (
+            <Kanban.ItemFooter>
+              <Kanban.ItemCount>
+                <Icon name="object.message" />
+                {card.comments}
+              </Kanban.ItemCount>
+              <Kanban.ItemCount>
+                <Icon name="object.document" />
+                {card.attachments}
+              </Kanban.ItemCount>
+              <Avatar.Root size="s" color="green" aria-label={card.assignee.name}>
+                <Avatar.Fallback>{card.assignee.initials}</Avatar.Fallback>
+              </Avatar.Root>
+            </Kanban.ItemFooter>
+          ) : null}
+        </Kanban.Item>
+      )}
+    />
+  );
+}

package/dist/skill/reference/components/kanban/examples/variants.tsx

@@ -0,0 +1,57 @@
+/** The same release board in both looks: columns as filled wells, and bare columns where the header and wider cards carry each column — `variant`. */
+import { Kanban, type KanbanVariant, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Task = { id: string; title: string; due: string };
+
+const VARIANTS: KanbanVariant[] = ["well", "plain"];
+
+const COLUMNS = [
+  { id: "todo", title: "К выполнению", description: "Берём после планирования" },
+  { id: "progress", title: "В работе", description: "Не больше трёх задач на человека" },
+  { id: "done", title: "Готово", description: "Проверено и выкачено" },
+];
+
+const TASKS: Task[] = [
+  { id: "PRJ-214", title: "Экспорт счетов в CSV для бухгалтерии", due: "14 окт" },
+  { id: "PRJ-221", title: "Фильтр заказов по складу", due: "17 окт" },
+  { id: "PRJ-198", title: "Повторная отправка приглашений в команду", due: "10 окт" },
+  { id: "PRJ-176", title: "Онбординг нового проекта", due: "3 окт" },
+];
+
+const PLACEMENT = {
+  todo: ["PRJ-214", "PRJ-221"],
+  progress: ["PRJ-198"],
+  done: ["PRJ-176"],
+};
+
+export default function KanbanVariantsExample() {
+  return VARIANTS.map((variant) => (
+    <div key={variant}>
+      <div>
+        <Kanban.Root
+          aria-label={`Задачи релиза: ${variant}`}
+          className={styles.board}
+          variant={variant}
+          columns={COLUMNS}
+          items={TASKS}
+          getId={(task) => task.id}
+          getLabel={(task) => task.title}
+          defaultValue={PLACEMENT}
+          renderItem={(task) => (
+            <Kanban.Item>
+              <Kanban.ItemTitle>{task.title}</Kanban.ItemTitle>
+              <Kanban.ItemDescription>
+                {task.id} · до {task.due}
+              </Kanban.ItemDescription>
+            </Kanban.Item>
+          )}
+        />
+        <Typography as="span" variant="caption" tone="muted">
+          {variant}
+        </Typography>
+      </div>
+    </div>
+  ));
+}

package/dist/skill/reference/components/kbd/COMPONENT.md

@@ -0,0 +1,99 @@
+# Kbd
+
+**Category:** data-display
+**Kind:** primitive
+
+> A key cap for a keyboard key or a shortcut, rendered as a native `<kbd>`.
+
+## When to use
+- Shortcut hints inside buttons, search fields and menu items («Найти ⌘K», «/»).
+- Hotkey reference lists in help panels or settings.
+- Keys mentioned in instructions.
+
+## When not to use
+- A status, category or counter → use [Badge](../badge/COMPONENT.md).
+- A clickable control → use [Button](../button/COMPONENT.md).
+- A block of code → use [CodeBlock](../code-block/COMPONENT.md).
+
+## Import
+```tsx
+import { Kbd } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Kbd              <kbd>; one key, its badge tier, children (text, Icon or both)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Kbd
+`ref` → `HTMLElement`. A native `<kbd>`: one key per `Kbd`; passes its tier to a nested `Icon`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Badge tier, 16 · 20 · 24 · 28 · 32 px high. Without it the key follows the surrounding control one tier down (m → s); outside a control it is `m`. |
+| `children` | `ReactNode` | — | Key label, an `Icon`, or an icon and text. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "size">` | — | `className`, `title`, `aria-label` and the other `<kbd>` attributes. |
+
+## Variants
+Kbd has one look: monospace text in `text-secondary` on a translucent `fill-subtle-active` wash, no border, weight 500. No `variant`, `tone` or `color`.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 16px high, text 12, icon 12 | inside `xs` / `s` controls, dense menus | |
+| `s` | 20px high, text 12, icon 12 | inside `m` controls (inherited automatically) | |
+| `m` | 24px high, text 12, icon 14 | standalone keys in lists and text | yes (outside controls) |
+| `l` | 28px high, text 13, icon 16 | larger help panels | |
+| `xl` | 32px high, text 14, icon 16 | onboarding hints | |
+| — (omitted) | one tier below the surrounding control: `xs`/`s` → `xs`, `m` → `s`, `l` → `m`, `xl` → `l` | inside Button, Input, menu items | yes (inside controls) |
+
+Minimum width equals the height, so single-character keys are square.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| static | — | no hover, focus, disabled or loading |
+| size | `size`, else the surrounding control, else `m` | `data-size` (nominal), `data-tier` (visual tier, drives every dimension) |
+
+## Layout & spacing
+- Inline-flex, centered content, never shrinks, `vertical-align: middle`.
+- Keys of one chord: `gap: var(--prime-space-1)`; an optional «+» between them is `aria-hidden`.
+- In a hotkey list: action left, keys right (`justify-content: space-between`), rows `gap: var(--prime-space-3)`.
+- In a field, put the key in `Input.InlineAffix side="end"`.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Renders a native `<kbd>`; its text is read as is.
+- Symbol keys (⌘ ⌥ ⇧ ↵) need `aria-label` and `title` («Command», «Shift»).
+- A visual «+» between keys gets `aria-hidden="true"`.
+
+### 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 shortcut as one key per `Kbd`; symbol keys get a name — `aria-label`, `title`. |
+| [sizes.tsx](examples/sizes.tsx) | Every badge tier, 16 to 32 px high — `size`. |
+| [in-controls.tsx](examples/in-controls.tsx) | Inside a button or a field the key takes the tier one step down; an explicit `size` overrides it. |
+| [shortcut-list.tsx](examples/shortcut-list.tsx) | A hotkey reference: action on the left, its keys on the right, an icon inside a key. |
+
+## Mistakes
+- `<Kbd>⌘ + Shift + P</Kbd>` → one `Kbd` per key with an `aria-hidden` «+» between.
+- `<Kbd>⌘</Kbd>` without a name → add `aria-label="Command"`.
+- An explicit `size="m"` inside an `m` button → drop `size`; the key follows the button one tier down.
+- A `<span>` styled as a key, or a `Badge` used for a key → use `Kbd`.
+
+## Related
+- **Built from:** —
+- **See also:** [Badge](../badge/COMPONENT.md) (same tiers), [CommandMenu](../command-menu/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md)

package/dist/skill/reference/components/kbd/examples/examples.module.css

@@ -0,0 +1,37 @@
+/* Layout of the Kbd scenarios: semantic tokens only. */
+
+/* Keys of one chord: tighter than a control gap. */
+.chord {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--prime-space-1);
+}
+
+/* in-controls.tsx: two buttons and a search field. */
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* shortcut-list.tsx: action left, keys right. */
+.list {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-s));
+  margin: 0;
+}
+
+.listRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+}
+
+.listRow dd {
+  margin: 0;
+}

package/dist/skill/reference/components/kbd/examples/in-controls.tsx

@@ -0,0 +1,34 @@
+/** Inside a button or a field the key takes the tier one step down; an explicit `size` overrides it. */
+import { Button, Input, Kbd } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function KbdInControlsExample() {
+  return (
+    <div className={styles.controls}>
+      <Button.Root variant="outline" tone="neutral">
+        Найти
+        <span className={styles.chord}>
+          <Kbd aria-label="Command" title="Command">
+            ⌘
+          </Kbd>
+          <Kbd>K</Kbd>
+        </span>
+      </Button.Root>
+      <Button.Root tone="neutral">
+        Отправить
+        <Kbd size="xs" aria-label="Enter" title="Enter">
+          ↵
+        </Kbd>
+      </Button.Root>
+      <Input.Root>
+        <Input.Wrapper>
+          <Input.Field type="search" placeholder="Поиск по документам" aria-label="Поиск" />
+          <Input.InlineAffix side="end">
+            <Kbd>/</Kbd>
+          </Input.InlineAffix>
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/kbd/examples/overview.tsx

@@ -0,0 +1,24 @@
+/** A shortcut as one key per `Kbd`; symbol keys get a name — `aria-label`, `title`. */
+import { Kbd, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function KbdOverviewExample() {
+  return (
+    <span className={styles.chord}>
+      <Kbd aria-label="Command" title="Command">
+        ⌘
+      </Kbd>
+      <Typography as="span" variant="body-m" tone="muted" aria-hidden="true">
+        +
+      </Typography>
+      <Kbd aria-label="Shift" title="Shift">
+        ⇧
+      </Kbd>
+      <Typography as="span" variant="body-m" tone="muted" aria-hidden="true">
+        +
+      </Typography>
+      <Kbd>P</Kbd>
+    </span>
+  );
+}

package/dist/skill/reference/components/kbd/examples/shortcut-list.tsx

@@ -0,0 +1,49 @@
+/** A hotkey reference: action on the left, its keys on the right, an icon inside a key. */
+import { Icon, Kbd, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Accessible names for symbol keys. */
+const KEY_NAMES: Partial<Record<string, string>> = { "⌘": "Command" };
+
+const SHORTCUTS = [
+  { action: "Открыть палитру команд", keys: ["⌘", "K"] },
+  { action: "Сохранить черновик", keys: ["⌘", "S"] },
+  { action: "Перейти к поиску", keys: ["/"] },
+] as const;
+
+export default function KbdShortcutListExample() {
+  return (
+    <dl className={styles.list}>
+      {SHORTCUTS.map((item) => (
+        <div key={item.action} className={styles.listRow}>
+          <dt>
+            <Typography as="span" variant="body-m">
+              {item.action}
+            </Typography>
+          </dt>
+          <dd className={styles.chord}>
+            {item.keys.map((key) => (
+              <Kbd key={key} aria-label={KEY_NAMES[key]} title={KEY_NAMES[key]}>
+                {key}
+              </Kbd>
+            ))}
+          </dd>
+        </div>
+      ))}
+      <div className={styles.listRow}>
+        <dt>
+          <Typography as="span" variant="body-m">
+            Закрыть окно
+          </Typography>
+        </dt>
+        <dd className={styles.chord}>
+          <Kbd>
+            <Icon name="action.close" />
+            Esc
+          </Kbd>
+        </dd>
+      </div>
+    </dl>
+  );
+}

package/dist/skill/reference/components/kbd/examples/sizes.tsx

@@ -0,0 +1,19 @@
+/** Every badge tier, 16 to 32 px high — `size`. */
+import { Kbd, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function KbdSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Kbd size={size}>Ctrl</Kbd>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/label/COMPONENT.md

@@ -0,0 +1,126 @@
+# Label
+
+**Category:** inputs
+**Kind:** primitive
+
+> Field label (native `<label>`) with required and optional markers.
+
+## When to use
+- Above a control that has no built-in `label` prop: a custom control, or a hand-built field where you wire the ids yourself.
+- When a label needs an icon (`Label.Icon`) or an inline clarification (`Label.Description`).
+
+## When not to use
+- Input, Textarea, Select, SegmentedControl, DigitInput, Radio.Group and other fields with a `label` prop → pass `label`, `required`, `optional` to the field; it renders Label itself ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)).
+- Help or error text under a field → use [Hint](../hint/COMPONENT.md).
+- Labels for checkboxes, radios and switches → use their own label parts ([Checkbox](../checkbox/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md)).
+- Section or card headings → use [Typography](../typography/COMPONENT.md).
+- A placeholder instead of a label → never; always render a label.
+
+## Import
+```tsx
+import { Label } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Label.Root            <label>: text, then the required `*` or the optional marker
+├─ Label.Icon         muted leading icon slot (sized by the label size, aria-hidden)
+└─ Label.Description  muted inline clarification (units, context)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Label.Root
+`ref` → `HTMLLabelElement`. The native `<label>`: text, then the required `*` or the optional marker; provides its size to the icons inside.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Size of the paired field: xs/s 12/16 · m 13/20 · l/xl 14/20, weight 500. Without it the tier of its host, else `m`. |
+| `required` | `boolean` | — | Appends a red `*` (`aria-hidden`). Put native `required` on the control itself. |
+| `optional` | `boolean` | — | Appends the muted optional marker (`labels.optional`). |
+| `disabled` | `boolean` | — | Disabled color for the text and the markers, `aria-disabled`. |
+| `labels` | `Partial<LabelLabels>` | — | Built-in strings, see Labels. |
+| `htmlFor` | `string` | — | Id of a native control. For a custom control give the label an `id` and set `aria-labelledby` on the control. |
+| `…rest` | `Omit<LabelHTMLAttributes<HTMLLabelElement>, "size">` | — | `id`, `className` and the other label attributes. |
+
+### Label.Icon
+`ref` → `HTMLSpanElement`. A muted, non-shrinking icon slot (`aria-hidden`) before the text; kit icons take the label size. Native `<span>` props.
+
+### Label.Description
+`ref` → `HTMLSpanElement`. Regular-weight muted text in the same line (units, context); part of the accessible name. Native `<span>` props.
+
+## Variants
+Label has no `variant` or `tone`.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 12/16, medium, primary | Above an `xs` field | |
+| `s` | 12/16, medium, primary | Above an `s` field | |
+| `m` | 13/20, medium, primary | Above an `m` field | yes |
+| `l` | 14/20, medium, primary | Above an `l` field | |
+| `xl` | 14/20, medium, primary | Above an `xl` field | |
+
+**Sizes:** always the size of the field below. `xs`/`s` and `l`/`xl` share the type size; the difference is in the field height.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `required` | Red `*` right after the text | Most fields are optional — mark the required ones | — |
+| `optional` | Muted regular «необязательно» right after the text | Most fields are required — mark the optional ones | — |
+| `disabled` | Text, `*`, marker, description and icon in disabled color | The paired control is disabled | — |
+
+**Combinations**
+- Recommended: mark the minority of fields in a form; `Label.Description` for units («₽, без НДС»).
+- Pointless: `required` and `optional` together.
+- Forbidden: `required` without native `required` (or `aria-required`) on the control — the asterisk is decorative only.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| disabled | `disabled` | `data-disabled="true"`, `aria-disabled="true"` |
+| size | `size` | `data-size` |
+
+The label has no hover or focus state; clicking it focuses the control bound with `htmlFor`.
+
+## Layout & spacing
+- Label → field: the tier `label-gap` (`--prime-control-<size>-label-gap`: `--prime-space-1` on xs/s, `--prime-space-2` on m–xl) — the same gap fields use for their built-in label.
+- Inline-flex, wraps long text (`overflow-wrap: anywhere`); markers are separated by `--prime-space-1`.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Bind with `htmlFor` to a native control, or set `id` on the label and `aria-labelledby` on a custom control (a `role="radiogroup"`, a `fieldset` of cells).
+- The `*` is `aria-hidden`; requiredness must come from the control (`required`).
+- The optional marker and `Label.Description` are visible text and part of the accessible name; `Label.Icon` is `aria-hidden`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the text when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A standalone label above a hand-built field, linked to its input through `htmlFor` and `id`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the label takes the size of the field below it — `size`. |
+| [states.tsx](examples/states.tsx) | A default label next to a disabled one; the markers dim with the text — `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the text, sized by the label — `Label.Icon`. |
+| [structure.tsx](examples/structure.tsx) | The required asterisk, the optional marker and an inline clarification — `required`, `optional`, `Label.Description`. |
+
+## Mistakes
+- `<Label.Root>` above an Input → use `label` on `Input.Root` instead.
+- `required` on the label only → add native `required` on the control.
+- `htmlFor` pointing at a custom control or a fieldset → use `id` + `aria-labelledby`.
+- Label size different from the field size → use the same `size`.
+
+## Related
+- **Built from:** —
+- **See also:** [Hint](../hint/COMPONENT.md) — text under the field; [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/dist/skill/reference/components/label/examples/examples.module.css

@@ -0,0 +1,16 @@
+/* Layout of the Label scenarios: semantic tokens only. */
+
+/* overview.tsx: label → control gap of the m tier, like a field's own label. */
+.field {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--prime-control-m-label-gap);
+}
+
+/* structure.tsx: one label per row, its caption under it. */
+.structure {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+}

package/dist/skill/reference/components/label/examples/overview.tsx

@@ -0,0 +1,20 @@
+/** A standalone label above a hand-built field, linked to its input through `htmlFor` and `id`. */
+import { Input, Label } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function LabelOverviewExample() {
+  const inputId = React.useId();
+
+  return (
+    <div className={styles.field}>
+      <Label.Root htmlFor={inputId}>Название проекта</Label.Root>
+      <Input.Root id={inputId}>
+        <Input.Wrapper>
+          <Input.Field defaultValue="Редизайн личного кабинета" />
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/label/examples/sizes.tsx

@@ -0,0 +1,19 @@
+/** Every size; the label takes the size of the field below it — `size`. */
+import { Label, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function LabelSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Label.Root size={size}>Рабочая почта</Label.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}