prime-ui-kit 0.7.13 → 0.9.1

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

@@ -0,0 +1,91 @@
+/* Layout of the FileUpload scenarios: semantic tokens only. */
+
+/* A form column: zone and file rows, row → row 8. */
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* in-form.tsx: header → field 32 → actions 32 (foundation §1). */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.formHeader {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+}
+
+.formActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}
+
+/* sizes.tsx: a zone and its file row of one tier, then the next tier. */
+.sizeRow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  margin-bottom: var(--prime-space-4);
+}
+
+/* custom-body.tsx: source buttons under the title. */
+.sources {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: var(--prime-space-2);
+}
+
+/* narrow.tsx: a phone-width column. */
+.narrow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  width: min(100%, calc(var(--prime-space-16) * 4));
+}
+
+/* avatar-upload.tsx */
+.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. */
+.avatarZone {
+  --file-upload-padding: var(--prime-space-1);
+  --file-upload-radius: var(--prime-radius-full);
+  flex-shrink: 0;
+  width: fit-content;
+}
+
+/* Text block → actions: 12; title → description: 4. */
+.avatarText {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  min-width: 0;
+}
+
+.avatarCopy {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+  min-width: 0;
+}
+
+.avatarActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}

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

@@ -0,0 +1,76 @@
+/** A contract upload form: the required scan is checked on submit and its error replaces the hint — `required`, `error`, `name`. */
+import { Button, FileUpload, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const HINT = "PDF до 20 МБ, все страницы";
+
+export default function FileUploadInFormExample() {
+  const [files, setFiles] = React.useState<File[]>([]);
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(files.length === 0 ? "Приложите скан договора" : undefined);
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <div className={styles.formHeader}>
+        <Typography as="h3" variant="title-m">
+          Договор поставки
+        </Typography>
+        <Typography as="p" variant="body-s" tone="secondary">
+          Подписанный скан нужен до первой отгрузки.
+        </Typography>
+      </div>
+      <div className={styles.column}>
+        <FileUpload.Root
+          label="Скан договора"
+          name="contract"
+          accept=".pdf"
+          required
+          hint={HINT}
+          error={error}
+          onFilesChange={(next) => {
+            setFiles(next);
+            setError(undefined);
+          }}
+        />
+        {files.map((file) => (
+          <FileUpload.Item key={file.name}>
+            <FileUpload.FormatBadge format="pdf" color="red" />
+            <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
+            <FileUpload.ItemActions>
+              <Button.Root
+                variant="ghost"
+                tone="neutral"
+                aria-label={`Удалить ${file.name}`}
+                onClick={() => setFiles([])}
+              >
+                <Button.Icon>
+                  <Icon name="action.close" />
+                </Button.Icon>
+              </Button.Root>
+            </FileUpload.ItemActions>
+          </FileUpload.Item>
+        ))}
+      </div>
+      <div className={styles.formActions}>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          type="reset"
+          onClick={() => {
+            setFiles([]);
+            setError(undefined);
+          }}
+        >
+          Отменить
+        </Button.Root>
+        <Button.Root type="submit">Отправить</Button.Root>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,17 @@
+/** In a phone-width column the zone text wraps and a long file name truncates. */
+import { FileUpload } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <FileUpload.Root label="Чек об оплате" size="s" />
+      <FileUpload.Item size="s">
+        <FileUpload.FormatBadge format="pdf" color="red" />
+        <FileUpload.ItemName>Кассовый чек от 12 марта, заказ 48210.pdf</FileUpload.ItemName>
+        <FileUpload.ItemDescription>180 КБ</FileUpload.ItemDescription>
+      </FileUpload.Item>
+    </div>
+  );
+}

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

@@ -0,0 +1,52 @@
+/** Attachments of a request: a labelled drop zone and the chosen files as rows with a remove button — `label`, `hint`, `multiple`, `onFilesChange`, `FileUpload.Item`. */
+import { Button, FileUpload, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const formatSize = (bytes: number) =>
+  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 FileUploadOverviewExample() {
+  const [files, setFiles] = React.useState<File[]>([]);
+
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root
+        label="Документы к заявке"
+        hint="PDF, PNG или JPG, можно несколько"
+        multiple
+        accept=".pdf,.png,.jpg,.jpeg"
+        onFilesChange={(next) =>
+          setFiles((current) => {
+            const known = new Set(current.map(fileKey));
+            return [...current, ...next.filter((file) => !known.has(fileKey(file)))];
+          })
+        }
+      />
+      {files.map((file) => (
+        <FileUpload.Item key={fileKey(file)}>
+          <FileUpload.FormatBadge format={file.name.split(".").pop() ?? "file"} />
+          <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
+          <FileUpload.ItemDescription>{formatSize(file.size)}</FileUpload.ItemDescription>
+          <FileUpload.ItemActions>
+            <Button.Root
+              variant="ghost"
+              tone="neutral"
+              aria-label={`Удалить ${file.name}`}
+              onClick={() => setFiles((current) => current.filter((item) => item !== file))}
+            >
+              <Button.Icon>
+                <Icon name="action.close" />
+              </Button.Icon>
+            </Button.Root>
+          </FileUpload.ItemActions>
+        </FileUpload.Item>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,27 @@
+/** Every size of the zone and of a file row: padding, icon, button and text follow the tier — `size`. */
+import { FileUpload } 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.column}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.sizeRow}>
+          <FileUpload.Root
+            size={size}
+            label={size}
+            labels={{ title: "Перетащите файл", description: "" }}
+          />
+          <FileUpload.Item size={size}>
+            <FileUpload.FormatBadge format="pdf" color="red" />
+            <FileUpload.ItemName>Договор поставки.pdf</FileUpload.ItemName>
+            <FileUpload.ItemDescription>240 КБ</FileUpload.ItemDescription>
+          </FileUpload.Item>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,14 @@
+/** A default zone, a disabled one and an invalid one without a message — `disabled`, `invalid`. */
+import { FileUpload } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadStatesExample() {
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root label="default" hint="PDF или PNG до 20 МБ" />
+      <FileUpload.Root label="disabled" disabled hint="Станет доступно после выбора заказа" />
+      <FileUpload.Root label="invalid" invalid hint="PDF или PNG до 20 МБ" />
+    </div>
+  );
+}

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

@@ -0,0 +1,39 @@
+/** File rows while uploading, uploaded and failed with a retry — `FileUpload.ItemProgress`, `invalid`, `FileUpload.ItemActions`. */
+import { Button, FileUpload, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadUploadProgressExample() {
+  return (
+    <div className={styles.column}>
+      <FileUpload.Item>
+        <FileUpload.FormatBadge format="pdf" color="red" />
+        <FileUpload.ItemName>Отчёт за квартал.pdf</FileUpload.ItemName>
+        <FileUpload.ItemDescription>1,2 МБ из 3 МБ · загрузка 40%</FileUpload.ItemDescription>
+        <FileUpload.ItemProgress value={40} aria-label="Загрузка: Отчёт за квартал.pdf" />
+      </FileUpload.Item>
+      <FileUpload.Item>
+        <FileUpload.FormatBadge format="png" color="blue" />
+        <FileUpload.ItemName>Схема проезда.png</FileUpload.ItemName>
+        <FileUpload.ItemDescription>820 КБ · загружено</FileUpload.ItemDescription>
+        <FileUpload.ItemActions>
+          <Button.Root variant="ghost" tone="neutral" aria-label="Удалить Схема проезда.png">
+            <Button.Icon>
+              <Icon name="action.close" />
+            </Button.Icon>
+          </Button.Root>
+        </FileUpload.ItemActions>
+      </FileUpload.Item>
+      <FileUpload.Item invalid>
+        <FileUpload.FormatBadge format="mp4" color="purple" />
+        <FileUpload.ItemName>Презентация продукта.mp4</FileUpload.ItemName>
+        <FileUpload.ItemDescription>Файл больше 20 МБ</FileUpload.ItemDescription>
+        <FileUpload.ItemActions>
+          <Button.Root variant="soft" tone="danger" size="s">
+            Повторить
+          </Button.Root>
+        </FileUpload.ItemActions>
+      </FileUpload.Item>
+    </div>
+  );
+}

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

@@ -0,0 +1,19 @@
+/** A required zone with a hint, a rejected file whose error replaces the hint and an optional zone — `required`, `hint`, `error`, `optional`. */
+import { FileUpload } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadValidationExample() {
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root label="Скан договора" required hint="PDF до 20 МБ, все страницы" />
+      <FileUpload.Root
+        label="Счёт на оплату"
+        required
+        error="Файл не подошёл: нужен PDF до 20 МБ"
+        labels={{ title: "Выберите другой файл" }}
+      />
+      <FileUpload.Root label="Доверенность" optional hint="Если подписывает не директор" />
+    </div>
+  );
+}

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

@@ -0,0 +1,13 @@
+/** The dashed drop line next to a zone with only the fill, for cards and modals — `variant`. */
+import { FileUpload } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function FileUploadVariantsExample() {
+  return (
+    <div className={styles.column}>
+      <FileUpload.Root label="dashed" variant="dashed" />
+      <FileUpload.Root label="solid" variant="solid" />
+    </div>
+  );
+}

package/src/components/hint/COMPONENT.md

@@ -1,111 +1,113 @@
 # Hint
 
-**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
+**Category:** inputs
+**Kind:** primitive
 
-## 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 (SegmentedControl, Slider, a custom control) where you wire the ids yourself: format rules, limits, where the value comes from.
+- As the error message of such a control (`invalid`), in the same slot as the hint.
 
-## Extended
+## When not to use
+- Input, Textarea, Select, 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).
 
-### About
+## Import
+```tsx
+import { Hint } from "prime-ui-kit";
+```
 
-`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.
+## Anatomy
+```
+Hint.Root      <p> with the text
+└─ Hint.Icon   optional leading icon, centred on the first line (aria-hidden)
+```
 
-- **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.
+## API
 
-### Composition
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-- **`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.
+### Hint.Root
+`ref` → `HTMLParagraphElement`. A `<p>` with the support text; provides its tier to nested icons. + native `<p>` props (`id`, `role`, `className`, …).
 
-### Examples (source)
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the paired field: 12/16 for xs–m, 13/20 for l and xl. |
+| `invalid` | `boolean` | `false` | Error styling: danger text that drops in (fade + 4 px from above). |
+| `disabled` | `boolean` | `false` | Disabled text color, next to a disabled control. |
+| `children` | `ReactNode` | — | Text, optionally with `Hint.Icon` first. |
 
-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.
+### Hint.Icon
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` holding a glyph: 14 px for xs–m, 16 px for l and xl, centred on the first line. + native `<span>` props.
 
-| 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 |
+## Variants
+Hint has no `variant` or `tone`; its states are flags.
 
-### More examples (**Input**-centric)
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 12/16, muted, icon 14 | Under an `xs` field | |
+| `s` | 12/16, muted, icon 14 | 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 | |
 
-| 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 |
+The hint is always smaller than the field text; use the field's size.
 
-### Minimal example
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `invalid` | Danger text, drops in | Validation error | `false` |
+| `disabled` | Disabled text | Under a disabled control | `false` |
 
-```tsx
-import { Hint } from "prime-ui-kit";
+**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); add `role="alert"` to an error shown after a user action. `invalid` and `disabled` together make no sense. There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
 
-export function FieldHint() {
-  return <Hint.Root>The invitation will be valid for 7 days.</Hint.Root>;
-}
-```
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| error | `invalid` | `data-invalid="true"`; the message drops in over `fast` (fade + `--prime-space-1` from above, no shake, no layout shift) and the color eases from the hint color |
+| disabled | `disabled` | `data-disabled="true"` |
+| size | `size` | `data-size` |
 
-### Rules
+Hint is not interactive: hover and focus belong to the field.
 
-- **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).
+## Layout & spacing
+- Field → hint: the tier `hint-gap` (`--prime-control-<size>-hint-gap`), set by the field layout, not by Hint.
+- Icon → text gap: `--prime-space-1`. Long text wraps (`overflow-wrap: anywhere`).
 
-## API
+## Accessibility
 
-### Hint.Root
+### Keyboard
+No keyboard interaction.
 
-| 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.). |
+### ARIA
+- 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 carries the meaning.
 
-### Hint.Icon
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| 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. |
+No `labels`.
 
-## Related
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Help text under a control without its own `hint` prop, linked to it by `id` and `aria-describedby`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier, matching the field above: 12/16 for xs–m, 13/20 for l and xl — `size`. |
+| [states.tsx](examples/states.tsx) | Default help text next to an error and a hint under a disabled control — `invalid`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A leading icon centred on the first line, in the default and the error state — `Hint.Icon`. |
+| [hint-or-error.tsx](examples/hint-or-error.tsx) | After a check the error replaces the hint in the same element, without a layout jump, and is announced — `invalid`, `role`. |
 
-- [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
+- **Built from:** —
+- **See also:** [Label](../label/COMPONENT.md), [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -0,0 +1,14 @@
+/* Layout of the Hint scenarios: semantic tokens only. */
+
+/* overview.tsx, hint-or-error.tsx: label → control → support row with the m-tier gaps. */
+.field {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-control-m-hint-gap);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}

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

@@ -0,0 +1,27 @@
+/** After a check the error replaces the hint in the same element, without a layout jump, and is announced — `invalid`, `role`. */
+import { Button, Hint } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function HintHintOrErrorExample() {
+  const [invalid, setInvalid] = React.useState(false);
+
+  return (
+    <div className={styles.field}>
+      <div className={styles.actions}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setInvalid(true)}>
+          Опубликовать
+        </Button.Root>
+        <Button.Root variant="ghost" tone="neutral" onClick={() => setInvalid(false)}>
+          Сбросить
+        </Button.Root>
+      </div>
+      <Hint.Root invalid={invalid} role={invalid ? "alert" : undefined}>
+        {invalid
+          ? "Заполните название перед публикацией."
+          : "Черновик можно сохранить без названия."}
+      </Hint.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,34 @@
+/** Help text under a control without its own `hint` prop, linked to it by `id` and `aria-describedby`. */
+import { Hint, Label, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PERIODS = [
+  { value: "day", label: "День" },
+  { value: "week", label: "Неделя" },
+  { value: "month", label: "Месяц" },
+];
+
+export default function HintOverviewExample() {
+  const labelId = React.useId();
+  const hintId = React.useId();
+
+  return (
+    <div className={styles.field}>
+      <Label.Root id={labelId}>Период отчёта</Label.Root>
+      <SegmentedControl.Root
+        defaultValue="week"
+        aria-labelledby={labelId}
+        aria-describedby={hintId}
+      >
+        {PERIODS.map((period) => (
+          <SegmentedControl.Item key={period.value} value={period.value}>
+            {period.label}
+          </SegmentedControl.Item>
+        ))}
+      </SegmentedControl.Root>
+      <Hint.Root id={hintId}>Отчёт пересчитывается каждую ночь в 03:00 по Москве.</Hint.Root>
+    </div>
+  );
+}