prime-ui-kit 0.7.13 → 0.9.0

package/src/components/input/examples/examples.module.css

@@ -0,0 +1,151 @@
+/* Layout helpers for the Input examples. Semantic tokens only. */
+
+/* Vertical list of fields (field → field). */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  width: 100%;
+  min-width: 0;
+}
+
+/* ---- anatomy.tsx: rows are scenarios, columns are sizes xs…xl ---- */
+.anatomyScroller {
+  width: 100%;
+  min-width: 0;
+  overflow-x: auto;
+}
+
+.anatomyGrid {
+  display: grid;
+  grid-template-columns: repeat(
+      5,
+      minmax(calc(var(--prime-panel-min-width) - var(--prime-space-8)), 1fr)
+    );
+  align-items: start;
+  column-gap: var(--prime-space-5);
+  row-gap: var(--prime-space-4);
+}
+
+/* One scenario: its heading and the five cells share the outer columns (subgrid). */
+.anatomyRow {
+  grid-column: 1 / -1;
+  display: grid;
+  grid-template-columns: subgrid;
+  align-items: start;
+  row-gap: var(--prime-space-2);
+}
+
+.anatomyRowHead {
+  grid-column: 1 / -1;
+  padding-top: var(--prime-space-2);
+  border-top: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+/* ---- control-alignment.tsx: one row of controls per size ---- */
+.alignStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: 100%;
+  min-width: 0;
+}
+
+.alignRow {
+  display: grid;
+  grid-template-columns: var(--prime-space-8) repeat(4, minmax(0, max-content));
+  align-items: center;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}
+
+.alignField {
+  width: calc(var(--prime-panel-min-width) - var(--prime-space-4));
+}
+
+@media (max-width: 767px) {
+  .alignRow {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .alignSize {
+    grid-column: 1 / -1;
+  }
+
+  .alignField {
+    width: auto;
+  }
+}
+
+/* ---- sizes.tsx: five sizes in one row, field bottoms aligned ---- */
+.sizesRow {
+  display: grid;
+  grid-template-columns: repeat(
+      auto-fit,
+      minmax(calc(var(--prime-panel-min-width) - var(--prime-space-12)), 1fr)
+    );
+  align-items: end;
+  gap: var(--prime-space-4);
+  width: 100%;
+}
+
+/* ---- states.tsx ---- */
+.statesGrid {
+  display: grid;
+  grid-template-columns: repeat(
+      auto-fill,
+      minmax(calc(var(--prime-panel-min-width) + var(--prime-space-8)), 1fr)
+    );
+  align-items: start;
+  column-gap: var(--prime-space-6);
+  row-gap: var(--prime-space-5);
+  width: 100%;
+}
+
+/* ---- in-form.tsx: field → field 20, group → actions 32 (foundation §1) ---- */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+.formHeader {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+}
+
+.formFields {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--prime-space-5) var(--prime-space-4);
+}
+
+.formWide {
+  grid-column: 1 / -1;
+}
+
+.formActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}
+
+@media (max-width: 639px) {
+  .formFields {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+/* ---- full-width.tsx ---- */
+.widthRoot {
+  display: grid;
+  gap: var(--prime-space-6);
+  width: 100%;
+}
+
+.widthNarrow {
+  width: 100%;
+  max-width: calc(var(--prime-panel-min-width) + var(--prime-space-8));
+}

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

@@ -0,0 +1,23 @@
+/** Input.Root always fills its parent; the width comes from the layout column, there is no `fullWidth` prop. Use a capped wrapper for short values like a postal code. */
+import { Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function InputFullWidthExample() {
+  return (
+    <div className={styles.widthRoot}>
+      <div className={styles.widthNarrow}>
+        <Input.Root label="Индекс" hint="Колонка ограничена родителем">
+          <Input.Wrapper>
+            <Input.Field placeholder="190000" inputMode="numeric" />
+          </Input.Wrapper>
+        </Input.Root>
+      </div>
+      <Input.Root label="Адрес доставки" hint="Родитель на всю ширину">
+        <Input.Wrapper>
+          <Input.Field placeholder="Улица, дом, квартира" autoComplete="street-address" />
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

package/src/components/input/examples/icons-and-affixes.tsx

@@ -0,0 +1,32 @@
+/** Slots inside the field: a leading icon, a tinted section affix and an inline unit. Use them for e-mail/URL/amount fields that need a visual cue or a fixed prefix/suffix. */
+import { Icon, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function InputIconsAndAffixesExample() {
+  return (
+    <div className={styles.stack}>
+      <Input.Root label="Электронная почта">
+        <Input.Wrapper>
+          <Input.Icon side="start">
+            <Icon name="field.email" tone="secondary" />
+          </Input.Icon>
+          <Input.Field type="email" placeholder="name@company.ru" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Адрес магазина">
+        <Input.Wrapper>
+          <Input.Affix side="start">https://</Input.Affix>
+          <Input.Field placeholder="moy-magazin" />
+          <Input.Affix side="end">.shop.ru</Input.Affix>
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Сумма платежа">
+        <Input.Wrapper>
+          <Input.Field placeholder="0,00" inputMode="decimal" />
+          <Input.InlineAffix side="end">₽</Input.InlineAffix>
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

package/src/components/input/examples/in-form.tsx

@@ -0,0 +1,51 @@
+/** A settings form in a card: required and optional fields, an error that does not shift the row, actions at the end. Use it as the spacing reference for forms (field → field 20, group → actions 32). */
+import { Button, Input, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function InputInFormExample() {
+  return (
+    <form className={styles.form} onSubmit={(e) => e.preventDefault()}>
+      <div className={styles.formHeader}>
+        <Typography.Root as="h3" variant="title-m">
+          Реквизиты компании
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-s" tone="secondary">
+          Используются в счетах и закрывающих документах.
+        </Typography.Root>
+      </div>
+      <div className={styles.formFields}>
+        <div className={styles.formWide}>
+          <Input.Root label="Название организации" required>
+            <Input.Wrapper>
+              <Input.Field defaultValue="ООО «Северный ветер»" autoComplete="organization" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+        <Input.Root label="ИНН" required error="ИНН состоит из 10 цифр" reserveSupportRow>
+          <Input.Wrapper>
+            <Input.Field defaultValue="78123" inputMode="numeric" />
+          </Input.Wrapper>
+        </Input.Root>
+        <Input.Root label="КПП" optional reserveSupportRow>
+          <Input.Wrapper>
+            <Input.Field placeholder="9 цифр" inputMode="numeric" />
+          </Input.Wrapper>
+        </Input.Root>
+        <div className={styles.formWide}>
+          <Input.Root label="Email для счетов" hint="Сюда придут счета и акты">
+            <Input.Wrapper>
+              <Input.Field type="email" placeholder="buh@company.ru" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </div>
+      <div className={styles.formActions}>
+        <Button.Root variant="ghost" tone="neutral" type="reset">
+          Отменить
+        </Button.Root>
+        <Button.Root type="submit">Сохранить</Button.Root>
+      </div>
+    </form>
+  );
+}

package/src/components/input/examples/reserved-support-row.tsx

@@ -0,0 +1,33 @@
+/** `reserveSupportRow` keeps the support row in place, so an appearing error does not move the button below; also shows a custom `labels.optional` and an explicit `id`. Use it for fields validated on the fly. */
+import { Button, Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function InputReservedSupportRowExample() {
+  const [invalid, setInvalid] = React.useState(false);
+
+  return (
+    <div className={styles.stack}>
+      <Input.Root
+        optional
+        labels={{ optional: "если есть" }}
+        label="Промокод"
+        reserveSupportRow
+        error={invalid ? "Промокод недействителен или истёк" : undefined}
+      >
+        <Input.Wrapper>
+          <Input.Field placeholder="Введите код" defaultValue="SAVE50" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Button.Root variant="outline" tone="neutral" onClick={() => setInvalid((v) => !v)}>
+        {invalid ? "Убрать ошибку" : "Показать ошибку"}
+      </Button.Root>
+      <Input.Root id="delivery-phone" label="Телефон для курьера" optional>
+        <Input.Wrapper>
+          <Input.Field type="tel" autoComplete="tel" placeholder="+7 900 000-00-00" />
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

package/src/components/input/examples/search-without-focus-ring.tsx

@@ -0,0 +1,25 @@
+/** A search field with `focusRing={false}`: the caret and the lighter fill show focus. Use it only for a single search field where focus is otherwise obvious. */
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+export default function InputSearchWithoutFocusRingExample() {
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <Input.Root focusRing={false}>
+      <Input.Wrapper>
+        <Input.Icon side="start">
+          <Icon name="action.search" tone="secondary" />
+        </Input.Icon>
+        <Input.Field
+          type="search"
+          aria-label="Поиск"
+          placeholder="Поиск"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+        />
+        {query ? <Input.ClearButton onClick={() => setQuery("")} /> : null}
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}

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

@@ -0,0 +1,23 @@
+/** The same field on every size: height, padding, text and icon come from the tier. Pick the size that matches the other controls in the row. */
+import { Icon, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function InputSizesExample() {
+  return (
+    <div className={styles.sizesRow}>
+      {SIZES.map((size) => (
+        <Input.Root key={size} size={size} label={`size="${size}"`}>
+          <Input.Wrapper>
+            <Input.Icon side="start">
+              <Icon name="field.email" tone="secondary" />
+            </Input.Icon>
+            <Input.Field type="email" placeholder="Почта" />
+          </Input.Wrapper>
+        </Input.Root>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,44 @@
+/** Empty, filled, disabled, read-only and invalid fields (with and without an error message). Use it to check every state a form field can be in. */
+import { Icon, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function InputStatesExample() {
+  return (
+    <div className={styles.statesGrid}>
+      <Input.Root label="Пустое" hint="Плейсхолдер не заменяет подпись">
+        <Input.Wrapper>
+          <Input.Field placeholder="Например, Москва" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Заполненное">
+        <Input.Wrapper>
+          <Input.Field defaultValue="Санкт-Петербург" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Отключено" hint="Значение нельзя изменить">
+        <Input.Wrapper>
+          <Input.Field defaultValue="Екатеринбург" disabled />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Только чтение">
+        <Input.Wrapper>
+          <Input.Field defaultValue="ID 4821-0093" readOnly />
+          <Input.Icon side="end">
+            <Icon name="status.locked" tone="secondary" />
+          </Input.Icon>
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Ошибка" required error="Укажите город доставки">
+        <Input.Wrapper>
+          <Input.Field placeholder="Город" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root invalid label="Ошибка без текста" hint="invalid — только кольцо">
+        <Input.Wrapper>
+          <Input.Field defaultValue="Казань" />
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,12 @@
+/** A plain field whose fill comes from the surface context: white on the canvas, gray inside Card, Modal or Popover. Drop fields into any surface without overriding their background. */
+import { Input } from "prime-ui-kit";
+
+export default function InputSurfacesExample() {
+  return (
+    <Input.Root label="Город" hint="Заливка зависит от фона">
+      <Input.Wrapper>
+        <Input.Field placeholder="Москва" />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}

package/src/components/input/examples/with-badge.tsx

@@ -0,0 +1,40 @@
+/** A soft status badge inside the field (`Input.Badge`, `Select.Badge`, `Datepicker.Badge`). Use it to mark a field value as verified, new or missing without changing the field height. */
+import { Datepicker, Input, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function InputWithBadgeExample() {
+  const [serviceDate, setServiceDate] = React.useState<Date | null>(null);
+  return (
+    <div className={styles.stack}>
+      <Datepicker.Root
+        mode="single"
+        label="Дата последнего ТО"
+        placeholder="дд.мм.гггг"
+        fullWidth
+        value={serviceDate}
+        onValueChange={setServiceDate}
+      >
+        {serviceDate ? null : <Datepicker.Badge color="orange">Не заполнено</Datepicker.Badge>}
+      </Datepicker.Root>
+      <Input.Root label="ИНН контрагента">
+        <Input.Wrapper>
+          <Input.Field defaultValue="7707083893" inputMode="numeric" />
+          <Input.Badge color="green">Проверен</Input.Badge>
+        </Input.Wrapper>
+      </Input.Root>
+      <Select.Root label="Тариф" defaultValue="business">
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Badge color="blue">Новое</Select.Badge>
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="start">Старт</Select.Item>
+          <Select.Item value="business">Бизнес с расширенной поддержкой</Select.Item>
+          <Select.Item value="corporate">Корпоративный</Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/kbd/COMPONENT.md

@@ -1,91 +1,114 @@
 # Kbd
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** data-display
 
-## Canonical
+> A key cap for a keyboard key or a shortcut, rendered as a native `<kbd>`.
 
-`Kbd` — примитив из одной части: **`Kbd.Root`** рендерит семантический **`kbd`** с оформлением кита (поднятая поверхность, рамка, лёгкая тень). Только **отображение** подписи клавиши; события клавиатуры и фокус не обрабатывает.
+## When to use
+- Shortcut hints inside buttons, search fields and menu items ("Найти ⌘K", "/").
+- Hotkey reference lists in help panels or settings.
+- Keys mentioned in instructions.
 
-- **API:** `size?: "s" | "m" | "l" | "xl"`; без пропа размер берётся из ближайшего **`ControlSizeProvider`**, иначе **`"m"`**; на поверхности контрола **`xs`** маппится в **`s`** для `kbd`.
-- **Импорт:** `import { Kbd } from "prime-ui-kit"` → **`Kbd.Root`**.
+## When not to use
+- A status, category or counter → use [Badge](../badge/COMPONENT.md).
+- A removable value → use [Tag](../tag/COMPONENT.md).
+- A clickable control → use [Button](../button/COMPONENT.md).
+- A block of code → use [CodeBlock](../code-block/COMPONENT.md).
 
+## Import
 ```tsx
 import { Kbd } from "prime-ui-kit";
-
-export function Example() {
-  return <Kbd.Root>Esc</Kbd.Root>;
-}
 ```
 
-Секция Kbd в плейграунде (`playground/sections/KbdSection.tsx`) рендерит сниппеты из **`playground/snippets/kbd/*.tsx`**. Файлы в **`examples/`** с пометкой parity повторяют те же сценарии с импортом **`"prime-ui-kit"`** для копирования в приложение. Остальные примеры — продуктовые сценарии. Подробности — в **Extended**.
+## API
+
+### Kbd.Root
+Forwards `ref` to the `<kbd>` element. No `asChild`. Leaf component: one key per `Kbd.Root`.
 
-## Extended
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Key label, an icon, or icon + text. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` (`ControlSize`) | — (inherited, else `"m"`) | Badge tier. Without it the key follows the surrounding control one tier down; outside a control it is `m`. |
+| `className` | `string` | — | Extra class on the `<kbd>`. |
 
-### About
++ native props of `<kbd>` (`HTMLAttributes<HTMLElement>` without `size`), e.g. `title`, `aria-label`. `data-size` / `data-tier` are always set by the component.
 
-`Kbd.Root` помечает имена клавиш и фрагменты шорткатов как UI-хром, а не как основной текст абзаца.
+## Variants
 
-- **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** — в длинной документации, где обычный текст или моноширинный шрифт читабельнее «чипов» клавиш.
+Kbd has one look: monospace text in `text-secondary` on a translucent `fill-subtle-active` wash, no border, weight 500. No `variant`, `tone` or `color`.
 
-### Examples (`examples/`)
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 16px high, padding 4, text 12, icon 12 | Inside `xs`/`s` buttons, dense menus | |
+| `s` | 20px high, padding 6, text 12, icon 12 | Inside `m` controls (inherited automatically) | |
+| `m` | 24px high, padding 8, text 12, icon 14 | Standalone keys in lists and text | yes (outside controls) |
+| `l` | 28px high, padding 10, text 13, icon 16 | Larger help panels | |
+| `xl` | 32px high, padding 12, text 14, icon 16 | Onboarding / hero hints | |
 
-| Файл | Сценарий |
-|------|----------|
-| [`examples/sizes-ladder.tsx`](examples/sizes-ladder.tsx) | Ряд **`Kbd.Root`** с **`size`** `s`–`xl` (`snippets/kbd/sizes.tsx`). |
-| [`examples/states-title.tsx`](examples/states-title.tsx) | Без отдельных пропов состояния; **`title`** для нативной подсказки (`snippets/kbd/states.tsx`). |
-| [`examples/composition-chord-icon.tsx`](examples/composition-chord-icon.tsx) | Аккорд **`⌘` + `K`** и ряд с **`Icon`** внутри одного **`Kbd.Root`** (`snippets/kbd/composition.tsx`). |
-| [`examples/context-inherit-size.tsx`](examples/context-inherit-size.tsx) | Размер без пропа из **`ControlSizeProvider`**, **`xs`→`s`**, явный **`size`** перекрывает контекст (`snippets/kbd/inherit-size.tsx`). |
-| [`examples/shortcut-row.tsx`](examples/shortcut-row.tsx) | Строка списка/меню: подпись действия и шорткат справа. |
-| [`examples/docs-legend.tsx`](examples/docs-legend.tsx) | Легенда в документации: сетка «действие → комбинация». |
-| [`examples/toolbar-hints.tsx`](examples/toolbar-hints.tsx) | Тулбар: кнопка и рядом компактная подсказка-клавиши. |
-| [`examples/combination-keys.tsx`](examples/combination-keys.tsx) | Аккорд: несколько **`Kbd.Root`** и разделители вне ключей. |
-| [`examples/inline-doc-hint.tsx`](examples/inline-doc-hint.tsx) | Встроенная в абзац подсказка с **`Kbd`** в потоке текста. |
+Minimum width equals the height, so single-character keys are square.
 
-### Composition
+**Combinations**
+- Recommended: no `size` inside controls; one `Kbd.Root` per key in a chord.
+- Allowed: an explicit smaller `size` inside a control for a secondary hint (`<Kbd.Root size="xs">↵</Kbd.Root>` in an `m` button).
+- Avoid: one `Kbd.Root` holding a whole chord with "+" text inside; symbols without an accessible name.
 
-- **`Kbd`** экспортирует только **`Root`** — плоский API; внутрь передаётся подпись (текст, иконки, смешанный **`ReactNode`**).
-- **`Root`** выставляет **`data-size`**, оборачивает **`children`** в **`ControlSizeProvider`**, чтобы вложенные **`Icon`** наследовали контекст размера контрола.
+**Sizes**
+Same tiers as Badge and Tag. Without `size` inside a control: `xs`/`s` → `xs`, `m` → `s`, `l` → `m`, `xl` → `l`.
 
-### Rules
+## States
+Kbd is static: no hover, focus, disabled or loading.
 
-- **Sizing:** см. Canonical; явный **`size`** перекрывает контекст.
-- **Presentation only:** нет обработки клавиш, фокуса и состояния ОС.
-- **Semantics:** полиморфизма **`asChild`** нет — корень всегда **`kbd`**.
-- **Accessibility:** для аккордов — несколько **`Kbd.Root`**; **`+`** / «или» выносить **вне** ключей или помечать **`aria-hidden`**, чтобы скринридер не зачитывал их как часть каждой клавиши. Для пояснения — **`title`** или видимый текст; смысл не только цветом.
-- **Platform copy:** **⌘** vs **Ctrl** и т.п. — решение продукта/i18n, кит не нормализует.
-- **Styling:** один встроенный вид; расширение через **`className`** / стили проекта, отдельного **`variant`** нет.
+| Attribute | Driven by | Notes |
+|---|---|---|
+| `data-size` | `size`, else surrounding control size, else `m` | Nominal size. |
+| `data-tier` | resolved tier | One step down from the control when inherited. Drives dimensions. |
 
-## API
+Kbd also provides its tier to children through the control-size context, so a nested `Icon` matches the key.
 
-### Kbd.Root
+## Layout & spacing
+- Inline-flex, centered content, never shrinks, vertical-align middle.
+- Keys of one chord: `gap: var(--prime-space-1)`; an optional "+" between them is `aria-hidden`.
+- In a hotkey list: action text left, chord right (`justify-content: space-between`), rows `gap: var(--prime-space-3)`.
+- In a field, put Kbd in `Input.InlineAffix side="end"`.
 
-| 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-*`, …). |
+## Accessibility
+- Renders a native `<kbd>`; its text is read as is.
+- Symbol keys (⌘ ⌥ ⇧ ↵) need `aria-label` and preferably `title` ("Command", "Shift").
+- Visual separators like "+" between keys get `aria-hidden="true"`.
+- No `labels` keys.
 
-## Related
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | A chord in tiers xs–xl | Standalone shortcuts in text and docs |
+| [in-controls.tsx](examples/in-controls.tsx) | ⌘ + K chord in Button s/m/l, explicit `xs` ↵ with `aria-label`, key in a search field | Shortcut hints inside controls |
+| [modifier-keys.tsx](examples/modifier-keys.tsx) | ⌘ + ⇧ + P with `aria-label` / `title`, hidden "+" | Symbol keys |
+| [shortcut-list.tsx](examples/shortcut-list.tsx) | Hotkey reference list, key with icon and text | Help panels and settings |
 
-- [Button](../button/COMPONENT.md) — действие, на которое часто ссылается шорткат.
-- [Link button](../link-button/COMPONENT.md) — текстовые действия с подсказкой клавиши рядом.
-- [Input](../input/COMPONENT.md) — поля, где в `hint` или у подписи уместен `Kbd`.
-- [Textarea](../textarea/COMPONENT.md) — многострочные поля с тем же паттерном подсказок.
-- [Select](../select/COMPONENT.md) — триггеры и списки с документированием шорткатов.
-- [Tooltip](../tooltip/COMPONENT.md) — развёрнутые пояснения с повтором клавиш через `Kbd`.
-- [Command menu](../command-menu/COMPONENT.md) — списки с пер-элементными шорткатами.
-
-## LLM note
-
-- Публичный API: **`Kbd.Root`** только; импорт **`{ Kbd } from "prime-ui-kit"`**.
-- Нет **`variant`**, **`disabled`**, **`asChild`**; для подсказок используй нативные атрибуты (**`title`**, **`aria-*`**).
-- Аккорд: **не** клади строку `"⌘+K"` в один **`Kbd.Root`**, если нужна семантика «отдельные клавиши» — делай **`Kbd.Root` на каждую клавишу**, плюс **`span aria-hidden`** между ними для **`+`**.
-- Размер без пропа: **`useOptionalControlSize`** → **`controlSurfaceToInputSize`**; **`xs`** контекста → эффективный **`s`** на компоненте.
-- Не подменяй кнопку или ссылку одним **`Kbd`**; не ожидай событий клавиатуры от этого компонента.
-- Сценарии копирования: **`playground/snippets/kbd/*.tsx`** (демо) и зеркала в **`src/components/kbd/examples/*.tsx`** (импорт **`"prime-ui-kit"`**); parity-файлы названы в таблице выше.
+```tsx
+import { Kbd } from "prime-ui-kit";
+
+export function SaveHint() {
+  return (
+    <span>
+      <Kbd.Root aria-label="Command" title="Command">
+        ⌘
+      </Kbd.Root>
+      <Kbd.Root>S</Kbd.Root>
+    </span>
+  );
+}
+```
+
+## Mistakes
+- `<Kbd.Root>⌘ + Shift + P</Kbd.Root>` → one `Kbd.Root` per key with an `aria-hidden` "+" between.
+- `<Kbd.Root>⌘</Kbd.Root>` without a name → add `aria-label="Command"`.
+- `<Button.Root>Найти <Kbd.Root size="m">⌘K</Kbd.Root></Button.Root>` → drop `size` and use one key per `Kbd.Root`: `<Kbd.Root aria-label="Command">⌘</Kbd.Root><Kbd.Root>K</Kbd.Root>`; the keys follow the button one tier down.
+- A `<span>` styled as a key → use `Kbd.Root`.
+- `Badge` used for a key → use `Kbd.Root` (monospace, semantic `<kbd>`).
+
+## Related
+- [Badge](../badge/COMPONENT.md), [Tag](../tag/COMPONENT.md) — same tiers.
+- [CommandMenu](../command-menu/COMPONENT.md) — shortcut hints in the footer.
+- [Dropdown](../dropdown/COMPONENT.md) — shortcuts in menu items.