prime-ui-kit 0.3.2 → 0.4.1

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

@@ -0,0 +1,99 @@
+import { Copy, Edit, Trash2 } from "lucide-react";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Ярус `size` на `Dropdown.Content`: s, m, l, xl — как в `playground/snippets/dropdown/sizes.tsx`. */
+export default function DropdownSizesExample() {
+  return (
+    <>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="s" variant="neutral" mode="stroke">
+            size=&quot;s&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="s">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+            size=&quot;m&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="m">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="l" variant="neutral" mode="stroke">
+            size=&quot;l&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="l">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="xl" variant="neutral" mode="stroke">
+            size=&quot;xl&quot;
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content size="xl">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Edit} strokeWidth={2} />
+            Редактировать
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+            Удалить
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </>
+  );
+}

package/src/components/dropdown/examples/states.tsx

@@ -0,0 +1,20 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Недоступный пункт через `disabled` — как в `playground/snippets/dropdown/states.tsx`. */
+export default function DropdownStatesExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Доступ к отчёту
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Скачать PDF</Dropdown.Item>
+        <Dropdown.Item disabled>Экспорт в Excel (нет прав)</Dropdown.Item>
+        <Dropdown.Item>Отправить на почту</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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

@@ -0,0 +1,21 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Обычные пункты и `destructive` на `Dropdown.Item` — как в `playground/snippets/dropdown/variants.tsx`. */
+export default function DropdownVariantsExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="lighter">
+          Документ
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Переименовать</Dropdown.Item>
+        <Dropdown.Item>Переместить…</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item destructive>Удалить безвозвратно</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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>
+  );
+}