prime-ui-kit 0.3.2 → 0.4.0

package/src/components/file-upload/COMPONENT.md

@@ -35,14 +35,34 @@ Composable UI for choosing files: a `label` wrapping a hidden `input type="file"
 - **`FileUpload.Root`** — outer `label`, hidden file `input`, `ControlSizeProvider` for descendants. Omit `children` to get the default inner layout (`Icon`, `Title`, `Hint`, `BrowseLabel`). Replace `children` with `DropBody` / `Title` / `BrowseLink` / `ActionsRow` / `Chip` / `ChipLabel` for custom copy; use `inputRef` + `click()` from `BrowseLink` or `Chip` handlers because those elements stop propagation to the `label`.
 - **File row** — `FileUpload.Item` (optional `variant`, `size`) → `ItemRow` → `FormatBadge` and `ItemMain`. Inside `ItemMain`, use `ItemTextGroup` with `ItemName` / `ItemMeta` / `ItemMetaSep`, or `ItemStack` with `ItemTryAgain` for error layouts; optional `ItemActions`. Below the row, optional `ItemProgress` (bar when `value` is set and `children` omitted) or `ItemFooter`.
 
-### Scenarios (примеры в `examples/`)
-
-| Файл | Идея |
-|------|------|
-| `examples/avatar-upload.tsx` | Одно изображение, `accept` для картинок, превью через [Avatar](../avatar/COMPONENT.md) и `URL.createObjectURL`. |
-| `examples/document-attach.tsx` | Вложения к сообщению: `multiple`, фильтр типов, строки `Item` + `FormatBadge` / мета размера. |
-| `examples/drag-area.tsx` | Кастомная зона: `appearance="solid"`, `DropBody`, `BrowseLink` + `inputRef` (как в модалках). |
-| `examples/controlled-list.tsx` | Контролируемый массив `File[]`, удаление строк и сброс списка через [Button](../button/COMPONENT.md). |
+### Playground snippets
+
+Демо совпадают по порядку и смыслу с **`playground/sections/FileUploadSection.tsx`**. Исходники с импортами **`@/`** лежат в **`playground/snippets/file-upload/`**:
+
+| Блок | Файл | Содержание |
+|------|------|------------|
+| **Размеры** | [`sizes.tsx`](../../../playground/snippets/file-upload/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/file-upload/sizes.module.css)) | Сетка **`FileUpload.Root`** с **`size`** `s`–`xl` и такие же **`FileUpload.Item`** с **`FormatBadge`**, индикатором в **`ItemName`**, **`ItemProgress`** с **`value`**. |
+| **Варианты** | [`variants.tsx`](../../../playground/snippets/file-upload/variants.tsx) (+ [`variants.module.css`](../../../playground/snippets/file-upload/variants.module.css)) | У корня **`appearance`** **`dashed`** / **`solid`**; у карточки **`variant`** **`default`** / **`error`**. |
+| **Состояния** | [`states.tsx`](../../../playground/snippets/file-upload/states.tsx) (+ [`states.module.css`](../../../playground/snippets/file-upload/states.module.css)) | Обычная и **`disabled`** зона; карточки с прогрессом, успехом и ошибкой (**`ItemStack`** + **`ItemTryAgain`**). Подсветка при перетаскивании — **`data-dragover`** на **`Root`**. |
+| **Контролируемый режим** | [`controlled.tsx`](../../../playground/snippets/file-upload/controlled.tsx) | **`onFilesChange`**, **`multiple`**, **`accept`**; список имён и сброс через [Button](../button/COMPONENT.md). |
+| **Композиция** | [`composition.tsx`](../../../playground/snippets/file-upload/composition.tsx) (+ [`composition.module.css`](../../../playground/snippets/file-upload/composition.module.css)) | **`DropBody`**, **`Title tone="muted"`**, **`BrowseLink`**, **`ActionsRow`** / **`Chip`** / **`ChipLabel`**, общий **`inputRef`** для программного **`click()`**. |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/file-upload/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/file-upload/full-width.module.css)) | **`Root`** на всю ширину родителя (колонка формы). |
+| **Свой контент и accept** | [`custom-children.tsx`](../../../playground/snippets/file-upload/custom-children.tsx) (+ [`custom-children.module.css`](../../../playground/snippets/file-upload/custom-children.module.css)) | Замена тела зоны через **`children`**, **`accept="image/*"`**. |
+| **Круглая зона** | [`circle-modal.tsx`](../../../playground/snippets/file-upload/circle-modal.tsx) (+ [`circle-modal.module.css`](../../../playground/snippets/file-upload/circle-modal.module.css)) | Круглый контейнер (CSS), **`DropBody`**, внешняя кнопка загрузки с тем же **`inputRef`**. |
+| **Список с аватаром** | [`avatar-rows.tsx`](../../../playground/snippets/file-upload/avatar-rows.tsx) | Макет строки профиля (**`Avatar`**, кнопки). **`FileUpload` в сниппете не рендерится** — в приложении при необходимости свяжите кнопки с общим **`inputRef`**. |
+
+### Scenarios (recipes)
+
+Готовые рецепты с импортом **`prime-ui-kit`** — **`examples/*.tsx`**. Лестницы размеров/состояний и разметка модалок — в **Playground snippets** выше.
+
+| Файл | Идея | Связь со сниппетами |
+|------|------|---------------------|
+| [`examples/controlled-list.tsx`](examples/controlled-list.tsx) | Контролируемый список с **`Item`**, удаление по строке, очистка всего. | Расширяет [`controlled.tsx`](../../../playground/snippets/file-upload/controlled.tsx) карточками и действиями. |
+| [`examples/drag-area.tsx`](examples/drag-area.tsx) | **`DropBody`**, **`BrowseLink`**, **`inputRef`**, счётчик последнего выбора. | Упрощённая композиция рядом с [`composition.tsx`](../../../playground/snippets/file-upload/composition.tsx) (без **`ActionsRow`** / **`Chip`**). |
+| [`examples/document-attach.tsx`](examples/document-attach.tsx) | Вложения: **`multiple`**, фильтр типов, список **`Item`**. | Тематически близко к композиции и контролируемому режиму; визуальные паттерны карточек см. **Размеры** / **Состояния** в плейграунде. |
+| [`examples/avatar-upload.tsx`](examples/avatar-upload.tsx) | Одно изображение, превью [Avatar](../avatar/COMPONENT.md), **`URL.createObjectURL`**. | См. [`circle-modal.tsx`](../../../playground/snippets/file-upload/circle-modal.tsx) для круглой зоны и внешней кнопки. |
+| [`examples/full-width.tsx`](examples/full-width.tsx) | Колонка формы: зона на всю ширину родителя. | Зеркало [`full-width.tsx`](../../../playground/snippets/file-upload/full-width.tsx) для потребителей пакета. |
+| [`examples/custom-children.tsx`](examples/custom-children.tsx) | **`children`** вместо дефолтного тела, **`accept`** для изображений. | Зеркало [`custom-children.tsx`](../../../playground/snippets/file-upload/custom-children.tsx) для потребителей пакета. |
 
 ### Minimal example
 
@@ -227,3 +247,4 @@ export function Example() {
 - **Presentation rows:** `FileUpload.Item` subtree (`ItemRow`, `FormatBadge`, `ItemMain`, `ItemProgress`, …) does not manage data; bind to app state yourself.
 - **Appearances:** `appearance` on Root: `dashed` (default) vs `solid` (embedded / modal-style).
 - **A11y:** `FormatBadge` and default icon wrapper are `aria-hidden`; file identity belongs in `ItemName` / visible text.
+- **Playground vs recipes:** полная сетка демо и порядок блоков — **`playground/snippets/file-upload/*.tsx`** и **`FileUploadSection.tsx`**; копипаст под продукт — **`examples/*.tsx`** (см. таблицы **Playground snippets** и **Scenarios (recipes)**).

package/src/components/file-upload/examples/custom-children.tsx

@@ -0,0 +1,21 @@
+import { FileUpload } from "prime-ui-kit";
+
+/**
+ * Свой контент зоны и accept для изображений.
+ * См. playground/snippets/file-upload/custom-children.tsx.
+ */
+export function FileUploadCustomChildrenExample() {
+  return (
+    <FileUpload.Root accept="image/*">
+      <div
+        style={{
+          padding: "var(--prime-sys-spacing-x4)",
+          fontSize: "var(--prime-sys-size-control-l-text)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Custom drop area — images only
+      </div>
+    </FileUpload.Root>
+  );
+}

package/src/components/file-upload/examples/full-width.tsx

@@ -0,0 +1,32 @@
+import { FileUpload } from "prime-ui-kit";
+
+/**
+ * Зона на всю ширину колонки: у Root уже width 100%.
+ * См. playground/snippets/file-upload/full-width.tsx.
+ */
+export function FileUploadFullWidthExample() {
+  return (
+    <div
+      style={{
+        boxSizing: "border-box",
+        width: "100%",
+        maxWidth: "40rem",
+        padding: "var(--prime-sys-spacing-x4)",
+        borderRadius: "var(--prime-sys-shape-radius-l)",
+        border: "1px dashed var(--prime-sys-color-border-subtle)",
+        background: "var(--prime-sys-color-surface-default)",
+      }}
+    >
+      <p
+        style={{
+          margin: "0 0 var(--prime-sys-spacing-x3)",
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Родитель на всю колонку: зона тянется вместе с формой или панелью.
+      </p>
+      <FileUpload.Root size="m" appearance="solid" />
+    </div>
+  );
+}

package/src/components/hint/COMPONENT.md

@@ -30,15 +30,27 @@
 - **`Hint.Icon`** — optional; render as the first child of **`Hint.Root`** when you need a decorative icon before the text.
 - Order: **`Hint.Root`** contains optional **`Hint.Icon`** then text (or mixed **`ReactNode`**); no other named parts.
 
-### Scenarios (see `examples/`)
-
-| Scenario | Approach |
-|----------|----------|
-| Field help | **`variant="default"`**, same **`size`** as the control, **`id`** + **`aria-describedby`**. → [`examples/field-help.tsx`](examples/field-help.tsx) |
-| Error hint | **`variant="error"`**, invalid input **`aria-invalid`**, consider **`role="alert"`** if the message must interrupt. → [`examples/error-hint.tsx`](examples/error-hint.tsx) |
-| Success / confirmation | Only **`default`** / **`error`** / **`disabled`** exist; use **`default`** for neutral “saved / verified” copy under the field. → [`examples/success-confirmation.tsx`](examples/success-confirmation.tsx) |
-| Inline tip in a form | Stack **Label** + **Input** + **Hint** per row; optional **Hint.Icon** for scanability. → [`examples/inline-tip-form.tsx`](examples/inline-tip-form.tsx) |
-| Icon + text | **`Hint.Icon`** first, then string or nodes; meaning must not rely on the icon alone. → [`examples/with-icon.tsx`](examples/with-icon.tsx) |
+### Examples (source)
+
+Runnable files next to this doc use **`import { … } from "prime-ui-kit"`**. Playground demos (`playground/snippets/hint/*.tsx`, Russian copy, `@/` imports, `playground/snippets/hint/snippets.module.css` for field layout) follow the same scenarios; keep them in sync when changing behavior.
+
+| Playground snippet | Example | Intent |
+|--------------------|---------|--------|
+| `playground/snippets/hint/sizes.tsx` | [`examples/sizes.tsx`](examples/sizes.tsx) | Ladder **`s` → `xl`** on **`Hint.Root`** |
+| `playground/snippets/hint/variants.tsx` | [`examples/variants.tsx`](examples/variants.tsx) | **`default`**, **`error`**, **`disabled`** on **`size="m"`** |
+| `playground/snippets/hint/field-states.tsx` | [`examples/field-states.tsx`](examples/field-states.tsx) | **Label** + **Input** + **Hint** for OK / error / disabled rows |
+| `playground/snippets/hint/controlled-variant.tsx` | [`examples/controlled-variant.tsx`](examples/controlled-variant.tsx) | Parent state toggles **`variant`** (and copy) |
+| `playground/snippets/hint/composition-icon.tsx` | [`examples/with-icon.tsx`](examples/with-icon.tsx) | **`Hint.Icon`** + text (**`aria-hidden`** icon) |
+| `playground/snippets/hint/a11y-describedby.tsx` | [`examples/a11y-describedby.tsx`](examples/a11y-describedby.tsx) | **`id`** on hint + **`aria-describedby`** on control |
+
+### More examples (**Input**-centric)
+
+| File | Intent |
+|------|--------|
+| [`examples/field-help.tsx`](examples/field-help.tsx) | Neutral helper with **`Input.Root`**, **`aria-describedby`** |
+| [`examples/error-hint.tsx`](examples/error-hint.tsx) | **`hasError`**, **`variant="error"`**, optional **`role="alert"`** |
+| [`examples/success-confirmation.tsx`](examples/success-confirmation.tsx) | No **`success`** variant — **`default`** copy for “saved / verified” |
+| [`examples/inline-tip-form.tsx`](examples/inline-tip-form.tsx) | Two stacked fields with hints |
 
 ### Minimal example
 

package/src/components/hint/examples/a11y-describedby.tsx

@@ -0,0 +1,23 @@
+import { Hint, Label } from "prime-ui-kit";
+
+/** Stable `id` on `Hint.Root` and `aria-describedby` on the control so the hint is read with the field. */
+export default function HintA11yDescribedbyExample() {
+  return (
+    <>
+      <Label.Root htmlFor="hint-ex-a11y-volume" size="m">
+        Notification volume
+      </Label.Root>
+      <input
+        id="hint-ex-a11y-volume"
+        type="range"
+        min={0}
+        max={100}
+        defaultValue={40}
+        aria-describedby="hint-ex-a11y-volume-help"
+      />
+      <Hint.Root id="hint-ex-a11y-volume-help" size="m" variant="default">
+        Does not affect calls and alarms in the mobile app.
+      </Hint.Root>
+    </>
+  );
+}

package/src/components/hint/examples/controlled-variant.tsx

@@ -0,0 +1,23 @@
+import { Button, Hint } from "prime-ui-kit";
+import * as React from "react";
+
+/** Parent drives `variant` (and copy) from state — e.g. after validation. */
+export default function HintControlledVariantExample() {
+  const [variant, setVariant] = React.useState<"default" | "error">("default");
+
+  return (
+    <>
+      <Button.Root size="s" variant="neutral" mode="stroke" onClick={() => setVariant("default")}>
+        Reset
+      </Button.Root>
+      <Button.Root size="s" variant="error" mode="lighter" onClick={() => setVariant("error")}>
+        Show error
+      </Button.Root>
+      <Hint.Root size="m" variant={variant}>
+        {variant === "error"
+          ? "Fill the field before saving the draft."
+          : "You can save the draft without required fields."}
+      </Hint.Root>
+    </>
+  );
+}

package/src/components/hint/examples/field-states.tsx

@@ -0,0 +1,44 @@
+import { Hint, Input, Label } from "prime-ui-kit";
+
+/** Label + field + hint for default, invalid, and disabled rows (aligned with playground `field-states`). */
+export default function HintFieldStatesExample() {
+  return (
+    <>
+      <Label.Root htmlFor="hint-ex-st-ok" size="m">
+        Project name
+      </Label.Root>
+      <Input.Root size="m" id="hint-ex-st-ok">
+        <Input.Wrapper>
+          <Input.Field type="text" defaultValue="Alpha" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root size="m" variant="default">
+        Visible to everyone in this workspace.
+      </Hint.Root>
+
+      <Label.Root htmlFor="hint-ex-st-err" size="m">
+        Tax ID
+      </Label.Root>
+      <Input.Root size="m" id="hint-ex-st-err" hasError>
+        <Input.Wrapper>
+          <Input.Field type="text" defaultValue="12" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root size="m" variant="error">
+        Enter 10 or 12 digits.
+      </Hint.Root>
+
+      <Label.Root htmlFor="hint-ex-st-dis" size="m" disabled>
+        Request limit
+      </Label.Root>
+      <Input.Root size="m" id="hint-ex-st-dis">
+        <Input.Wrapper>
+          <Input.Field type="text" disabled defaultValue="read only" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root size="m" variant="disabled">
+        Value comes from the plan and cannot be edited.
+      </Hint.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,13 @@
+import { Hint } from "prime-ui-kit";
+
+/** Nominal `size` matches the field tier; hint typography is one step smaller (see styles). */
+export default function HintSizesExample() {
+  return (
+    <>
+      <Hint.Root size="s">Hint size s</Hint.Root>
+      <Hint.Root size="m">Hint size m</Hint.Root>
+      <Hint.Root size="l">Hint size l</Hint.Root>
+      <Hint.Root size="xl">Hint size xl</Hint.Root>
+    </>
+  );
+}

package/src/components/hint/examples/variants.tsx

@@ -0,0 +1,18 @@
+import { Hint } from "prime-ui-kit";
+
+/** `variant` on default size `m`: secondary, error, and disabled tones. */
+export default function HintVariantsExample() {
+  return (
+    <>
+      <Hint.Root size="m" variant="default">
+        Neutral helper or format guidance.
+      </Hint.Root>
+      <Hint.Root size="m" variant="error">
+        Value does not meet password policy requirements.
+      </Hint.Root>
+      <Hint.Root size="m" variant="disabled">
+        Editing is not available for the selected role.
+      </Hint.Root>
+    </>
+  );
+}

package/src/components/input/COMPONENT.md

@@ -8,7 +8,8 @@
 - **Скелет:** `Input.Root` → `Input.Wrapper` → `Input.Field` (плюс при необходимости `Input.Icon` / `Input.Affix` / `Input.InlineAffix` в нужном порядке внутри обёртки).
 - **Размер:** только на **`Input.Root`**: `size` ∈ `s | m | l | xl`, по умолчанию **`m`**. На **`Input.Field`** атрибут HTML **`size` не передаётся** (зарезервирован системой).
 - **Состояние ввода:** контролируемый режим — `value` / `onChange` на **`Input.Field`**. Подпись, `hint`, `error`, `optionalLabel` — на **`Input.Root`**.
-- **Примеры сценариев:** каталог `examples/` — [login email](./examples/login-email.tsx), [search](./examples/search.tsx), [password + hint](./examples/password-with-hint.tsx), [checkout full-width column](./examples/checkout-full-width.tsx).
+- **Playground** (`playground/snippets/input/`, порядок как в `playground/sections/InputSection.tsx`): [sizes](../../../playground/snippets/input/sizes.tsx) — ряд `size` `s`–`xl` с иконкой; [states](../../../playground/snippets/input/states.tsx) — `hint`, `disabled`, `readOnly`, `required`, `error`; [controlled](../../../playground/snippets/input/controlled.tsx) — `value`/`onChange` на `Input.Field` и `aria-label`; [composition](../../../playground/snippets/input/composition.tsx) — `Icon`, `Affix`, `InlineAffix`; [full-width](../../../playground/snippets/input/full-width.tsx) — узкая колонка и блок на всю ширину (стили [full-width.module.css](../../../playground/snippets/input/full-width.module.css)); [features](../../../playground/snippets/input/features.tsx) — явный `id`, `optionalLabel`, одновременно `hint` и `error`.
+- **Примеры пакета** (`examples/`): [login email](./examples/login-email.tsx), [search](./examples/search.tsx), [password + hint](./examples/password-with-hint.tsx), [checkout full-width](./examples/checkout-full-width.tsx), [affix URL и сумма](./examples/affix-url-and-amount.tsx).
 
 ```tsx
 import { Input } from "prime-ui-kit";
@@ -135,5 +136,5 @@ Returns `{ size, hasError, inputId, describedBy }` for building custom subcompon
 - **Доступность:** имя поля — `label` на Root или `aria-label` / `aria-labelledby` на `Input.Field`. Иконки и аффиксы не озвучиваются (`aria-hidden`).
 - **Контроль:** состояние строки — на `Input.Field` (`value`, `onChange`, `defaultValue`).
 - **Ширина:** отдельного пропа `fullWidth` нет; корень растягивается по ширине родителя — задавай ширину контейнеру формы/карточки.
-- **Сценарии из репозитория:** `examples/login-email.tsx`, `examples/search.tsx`, `examples/password-with-hint.tsx`, `examples/checkout-full-width.tsx`; в playground — `playground/snippets/input/*`.
-- **Playground:** размеры, состояния, композиция, full-width — `playground/snippets/input/sizes.tsx`, `states.tsx`, `composition.tsx`, `full-width.tsx`, `features.tsx`, `controlled.tsx`.
+- **Сценарии из репозитория:** `examples/login-email.tsx`, `examples/search.tsx`, `examples/password-with-hint.tsx`, `examples/checkout-full-width.tsx`, `examples/affix-url-and-amount.tsx`.
+- **Playground (порядок секции Input):** `playground/snippets/input/sizes.tsx` → `states.tsx` → `controlled.tsx` → `composition.tsx` → `full-width.tsx` (+ `full-width.module.css`) → `features.tsx`.

package/src/components/input/examples/affix-url-and-amount.tsx

@@ -0,0 +1,24 @@
+import { Input } from "prime-ui-kit";
+
+/**
+ * Блочные аффиксы для URL и инлайн-символ валюты — как в playground `composition.tsx`.
+ */
+export default function AffixUrlAndAmountExample() {
+  return (
+    <>
+      <Input.Root size="m" label="Сайт" hint="Поддомен без схемы">
+        <Input.Wrapper>
+          <Input.Affix side="start">https://</Input.Affix>
+          <Input.Field placeholder="поддомен" />
+          <Input.Affix side="end">.example</Input.Affix>
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root size="m" label="Сумма" hint="Дробная часть через запятую">
+        <Input.Wrapper>
+          <Input.InlineAffix side="start">₽</Input.InlineAffix>
+          <Input.Field placeholder="0,00" inputMode="decimal" />
+        </Input.Wrapper>
+      </Input.Root>
+    </>
+  );
+}

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

@@ -23,6 +23,7 @@ export default function SearchExample() {
           placeholder="Название или артикул"
           value={query}
           onChange={(e) => setQuery(e.target.value)}
+          aria-label="Поиск по каталогу"
         />
       </Input.Wrapper>
     </Input.Root>

package/src/components/kbd/COMPONENT.md

@@ -17,7 +17,7 @@ export function Example() {
 }
 ```
 
-Готовые сценарии — в **`examples/`** (ряд «действие — шорткат», легенда документации, подсказки у тулбара, аккорды из нескольких клавиш, встроенная подсказка в тексте). Подробности — в **Extended**.
+Секция Kbd в плейграунде (`playground/sections/KbdSection.tsx`) рендерит сниппеты из **`playground/snippets/kbd/*.tsx`**. Файлы в **`examples/`** с пометкой parity повторяют те же сценарии с импортом **`"prime-ui-kit"`** для копирования в приложение. Остальные примеры — продуктовые сценарии. Подробности — в **Extended**.
 
 ## Extended
 
@@ -36,6 +36,10 @@ export function Example() {
 
 | Файл | Сценарий |
 |------|----------|
+| [`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) | Тулбар: кнопка и рядом компактная подсказка-клавиши. |
@@ -84,4 +88,4 @@ export function Example() {
 - Аккорд: **не** клади строку `"⌘+K"` в один **`Kbd.Root`**, если нужна семантика «отдельные клавиши» — делай **`Kbd.Root` на каждую клавишу**, плюс **`span aria-hidden`** между ними для **`+`**.
 - Размер без пропа: **`useOptionalControlSize`** → **`controlSurfaceToInputSize`**; **`xs`** контекста → эффективный **`s`** на компоненте.
 - Не подменяй кнопку или ссылку одним **`Kbd`**; не ожидай событий клавиатуры от этого компонента.
-- Сценарии копирования: смотри **`src/components/kbd/examples/*.tsx`**.
+- Сценарии копирования: **`playground/snippets/kbd/*.tsx`** (демо) и зеркала в **`src/components/kbd/examples/*.tsx`** (импорт **`"prime-ui-kit"`**); parity-файлы названы в таблице выше.

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/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/label/COMPONENT.md

@@ -8,7 +8,8 @@
 - **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).
+- **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
 
@@ -57,6 +58,30 @@ export function Example() {
 }
 ```
 
+### 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.
@@ -68,14 +93,19 @@ export function Example() {
 - 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/`)
+### Scenarios (see `examples/` and playground snippets)
 
 | 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 |
+| 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
 

package/src/components/label/examples/mixed-required-optional.tsx

@@ -0,0 +1,17 @@
+import { Label } from "prime-ui-kit";
+
+/** Mirrors `playground/snippets/label/mixed-required-optional.tsx`: asterisk vs optional `Label.Sub`. */
+export function LabelMixedRequiredOptionalExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-mx-1">
+        Contract number
+        <Label.Asterisk />
+      </Label.Root>
+      <Label.Root htmlFor="example-label-mx-2">
+        Order note
+        <Label.Sub>optional</Label.Sub>
+      </Label.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,37 @@
+import { Icon, Label } from "prime-ui-kit";
+
+/** Mirrors `playground/snippets/label/sizes.tsx`: plain text and `Label.Icon` rows for `s`–`xl`. */
+export function LabelSizesExample() {
+  return (
+    <>
+      <Label.Root size="s">Label s</Label.Root>
+      <Label.Root size="m">Label m</Label.Root>
+      <Label.Root size="l">Label l</Label.Root>
+      <Label.Root size="xl">Label xl</Label.Root>
+      <Label.Root size="s">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label s
+      </Label.Root>
+      <Label.Root size="m">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label m
+      </Label.Root>
+      <Label.Root size="l">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label l
+      </Label.Root>
+      <Label.Root size="xl">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label xl
+      </Label.Root>
+    </>
+  );
+}