prime-ui-kit 0.3.1 → 0.4.0

package/src/components/input/examples/login-email.tsx

@@ -0,0 +1,33 @@
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Вход: email с подписью, иконкой и автозаполнением.
+ */
+export default function LoginEmailExample() {
+  const [email, setEmail] = React.useState("");
+
+  return (
+    <Input.Root
+      size="m"
+      label="Электронная почта"
+      hint="Мы отправим код подтверждения на этот адрес"
+    >
+      <Input.Wrapper>
+        <Input.Icon side="start">
+          <Icon name="field.email" size="s" tone="subtle" />
+        </Input.Icon>
+        <Input.Field
+          type="email"
+          name="email"
+          autoComplete="email"
+          inputMode="email"
+          placeholder="you@example.com"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+        />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}

package/src/components/input/examples/password-with-hint.tsx

@@ -0,0 +1,28 @@
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Пароль: подсказка под полем и иконка справа (декоративная, без роли имени).
+ */
+export default function PasswordWithHintExample() {
+  const [password, setPassword] = React.useState("");
+
+  return (
+    <Input.Root size="m" label="Пароль" hint="Не менее 8 символов, буквы и цифры">
+      <Input.Wrapper>
+        <Input.Field
+          type="password"
+          name="password"
+          autoComplete="current-password"
+          placeholder="••••••••"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          required
+        />
+        <Input.Icon side="end">
+          <Icon name="status.locked" size="s" tone="subtle" />
+        </Input.Icon>
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}

package/src/components/input/examples/search.tsx

@@ -0,0 +1,31 @@
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Поиск: контролируемое значение и иконка слева.
+ */
+export default function SearchExample() {
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <Input.Root
+      size="m"
+      label="Поиск по каталогу"
+      hint={query ? `Запрос: «${query}»` : "Введите название или артикул"}
+    >
+      <Input.Wrapper>
+        <Input.Icon side="start">
+          <Icon name="nav.layoutGrid" size="s" tone="subtle" />
+        </Input.Icon>
+        <Input.Field
+          type="search"
+          name="q"
+          placeholder="Название или артикул"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          aria-label="Поиск по каталогу"
+        />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}

package/src/components/kbd/COMPONENT.md

@@ -2,23 +2,12 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
 
-`Kbd` is a single-part primitive: `Kbd.Root` renders a semantic `kbd` with kit styling so key names and shortcut fragments read as UI chrome, not body copy.
+`Kbd` — примитив из одной части: **`Kbd.Root`** рендерит семантический **`kbd`** с оформлением кита (поднятая поверхность, рамка, лёгкая тень). Только **отображение** подписи клавиши; события клавиатуры и фокус не обрабатывает.
 
-- **When to use** — show hotkeys next to menu items, toolbar actions, or command labels in dense app chrome.
-- **When to use** — mark one or a few keys inside helper text, field hints, or modal footers where the shortcut is part of the instruction.
-- **When to use** — pair with the same `size` tier as nearby controls so typography and nested icons stay aligned with [Input](../input/COMPONENT.md), [Button](../button/COMPONENT.md), or other sized surfaces.
-- **When not to use** — as the only actionable control; shortcuts still need a real [Button](../button/COMPONENT.md), [Link button](../link-button/COMPONENT.md), or focusable target.
-- **When not to use** — when you need the element to listen for or mirror actual keyboard input; this component is display-only.
-- **When not to use** — for long prose or documentation pages where plain text or a code font is clearer than chip-style keys.
-
-## Composition
-
-- **`Kbd`** exports **`Root` only** — a flat API with no nested parts or ordering rules beyond wrapping the key label (text, icons, or mixed `ReactNode`) inside **`Kbd.Root`**.
-- **`Root`** renders a native **`kbd`**, applies `data-size`, and wraps **`children`** in **`ControlSizeProvider`** so nested **`Icon`** (and similar) pick up the same control-size context.
-
-### Minimal example
+- **API:** `size?: "s" | "m" | "l" | "xl"`; без пропа размер берётся из ближайшего **`ControlSizeProvider`**, иначе **`"m"`**; на поверхности контрола **`xs`** маппится в **`s`** для `kbd`.
+- **Импорт:** `import { Kbd } from "prime-ui-kit"` → **`Kbd.Root`**.
 
 ```tsx
 import { Kbd } from "prime-ui-kit";
@@ -28,14 +17,48 @@ export function Example() {
 }
 ```
 
-## Rules
+Секция Kbd в плейграунде (`playground/sections/KbdSection.tsx`) рендерит сниппеты из **`playground/snippets/kbd/*.tsx`**. Файлы в **`examples/`** с пометкой parity повторяют те же сценарии с импортом **`"prime-ui-kit"`** для копирования в приложение. Остальные примеры — продуктовые сценарии. Подробности — в **Extended**.
+
+## Extended
+
+### About
+
+`Kbd.Root` помечает имена клавиш и фрагменты шорткатов как UI-хром, а не как основной текст абзаца.
+
+- **When to use** — горячие клавиши у пунктов меню, действий тулбара, подписей в [Command menu](../command-menu/COMPONENT.md).
+- **When to use** — одна или несколько клавиш во вспомогательном тексте, подсказках полей, футерах модалок, где шорткат — часть инструкции.
+- **When to use** — согласовать **`size`** с соседними контролами ([Input](../input/COMPONENT.md), [Button](../button/COMPONENT.md)), чтобы вложенные иконки и кегль совпадали с рядом стоящими контролами.
+- **When not to use** — как единственный интерактивный элемент; нужна настоящая [Button](../button/COMPONENT.md), [Link button](../link-button/COMPONENT.md) или другой фокусируемый target.
+- **When not to use** — для зеркалирования или перехвата реального ввода с клавиатуры; компонент только показывает подпись.
+- **When not to use** — в длинной документации, где обычный текст или моноширинный шрифт читабельнее «чипов» клавиш.
+
+### Examples (`examples/`)
+
+| Файл | Сценарий |
+|------|----------|
+| [`examples/sizes-ladder.tsx`](examples/sizes-ladder.tsx) | Ряд **`Kbd.Root`** с **`size`** `s`–`xl` (`snippets/kbd/sizes.tsx`). |
+| [`examples/states-title.tsx`](examples/states-title.tsx) | Без отдельных пропов состояния; **`title`** для нативной подсказки (`snippets/kbd/states.tsx`). |
+| [`examples/composition-chord-icon.tsx`](examples/composition-chord-icon.tsx) | Аккорд **`⌘` + `K`** и ряд с **`Icon`** внутри одного **`Kbd.Root`** (`snippets/kbd/composition.tsx`). |
+| [`examples/context-inherit-size.tsx`](examples/context-inherit-size.tsx) | Размер без пропа из **`ControlSizeProvider`**, **`xs`→`s`**, явный **`size`** перекрывает контекст (`snippets/kbd/inherit-size.tsx`). |
+| [`examples/shortcut-row.tsx`](examples/shortcut-row.tsx) | Строка списка/меню: подпись действия и шорткат справа. |
+| [`examples/docs-legend.tsx`](examples/docs-legend.tsx) | Легенда в документации: сетка «действие → комбинация». |
+| [`examples/toolbar-hints.tsx`](examples/toolbar-hints.tsx) | Тулбар: кнопка и рядом компактная подсказка-клавиши. |
+| [`examples/combination-keys.tsx`](examples/combination-keys.tsx) | Аккорд: несколько **`Kbd.Root`** и разделители вне ключей. |
+| [`examples/inline-doc-hint.tsx`](examples/inline-doc-hint.tsx) | Встроенная в абзац подсказка с **`Kbd`** в потоке текста. |
+
+### Composition
+
+- **`Kbd`** экспортирует только **`Root`** — плоский API; внутрь передаётся подпись (текст, иконки, смешанный **`ReactNode`**).
+- **`Root`** выставляет **`data-size`**, оборачивает **`children`** в **`ControlSizeProvider`**, чтобы вложенные **`Icon`** наследовали контекст размера контрола.
+
+### Rules
 
-- **Sizing:** optional **`size`** is **`"s"` \| `"m"` \| `"l"` \| `"xl"`** (`KbdSize`). If omitted, the effective size comes from the nearest ancestor **`ControlSizeProvider`** (via **`useOptionalControlSize`**), mapped with **`controlSurfaceToInputSize`** — **`"xs"`** on the control surface becomes **`"s"`** on the `kbd`. If there is no context, the fallback is **`"m"`**.
-- **Presentation only:** the component does not handle key events, focus management, or OS shortcut state; it only displays a label.
-- **Semantics:** there is no **`asChild`** or element polymorphism — the root is always **`kbd`**.
-- **Accessibility:** semantic **`kbd`** helps assistive tech distinguish key labels from surrounding text. For chord hints, prefer several **`Kbd.Root`** instances with short separators (**`+`**, “or”) **outside** the keys, or mark decorative separators with **`aria-hidden`**, so they are not announced as part of each key. Use **`title`** (or visible copy) when the shortcut needs extra explanation; do not rely on surface color alone for meaning.
-- **Platform copy:** glyphs such as **⌘** vs **Ctrl** are a product/i18n choice; the kit does not normalize platform key names.
-- **Styling:** one built-in look (raised surface, border, light shadow). Further changes go through **`className`** or project styles, not a separate **`variant`** prop.
+- **Sizing:** см. Canonical; явный **`size`** перекрывает контекст.
+- **Presentation only:** нет обработки клавиш, фокуса и состояния ОС.
+- **Semantics:** полиморфизма **`asChild`** нет — корень всегда **`kbd`**.
+- **Accessibility:** для аккордов — несколько **`Kbd.Root`**; **`+`** / «или» выносить **вне** ключей или помечать **`aria-hidden`**, чтобы скринридер не зачитывал их как часть каждой клавиши. Для пояснения — **`title`** или видимый текст; смысл не только цветом.
+- **Platform copy:** **⌘** vs **Ctrl** и т.п. — решение продукта/i18n, кит не нормализует.
+- **Styling:** один встроенный вид; расширение через **`className`** / стили проекта, отдельного **`variant`** нет.
 
 ## API
 
@@ -43,17 +66,26 @@ export function Example() {
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| size | `KbdSize` (`"s" \| "m" \| "l" \| "xl"`) | from context or `"m"` | No | Nominal size; without the prop, taken from `ControlSizeProvider` if present, otherwise `"m"`; `xs` context maps to `s`. |
-| children | `React.ReactNode` | — | Yes | Key label, icons, or mixed content. |
-| className | `string` | — | No | Additional class on the `kbd`. |
-| …rest | `Omit<React.HTMLAttributes<HTMLElement>, "size">` | — | No | Native attributes (`title`, `hidden`, `aria-*`, `data-*`, etc.). |
+| size | `KbdSize` (`"s" \| "m" \| "l" \| "xl"`) | from context or `"m"` | No | Номинальный размер; без пропа — из `ControlSizeProvider` или `"m"`; контекст `xs` → `s` на `kbd`. |
+| children | `React.ReactNode` | — | Yes | Подпись клавиши, иконки или смешанный контент. |
+| className | `string` | — | No | Дополнительный класс на `kbd`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLElement>, "size">` | — | No | Нативные атрибуты (`title`, `hidden`, `aria-*`, `data-*`, …). |
 
 ## Related
 
-- [Button](../button/COMPONENT.md) — primary action a shortcut often refers to.
-- [Link button](../link-button/COMPONENT.md) — text-style actions that may show a key hint beside the label.
-- [Input](../input/COMPONENT.md) — fields whose `hint` or label area can include `Kbd`.
-- [Textarea](../textarea/COMPONENT.md) — multiline fields with the same hint pattern where applicable.
-- [Select](../select/COMPONENT.md) — triggers and lists that may document shortcuts.
-- [Tooltip](../tooltip/COMPONENT.md) — longer explanations that can repeat keys with `Kbd`.
-- [Command menu](../command-menu/COMPONENT.md) — lists that commonly show per-item shortcuts.
+- [Button](../button/COMPONENT.md) — действие, на которое часто ссылается шорткат.
+- [Link button](../link-button/COMPONENT.md) — текстовые действия с подсказкой клавиши рядом.
+- [Input](../input/COMPONENT.md) — поля, где в `hint` или у подписи уместен `Kbd`.
+- [Textarea](../textarea/COMPONENT.md) — многострочные поля с тем же паттерном подсказок.
+- [Select](../select/COMPONENT.md) — триггеры и списки с документированием шорткатов.
+- [Tooltip](../tooltip/COMPONENT.md) — развёрнутые пояснения с повтором клавиш через `Kbd`.
+- [Command menu](../command-menu/COMPONENT.md) — списки с пер-элементными шорткатами.
+
+## LLM note
+
+- Публичный API: **`Kbd.Root`** только; импорт **`{ Kbd } from "prime-ui-kit"`**.
+- Нет **`variant`**, **`disabled`**, **`asChild`**; для подсказок используй нативные атрибуты (**`title`**, **`aria-*`**).
+- Аккорд: **не** клади строку `"⌘+K"` в один **`Kbd.Root`**, если нужна семантика «отдельные клавиши» — делай **`Kbd.Root` на каждую клавишу**, плюс **`span aria-hidden`** между ними для **`+`**.
+- Размер без пропа: **`useOptionalControlSize`** → **`controlSurfaceToInputSize`**; **`xs`** контекста → эффективный **`s`** на компоненте.
+- Не подменяй кнопку или ссылку одним **`Kbd`**; не ожидай событий клавиатуры от этого компонента.
+- Сценарии копирования: **`playground/snippets/kbd/*.tsx`** (демо) и зеркала в **`src/components/kbd/examples/*.tsx`** (импорт **`"prime-ui-kit"`**); parity-файлы названы в таблице выше.

package/src/components/kbd/examples/combination-keys.tsx

@@ -0,0 +1,22 @@
+import { Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x1)",
+};
+
+/** Аккорд из нескольких клавиш: каждая клавиша — отдельный `Kbd.Root`, плюс вне ключей. */
+export default function CombinationKeysExample() {
+  return (
+    <div style={row}>
+      <Kbd.Root>Ctrl</Kbd.Root>
+      <span aria-hidden="true">+</span>
+      <Kbd.Root>Shift</Kbd.Root>
+      <span aria-hidden="true">+</span>
+      <Kbd.Root>P</Kbd.Root>
+    </div>
+  );
+}

package/src/components/kbd/examples/composition-chord-icon.tsx

@@ -0,0 +1,34 @@
+import { Icon, Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x1)",
+};
+
+const stack: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--prime-sys-spacing-m)",
+};
+
+/** Сочетание из нескольких `Kbd.Root` и один бейдж с иконкой внутри (parity with `playground/snippets/kbd/composition.tsx`). */
+export default function KbdCompositionChordIconExample() {
+  return (
+    <div style={stack}>
+      <div style={row}>
+        <Kbd.Root>⌘</Kbd.Root>
+        <span aria-hidden="true">+</span>
+        <Kbd.Root>K</Kbd.Root>
+      </div>
+      <div style={row}>
+        <Kbd.Root size="m">
+          <Icon name="action.close" aria-hidden />
+          <span>Esc</span>
+        </Kbd.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/kbd/examples/context-inherit-size.tsx

@@ -0,0 +1,46 @@
+import { ControlSizeProvider, Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x1)",
+};
+
+const stack: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--prime-sys-spacing-m)",
+};
+
+/**
+ * Без `size` — масштаб из ближайшего `ControlSizeProvider`; явный `size` перекрывает контекст.
+ * Контекст `xs` на поверхности контрола маппится в эффективный `s` на kbd (parity with `playground/snippets/kbd/inherit-size.tsx`).
+ */
+export default function KbdContextInheritSizeExample() {
+  return (
+    <div style={stack}>
+      <ControlSizeProvider value="xl">
+        <div style={row}>
+          <Kbd.Root>Ctrl</Kbd.Root>
+          <span aria-hidden="true">+</span>
+          <Kbd.Root>B</Kbd.Root>
+        </div>
+      </ControlSizeProvider>
+      <ControlSizeProvider value="s">
+        <div style={row}>
+          <Kbd.Root>Tab</Kbd.Root>
+        </div>
+      </ControlSizeProvider>
+      <ControlSizeProvider value="xs">
+        <div style={row}>
+          <Kbd.Root>xs→s</Kbd.Root>
+        </div>
+      </ControlSizeProvider>
+      <ControlSizeProvider value="xl">
+        <Kbd.Root size="s">Явный s</Kbd.Root>
+      </ControlSizeProvider>
+    </div>
+  );
+}

package/src/components/kbd/examples/docs-legend.tsx

@@ -0,0 +1,44 @@
+import { Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const grid: React.CSSProperties = {
+  display: "grid",
+  gridTemplateColumns: "1fr auto",
+  alignItems: "center",
+  columnGap: "var(--prime-sys-spacing-l)",
+  rowGap: "var(--prime-sys-spacing-s)",
+  maxWidth: "calc(var(--prime-sys-unit-1rem) * 24)",
+};
+
+const chord: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x1)",
+};
+
+/** Легенда в документации: пары «действие → комбинация». */
+export default function DocsLegendExample() {
+  return (
+    <dl style={grid}>
+      <dt>Copy</dt>
+      <dd style={chord}>
+        <Kbd.Root>⌘</Kbd.Root>
+        <span aria-hidden="true">+</span>
+        <Kbd.Root>C</Kbd.Root>
+      </dd>
+      <dt>Command palette</dt>
+      <dd style={chord}>
+        <Kbd.Root>⌘</Kbd.Root>
+        <span aria-hidden="true">+</span>
+        <Kbd.Root>K</Kbd.Root>
+      </dd>
+      <dt>Undo</dt>
+      <dd style={chord}>
+        <Kbd.Root>⌘</Kbd.Root>
+        <span aria-hidden="true">+</span>
+        <Kbd.Root>Z</Kbd.Root>
+      </dd>
+    </dl>
+  );
+}

package/src/components/kbd/examples/inline-doc-hint.tsx

@@ -0,0 +1,18 @@
+import { Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const paragraph: React.CSSProperties = {
+  maxWidth: "calc(var(--prime-sys-unit-1rem) * 32)",
+  margin: 0,
+  font: "inherit",
+  color: "var(--prime-sys-color-content-primary)",
+};
+
+/** Встроенная подсказка в тексте: `Kbd` в потоке абзаца. */
+export default function InlineDocHintExample() {
+  return (
+    <p style={paragraph}>
+      To cancel, press <Kbd.Root>Esc</Kbd.Root>. To confirm, press <Kbd.Root>Enter</Kbd.Root>.
+    </p>
+  );
+}

package/src/components/kbd/examples/shortcut-row.tsx

@@ -0,0 +1,21 @@
+import { Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const shortcutRow: React.CSSProperties = {
+  boxSizing: "border-box",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: "var(--prime-sys-spacing-m)",
+  maxWidth: "calc(var(--prime-sys-unit-1rem) * 22)",
+};
+
+/** Строка меню или списка команд: действие слева, шорткат справа (`size="s"` — плотный хром). */
+export default function ShortcutRowExample() {
+  return (
+    <div style={shortcutRow}>
+      <span>Save</span>
+      <Kbd.Root size="s">⌘S</Kbd.Root>
+    </div>
+  );
+}

package/src/components/kbd/examples/sizes-ladder.tsx

@@ -0,0 +1,21 @@
+import { Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x1)",
+};
+
+/** Номинальные размеры `s`–`xl` (parity with `playground/snippets/kbd/sizes.tsx`). */
+export default function KbdSizesLadderExample() {
+  return (
+    <div style={row}>
+      <Kbd.Root size="s">Kbd s</Kbd.Root>
+      <Kbd.Root size="m">Kbd m</Kbd.Root>
+      <Kbd.Root size="l">Kbd l</Kbd.Root>
+      <Kbd.Root size="xl">Kbd xl</Kbd.Root>
+    </div>
+  );
+}

package/src/components/kbd/examples/states-title.tsx

@@ -0,0 +1,19 @@
+import { Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x1)",
+};
+
+/** Обычный `Kbd` и вариант с нативной подсказкой через `title` (parity with `playground/snippets/kbd/states.tsx`). */
+export default function KbdStatesTitleExample() {
+  return (
+    <div style={row}>
+      <Kbd.Root>Enter</Kbd.Root>
+      <Kbd.Root title="Сохранить и закрыть">Ctrl+Enter</Kbd.Root>
+    </div>
+  );
+}

package/src/components/kbd/examples/toolbar-hints.tsx

@@ -0,0 +1,31 @@
+import { Button, Kbd } from "prime-ui-kit";
+import type * as React from "react";
+
+const toolbar: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-m)",
+};
+
+const hintCluster: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x2)",
+};
+
+/** Подсказки у тулбара: основное действие и рядом компактные клавиши того же визуального ряда. */
+export default function ToolbarHintsExample() {
+  return (
+    <div role="toolbar" aria-label="Formatting" style={toolbar}>
+      <div style={hintCluster}>
+        <Button.Root size="m">Bold</Button.Root>
+        <Kbd.Root size="s">⌘B</Kbd.Root>
+      </div>
+      <div style={hintCluster}>
+        <Button.Root size="m">Italic</Button.Root>
+        <Kbd.Root size="s">⌘I</Kbd.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/label/COMPONENT.md

@@ -2,7 +2,29 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
+
+- **Surface:** `Label.Root` is always a native **`<label>`**; slots **`Label.Icon`**, **`Label.Asterisk`**, **`Label.Sub`** for icon, required marker, secondary text.
+- **Associate** the caption with a control: **`htmlFor`** on **`Label.Root`** = control **`id`**, or nest the control inside **`Label.Root`**.
+- **Required:** **`Label.Asterisk`** is visual only; set **`required`** / **`aria-required`** on the control. Optional fields often use **`Label.Sub`** (e.g. “optional”).
+- **Defaults:** **`size="m"`** on **`Label.Root`**; **`disabled`** sets **`aria-disabled`** + muted styles (mirror real control state).
+- **Playground:** [`playground/sections/LabelSection.tsx`](../../../playground/sections/LabelSection.tsx) renders snippets from [`playground/snippets/label/`](../../../playground/snippets/label/).
+- **Package examples** (import **`"prime-ui-kit"`**): see the table under [Example files in `examples/`](#example-files-in-examples); each row maps a snippet to a twin under [`examples/`](examples/).
+
+## LLM note
+
+When generating UI with **Label**:
+
+1. Never drop **programmatic association**: every **`Label.Root`** must either use **`htmlFor` + matching `id`** on the control or wrap the control inside the root.
+2. Do not treat **`Label.Asterisk`** as sufficient for “required”; always set **`required`** (and validation) on the actual input/select/textarea (and **`aria-required`** if you mirror state without the native attribute).
+3. Decorative icons in **`Label.Icon`** should use **`aria-hidden="true"`** when the visible label text already names the field.
+4. Prefer **[Hint](../hint/COMPONENT.md)** (or field error UI) for validation and long help; **`Label.Sub`** is for a short secondary line in the label row, not a substitute for error text.
+5. The root is **not** polymorphic: no **`asChild`** — do not swap **`label`** for another element.
+6. For a **group** of related fields, use **`<fieldset>`** + **`<legend>`** (or an equivalent ARIA grouping pattern) and keep **one `Label.Root` per control** where each control has its own **`id`**.
+
+## Extended
+
+### About
 
 Composite caption for form fields: `Label.Root` is a native `label` with optional slots `Label.Icon`, `Label.Asterisk`, and `Label.Sub` for icon, required marker, and secondary text.
 
@@ -13,7 +35,7 @@ Composite caption for form fields: `Label.Root` is a native `label` with optiona
 - **Do not use** expecting the label to set `required` on inputs; that remains on the control.
 - **Do not use** `Label` as a non-label wrapper; the root is always a `label` element (no polymorphic `asChild`).
 
-## Composition
+### Composition
 
 - **`Label.Root`** — `<label>`; sets `data-size` (from `size`, default `m`) and `data-disabled` when `disabled`. Wraps children in `LabelSizeContext` so slots inherit the same size.
 - **`Label.Icon`** — `<span>` before or beside the main text; forwards label size to children via `ControlSizeProvider` (e.g. for kit `Icon` sizing).
@@ -36,7 +58,31 @@ export function Example() {
 }
 ```
 
-## Rules
+### Example files in `examples/`
+
+| File | Scenario |
+|------|----------|
+| [`sizes.tsx`](examples/sizes.tsx) | `size` `s`–`xl`, text-only and with `Label.Icon` ([`snippets/label/sizes.tsx`](../../../playground/snippets/label/sizes.tsx)) |
+| [`states.tsx`](examples/states.tsx) | Default, `disabled`, `Label.Asterisk` ([`snippets/label/states.tsx`](../../../playground/snippets/label/states.tsx)) |
+| [`with-icon.tsx`](examples/with-icon.tsx) | `Label.Icon` + `htmlFor`; same composition pattern as [`snippets/label/composition.tsx`](../../../playground/snippets/label/composition.tsx) (snippet uses `field.email` / Russian copy) |
+| [`sub-line.tsx`](examples/sub-line.tsx) | `Label.Sub` for a short secondary line ([`snippets/label/sub-line.tsx`](../../../playground/snippets/label/sub-line.tsx)) |
+| [`mixed-required-optional.tsx`](examples/mixed-required-optional.tsx) | `Label.Asterisk` vs `Label.Sub` “optional” ([`snippets/label/mixed-required-optional.tsx`](../../../playground/snippets/label/mixed-required-optional.tsx)) |
+| [`required-field.tsx`](examples/required-field.tsx) | Required marker + `required` on the control |
+| [`optional-field.tsx`](examples/optional-field.tsx) | `Label.Sub` “optional” + sibling input |
+| [`grouped-labels.tsx`](examples/grouped-labels.tsx) | `fieldset` / `legend` + per-field labels |
+| [`accessibility-pattern.tsx`](examples/accessibility-pattern.tsx) | `htmlFor`/`id`, decorative icon, `required`, short `Label.Sub` vs long copy → [Hint](../hint/COMPONENT.md) |
+
+### Playground snippets (repo paths)
+
+| Snippet | Intent |
+|---------|--------|
+| [`sizes.tsx`](../../../playground/snippets/label/sizes.tsx) | Scale `s`–`xl` with and without icon |
+| [`states.tsx`](../../../playground/snippets/label/states.tsx) | Linked label, disabled look, asterisk |
+| [`composition.tsx`](../../../playground/snippets/label/composition.tsx) | Icon slot + caption + `htmlFor` |
+| [`sub-line.tsx`](../../../playground/snippets/label/sub-line.tsx) | `Label.Sub` units / context |
+| [`mixed-required-optional.tsx`](../../../playground/snippets/label/mixed-required-optional.tsx) | Required vs optional in one form row |
+
+### Rules
 
 - **Association:** set **`htmlFor` on `Label.Root`** to match the control’s **`id`**, or place the interactive control inside **`Label.Root`** so the caption is programmatically linked.
 - **`disabled` on `Label.Root`:** sets **`aria-disabled`** and **`data-disabled`** for muted styling; keep the actual field non-interactive (`disabled`, `readOnly`, etc.) or behavior will not match the label-only state.
@@ -45,10 +91,25 @@ export function Example() {
 - There is no separate **`variant`** prop; appearance follows **`size`** and slot composition (asterisk uses danger-accent styling from the theme).
 - The root does **not** implement **`asChild`**; it is always a **`label`**.
 - Nesting an input inside **`Label.Root`** is valid HTML; the common kit pattern is sibling **`Label.Root`** + control with **`htmlFor`** / **`id`**.
+- **Grouped fields:** use **`fieldset`** / **`legend`** (or `role="group"` with an accessible name) for the section; each control in the group still gets its own **`Label.Root`** and unique **`id`** unless the control is nested inside its label.
+
+### Scenarios (see `examples/` and playground snippets)
+
+| Scenario | Intent |
+|----------|--------|
+| Sizes | `size` ladder with optional `Label.Icon` — [`examples/sizes.tsx`](examples/sizes.tsx), [`snippets/label/sizes.tsx`](../../../playground/snippets/label/sizes.tsx) |
+| States | Default, `disabled`, asterisk-only marker — [`examples/states.tsx`](examples/states.tsx), [`snippets/label/states.tsx`](../../../playground/snippets/label/states.tsx) |
+| Icon composition | `Label.Icon` + text — [`examples/with-icon.tsx`](examples/with-icon.tsx), [`snippets/label/composition.tsx`](../../../playground/snippets/label/composition.tsx) |
+| Sub line | Short second line in the label — [`examples/sub-line.tsx`](examples/sub-line.tsx), [`snippets/label/sub-line.tsx`](../../../playground/snippets/label/sub-line.tsx) |
+| Mixed required / optional | Asterisk row + optional row — [`examples/mixed-required-optional.tsx`](examples/mixed-required-optional.tsx), [`snippets/label/mixed-required-optional.tsx`](../../../playground/snippets/label/mixed-required-optional.tsx) |
+| Required field | `Label.Asterisk` + **`required`** on the control — [`examples/required-field.tsx`](examples/required-field.tsx) |
+| Optional field | `Label.Sub` for “optional” (or similar); no asterisk — [`examples/optional-field.tsx`](examples/optional-field.tsx) |
+| Grouped labels | `fieldset` + `legend` + per-field `Label.Root` + `htmlFor` / `id` — [`examples/grouped-labels.tsx`](examples/grouped-labels.tsx) |
+| Accessibility | Association, decorative icon hidden, required on control, short sub-line vs [Hint](../hint/COMPONENT.md) — [`examples/accessibility-pattern.tsx`](examples/accessibility-pattern.tsx) |
 
-## API
+### API
 
-### Label.Root
+#### Label.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -59,7 +120,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Text and `Label.Icon`, `Label.Asterisk`, `Label.Sub` |
 | …rest | `Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "size">` | — | No | Other native `label` attributes (`size` is reserved for the design-system prop) |
 
-### Label.Icon
+#### Label.Icon
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -67,7 +128,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Typically an icon; receives control size from label context |
 | …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
 
-### Label.Asterisk
+#### Label.Asterisk
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -75,7 +136,7 @@ export function Example() {
 | children | `React.ReactNode` | `"*"` | No | Overrides the default asterisk character when provided |
 | …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
 
-### Label.Sub
+#### Label.Sub
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -83,7 +144,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Secondary line under the main caption |
 | …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
 
-## Related
+### Related
 
 - [Input](../input/COMPONENT.md)
 - [Textarea](../textarea/COMPONENT.md)