prime-ui-kit 0.7.11 → 0.9.0

package/src/components/popover/examples/features.tsx

@@ -1,57 +1,55 @@
-import { Button, Input, Popover, Select, Typography } from "prime-ui-kit";
+/** Invite form in a popover: `trapFocus`, a nested Select whose list is not an outside click, submit closes the panel. Use for short forms anchored to a button. */
+import { Button, Input, Label, Popover, Select } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./popover-examples.module.css";
+import preview from "./examples.module.css";
 
-/**
- * `trapFocus` with `Input` and nested `Select`: portaled listbox clicks are not treated as outside close.
- */
 export default function PopoverFeaturesExample() {
+  const roleId = React.useId();
   const [open, setOpen] = React.useState(false);
-  const [name, setName] = React.useState("");
 
   return (
     <Popover.Root open={open} onOpenChange={setOpen}>
-      <Popover.Trigger asChild>
-        <Button.Root className={styles.triggerWide} mode="stroke" variant="neutral">
-          Access request
-        </Button.Root>
+      <Popover.Trigger>
+        <Button.Root>Пригласить</Button.Root>
       </Popover.Trigger>
-      <Popover.Content align="start" className={styles.formPanel} sameMinWidthAsTrigger trapFocus>
-        <Typography.Root as="p" variant="body-small" weight="medium">
-          Short form
-        </Typography.Root>
-        <Typography.Root as="p" className={styles.panelTextMuted} variant="body-small">
-          <code>trapFocus</code> keeps Tab inside the panel; opening the Select listbox does not
-          count as an outside click, so the popover stays open.
-        </Typography.Root>
-        <Input.Root label="Comment">
-          <Input.Wrapper>
-            <Input.Field
-              placeholder="Why access is needed"
-              value={name}
-              onChange={(e) => setName(e.target.value)}
-            />
-          </Input.Wrapper>
-        </Input.Root>
-        <Select.Root placeholder="Role">
-          <Select.Trigger>
-            <Select.Value />
-          </Select.Trigger>
-          <Select.Content>
-            <Select.Item value="viewer">Viewer</Select.Item>
-            <Select.Item value="editor">Editor</Select.Item>
-            <Select.Item value="admin">Admin</Select.Item>
-          </Select.Content>
-        </Select.Root>
-        <div className={styles.actionsRow}>
-          <Button.Root mode="ghost" variant="neutral" onClick={() => setOpen(false)}>
-            Cancel
-          </Button.Root>
-          <Button.Root mode="filled" variant="primary" onClick={() => setOpen(false)}>
-            Submit
-          </Button.Root>
-        </div>
+      <Popover.Content className={preview.panelWidth} trapFocus>
+        <Popover.Header>
+          <Popover.Title>Пригласить в проект</Popover.Title>
+          <Popover.Description>Приглашение придёт на почту.</Popover.Description>
+        </Popover.Header>
+        <form
+          className={preview.stack}
+          onSubmit={(event) => {
+            event.preventDefault();
+            setOpen(false);
+          }}
+        >
+          <Input.Root label="Почта" required>
+            <Input.Wrapper>
+              <Input.Field type="email" placeholder="name@company.ru" />
+            </Input.Wrapper>
+          </Input.Root>
+          <div className={preview.field}>
+            <Label.Root id={roleId}>Роль</Label.Root>
+            <Select.Root defaultValue="editor">
+              <Select.Trigger aria-labelledby={roleId}>
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                <Select.Item value="viewer">Наблюдатель</Select.Item>
+                <Select.Item value="editor">Редактор</Select.Item>
+                <Select.Item value="admin">Администратор</Select.Item>
+              </Select.Content>
+            </Select.Root>
+          </div>
+          <Popover.Actions>
+            <Button.Root variant="ghost" tone="neutral" onClick={() => setOpen(false)}>
+              Отмена
+            </Button.Root>
+            <Button.Root type="submit">Отправить</Button.Root>
+          </Popover.Actions>
+        </form>
       </Popover.Content>
     </Popover.Root>
   );

package/src/components/popover/examples/full-width.tsx

@@ -1,25 +1,21 @@
-import { Button, Popover } from "prime-ui-kit";
+/** `sameMinWidthAsTrigger`: the panel takes the width of a full-width trigger and the text wraps. Use in narrow columns and sidebars. */
+import { Button, Popover, Typography } from "prime-ui-kit";
 
-import styles from "./popover-examples.module.css";
+import preview from "./examples.module.css";
 
-/**
- * `sameMinWidthAsTrigger`: panel width matches the trigger (`border-box`), useful in narrow columns.
- */
 export default function PopoverFullWidthExample() {
   return (
-    <div className={styles.narrowColumn}>
+    <div className={preview.narrowColumn}>
       <Popover.Root>
-        <Popover.Trigger asChild>
-          <Button.Root className={styles.fullWidthTrigger} mode="stroke" variant="neutral">
-            Match trigger width
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral" fullWidth>
+            Условия тарифа
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content align="start" sameMinWidthAsTrigger side="bottom">
-          <p className={styles.panelTextMuted}>
-            <code>sameMinWidthAsTrigger</code> sets panel <code>width</code> and{" "}
-            <code>minWidth</code> to the anchor — text wraps, still capped by panel max width and
-            the viewport.
-          </p>
+        <Popover.Content sameMinWidthAsTrigger>
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            До 10 пользователей, 50 ГБ хранилища и приоритетная поддержка.
+          </Typography.Root>
         </Popover.Content>
       </Popover.Root>
     </div>

package/src/components/popover/examples/inset-variants.tsx

@@ -1,44 +1,56 @@
-import { Button, Popover } from "prime-ui-kit";
+/** Panel density via `insetPadding` and `insetGap`: default, extra air and no gap. Use none/extra values only for custom layouts inside the panel. */
+import { Button, Popover, Typography } from "prime-ui-kit";
 
-import styles from "./popover-examples.module.css";
+import preview from "./examples.module.css";
 
-/**
- * `insetPadding` and `insetGap` on `Popover.Content`, including `none` for a flush layout.
- */
 export default function PopoverInsetVariantsExample() {
   return (
-    <div className={styles.sizesRow}>
+    <div className={preview.row}>
       <Popover.Root>
-        <Popover.Trigger asChild>
-          <Button.Root mode="stroke" variant="neutral">
-            padding: none
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            По умолчанию
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content insetGap="none" insetPadding="none">
-          <p className={styles.flushText}>Content flush to the panel radius.</p>
+        <Popover.Content>
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            Отступ панели по ярусу m — 16 px.
+          </Typography.Root>
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            Зазор между блоками — 12 px.
+          </Typography.Root>
         </Popover.Content>
       </Popover.Root>
 
       <Popover.Root>
-        <Popover.Trigger asChild>
-          <Button.Root mode="stroke" variant="neutral">
-            padding: x2
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            insetPadding=&quot;x3&quot;
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content insetGap="x2" insetPadding="x2">
-          <p className={styles.panelTextMuted}>Typical inset defaults for inner spacing.</p>
+        <Popover.Content insetPadding="x3" insetGap="x4">
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            Больше воздуха вокруг содержимого.
+          </Typography.Root>
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            И между абзацами (insetGap x4).
+          </Typography.Root>
         </Popover.Content>
       </Popover.Root>
 
       <Popover.Root>
-        <Popover.Trigger asChild>
-          <Button.Root mode="stroke" variant="neutral">
-            padding: x3
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            insetGap=&quot;none&quot;
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content insetGap="x4" insetPadding="x3">
-          <p className={styles.panelTextMuted}>More air between blocks (gap x4).</p>
-          <p className={styles.panelTextMuted}>Second paragraph shows vertical rhythm.</p>
+        <Popover.Content insetGap="none">
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            Строки идут вплотную —
+          </Typography.Root>
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            удобно для собственной разметки.
+          </Typography.Root>
         </Popover.Content>
       </Popover.Root>
     </div>

package/src/components/popover/examples/placement.tsx

@@ -1,33 +1,28 @@
+/** `side` (bottom · top) and `align` (start · center · end). Near the viewport edge the panel flips and shifts automatically. */
 import { Button, Popover, Typography } from "prime-ui-kit";
 
-import styles from "./popover-examples.module.css";
+import preview from "./examples.module.css";
 
-type Demo = { label: string; side: "top" | "bottom"; align: "start" | "center" | "end" };
+const PLACEMENTS = [
+  { label: "Снизу · начало", side: "bottom", align: "start" },
+  { label: "Снизу · центр", side: "bottom", align: "center" },
+  { label: "Снизу · конец", side: "bottom", align: "end" },
+  { label: "Сверху · начало", side: "top", align: "start" },
+] as const;
 
-const demos: Demo[] = [
-  { label: "Bottom · start", side: "bottom", align: "start" },
-  { label: "Bottom · center", side: "bottom", align: "center" },
-  { label: "Bottom · end", side: "bottom", align: "end" },
-  { label: "Top · start", side: "top", align: "start" },
-];
-
-/**
- * Preferred `side` and `align`; the kit may flip at the viewport edge.
- */
-export default function PlacementExample() {
+export default function PopoverPlacementExample() {
   return (
-    <div className={styles.placementGrid}>
-      {demos.map(({ label, side, align }) => (
+    <div className={preview.row}>
+      {PLACEMENTS.map(({ label, side, align }) => (
         <Popover.Root key={label}>
-          <Popover.Trigger asChild>
-            <Button.Root className={styles.placementTrigger} mode="stroke" variant="neutral">
+          <Popover.Trigger>
+            <Button.Root variant="soft" tone="neutral">
               {label}
             </Button.Root>
           </Popover.Trigger>
-          <Popover.Content align={align} side={side}>
-            <Typography.Root as="p" variant="body-small">
-              <code>side=&quot;{side}&quot;</code>, <code>align=&quot;{align}&quot;</code>. Near the
-              viewport edge the panel may flip to stay on screen.
+          <Popover.Content side={side} align={align}>
+            <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+              side=&quot;{side}&quot;, align=&quot;{align}&quot;
             </Typography.Root>
           </Popover.Content>
         </Popover.Root>

package/src/components/popover/examples/sizes.tsx

@@ -1,27 +1,30 @@
+/** Popover.Content at every size tier xs → xl with a header and actions. Give the panel the same size as its trigger. */
 import { Button, Popover } from "prime-ui-kit";
+import preview from "./examples.module.css";
 
-import styles from "./popover-examples.module.css";
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-const sizes = ["s", "m", "l", "xl"] as const;
-
-/**
- * Content `size` tier: panel padding, type scale, and `ControlSizeProvider` for nested controls.
- */
 export default function PopoverSizesExample() {
   return (
-    <div className={styles.sizesRow}>
-      {sizes.map((size) => (
+    <div className={preview.row}>
+      {SIZES.map((size) => (
         <Popover.Root key={size}>
-          <Popover.Trigger asChild>
-            <Button.Root mode="stroke" variant="neutral">
-              Size {size}
+          <Popover.Trigger>
+            <Button.Root variant="soft" tone="neutral" size={size}>
+              Размер {size}
             </Button.Root>
           </Popover.Trigger>
-          <Popover.Content align="start" side="bottom" size={size}>
-            <p className={styles.panelTextMuted}>
-              Panel with <code>size=&quot;{size}&quot;</code>: padding and type scale from the
-              control tier; nested controls use <code>ControlSizeProvider</code>.
-            </p>
+          <Popover.Content size={size}>
+            <Popover.Header>
+              <Popover.Title>Сохранить фильтр?</Popover.Title>
+              <Popover.Description>Он появится в списке слева.</Popover.Description>
+            </Popover.Header>
+            <Popover.Actions>
+              <Button.Root variant="ghost" tone="neutral" size={size}>
+                Отмена
+              </Button.Root>
+              <Button.Root size={size}>Сохранить</Button.Root>
+            </Popover.Actions>
           </Popover.Content>
         </Popover.Root>
       ))}

package/src/components/popover/examples/states.tsx

@@ -1,34 +1,46 @@
-import { Button, Popover } from "prime-ui-kit";
+/** A destructive confirm with Header, Title, Description and Actions, and a disabled trigger that never opens the panel. Use for lightweight confirmations next to the action. */
+import { Button, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
 
-import styles from "./popover-examples.module.css";
+import preview from "./examples.module.css";
 
-/**
- * `defaultOpen` for initially visible panel; disabled trigger does not open the popover.
- */
 export default function PopoverStatesExample() {
+  const [open, setOpen] = React.useState(false);
+
   return (
-    <div className={styles.sizesRow}>
-      <Popover.Root defaultOpen>
-        <Popover.Trigger asChild>
-          <Button.Root mode="stroke" variant="neutral">
-            Starts open
+    <div className={preview.row}>
+      <Popover.Root open={open} onOpenChange={setOpen}>
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="danger">
+            Удалить комментарий
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content align="start" side="bottom">
-          <p className={styles.panelTextMuted}>
-            <code>defaultOpen</code> on the root — initial open state without lifting state up.
-          </p>
+        <Popover.Content className={preview.panelWidth}>
+          <Popover.Header>
+            <Popover.Title>Удалить комментарий?</Popover.Title>
+            <Popover.Description>Его нельзя будет восстановить.</Popover.Description>
+          </Popover.Header>
+          <Popover.Actions>
+            <Button.Root variant="ghost" tone="neutral" onClick={() => setOpen(false)}>
+              Отмена
+            </Button.Root>
+            <Button.Root tone="danger" onClick={() => setOpen(false)}>
+              Удалить
+            </Button.Root>
+          </Popover.Actions>
         </Popover.Content>
       </Popover.Root>
 
       <Popover.Root>
-        <Popover.Trigger asChild>
-          <Button.Root disabled mode="stroke" variant="neutral">
-            Trigger disabled
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral" disabled>
+            Недоступно
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content align="start" side="bottom">
-          <p className={styles.panelTextMuted}>Panel never opens while the button is disabled.</p>
+        <Popover.Content>
+          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+            Не откроется: триггер отключён.
+          </Typography.Root>
         </Popover.Content>
       </Popover.Root>
     </div>

package/src/components/progress-bar/COMPONENT.md

@@ -1,101 +1,110 @@
 # ProgressBar
 
-**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
+**Category:** feedback
 
-## Canonical
+> Linear progress indicator on a native `<progress>` with a label, a percentage and a status color.
 
-- **`ProgressBar`** — horizontal determinate meter: only **`ProgressBar.Root`** is public; it wraps a native **`<progress>`** (role **`progressbar`**) and optional **`label`**.
-- **`value`** is **required** and clamped to **`[0, max]`**; **`max`** defaults to **`100`** (if **`max <= 0`**, **`100`** is used).
-- **`size`:** **`s` | `m` | `l` | `xl`** — track height and label scale (**`ProgressBarSize`**).
-- **Not indeterminate:** the API does not omit **`value`** or set an indeterminate native state — for unknown duration, use loading patterns on controls (for example [Button](../button/COMPONENT.md) **`loading`** + **`Button.Spinner`**) or other kit feedback; see **`examples/indeterminate-busy-state.tsx`**.
-- **A11y:** with **`label`**, **`aria-labelledby`** references the label **`span`**; the bar is not focusable.
-- **No `disabled` / `loading` / `error`** on the root — hide or mute the block at screen level if needed.
+## When to use
+- Determinate progress of an operation: file upload, import, export.
+- How much of a quota or a set of steps is done ("Профиль: 3 из 5 шагов").
+- Per-row progress inside lists (FileUpload rows use it through `FileUpload.ItemProgress`).
 
-## Extended
-
-### About
-
-`ProgressBar` is a horizontal completion indicator for operations that map to a numeric range: file transfer, form steps, or any bounded task.
-
-- **When to use** — uploads, downloads, or sync where you can compute **`value`** and **`max`**.
-- **When to use** — multi-step flows where “step *k* of *n*” should match a single fill (**`value={k}`**, **`max={n}`**).
-- **When to use** — when a short visible name should be tied to the meter for sighted users and assistive tech (**`label`**).
-- **When not to use** — indeterminate or endless busy states without a numeric model; prefer **`Button`** **`loading`**, spinners, or other patterns.
-- **When not to use** — vertical or circular meters; for a ring indicator see [ProgressCircle](../progress-circle/COMPONENT.md).
-- **When not to use** — when you need extra native attributes on **`<progress>`** beyond what the wrapper sets; they are not forwarded — compose or wrap at the app layer if required.
-
-### Composition
-
-- **`ProgressBar.Root`** — outer **`div`** with **`data-size`**, optional **`label`** (**`<span>`** + generated **`id`**), then **`<progress>`** with **`value`**, **`max`**, and **`className`** on the track. Width follows the parent (full width of the container).
-
-### Playground (`playground/sections/ProgressBarSection.tsx`)
-
-The section renders snippets from **`playground/snippets/progress/`** (bar demos only):
-
-| Demo (section) | Snippet | What it shows |
-|----------------|---------|----------------|
-| Размеры | [`bar-sizes.tsx`](../../../playground/snippets/progress/bar-sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`**, each with a **`label`** (track height and label scale from control-size tokens). |
-| Values | [`bar-values.tsx`](../../../playground/snippets/progress/bar-values.tsx) | **`value`** **`0`**, **`25`**, **`75`**, **`100`** without **`label`**. |
-| With label | [`bar-label.tsx`](../../../playground/snippets/progress/bar-label.tsx) | **`value={60}`**, **`label="Profile completion"`** (same English copy as the snippet; section preview matches this structure). |
-
-Other bar-only snippets in the same folder (**`bar-full-width`**, **`bar-states`**, **`bar-controlled`**, **`bar-composition`**) are not mounted in **`ProgressBarSection`**; they follow the same **`@/components/progress-bar`** import style for local dev.
-
-### Example files in `examples/`
-
-Imports use **`"prime-ui-kit"`** so the same patterns work in an app. **`sizes`**, **`values`**, and **`labeled`** mirror the three playground frames above (same structure; English labels in **`sizes`** where the snippet uses Russian).
-
-| File | Scenario |
-|------|----------|
-| [`sizes.tsx`](examples/sizes.tsx) | **`size`** ladder **`s`–`xl`** with labels (`snippets/progress/bar-sizes.tsx`). |
-| [`values.tsx`](examples/values.tsx) | **`value`** 0 / 25 / 75 / 100, no **`label`** (`snippets/progress/bar-values.tsx`). |
-| [`labeled.tsx`](examples/labeled.tsx) | **`label`** + **`aria-labelledby`** wiring (`snippets/progress/bar-label.tsx`). |
-| [`upload-progress.tsx`](examples/upload-progress.tsx) | Controlled **`value`** from progress percent; filename and actions in surrounding copy. |
-| [`step-progress.tsx`](examples/step-progress.tsx) | **`value`** / **`max`** as step *k* of *n*. |
-| [`indeterminate-busy-state.tsx`](examples/indeterminate-busy-state.tsx) | Unknown duration: **`Button`** **`loading`**, not an indeterminate **`ProgressBar`**. |
-| [`wizard-composition.tsx`](examples/wizard-composition.tsx) | **Typography** + bar + muted helper (aligned with **`bar-composition.tsx`** idea; app-ready English). |
-
-### Minimal example
+## When not to use
+- Progress made of several parts or a distribution of shares → use [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md).
+- A compact radial indicator or a KPI ring → use [ProgressCircle](../progress-circle/COMPONENT.md).
+- Unknown duration (no value) → use a spinner, e.g. `Button` `loading`; ProgressBar has no indeterminate mode.
+- Navigation through wizard steps → use [Stepper](../stepper/COMPONENT.md).
 
+## Import
 ```tsx
 import { ProgressBar } from "prime-ui-kit";
-
-export function Example() {
-  return <ProgressBar.Root value={40} max={100} />;
-}
 ```
 
-### Rules
-
-- **Controlled usage** — pass React state into **`value`**; there is no internal uncontrolled store.
-- **Refs** — **`ref`** targets the native **`<progress>`** element.
-- **Clamping** — negative **`value`** becomes **`0`**; **`value > max`** becomes **`max`**.
-
 ## API
 
 ### ProgressBar.Root
+Leaf component. `forwardRef` to the inner `HTMLProgressElement`. No native props passthrough.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — (required) | Current value; clamped to `0…max`. |
+| `max` | `number` | `100` | Top of the scale; a value `<= 0` falls back to `100`. |
+| `label` | `string` | — | Visible label above the track and the accessible name of the `<progress>` (`aria-labelledby`). |
+| `showValue` | `boolean` | `false` | Shows the rounded percentage at the right of the header (`tabular-nums`, `aria-hidden`). |
+| `tone` | `"accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Fill color. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Track height and label typography. |
+| `className` | `string` | — | Class on the root `<div>`. |
+
+## Variants
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `accent` | Accent fill on a `fill-strong` track | Progress in flight | yes |
+| `success` | Success fill | Finished operations, healthy quota | |
+| `warning` | Warning fill | Quota almost used, slow progress | |
+| `danger` | Danger fill | Failed or interrupted operation | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | Track 4px, label 12/16, header gap 4 | Dense tables, inline rows | |
+| `s` | Track 4px, label 12/16, header gap 4 | Compact lists | |
+| `m` | Track 4px, label 13/20, header gap 8 | Default | yes |
+| `l` | Track 8px, label 14/20, header gap 8 | Prominent single progress | |
+| `xl` | Track 8px, label 14/20, header gap 8 | Hero / onboarding progress | |
+
+### showValue
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` | Label only (or no header) | The exact number does not matter | yes |
+| `true` | Secondary `NN%` at the right of the header | Uploads, quotas where the user tracks the number | |
+
+**Combinations**
+- Recommended: `accent` while running, then switch to `success` or `danger` with the result; `label` + `showValue` for uploads.
+- Pointless: `showValue` with `max` meant as a count ("3 из 5") — put the count into `label` as in the example.
+- Avoid: `danger` for normal high values — use it for failures only.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| tone / size | props | `data-tone`, `data-size` on the root |
+| value | `value`, `max` | native `value` / `max` on `<progress>`; the fill width animates (none under `prefers-reduced-motion`) |
+
+Always controlled: pass the current `value` on every render.
+
+## Layout & spacing
+- `width: 100%` of the parent; the header is a row with the label (ellipsis) and the value.
+- Label → track: `--prime-space-1` (xs/s) or `--prime-space-2` (m–xl).
+- Stack several bars with `--prime-space-4`–`--prime-space-5`.
+
+## Accessibility
+- Native `<progress>`: role `progressbar` with value and max for screen readers.
+- Give every bar a `label`: there is no `aria-label` prop, so a bar without `label` has no accessible name.
+- The percentage text is `aria-hidden` (the native value is announced instead).
+- ProgressBar has no `labels`.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [file-upload.tsx](examples/file-upload.tsx) | Live uploads in a card: growing progress, `success` when done, `danger` on failure | Per-item progress of background operations |
+| [values-and-tones.tsx](examples/values-and-tones.tsx) | 0 / partial / 100, `success` / `warning` / `danger`, `max={5}` | Showing outcome and custom scales |
+| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` with `label` and `showValue` | Picking a size |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `value` | `number` | — | Yes | Current value; clamped to `[0, max]` after `max` is normalized. |
-| `max` | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used. |
-| `label` | `string` | — | No | Text above the track; `aria-labelledby` references this element when set. |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height and label typography scale. |
-| `className` | `string` | — | No | Class on the outer wrapper around the label and `progress`. |
-| `ref` | `React.Ref<HTMLProgressElement>` | — | No | Ref to the native `progress` element. |
-
-## Related
+```tsx
+import { ProgressBar } from "prime-ui-kit";
 
-- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple proportional segments instead of one value.
-- [ProgressCircle](../progress-circle/COMPONENT.md) — circular determinate indicator.
-- [Typography](../typography/COMPONENT.md) — headings and supporting copy around a status block.
-- [Button](../button/COMPONENT.md) — cancel, pause, or **`loading`** next to long-running work.
+export function ImportProgress() {
+  return <ProgressBar.Root value={42} label="Импорт контактов" showValue />;
+}
+```
 
-## LLM note
+## Mistakes
+- No `label` → the progress has no accessible name; add `label`.
+- `tone="info"` / `tone="neutral"` → not supported; use `accent`.
+- Values over `max` expecting overflow → they are clamped.
+- Using it as a spinner with a fake value → use a loading state instead.
 
-- Export: **`import { ProgressBar } from "prime-ui-kit"`** — **`ProgressBar.Root`** only.
-- **`ProgressBarRootProps`**: **`value`** (required), **`max?`**, **`label?`**, **`size?`**, **`className?`**, **`ref?`** — no `disabled`, `loading`, or indeterminate flag.
-- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
-- **`value`** is always required; do not suggest omitting **`value`** for a “loading” bar — use **Button** **`loading`** / **`Button.Spinner`** or another pattern.
-- Native **`<progress>`** is not a props bag: extra attributes are **not** forwarded from **`ProgressBar.Root`**.
-- Step flows: **`value={currentStep}`**, **`max={totalSteps}`** (not necessarily 0–100).
-- Playground bar frames: **`playground/sections/ProgressBarSection.tsx`** uses **`bar-sizes`**, **`bar-values`**, **`bar-label`**; **`examples/sizes`**, **`examples/values`**, **`examples/labeled`** mirror those three for **`prime-ui-kit`** consumers.
+## Related
+- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md) — other progress forms.
+- [FileUpload](../file-upload/COMPONENT.md) — `FileUpload.ItemProgress` renders a ProgressBar.

package/src/components/progress-bar/examples/examples.module.css

@@ -0,0 +1,40 @@
+/* Layout helpers for the ProgressBar examples. Semantic tokens only. */
+
+/* 28rem column of bars. */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, calc(var(--prime-space-24) * 4 + var(--prime-space-16)));
+  min-width: 0;
+}
+
+.card {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 4 + var(--prime-space-16)));
+  padding: var(--prime-card-padding-m);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-card-bg);
+  box-shadow: var(--prime-card-shadow);
+}
+
+.cardHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+}
+
+.file {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+  min-width: 0;
+}
+
+.meta {
+  font-variant-numeric: tabular-nums;
+}