prime-ui-kit 0.2.5 → 0.3.2

package/src/components/input/examples/checkout-full-width.module.css

@@ -0,0 +1,8 @@
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  width: 100%;
+  max-width: 28rem;
+  box-sizing: border-box;
+}

package/src/components/input/examples/checkout-full-width.tsx

@@ -0,0 +1,39 @@
+import { Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./checkout-full-width.module.css";
+
+/**
+ * Оформление заказа: колонка на всю ширину родителя (`Input.Root` уже тянется на 100%).
+ */
+export default function CheckoutFullWidthExample() {
+  const [fullName, setFullName] = React.useState("");
+  const [address, setAddress] = React.useState("");
+
+  return (
+    <div className={styles.column}>
+      <Input.Root size="m" label="ФИО получателя" hint="Как в паспорте — для доставки">
+        <Input.Wrapper>
+          <Input.Field
+            name="fullName"
+            autoComplete="name"
+            placeholder="Иванов Иван Иванович"
+            value={fullName}
+            onChange={(e) => setFullName(e.target.value)}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root size="m" label="Адрес доставки" optionalLabel="квартира, подъезд">
+        <Input.Wrapper>
+          <Input.Field
+            name="address"
+            autoComplete="street-address"
+            placeholder="Город, улица, дом"
+            value={address}
+            onChange={(e) => setAddress(e.target.value)}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

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,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
+      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)}
+        />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}

package/src/components/kbd/COMPONENT.md

@@ -0,0 +1,87 @@
+# 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>;
+}
+```
+
+Готовые сценарии — в **`examples/`** (ряд «действие — шорткат», легенда документации, подсказки у тулбара, аккорды из нескольких клавиш, встроенная подсказка в тексте). Подробности — в **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/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`**; не ожидай событий клавиатуры от этого компонента.
+- Сценарии копирования: смотри **`src/components/kbd/examples/*.tsx`**.

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/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/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

@@ -0,0 +1,125 @@
+# 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).
+- **Examples (source):** [`examples/required-field.tsx`](examples/required-field.tsx), [`examples/optional-field.tsx`](examples/optional-field.tsx), [`examples/grouped-labels.tsx`](examples/grouped-labels.tsx), [`examples/accessibility-pattern.tsx`](examples/accessibility-pattern.tsx), [`examples/with-icon.tsx`](examples/with-icon.tsx).
+
+## 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" />
+    </>
+  );
+}
+```
+
+### 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/`)
+
+| Scenario | Intent |
+|----------|--------|
+| Required field | `Label.Asterisk` + **`required`** on the control |
+| Optional field | `Label.Sub` for “optional” (or similar); no asterisk |
+| Grouped labels | `fieldset` + `legend` + per-field `Label.Root` + `htmlFor` / `id` |
+| Accessibility | Association, decorative icon hidden, required on control, short sub-line vs Hint |
+
+### 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>
+  );
+}

package/src/components/label/examples/optional-field.tsx

@@ -0,0 +1,14 @@
+import { Label } from "prime-ui-kit";
+
+/** Optional field: clarify in `Label.Sub` without a required marker on the control. */
+export function OptionalFieldExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-optional-note">
+        Internal comment
+        <Label.Sub>optional</Label.Sub>
+      </Label.Root>
+      <input id="example-label-optional-note" type="text" name="note" />
+    </>
+  );
+}

package/src/components/label/examples/required-field.tsx

@@ -0,0 +1,20 @@
+import { Label } from "prime-ui-kit";
+
+/** Required field: visual marker via `Label.Asterisk`; semantics via `required` on the control. */
+export function RequiredFieldExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-required-email">
+        Work email
+        <Label.Asterisk />
+      </Label.Root>
+      <input
+        id="example-label-required-email"
+        type="email"
+        name="email"
+        required
+        autoComplete="email"
+      />
+    </>
+  );
+}

package/src/components/label/examples/with-icon.tsx

@@ -0,0 +1,16 @@
+import { Icon, Label } from "prime-ui-kit";
+
+/** Icon slot: size follows `Label.Root`; hide decorative glyphs from assistive tech. */
+export function WithIconExample() {
+  return (
+    <>
+      <Label.Root size="m" htmlFor="example-label-icon-upload">
+        <Label.Icon>
+          <Icon aria-hidden name="action.upload" />
+        </Label.Icon>
+        Attachment
+      </Label.Root>
+      <input id="example-label-icon-upload" type="file" name="attachment" />
+    </>
+  );
+}