prime-ui-kit 0.7.11 → 0.9.0

package/src/components/file-upload/examples/examples.module.css

@@ -0,0 +1,109 @@
+.column {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+/* File rows inside a card: as wide as the drop zone above them. */
+.list {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: 100%;
+}
+
+.zones {
+  display: grid;
+  grid-template-columns: repeat(
+      auto-fit,
+      minmax(min(100%, calc(var(--prime-panel-min-width) * 1.5)), 1fr)
+    );
+  align-items: end;
+  gap: var(--prime-space-4);
+  width: 100%;
+}
+
+.sizeZones {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
+  align-items: end;
+  gap: var(--prime-space-3);
+  width: 100%;
+}
+
+.sizeCell {
+  display: grid;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}
+
+/* Title + hint inside a custom zone body. */
+.copy {
+  display: grid;
+  justify-items: center;
+  gap: var(--prime-space-1);
+}
+
+.chipGlyph {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--prime-control-xs-height);
+  height: var(--prime-control-xs-height);
+  border-radius: var(--prime-radius-full);
+  background: var(--prime-color-fill-muted);
+}
+
+.card {
+  width: 100%;
+  max-width: var(--prime-modal-width-m);
+}
+
+.avatarRow {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+/* The whole avatar is the drop target: a round zone that hugs it. */
+.avatarRow .avatarZone {
+  width: auto;
+  flex-shrink: 0;
+  padding: var(--prime-space-1);
+  border-radius: var(--prime-radius-full);
+}
+
+/* Text block → actions: 12; title → description: 4. */
+.avatarText {
+  display: grid;
+  gap: var(--prime-space-3);
+  min-width: 0;
+}
+
+.avatarCopy {
+  display: grid;
+  gap: var(--prime-space-1);
+  min-width: 0;
+}
+
+.avatarActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}
+
+/* Zones above, file rows below. */
+.stack {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.caption {
+  width: 100%;
+  text-align: center;
+}

package/src/components/file-upload/examples/file-list.tsx

@@ -0,0 +1,67 @@
+/** `multiple` + `accept`: every `onFilesChange` call appends files to state and each row can be removed. Use it when the app keeps the selected files before sending them. */
+import { Button, FileUpload, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+function formatSize(bytes: number) {
+  return bytes < 1024 * 1024
+    ? `${Math.max(1, Math.round(bytes / 1024))} КБ`
+    : `${(bytes / 1024 / 1024).toFixed(1)} МБ`;
+}
+
+const fileKey = (file: File) => `${file.name}-${file.size}-${file.lastModified}`;
+
+export default function FileUploadFileListExample() {
+  const [files, setFiles] = React.useState<File[]>([]);
+
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root
+        multiple
+        accept=".pdf,.png,.jpg,.jpeg"
+        onFilesChange={(next) =>
+          setFiles((prev) => {
+            const known = new Set(prev.map(fileKey));
+            return [...prev, ...next.filter((file) => !known.has(fileKey(file)))];
+          })
+        }
+      >
+        <FileUpload.DropBody>
+          <FileUpload.Icon>
+            <Icon name="action.upload" size="m" tone="secondary" />
+          </FileUpload.Icon>
+          <div className={styles.copy}>
+            <FileUpload.Title>Перетащите файлы или выберите на компьютере</FileUpload.Title>
+            <FileUpload.Hint>PDF, PNG или JPG — можно несколько</FileUpload.Hint>
+          </div>
+          <FileUpload.BrowseLabel>Выбрать файлы</FileUpload.BrowseLabel>
+        </FileUpload.DropBody>
+      </FileUpload.Root>
+
+      {files.map((file) => (
+        <FileUpload.Item key={fileKey(file)}>
+          <FileUpload.ItemRow>
+            <FileUpload.FormatBadge format={file.name.split(".").pop() ?? "file"} />
+            <FileUpload.ItemMain>
+              <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
+              <FileUpload.ItemMeta>{formatSize(file.size)}</FileUpload.ItemMeta>
+            </FileUpload.ItemMain>
+            <FileUpload.ItemActions>
+              <Button.Root
+                variant="ghost"
+                tone="neutral"
+                aria-label={`Удалить ${file.name}`}
+                onClick={() => setFiles((prev) => prev.filter((f) => f !== file))}
+              >
+                <Button.Icon>
+                  <Icon name="action.close" />
+                </Button.Icon>
+              </Button.Root>
+            </FileUpload.ItemActions>
+          </FileUpload.ItemRow>
+        </FileUpload.Item>
+      ))}
+    </div>
+  );
+}

package/src/components/file-upload/examples/in-card.tsx

@@ -0,0 +1,84 @@
+/** A `solid` zone in a card with a custom body (`DropBody`, muted `Title` with `BrowseLink`, source `Chip`s) and file rows below. Use it for document attachments in a request form. */
+import { Button, Card, FileUpload, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadInCardExample() {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const openPicker = () => inputRef.current?.click();
+
+  return (
+    <Card.Root variant="panel" className={styles.card}>
+      <Card.SectionHeader>
+        <Card.SectionTitle>Документы к заявке</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <FileUpload.Root inputRef={inputRef} variant="solid" multiple>
+          <FileUpload.DropBody>
+            <FileUpload.Title tone="muted">
+              Перетащите файлы сюда или{" "}
+              <FileUpload.BrowseLink onClick={openPicker}>
+                выберите на компьютере
+              </FileUpload.BrowseLink>
+            </FileUpload.Title>
+            <FileUpload.ActionsRow>
+              <FileUpload.Chip onClick={openPicker}>
+                <span className={styles.chipGlyph}>
+                  <Icon name="nav.layoutGrid" size="s" tone="secondary" />
+                </span>
+                <FileUpload.ChipLabel>Из галереи</FileUpload.ChipLabel>
+              </FileUpload.Chip>
+              <FileUpload.Chip onClick={openPicker}>
+                <span className={styles.chipGlyph}>
+                  <Icon name="field.email" size="s" tone="secondary" />
+                </span>
+                <FileUpload.ChipLabel>Из почты</FileUpload.ChipLabel>
+              </FileUpload.Chip>
+            </FileUpload.ActionsRow>
+          </FileUpload.DropBody>
+        </FileUpload.Root>
+
+        <div className={styles.list}>
+          <FileUpload.Item>
+            <FileUpload.ItemRow>
+              <FileUpload.FormatBadge format="pdf" color="red" />
+              <FileUpload.ItemMain>
+                <FileUpload.ItemName>Паспорт, разворот.pdf</FileUpload.ItemName>
+                <FileUpload.ItemMeta>
+                  <span>640 КБ из 1,6 МБ</span>
+                  <FileUpload.ItemMetaSep />
+                  <strong>Загрузка 40%</strong>
+                </FileUpload.ItemMeta>
+              </FileUpload.ItemMain>
+            </FileUpload.ItemRow>
+            <FileUpload.ItemProgress value={40} />
+          </FileUpload.Item>
+          <FileUpload.Item>
+            <FileUpload.ItemRow>
+              <FileUpload.FormatBadge format="jpg" color="green" />
+              <FileUpload.ItemMain>
+                <FileUpload.ItemName>СНИЛС.jpg</FileUpload.ItemName>
+                <FileUpload.ItemMeta>420 КБ</FileUpload.ItemMeta>
+              </FileUpload.ItemMain>
+              <FileUpload.ItemActions>
+                <Button.Root variant="ghost" tone="neutral" aria-label="Удалить СНИЛС.jpg">
+                  <Button.Icon>
+                    <Icon name="action.close" />
+                  </Button.Icon>
+                </Button.Root>
+              </FileUpload.ItemActions>
+            </FileUpload.ItemRow>
+          </FileUpload.Item>
+        </div>
+
+        <Card.Actions>
+          <Button.Root>Отправить заявку</Button.Root>
+          <Button.Root variant="ghost" tone="neutral">
+            Отмена
+          </Button.Root>
+        </Card.Actions>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/file-upload/examples/sizes.tsx

@@ -0,0 +1,48 @@
+/** Drop zone and file row on every size: padding, icon circle, browse button and row typography follow the tier. Match the size of the surrounding form. */
+import { FileUpload, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function FileUploadSizesExample() {
+  return (
+    <div className={styles.stack}>
+      <div className={styles.sizeZones}>
+        {SIZES.map((size) => (
+          <div key={size} className={styles.sizeCell}>
+            <FileUpload.Root size={size}>
+              <FileUpload.DropBody>
+                <FileUpload.Icon>
+                  <Icon name="action.upload" size={size} tone="secondary" />
+                </FileUpload.Icon>
+                <FileUpload.Title>Перетащите файл</FileUpload.Title>
+                <FileUpload.BrowseLabel>Выбрать</FileUpload.BrowseLabel>
+              </FileUpload.DropBody>
+            </FileUpload.Root>
+            <Typography.Root as="span" variant="caption" tone="muted" className={styles.caption}>
+              {size}
+            </Typography.Root>
+          </div>
+        ))}
+      </div>
+      <div className={styles.column}>
+        {SIZES.map((size) => (
+          <FileUpload.Item key={size} size={size}>
+            <FileUpload.ItemRow>
+              <FileUpload.FormatBadge format="pdf" color="red" />
+              <FileUpload.ItemMain>
+                <FileUpload.ItemName>Договор поставки.pdf</FileUpload.ItemName>
+                <FileUpload.ItemMeta>
+                  <span>240 КБ</span>
+                  <FileUpload.ItemMetaSep />
+                  <span>size=&quot;{size}&quot;</span>
+                </FileUpload.ItemMeta>
+              </FileUpload.ItemMain>
+            </FileUpload.ItemRow>
+          </FileUpload.Item>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/file-upload/examples/states.tsx

@@ -0,0 +1,106 @@
+/** Zone states (default, disabled, invalid with custom labels) and file rows (uploading with progress, uploaded with a remove action, failed with retry). Use it as the reference for upload feedback. */
+import { Button, FileUpload, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+function ZoneBody() {
+  return (
+    <FileUpload.DropBody>
+      <FileUpload.Icon>
+        <Icon name="action.upload" size="m" tone="secondary" />
+      </FileUpload.Icon>
+      <div className={styles.copy}>
+        <FileUpload.Title>Перетащите файл сюда</FileUpload.Title>
+        <FileUpload.Hint>PDF или PNG до 20 МБ</FileUpload.Hint>
+      </div>
+      <FileUpload.BrowseLabel>Выбрать файл</FileUpload.BrowseLabel>
+    </FileUpload.DropBody>
+  );
+}
+
+export default function FileUploadStatesExample() {
+  return (
+    <div className={styles.stack}>
+      <div className={styles.zones}>
+        <div className={styles.sizeCell}>
+          <FileUpload.Root>
+            <ZoneBody />
+          </FileUpload.Root>
+          <Typography.Root as="span" variant="caption" tone="muted" className={styles.caption}>
+            По умолчанию
+          </Typography.Root>
+        </div>
+        <div className={styles.sizeCell}>
+          <FileUpload.Root disabled>
+            <ZoneBody />
+          </FileUpload.Root>
+          <Typography.Root as="span" variant="caption" tone="muted" className={styles.caption}>
+            disabled
+          </Typography.Root>
+        </div>
+        <div className={styles.sizeCell}>
+          <FileUpload.Root
+            invalid
+            labels={{ title: "Файл не подошёл", hint: "Нужен PDF или PNG до 20 МБ" }}
+          />
+          <Typography.Root as="span" variant="caption" tone="muted" className={styles.caption}>
+            invalid + labels
+          </Typography.Root>
+        </div>
+      </div>
+
+      <div className={styles.column}>
+        <FileUpload.Item>
+          <FileUpload.ItemRow>
+            <FileUpload.FormatBadge format="pdf" color="red" />
+            <FileUpload.ItemMain>
+              <FileUpload.ItemName>Отчёт за квартал.pdf</FileUpload.ItemName>
+              <FileUpload.ItemMeta>
+                <span>1,2 МБ из 3 МБ</span>
+                <FileUpload.ItemMetaSep />
+                <strong>Загрузка 40%</strong>
+              </FileUpload.ItemMeta>
+            </FileUpload.ItemMain>
+          </FileUpload.ItemRow>
+          <FileUpload.ItemProgress value={40} />
+        </FileUpload.Item>
+
+        <FileUpload.Item>
+          <FileUpload.ItemRow>
+            <FileUpload.FormatBadge format="png" color="blue" />
+            <FileUpload.ItemMain>
+              <FileUpload.ItemName>Схема проезда.png</FileUpload.ItemName>
+              <FileUpload.ItemMeta>
+                <span>820 КБ</span>
+                <FileUpload.ItemMetaSep />
+                <span>Загружено</span>
+              </FileUpload.ItemMeta>
+            </FileUpload.ItemMain>
+            <FileUpload.ItemActions>
+              <Button.Root variant="ghost" tone="neutral" aria-label="Удалить файл">
+                <Button.Icon>
+                  <Icon name="action.close" />
+                </Button.Icon>
+              </Button.Root>
+            </FileUpload.ItemActions>
+          </FileUpload.ItemRow>
+        </FileUpload.Item>
+
+        <FileUpload.Item invalid>
+          <FileUpload.ItemRow>
+            <FileUpload.FormatBadge format="mp4" color="purple" />
+            <FileUpload.ItemMain>
+              <FileUpload.ItemStack>
+                <FileUpload.ItemTextGroup>
+                  <FileUpload.ItemName>Презентация.mp4</FileUpload.ItemName>
+                  <FileUpload.ItemMeta>Файл больше 20 МБ</FileUpload.ItemMeta>
+                </FileUpload.ItemTextGroup>
+                <FileUpload.ItemTryAgain>Попробовать снова</FileUpload.ItemTryAgain>
+              </FileUpload.ItemStack>
+            </FileUpload.ItemMain>
+          </FileUpload.ItemRow>
+        </FileUpload.Item>
+      </div>
+    </div>
+  );
+}

package/src/components/file-upload/examples/variants.tsx

@@ -0,0 +1,26 @@
+/** `variant="dashed"` (default) vs `"solid"`; the fill follows the surface context. Use `solid` inside cards and modals where the dashed line is too loud. */
+import { FileUpload, Icon } from "prime-ui-kit";
+import styles from "./examples.module.css";
+
+export default function FileUploadVariantsExample() {
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root variant="dashed" size="s">
+        <FileUpload.DropBody>
+          <FileUpload.Icon>
+            <Icon name="action.upload" size="s" tone="secondary" />
+          </FileUpload.Icon>
+          <FileUpload.Title>dashed — пунктир</FileUpload.Title>
+        </FileUpload.DropBody>
+      </FileUpload.Root>
+      <FileUpload.Root variant="solid" size="s">
+        <FileUpload.DropBody>
+          <FileUpload.Icon>
+            <Icon name="action.upload" size="s" tone="secondary" />
+          </FileUpload.Icon>
+          <FileUpload.Title>solid — только заливка</FileUpload.Title>
+        </FileUpload.DropBody>
+      </FileUpload.Root>
+    </div>
+  );
+}

package/src/components/hint/COMPONENT.md

@@ -1,111 +1,119 @@
 # Hint
 
-**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
+**Category:** inputs
 
-## Canonical
+> Help text or a validation error under a field.
 
-- **`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`**.
+## When to use
+- Under a control without `hint`/`error` props (DigitInput, ColorPicker, a custom control) or a hand-built field where you wire the ids yourself: format rules, limits, where the value comes from.
+- As the error message of such a field (`invalid`), in the same slot as the 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
+## When not to use
+- Input, Textarea, Checkbox and other fields with `hint` / `error` props → pass the props; they render Hint and link the ids ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md)).
+- The field name → use [Label](../label/COMPONENT.md).
+- A message about the whole page or form (success, warning) → use [Banner](../banner/COMPONENT.md) or a [Notification](../notification/COMPONENT.md).
+- An explanation on hover → use [Tooltip](../tooltip/COMPONENT.md).
 
+## Import
 ```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).
+## Anatomy
+```
+Hint.Root      <p> with the text
+└─ Hint.Icon   optional leading icon, centered on the first line (aria-hidden)
+```
 
 ## API
 
 ### Hint.Root
+No ref. + native `<p>` props (`id`, `role`, `className`, …).
 
-| 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.). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size of the paired field: xs/s/m 12/16 · l/xl 13/20. Also provided to nested icons via the control-size context. |
+| `invalid` | `boolean` | — | Error message styling: danger text. |
+| `disabled` | `boolean` | — | Disabled text color, next to a disabled control. |
+| `children` | `ReactNode` | — | Text, optionally with `Hint.Icon` first. |
+| `className` | `string` | — | Class on the `<p>`. |
 
 ### Hint.Icon
+No ref. + native `<span>` props. Always `aria-hidden`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | An icon; drawn at 14px for xs/s/m and 16px for l/xl, centered on the first line. |
+| `className` | `string` | — | Class on the `<span>`. |
+
+## Variants
+Hint has no `variant` or `tone`; its states are flags.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 12/16, muted | Under an `xs` field | |
+| `s` | 12/16, muted | Under an `s` field | |
+| `m` | 12/16, muted, icon 14 | Under an `m` field | yes |
+| `l` | 13/20, muted, icon 16 | Under an `l` field | |
+| `xl` | 13/20, muted, icon 16 | Under an `xl` field | |
+
+**Sizes:** the hint is always smaller than the field text; use the field's size.
+
+### State flags
+| Flag | Looks like | Use when | Default |
+|---|---|---|---|
+| — (none) | Muted text, caption tracking | Help, format, limits | yes |
+| `invalid` | Danger text | Validation error | — |
+| `disabled` | Disabled text | Under a disabled control | — |
+
+**Combinations**
+- Recommended: one element that switches between hint text and error text with `invalid` (no layout jump); `role="alert"` for errors shown after a user action.
+- Pointless: `invalid` and `disabled` together.
+- There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| error | `invalid` | `data-invalid="true"` |
+| disabled | `disabled` | `data-disabled="true"` |
+| size | `size` | `data-size` |
+
+Hint is not interactive: hover and focus belong to the field.
+
+## Layout & spacing
+- Field → hint: the tier `hint-gap` (`--prime-control-<size>-hint-gap` = `--prime-space-1`), set by the field layout, not by Hint.
+- Hint → icon gap: `--prime-space-1`. Long text wraps (`overflow-wrap: anywhere`).
+
+## Accessibility
+- Give the hint an `id` and put it into the control's `aria-describedby` so screen readers read it with the field.
+- Add `role="alert"` to an error that appears after a user action.
+- `Hint.Icon` is decorative; the text must carry the meaning.
+- Hint has no `labels`.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` | Matching the field size |
+| [states.tsx](examples/states.tsx) | Default, `invalid`, `disabled`, with `Hint.Icon` | Picking the message style |
+| [field-states.tsx](examples/field-states.tsx) | Label + Select + Hint with `aria-describedby` in default / error / disabled | Hand-built fields |
+| [hint-or-error.tsx](examples/hint-or-error.tsx) | Toggling `invalid` and text in the same element with `role="alert"` | Validation after an action |
+| [in-form.tsx](examples/in-form.tsx) | Password change form using the Input `hint` / `error` props | Fields that have hint props |
 
-| 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. |
+```tsx
+import { Hint } from "prime-ui-kit";
 
-## Related
+export function PhoneHint() {
+  return <Hint.Root id="phone-hint">Формат: +7 900 000-00-00</Hint.Root>;
+}
+```
 
-- [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.
+## Mistakes
+- `<Hint.Root>` under an Input → use `hint` / `error` on `Input.Root`; it links the ids itself.
+- A separate hint and error element at the same time → one element; the error replaces the hint.
+- Hint without `id` + `aria-describedby` → the screen reader does not connect it to the field.
+- Hint size different from the field size → use the same `size`.
+
+## Related
+- [Label](../label/COMPONENT.md) — the field name above.
+- [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [Select](../select/COMPONENT.md).