prime-ui-kit 0.0.1

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 appearance="solid" />
+    </div>
+  );
+}

package/src/components/hint/COMPONENT.md

@@ -0,0 +1,111 @@
+# Hint
+
+**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
+
+## Canonical
+
+- **`Hint`** — compact helper or status line under a control: **`Hint.Root`** (`<p>`, `data-size`, `data-variant`) and optional **`Hint.Icon`** (leading, `aria-hidden`).
+- **`variant`:** **`default`** (secondary text), **`error`** (danger), **`disabled`** (muted; mirrors inactive fields — not a boolean on the root).
+- **`size`:** **`s` | `m` | `l` | `xl`** — match the paired field; typography is one step smaller than the control tier (see styles).
+- **No `success` variant** — positive confirmation uses **`default`** copy and tone, or another pattern (for example [Banner](../banner/COMPONENT.md)) if you need semantic success chrome.
+- **A11y:** stable **`id`** on **`Hint.Root`** + **`aria-describedby`** on the input; optional **`role="alert"`** on the root for errors via **`…rest`**.
+- **Prefer [Input](../input/COMPONENT.md) `hint` / `error`** when the whole field is composed with **`Input.Root`** — avoid duplicating the same line with a second **`Hint`**.
+
+## Extended
+
+### 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** — after a successful action, short confirmation under the field: use **`variant="default"`** with clear copy (no dedicated success color on **`Hint`**).
+- **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.
+
+### 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
+
+```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.
+- **Sizing:** 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 the 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`**.
+
+## LLM note
+
+- Export: **`import { Hint } from "prime-ui-kit"`** — **`Hint.Root`**, **`Hint.Icon`** only.
+- **`HintRootProps`**: **`size?`**, **`variant?`**, **`className?`**, **`children?`**, plus **`HTMLAttributes<HTMLParagraphElement>`** (forward **`id`**, **`role`**, **`aria-*`**).
+- **`variant`** literals: **`default`**, **`error`**, **`disabled`** — **no `success`**; success-style messaging = **`default`** + wording, or another component.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
+- Root DOM: **`<p>`**; **`Hint.Icon`** → **`<span aria-hidden="true">`**.
+- Do not tell users to add a **`success`** **`variant`**; it does not exist on **`Hint`**.
+- When **`Input.Root`** already provides **`hint`** or **`error`**, do not add a duplicate **`Hint`** for the same string.
+- Pair with **`Label`** + **`Input.Root`** / **`Input.Wrapper`** / **`Input.Field`**; wire **`aria-describedby`** on **`Input.Field`** to **`Hint.Root`**’s **`id`** when hints are siblings outside **`Input`**’s built-in meta slots.

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

@@ -0,0 +1,21 @@
+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">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" 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 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/error-hint.tsx

@@ -0,0 +1,20 @@
+import { Hint, Input, Label } from "prime-ui-kit";
+
+/** Validation message: `variant="error"`, invalid field, optional `role="alert"`. */
+export default function ErrorHintExample() {
+  const hintId = "hint-example-error-desc";
+
+  return (
+    <>
+      <Label.Root htmlFor="hint-example-error">Tax ID</Label.Root>
+      <Input.Root id="hint-example-error" hasError>
+        <Input.Wrapper>
+          <Input.Field type="text" defaultValue="12" aria-describedby={hintId} />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root id={hintId} variant="error" role="alert">
+        Enter 10 or 12 digits.
+      </Hint.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,25 @@
+import { Hint, Input, Label } from "prime-ui-kit";
+
+/** Neutral helper under a field: same `size` as the input, linked with `aria-describedby`. */
+export default function FieldHelpExample() {
+  const hintId = "hint-example-field-help-desc";
+
+  return (
+    <>
+      <Label.Root htmlFor="hint-example-field-help">Project name</Label.Root>
+      <Input.Root id="hint-example-field-help">
+        <Input.Wrapper>
+          <Input.Field
+            type="text"
+            defaultValue="Alpha"
+            autoComplete="organization"
+            aria-describedby={hintId}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root id={hintId} variant="default">
+        Visible to everyone in this workspace.
+      </Hint.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,34 @@
+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">Project name</Label.Root>
+      <Input.Root id="hint-ex-st-ok">
+        <Input.Wrapper>
+          <Input.Field type="text" defaultValue="Alpha" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root variant="default">Visible to everyone in this workspace.</Hint.Root>
+
+      <Label.Root htmlFor="hint-ex-st-err">Tax ID</Label.Root>
+      <Input.Root id="hint-ex-st-err" hasError>
+        <Input.Wrapper>
+          <Input.Field type="text" defaultValue="12" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root variant="error">Enter 10 or 12 digits.</Hint.Root>
+
+      <Label.Root htmlFor="hint-ex-st-dis" disabled>
+        Request limit
+      </Label.Root>
+      <Input.Root id="hint-ex-st-dis">
+        <Input.Wrapper>
+          <Input.Field type="text" disabled defaultValue="read only" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root variant="disabled">Value comes from the plan and cannot be edited.</Hint.Root>
+    </>
+  );
+}

package/src/components/hint/examples/inline-tip-form.tsx

@@ -0,0 +1,40 @@
+import { Hint, Input, Label } from "prime-ui-kit";
+
+/** Multiple rows: label, control, hint — tip copy inline with the form stack. */
+export default function InlineTipFormExample() {
+  const emailHintId = "hint-example-form-email-desc";
+  const budgetHintId = "hint-example-form-budget-desc";
+
+  return (
+    <>
+      <Label.Root htmlFor="hint-example-form-email">Billing email</Label.Root>
+      <Input.Root id="hint-example-form-email">
+        <Input.Wrapper>
+          <Input.Field
+            type="email"
+            placeholder="finance@company.com"
+            aria-describedby={emailHintId}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root id={emailHintId} variant="default">
+        Invoices and receipts go here; not the same as your login email.
+      </Hint.Root>
+
+      <Label.Root htmlFor="hint-example-form-budget">Monthly budget</Label.Root>
+      <Input.Root id="hint-example-form-budget">
+        <Input.Wrapper>
+          <Input.Field
+            type="text"
+            inputMode="decimal"
+            placeholder="0"
+            aria-describedby={budgetHintId}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root id={budgetHintId} variant="disabled">
+        Optional — leave empty to use the workspace default.
+      </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/success-confirmation.tsx

@@ -0,0 +1,28 @@
+import { Hint, Input, Label } from "prime-ui-kit";
+
+/**
+ * There is no `success` variant on `Hint`. Use `variant="default"` for short,
+ * neutral confirmation copy under the field (secondary text color).
+ */
+export default function SuccessConfirmationExample() {
+  const hintId = "hint-example-success-desc";
+
+  return (
+    <>
+      <Label.Root htmlFor="hint-example-success">API token</Label.Root>
+      <Input.Root id="hint-example-success">
+        <Input.Wrapper>
+          <Input.Field
+            type="text"
+            readOnly
+            defaultValue="pk_live_••••••••"
+            aria-describedby={hintId}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root id={hintId} variant="default">
+        Token saved. Rotate it from settings anytime.
+      </Hint.Root>
+    </>
+  );
+}

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

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

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

@@ -0,0 +1,13 @@
+import { Hint, Icon } from "prime-ui-kit";
+
+/** Decorative leading icon; meaning must be repeated in text (`Hint.Icon` is `aria-hidden`). */
+export default function HintWithIconExample() {
+  return (
+    <Hint.Root variant="default">
+      <Hint.Icon>
+        <Icon name="field.email" tone="subtle" />
+      </Hint.Icon>
+      We will send a confirmation code to this address.
+    </Hint.Root>
+  );
+}

package/src/components/input/COMPONENT.md

@@ -0,0 +1,140 @@
+# Input
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+- **Назначение:** однострочное поле с опциональной подписью, обводкой вокруг нативного `input`, слотами для иконок и аффиксов; подсказка и ошибка снизу через **Hint**.
+- **Скелет:** `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`**.
+- **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";
+
+export function Example() {
+  return (
+    <Input.Root label="Поле">
+      <Input.Wrapper>
+        <Input.Field placeholder="Значение" />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}
+```
+
+## Extended
+
+### 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.
+
+### 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.).
+- **Full width:** root already uses **`width: 100%`** and **`min-width: 0`**. To fill a card or form column, place **`Input.Root`** inside a parent that spans the desired width (see **`examples/checkout-full-width.tsx`**).
+
+### 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)
+
+## LLM note
+
+- **Обязательная иерархия:** `Input.Root` → `Input.Wrapper` → `Input.Field`. Не подменять разметку кастомными обёртками ради внешнего вида — только публичный API и слоты.
+- **`size`:** только `Input.Root`. Не прокидывать `size` в `Input.Field` (тип его исключает).
+- **Ошибка:** `error` на Root задаёт текст и включает invalid-стили; `hasError` без `error` — только состояние без текста.
+- **Доступность:** имя поля — `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`, `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 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 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/checkout-full-width.module.css

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

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

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

package/src/components/input/examples/login-email.tsx

@@ -0,0 +1,29 @@
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Вход: email с подписью, иконкой и автозаполнением.
+ */
+export default function LoginEmailExample() {
+  const [email, setEmail] = React.useState("");
+
+  return (
+    <Input.Root label="Электронная почта" hint="Мы отправим код подтверждения на этот адрес">
+      <Input.Wrapper>
+        <Input.Icon side="start">
+          <Icon name="field.email" size="s" tone="subtle" />
+        </Input.Icon>
+        <Input.Field
+          type="email"
+          name="email"
+          autoComplete="email"
+          inputMode="email"
+          placeholder="you@example.com"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+        />
+      </Input.Wrapper>
+    </Input.Root>
+  );
+}