prime-ui-kit 0.0.1

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 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,30 @@
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Поиск: контролируемое значение и иконка слева.
+ */
+export default function SearchExample() {
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <Input.Root
+      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

@@ -0,0 +1,91 @@
+# Kbd
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+`Kbd` — примитив из одной части: **`Kbd.Root`** рендерит семантический **`kbd`** с оформлением кита (поднятая поверхность, рамка, лёгкая тень). Только **отображение** подписи клавиши; события клавиатуры и фокус не обрабатывает.
+
+- **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";
+
+export function Example() {
+  return <Kbd.Root>Esc</Kbd.Root>;
+}
+```
+
+Секция 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:** см. Canonical; явный **`size`** перекрывает контекст.
+- **Presentation only:** нет обработки клавиш, фокуса и состояния ОС.
+- **Semantics:** полиморфизма **`asChild`** нет — корень всегда **`kbd`**.
+- **Accessibility:** для аккордов — несколько **`Kbd.Root`**; **`+`** / «или» выносить **вне** ключей или помечать **`aria-hidden`**, чтобы скринридер не зачитывал их как часть каждой клавиши. Для пояснения — **`title`** или видимый текст; смысл не только цветом.
+- **Platform copy:** **⌘** vs **Ctrl** и т.п. — решение продукта/i18n, кит не нормализует.
+- **Styling:** один встроенный вид; расширение через **`className`** / стили проекта, отдельного **`variant`** нет.
+
+## API
+
+### Kbd.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| 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) — действие, на которое часто ссылается шорткат.
+- [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>
+          <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>Bold</Button.Root>
+        <Kbd.Root size="s">⌘B</Kbd.Root>
+      </div>
+      <div style={hintCluster}>
+        <Button.Root>Italic</Button.Root>
+        <Kbd.Root size="s">⌘I</Kbd.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/label/COMPONENT.md

@@ -0,0 +1,155 @@
+# Label
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## 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.
+
+- **Use** to associate visible text with a control via `htmlFor` / `id` or by nesting the control inside the root.
+- **Use** when you want a consistent type scale (`size`) and optional icon or second-line hint in one label row.
+- **Use** `Label.Asterisk` for a visual required marker next to the caption.
+- **Do not use** as a replacement for field validation messages or long help copy; pair with [Hint](../hint/COMPONENT.md) or similar when you need status or errors below the field.
+- **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
+
+- **`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).
+- **`Label.Asterisk`** — `<span>` for the required marker; default child text is `*` if `children` is omitted.
+- **`Label.Sub`** — `<span>` for secondary line or hint text on the same label.
+- Slot order in markup is flexible; keep reading order sensible for screen readers (e.g. icon, title, asterisk, sub).
+
+### Minimal example
+
+```tsx
+import { Label } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <>
+      <Label.Root htmlFor="field-id">Caption</Label.Root>
+      <input id="field-id" />
+    </>
+  );
+}
+```
+
+### 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.
+- **`Label.Icon`:** when the icon is decorative and the visible label text is sufficient, mark the icon **`aria-hidden`**.
+- **`Label.Asterisk`** is visual-only; expose required state on the control with **`required`** / **`aria-required`** and errors via hint or validation UI as needed.
+- 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
+
+#### Label.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Type scale, spacing, and size context for nested slots (e.g. `Label.Icon`) |
+| disabled | `boolean` | — | No | Disabled look; sets `aria-disabled` and `data-disabled` |
+| htmlFor | `string` | — | No | `id` of the associated control |
+| className | `string` | — | No | Additional class on the root |
+| 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
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the wrapper |
+| children | `React.ReactNode` | — | No | Typically an icon; receives control size from label context |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
+
+#### Label.Asterisk
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the wrapper |
+| children | `React.ReactNode` | `"*"` | No | Overrides the default asterisk character when provided |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
+
+#### Label.Sub
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the wrapper |
+| children | `React.ReactNode` | — | No | Secondary line under the main caption |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
+
+### Related
+
+- [Input](../input/COMPONENT.md)
+- [Textarea](../textarea/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [Checkbox](../checkbox/COMPONENT.md)
+- [Radio](../radio/COMPONENT.md)
+- [Switch](../switch/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)

package/src/components/label/examples/accessibility-pattern.tsx

@@ -0,0 +1,28 @@
+import { Icon, Label } from "prime-ui-kit";
+
+/**
+ * Accessibility checklist: `htmlFor`/`id` link; decorative icon `aria-hidden`;
+ * `required` on the input; short sub-line stays inside the label (long copy → Hint below field).
+ */
+export function AccessibilityPatternExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-a11y-email" id="example-label-a11y-email-label">
+        <Label.Icon>
+          <Icon aria-hidden name="field.email" />
+        </Label.Icon>
+        Billing contact email
+        <Label.Asterisk />
+        <Label.Sub>invoices and receipts</Label.Sub>
+      </Label.Root>
+      <input
+        id="example-label-a11y-email"
+        type="email"
+        name="billingEmail"
+        required
+        aria-required="true"
+        autoComplete="email"
+      />
+    </>
+  );
+}

package/src/components/label/examples/grouped-labels.tsx

@@ -0,0 +1,30 @@
+import { Label } from "prime-ui-kit";
+
+/**
+ * Grouped fields: `fieldset` + `legend` names the group; each control keeps its own
+ * `Label.Root` + unique `id` / `htmlFor` pair.
+ */
+export function GroupedLabelsExample() {
+  return (
+    <fieldset>
+      <legend>Billing address</legend>
+      <div>
+        <Label.Root htmlFor="example-label-group-line1">Address line 1</Label.Root>
+        <input id="example-label-group-line1" type="text" name="line1" required />
+      </div>
+      <div>
+        <Label.Root htmlFor="example-label-group-line2">
+          Address line 2<Label.Sub>optional</Label.Sub>
+        </Label.Root>
+        <input id="example-label-group-line2" type="text" name="line2" />
+      </div>
+      <div>
+        <Label.Root htmlFor="example-label-group-postal">
+          Postal code
+          <Label.Asterisk />
+        </Label.Root>
+        <input id="example-label-group-postal" type="text" name="postal" required />
+      </div>
+    </fieldset>
+  );
+}