prime-ui-kit 0.3.1 → 0.4.0

package/src/components/hint/COMPONENT.md

@@ -1,23 +1,56 @@
 # Hint
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
 
-## About
+## 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** — align typography and spacing with the field via the same `size` tier as the control.
+- **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** — 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
+### 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)
 
-- **`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.
+| 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
 
@@ -29,15 +62,15 @@ export function FieldHint() {
 }
 ```
 
-## Rules
+### 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).
+- **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
 
@@ -47,21 +80,32 @@ export function FieldHint() {
 |------|------|---------|----------|-------------|
 | 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.). |
+| 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`. |
+| 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.
+- [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`.
+- [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,23 @@
+import { Hint, Label } from "prime-ui-kit";
+
+/** Stable `id` on `Hint.Root` and `aria-describedby` on the control so the hint is read with the field. */
+export default function HintA11yDescribedbyExample() {
+  return (
+    <>
+      <Label.Root htmlFor="hint-ex-a11y-volume" size="m">
+        Notification volume
+      </Label.Root>
+      <input
+        id="hint-ex-a11y-volume"
+        type="range"
+        min={0}
+        max={100}
+        defaultValue={40}
+        aria-describedby="hint-ex-a11y-volume-help"
+      />
+      <Hint.Root id="hint-ex-a11y-volume-help" size="m" variant="default">
+        Does not affect calls and alarms in the mobile app.
+      </Hint.Root>
+    </>
+  );
+}

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

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

package/src/components/hint/examples/error-hint.tsx

@@ -0,0 +1,22 @@
+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" size="m">
+        Tax ID
+      </Label.Root>
+      <Input.Root size="m" id="hint-example-error" hasError>
+        <Input.Wrapper>
+          <Input.Field type="text" defaultValue="12" aria-describedby={hintId} />
+        </Input.Wrapper>
+      </Input.Root>
+      <Hint.Root id={hintId} size="m" variant="error" role="alert">
+        Enter 10 or 12 digits.
+      </Hint.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,27 @@
+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" size="m">
+        Project name
+      </Label.Root>
+      <Input.Root size="m" 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} size="m" variant="default">
+        Visible to everyone in this workspace.
+      </Hint.Root>
+    </>
+  );
+}

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

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

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

@@ -0,0 +1,44 @@
+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" size="m">
+        Billing email
+      </Label.Root>
+      <Input.Root size="m" 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} size="m" variant="default">
+        Invoices and receipts go here; not the same as your login email.
+      </Hint.Root>
+
+      <Label.Root htmlFor="hint-example-form-budget" size="m">
+        Monthly budget
+      </Label.Root>
+      <Input.Root size="m" 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} size="m" 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,30 @@
+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" size="m">
+        API token
+      </Label.Root>
+      <Input.Root size="m" 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} size="m" variant="default">
+        Token saved. Rotate it from settings anytime.
+      </Hint.Root>
+    </>
+  );
+}

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

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

package/src/components/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 size="m" 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

@@ -2,7 +2,32 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## 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.
 
@@ -18,30 +43,14 @@ A composite single-line text field: optional label row outside the control, a bo
 - 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
+### 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
+### 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.
@@ -50,10 +59,11 @@ export function Example() {
 - **`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
+### API
 
-### Input.Root
+#### Input.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -67,14 +77,14 @@ export function Example() {
 | children | `React.ReactNode` | — | yes | Field body (typically `Input.Wrapper` with content). |
 | className | `string` | — | no | Class on the root element. |
 
-### Input.Wrapper
+#### 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
+#### Input.Field
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -82,7 +92,7 @@ export function Example() {
 | 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
+#### Input.Icon
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -90,7 +100,7 @@ export function Example() {
 | children | `React.ReactNode` | — | yes | Usually an icon component from the kit. |
 | className | `string` | — | no | Class on the wrapping `span`. |
 
-### Input.Affix
+#### Input.Affix
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -98,7 +108,7 @@ export function Example() {
 | children | `React.ReactNode` | — | yes | Static text segment (e.g. URL prefix). |
 | className | `string` | — | no | Class on the container. |
 
-### Input.InlineAffix
+#### Input.InlineAffix
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -106,14 +116,25 @@ export function Example() {
 | children | `React.ReactNode` | — | yes | Short text (e.g. currency symbol). |
 | className | `string` | — | no | Class on the `span`. |
 
-### useInputContext()
+#### useInputContext()
 
 Returns `{ size, hasError, inputId, describedBy }` for building custom subcomponents that stay consistent with **`Input.Field`**.
 
-## Related
+### 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 size="m" label="Сайт" hint="Поддомен без схемы">
+        <Input.Wrapper>
+          <Input.Affix side="start">https://</Input.Affix>
+          <Input.Field placeholder="поддомен" />
+          <Input.Affix side="end">.example</Input.Affix>
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root size="m" label="Сумма" hint="Дробная часть через запятую">
+        <Input.Wrapper>
+          <Input.InlineAffix side="start">₽</Input.InlineAffix>
+          <Input.Field placeholder="0,00" inputMode="decimal" />
+        </Input.Wrapper>
+      </Input.Root>
+    </>
+  );
+}

package/src/components/input/examples/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 size="m" 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 size="m" 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>
+  );
+}