prime-ui-kit 0.2.3 → 0.3.1

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

@@ -0,0 +1,200 @@
+# FileUpload
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Composable UI for choosing files: a `label` wrapping a hidden `input type="file"`, optional drag-and-drop styling, and building blocks for per-file rows (badge, name/meta, progress, actions).
+
+**When to use**
+
+- A visible drop zone plus native picker, with `accept`, `multiple`, and optional `disabled`.
+- Drag-and-drop and click on the same target, with `onFilesChange` to feed app or server logic.
+- Lists of uploads styled as cards with `FormatBadge`, typography slots, and optional `ItemProgress`.
+- Dense modal layouts using `DropBody`, `Title`, `BrowseLink`, `ActionsRow`, and `Chip`, often with `inputRef` to open the dialog from nested controls.
+
+**When not to use**
+
+- A headless file field with no shared drop-zone affordance (use a plain `input` or minimal markup).
+- Built-in upload, scanning, or storage integration (only UI and `File[]` callbacks).
+- Automatic list state or remove/retry semantics inside the kit (`Item` is presentational).
+- Scenarios where a non-`label` activation pattern is required without rethinking focus and hit targets.
+
+## Composition
+
+- **`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`.
+
+### Minimal example
+
+```tsx
+import { FileUpload } from "prime-ui-kit";
+
+export function Example() {
+  return <FileUpload.Root />;
+}
+```
+
+## Rules
+
+- After each change or drop, `onFilesChange` receives a `File[]`; the input’s value is cleared so selecting the same file again still fires the callback.
+- When `disabled` is set, the input is disabled, drops are ignored, and `data-disabled` is set on the `label` (`aria-disabled` is mirrored on the input).
+- While a drag hovers the zone, the root `label` has `data-dragover` for styling.
+- `BrowseLink` and `Chip` call `preventDefault` and `stopPropagation` on click — they do not open the picker unless you call `inputRef.current?.click()`.
+- `FileUpload.Icon` and `FileUpload.FormatBadge` set `aria-hidden`; expose file meaning in visible text (e.g. `ItemName` / `ItemMeta`).
+- `ItemProgress` renders `ProgressBar.Root` when `value` is defined and `children` are omitted; with no `value` and no `children`, only the empty wrapper is present.
+- `DropBody` uses `pointer-events: none` on the wrapper so nested controls must remain interactive via nested `pointer-events` (as in the module styles).
+
+## API
+
+### FileUpload.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `FileUploadSize` (`"s" \| "m" \| "l" \| "xl"`) | `"m"` | No | Tokens for the zone, built-in icon, and hint context. |
+| appearance | `FileUploadAppearance` (`"dashed" \| "solid"`) | `"dashed"` | No | Dashed vs solid border and field-like background. |
+| inputRef | `React.Ref<HTMLInputElement>` | — | No | Ref to the hidden input (e.g. programmatic `click()`). |
+| accept | `string` | — | No | Native `accept`. |
+| multiple | `boolean` | — | No | Multi-select in the file dialog. |
+| disabled | `boolean` | — | No | Disables input and drops. |
+| onFilesChange | `(files: File[]) => void` | — | No | Called after picker change or drop. |
+| children | `React.ReactNode` | — | No | Replaces the default drop-zone body. |
+| className | `string` | — | No | Class on the `label`. |
+| …rest | `Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "children">` | — | No | `id`, `htmlFor`, ARIA, and other label attributes. |
+
+### FileUpload.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Wrapper class. |
+| children | `React.ReactNode` | — | No | Icon or other content. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Passed to `span` (`aria-hidden` is set on the component). |
+
+### FileUpload.Title
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| tone | `"default" \| "muted"` | `"default"` | No | Text emphasis. |
+| className | `string` | — | No | Class on the `p`. |
+| children | `React.ReactNode` | — | No | Title text. |
+| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Other paragraph attributes. |
+
+### FileUpload.Hint
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class passed to `Hint.Root`. |
+| children | `React.ReactNode` | — | No | Hint content. |
+| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Forwarded into `Hint.Root`; size follows `Root` context. |
+
+### FileUpload.BrowseLabel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | `span` class. |
+| children | `React.ReactNode` | — | No | Browse chip label. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes. |
+
+### FileUpload.BrowseLink
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Button `type`. |
+| className | `string` | — | No | Class on the `button`. |
+| onClick | `React.MouseEventHandler<HTMLButtonElement>` | — | No | Invoked after `preventDefault` / `stopPropagation`. |
+| children | `React.ReactNode` | — | No | Link text. |
+| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | Other button attributes. |
+
+### FileUpload.DropBody
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Column wrapper class. |
+| children | `React.ReactNode` | — | No | Custom layout. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
+
+### FileUpload.ActionsRow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Row class. |
+| children | `React.ReactNode` | — | No | Chips or other actions. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
+
+### FileUpload.Chip
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Button `type`. |
+| className | `string` | — | No | Class on the `button`. |
+| onClick | `React.MouseEventHandler<HTMLButtonElement>` | — | No | Invoked after `preventDefault` / `stopPropagation`. |
+| children | `React.ReactNode` | — | No | Chip contents (e.g. icon + `ChipLabel`). |
+| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | Other button attributes. |
+
+### FileUpload.ChipLabel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the `span`. |
+| children | `React.ReactNode` | — | No | Chip text. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | `span` attributes. |
+
+### FileUpload.FormatBadge
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| format | `string` | — | Yes | Source string; trimmed, truncated, and uppercased for display. |
+| color | `FileUploadFormatBadgeColor` | `"gray"` | No | Badge palette (`gray`, `red`, `blue`, `green`, `orange`, `purple`, `sky`, `yellow`). |
+| className | `string` | — | No | Extra class on the `span`. |
+
+### FileUpload.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `FileUploadItemVariant` (`"default" \| "error"`) | `"default"` | No | Card emphasis. |
+| size | `FileUploadSize` | `"m"` | No | Card and inline scale. |
+| className | `string` | — | No | Container class. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
+
+### FileUpload.ItemRow, ItemMain, ItemStack, ItemTextGroup, ItemName, ItemMeta, ItemActions, ItemFooter
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Extra class. |
+| children | `React.ReactNode` | — | No | Nested markup. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | `div` attributes. |
+
+### FileUpload.ItemMetaSep
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | `span` class. |
+| children | `React.ReactNode` | — | No | Avoid relying on `children`; the glyph is fixed. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Passed to `span` (`aria-hidden`). |
+
+### FileUpload.ItemTryAgain
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Button `type`. |
+| className | `string` | — | No | Class on the `button`. |
+| children | `React.ReactNode` | — | No | Label. |
+| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | Other button attributes. |
+
+### FileUpload.ItemProgress
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `number` | — | No | When set and `children` omitted, renders `ProgressBar.Root`. |
+| max | `number` | — | No | Progress maximum (passed to `ProgressBar.Root`). |
+| className | `string` | — | No | Wrapper class. |
+| children | `React.ReactNode` | — | No | Custom indicator instead of the bar. |
+
+## Related
+
+- [Button](../button/COMPONENT.md) — actions that call `inputRef.current?.click()`, clear lists, or sit in `ItemActions`.
+- [Hint](../hint/COMPONENT.md) — underlying primitive for `FileUpload.Hint`.
+- [ProgressBar](../progress-bar/COMPONENT.md) — used inside `ItemProgress` when `value` is provided without custom `children`.
+- [Label](../label/COMPONENT.md) — pairing copy with the zone in forms.
+- [Avatar](../avatar/COMPONENT.md) — image preview next to upload actions on profile-style screens.
+- [Divider](../divider/COMPONENT.md) — separating rows in attachment lists.

package/src/components/hint/COMPONENT.md

@@ -0,0 +1,67 @@
+# Hint
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+`Hint` is a compact line of helper or status text under a field: neutral copy, validation errors, or muted text for inactive inputs, with an optional leading icon.
+
+- **When to use** — explain format rules, limits, units, or where a read-only value comes from under a single control.
+- **When to use** — show validation or integration errors tied to a field without a separate notification block.
+- **When to use** — align typography and spacing with the field via the same `size` tier as the control.
+- **When not to use** — as the primary name of the field; use [Label](../label/COMPONENT.md) for that.
+- **When not to use** — when [Input](../input/COMPONENT.md) already takes `hint` / `error` on the root, or [Textarea](../textarea/COMPONENT.md) already includes `Textarea.Hint` / `Textarea.Error` in the same field block.
+- **When not to use** — for long prose or page-level messaging; prefer dedicated content or banner patterns.
+
+## Composition
+
+- **`Hint.Root`** — required wrapper: a `p` with `data-size` and `data-variant`, wrapped in `ControlSizeProvider` so size cascades to the icon slot.
+- **`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.
+
+### Minimal example
+
+```tsx
+import { Hint } from "prime-ui-kit";
+
+export function FieldHint() {
+  return <Hint.Root>The invitation will be valid for 7 days.</Hint.Root>;
+}
+```
+
+## Rules
+
+- **Variants:** `default` is secondary helper text; `error` is for validation or failure copy; `disabled` matches visually inactive fields (there is no separate `disabled` boolean on the root).
+- **Sizing:** `size` is one of `s`, `m`, `l`, `xl`; pick the same tier as the paired field for consistent type and icon gap.
+- **Semantics:** the root is always a `<p>` — there is no `asChild` or element polymorphism.
+- **Association:** give `Hint.Root` a stable `id` and point the control at it with `aria-describedby` so assistive tech reads hint after the label.
+- **Errors:** you may pass `role="alert"` or live-region attributes through `…rest` on `Hint.Root` if your form flow requires it.
+- **`Hint.Icon`** is `aria-hidden`; do not rely on it to convey meaning without redundant text.
+- **State:** text and `variant` are fully controlled by the parent (no built-in validation or open state).
+
+## API
+
+### Hint.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `HintSize` (`"s" \| "m" \| "l" \| "xl"`) | `"m"` | No | Nominal size aligned with the field. |
+| variant | `"default" \| "error" \| "disabled"` | `"default"` | No | Text tone: secondary, danger, or disabled content. |
+| children | `React.ReactNode` | — | No | Text; optionally include `Hint.Icon`. |
+| className | `string` | — | No | Additional class on the root `p`. |
+| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Native paragraph attributes (`id`, `role`, `aria-*`, etc.). |
+
+### Hint.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon markup (for example SVG). |
+| className | `string` | — | No | Additional class on the wrapper `span`. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other attributes on the wrapper. |
+
+## Related
+
+- [Label](../label/COMPONENT.md) — primary field caption and `htmlFor` / `id` wiring.
+- [Input](../input/COMPONENT.md) — field composition with optional built-in hint and error.
+- [Textarea](../textarea/COMPONENT.md) — multiline field with the same metadata pattern where applicable.
+- [Button](../button/COMPONENT.md) — actions that trigger validation and updated hint copy or `variant`.

package/src/components/input/COMPONENT.md

@@ -0,0 +1,119 @@
+# Input
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A composite single-line text field: optional label row outside the control, a bordered wrapper around the native `input`, and optional icons or text affixes inside the row. Hint and error text render below via the shared Hint primitive.
+
+**When to use**
+
+- Single-line text, email, password, search, tel, number, and other native `input` types in forms, filters, and settings.
+- Fields that need a built-in label, optional secondary header text, hint, or error line tied to the input id.
+- Dense layouts where `Input.Icon`, `Input.Affix`, or `Input.InlineAffix` clarify format (URL prefix, currency, search glyph) without extra wrappers.
+
+**When not to use**
+
+- Multiline or auto-growing text — use [Textarea](../textarea/COMPONENT.md).
+- Fixed-length codes split into cells or heavy masking — use [DigitInput](../digit-input/COMPONENT.md) or app-level logic.
+- When the label must be fully decoupled from the field chrome — consider [Label](../label/COMPONENT.md) plus a minimal field pattern instead of `label` on Root.
+
+## Composition
+
+- **`Input.Root`** — outer `div` with `data-size`, context provider, and `ControlSizeProvider`. Optional header: `label` (`htmlFor` → input id) and `optionalLabel`. Children (usually **`Input.Wrapper`**) sit between header and meta. If `hint` or `error` is set, a meta block renders **`Hint.Root`** rows for each.
+- **`Input.Wrapper`** — flex row with field border and background; `data-size` and `data-has-error` come from context. Place **`Input.Field`**, **`Input.Icon`**, **`Input.Affix`**, and **`Input.InlineAffix`** inside in the order your layout needs.
+- **`Input.Field`** — the actual `<input>`; receives `id`, merged `aria-describedby`, and `aria-invalid` from context.
+- **`Input` namespace** — `Root`, `Wrapper`, `Field`, `Icon`, `Affix`, `InlineAffix`. **`useInputContext`** is exported for custom inner pieces that must align with the same size and ids.
+
+### Minimal example
+
+```tsx
+import { Input } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Input.Root>
+      <Input.Wrapper>
+        <Input.Field />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}
+```
+
+## Rules
+
+- Use **`Input.Root`** `size` for control sizing; **`Input.Field`** omits the HTML `size` attribute (it is stripped from props) — do not rely on passing `size` to the native input.
+- Passing **`error`** on Root sets **`hasError`** internally for visuals and `aria-invalid`; you may set **`hasError`** alone for validation without message text.
+- Controlled usage: pass **`value`** / **`onChange`** (and related) on **`Input.Field`**. Uncontrolled: omit **`value`** and optionally use **`defaultValue`**.
+- Prefer Root **`label`** for the common case; if there is no visible label, set **`aria-label`** or **`aria-labelledby`** on **`Input.Field`**.
+- **`Input.Icon`**, **`Input.Affix`**, and **`Input.InlineAffix`** are **`aria-hidden`**; do not rely on them for the accessible name. You may append ids to **`aria-describedby`** on **`Input.Field`**; values merge with hint/error ids from context.
+- Set **`id`** on Root when you need a stable input id (e.g. tests or external `htmlFor`). Otherwise an id is generated in **`useFieldIds`**.
+- There is no separate **`variant`** prop: visual error state comes from **`error`** / **`hasError`**. Behavioral differences use native attributes on **`Input.Field`** (`type`, `autoComplete`, `inputMode`, `pattern`, `maxLength`, `disabled`, `readOnly`, **`required`**, etc.).
+
+## API
+
+### Input.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Control size from `--prime-sys-size-control-*` tokens. |
+| hasError | `boolean` | `false` | no | Invalid state: propagates to wrapper and `aria-invalid` on the field; if `error` is set, treated as true. |
+| label | `React.ReactNode` | — | no | Label; rendered as `<label htmlFor={inputId}>`. |
+| optionalLabel | `React.ReactNode` | — | no | Secondary text in the header row. |
+| hint | `React.ReactNode` | — | no | Hint below the field. |
+| error | `React.ReactNode` | — | no | Error message; implies error styling and `hasError` behavior. |
+| id | `string` | — | no | Explicit input id; otherwise generated via `useFieldIds`. |
+| children | `React.ReactNode` | — | yes | Field body (typically `Input.Wrapper` with content). |
+| className | `string` | — | no | Class on the root element. |
+
+### Input.Wrapper
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Content inside the field border. |
+| className | `string` | — | no | Extra class; `data-size` and `data-has-error` come from context. |
+
+### Input.Field
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | no | Class on the `input`. |
+| aria-describedby | `string` | — | no | Appended to the id list from context (hint/error). |
+| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">` | — | no | Standard `input` attributes except `size` (reserved for the design system). |
+
+### Input.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| side | `"start" \| "end"` | — | yes | Icon position inside the wrapper. |
+| children | `React.ReactNode` | — | yes | Usually an icon component from the kit. |
+| className | `string` | — | no | Class on the wrapping `span`. |
+
+### Input.Affix
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| side | `"start" \| "end"` | — | yes | Side of the block affix. |
+| children | `React.ReactNode` | — | yes | Static text segment (e.g. URL prefix). |
+| className | `string` | — | no | Class on the container. |
+
+### Input.InlineAffix
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| side | `"start" \| "end"` | — | yes | Side of the inline affix. |
+| children | `React.ReactNode` | — | yes | Short text (e.g. currency symbol). |
+| className | `string` | — | no | Class on the `span`. |
+
+### useInputContext()
+
+Returns `{ size, hasError, inputId, describedBy }` for building custom subcomponents that stay consistent with **`Input.Field`**.
+
+## Related
+
+- [Label](../label/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)
+- [Textarea](../textarea/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [DigitInput](../digit-input/COMPONENT.md)

package/src/components/kbd/COMPONENT.md

@@ -0,0 +1,59 @@
+# Kbd
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+`Kbd` is a single-part primitive: `Kbd.Root` renders a semantic `kbd` with kit styling so key names and shortcut fragments read as UI chrome, not body copy.
+
+- **When to use** — show hotkeys next to menu items, toolbar actions, or command labels in dense app chrome.
+- **When to use** — mark one or a few keys inside helper text, field hints, or modal footers where the shortcut is part of the instruction.
+- **When to use** — pair with the same `size` tier as nearby controls so typography and nested icons stay aligned with [Input](../input/COMPONENT.md), [Button](../button/COMPONENT.md), or other sized surfaces.
+- **When not to use** — as the only actionable control; shortcuts still need a real [Button](../button/COMPONENT.md), [Link button](../link-button/COMPONENT.md), or focusable target.
+- **When not to use** — when you need the element to listen for or mirror actual keyboard input; this component is display-only.
+- **When not to use** — for long prose or documentation pages where plain text or a code font is clearer than chip-style keys.
+
+## Composition
+
+- **`Kbd`** exports **`Root` only** — a flat API with no nested parts or ordering rules beyond wrapping the key label (text, icons, or mixed `ReactNode`) inside **`Kbd.Root`**.
+- **`Root`** renders a native **`kbd`**, applies `data-size`, and wraps **`children`** in **`ControlSizeProvider`** so nested **`Icon`** (and similar) pick up the same control-size context.
+
+### Minimal example
+
+```tsx
+import { Kbd } from "prime-ui-kit";
+
+export function Example() {
+  return <Kbd.Root>Esc</Kbd.Root>;
+}
+```
+
+## Rules
+
+- **Sizing:** optional **`size`** is **`"s"` \| `"m"` \| `"l"` \| `"xl"`** (`KbdSize`). If omitted, the effective size comes from the nearest ancestor **`ControlSizeProvider`** (via **`useOptionalControlSize`**), mapped with **`controlSurfaceToInputSize`** — **`"xs"`** on the control surface becomes **`"s"`** on the `kbd`. If there is no context, the fallback is **`"m"`**.
+- **Presentation only:** the component does not handle key events, focus management, or OS shortcut state; it only displays a label.
+- **Semantics:** there is no **`asChild`** or element polymorphism — the root is always **`kbd`**.
+- **Accessibility:** semantic **`kbd`** helps assistive tech distinguish key labels from surrounding text. For chord hints, prefer several **`Kbd.Root`** instances with short separators (**`+`**, “or”) **outside** the keys, or mark decorative separators with **`aria-hidden`**, so they are not announced as part of each key. Use **`title`** (or visible copy) when the shortcut needs extra explanation; do not rely on surface color alone for meaning.
+- **Platform copy:** glyphs such as **⌘** vs **Ctrl** are a product/i18n choice; the kit does not normalize platform key names.
+- **Styling:** one built-in look (raised surface, border, light shadow). Further changes go through **`className`** or project styles, not a separate **`variant`** prop.
+
+## API
+
+### Kbd.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `KbdSize` (`"s" \| "m" \| "l" \| "xl"`) | from context or `"m"` | No | Nominal size; without the prop, taken from `ControlSizeProvider` if present, otherwise `"m"`; `xs` context maps to `s`. |
+| children | `React.ReactNode` | — | Yes | Key label, icons, or mixed content. |
+| className | `string` | — | No | Additional class on the `kbd`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLElement>, "size">` | — | No | Native attributes (`title`, `hidden`, `aria-*`, `data-*`, etc.). |
+
+## Related
+
+- [Button](../button/COMPONENT.md) — primary action a shortcut often refers to.
+- [Link button](../link-button/COMPONENT.md) — text-style actions that may show a key hint beside the label.
+- [Input](../input/COMPONENT.md) — fields whose `hint` or label area can include `Kbd`.
+- [Textarea](../textarea/COMPONENT.md) — multiline fields with the same hint pattern where applicable.
+- [Select](../select/COMPONENT.md) — triggers and lists that may document shortcuts.
+- [Tooltip](../tooltip/COMPONENT.md) — longer explanations that can repeat keys with `Kbd`.
+- [Command menu](../command-menu/COMPONENT.md) — lists that commonly show per-item shortcuts.

package/src/components/label/COMPONENT.md

@@ -0,0 +1,94 @@
+# Label
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Composite caption for form fields: `Label.Root` is a native `label` with optional slots `Label.Icon`, `Label.Asterisk`, and `Label.Sub` for icon, required marker, and secondary text.
+
+- **Use** to associate visible text with a control via `htmlFor` / `id` or by nesting the control inside the root.
+- **Use** when you want a consistent type scale (`size`) and optional icon or second-line hint in one label row.
+- **Use** `Label.Asterisk` for a visual required marker next to the caption.
+- **Do not use** as a replacement for field validation messages or long help copy; pair with [Hint](../hint/COMPONENT.md) or similar when you need status or errors below the field.
+- **Do not use** expecting the label to set `required` on inputs; that remains on the control.
+- **Do not use** `Label` as a non-label wrapper; the root is always a `label` element (no polymorphic `asChild`).
+
+## Composition
+
+- **`Label.Root`** — `<label>`; sets `data-size` (from `size`, default `m`) and `data-disabled` when `disabled`. Wraps children in `LabelSizeContext` so slots inherit the same size.
+- **`Label.Icon`** — `<span>` before or beside the main text; forwards label size to children via `ControlSizeProvider` (e.g. for kit `Icon` sizing).
+- **`Label.Asterisk`** — `<span>` for the required marker; default child text is `*` if `children` is omitted.
+- **`Label.Sub`** — `<span>` for secondary line or hint text on the same label.
+- Slot order in markup is flexible; keep reading order sensible for screen readers (e.g. icon, title, asterisk, sub).
+
+### Minimal example
+
+```tsx
+import { Label } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <>
+      <Label.Root htmlFor="field-id">Caption</Label.Root>
+      <input id="field-id" />
+    </>
+  );
+}
+```
+
+## Rules
+
+- **Association:** set **`htmlFor` on `Label.Root`** to match the control’s **`id`**, or place the interactive control inside **`Label.Root`** so the caption is programmatically linked.
+- **`disabled` on `Label.Root`:** sets **`aria-disabled`** and **`data-disabled`** for muted styling; keep the actual field non-interactive (`disabled`, `readOnly`, etc.) or behavior will not match the label-only state.
+- **`Label.Icon`:** when the icon is decorative and the visible label text is sufficient, mark the icon **`aria-hidden`**.
+- **`Label.Asterisk`** is visual-only; expose required state on the control with **`required`** / **`aria-required`** and errors via hint or validation UI as needed.
+- There is no separate **`variant`** prop; appearance follows **`size`** and slot composition (asterisk uses danger-accent styling from the theme).
+- The root does **not** implement **`asChild`**; it is always a **`label`**.
+- Nesting an input inside **`Label.Root`** is valid HTML; the common kit pattern is sibling **`Label.Root`** + control with **`htmlFor`** / **`id`**.
+
+## API
+
+### Label.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Type scale, spacing, and size context for nested slots (e.g. `Label.Icon`) |
+| disabled | `boolean` | — | No | Disabled look; sets `aria-disabled` and `data-disabled` |
+| htmlFor | `string` | — | No | `id` of the associated control |
+| className | `string` | — | No | Additional class on the root |
+| children | `React.ReactNode` | — | No | Text and `Label.Icon`, `Label.Asterisk`, `Label.Sub` |
+| …rest | `Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "size">` | — | No | Other native `label` attributes (`size` is reserved for the design-system prop) |
+
+### Label.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the wrapper |
+| children | `React.ReactNode` | — | No | Typically an icon; receives control size from label context |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
+
+### Label.Asterisk
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the wrapper |
+| children | `React.ReactNode` | `"*"` | No | Overrides the default asterisk character when provided |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
+
+### Label.Sub
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the wrapper |
+| children | `React.ReactNode` | — | No | Secondary line under the main caption |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes |
+
+## Related
+
+- [Input](../input/COMPONENT.md)
+- [Textarea](../textarea/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [Checkbox](../checkbox/COMPONENT.md)
+- [Radio](../radio/COMPONENT.md)
+- [Switch](../switch/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)

package/src/components/link-button/COMPONENT.md

@@ -0,0 +1,60 @@
+# LinkButton
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Text-style navigation control: one subpart (`LinkButton.Root`) with control typography and padding, underline on hover and `:focus-visible`, and four size options (`s`–`xl`).
+
+- **Use** for in-app routes and sections when the UI should read as a **link**, not a filled button.
+- **Use** inline in copy (help, legal, helper text) where a compact or scaled text link fits the layout.
+- **Use** when nested icons should follow **control** size tokens—`size` sets **`ControlSizeProvider`** for children.
+- **Do not use** for actions that do not navigate (submit, toggle, open dialogs); use **Button** or another control.
+- **Do not use** expecting **`asChild`** or polymorphic roots; you cannot attach these styles to a child router **`Link`** via one prop.
+- **Do not use** **`disabled`** to mean “still in tab order with full link semantics”; disabled mode removes focus and drops anchor attributes (see Rules).
+
+## Composition
+
+- **`LinkButton`** — namespace object with **`LinkButton.Root`** only; import **`LinkButton`** from **`prime-ui-kit`** and render **`LinkButton.Root`**.
+- **`LinkButton.Root`** — when **`disabled`** is false (default), renders **`<a>`** with anchor attributes from props and wraps **`children`** in **`ControlSizeProvider`** for **`size`**.
+- When **`disabled`** is true, renders **`<span role="link">`** with **`aria-disabled="true"`**, **`tabIndex={-1}`**, and the same size context—no **`href`** or other spread anchor props on the DOM node.
+
+### Minimal example
+
+```tsx
+import { LinkButton } from "prime-ui-kit";
+
+export function Example() {
+  return <LinkButton.Root href="/">Home</LinkButton.Root>;
+}
+```
+
+## Rules
+
+- **`size`** defaults to **`m`**; valid values are **`"s"`**, **`"m"`**, **`"l"`**, **`"xl"`** (control token tier).
+- With **`disabled={true}`**, **`...rest`** from **`React.AnchorHTMLAttributes`** is **not** applied—the root is a **`span`**, so **`href`**, **`target`**, **`onClick`**, and similar props have **no effect** on the output; do not rely on them for accessibility or behavior in that mode.
+- Active link: native **`<a>`** with your **`href`**; keyboard **Enter** activates like a normal link.
+- Disabled presentation: **`role="link"`**, **`aria-disabled="true"`**, **`tabIndex={-1}`**—not in tab order by default; avoid if the item should remain focusable as a link.
+- For **icon-only** links, provide a name (**`aria-label`** or visible text).
+- For **`target="_blank"`**, set **`rel="noopener noreferrer"`** (and warn in UI if policy requires it).
+- There is no loading or error variant; for async work without navigation, prefer **Button** (or another pattern).
+- One visual style only (no **`variant`**); hierarchy comes from **`size`** and surrounding layout. No built-in **`fullWidth`**—use layout or **`className`** on the root if you need block-level stretch.
+- **`ref`** is forwarded to the DOM root (**`<a>`** or the disabled **`<span>`**); the public ref type is **`HTMLAnchorElement`** even though the disabled node is a **`span`**.
+
+## API
+
+### LinkButton.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control height / type scale; size context for nested icons via `ControlSizeProvider`. |
+| disabled | `boolean` | `false` | No | Renders `span` with `role="link"` instead of `a`; no navigation. |
+| children | `React.ReactNode` | — | No | Link content (text, icons, etc.). |
+| className | `string` | — | No | Additional class on the root element. |
+| …rest | `React.AnchorHTMLAttributes<HTMLAnchorElement>` | — | No | Forwarded to `<a>` only when `disabled` is false (e.g. `href`, `target`, `rel`, `download`, `onClick`, `aria-*`, `tabIndex`). |
+
+## Related
+
+- [Button](../button/COMPONENT.md) — actions, forms, loading/disabled without link semantics.
+- [Breadcrumb](../breadcrumb/COMPONENT.md) — trail navigation; items may use `LinkButton` internally.
+- [Typography](../typography/COMPONENT.md) — body text and inline links without control padding; `LinkButton` matches control alignment and scale.