prime-ui-kit 0.0.1

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

@@ -0,0 +1,46 @@
+import { Button, Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * `insetPadding` and `insetGap` on `Popover.Content`, including `none` for a flush layout.
+ */
+export default function PopoverInsetVariantsExample() {
+  return (
+    <div className={styles.sizesRow}>
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" variant="neutral">
+            padding: none
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content insetGap="none" insetPadding="none">
+          <p className={styles.flushText}>Content flush to the panel radius.</p>
+        </Popover.Content>
+      </Popover.Root>
+
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" variant="neutral">
+            padding: x2
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content insetGap="x2" insetPadding="x2">
+          <p className={styles.panelTextMuted}>Typical inset defaults for inner spacing.</p>
+        </Popover.Content>
+      </Popover.Root>
+
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" variant="neutral">
+            padding: x3
+          </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>
+      </Popover.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,37 @@
+import { Button, Popover, Typography } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+type Demo = { label: string; side: "top" | "bottom"; align: "start" | "center" | "end" };
+
+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() {
+  return (
+    <div className={styles.placementGrid}>
+      {demos.map(({ label, side, align }) => (
+        <Popover.Root key={label}>
+          <Popover.Trigger asChild>
+            <Button.Root className={styles.placementTrigger} mode="stroke" variant="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.
+            </Typography.Root>
+          </Popover.Content>
+        </Popover.Root>
+      ))}
+    </div>
+  );
+}

package/src/components/popover/examples/popover-examples.module.css

@@ -0,0 +1,104 @@
+.sizesRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.placementGrid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.placementTrigger {
+  min-width: 10rem;
+}
+
+.controlledRow {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.stateLine {
+  margin: 0;
+}
+
+.compositionHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.headerIcon {
+  width: var(--prime-sys-size-control-m-icon);
+  height: var(--prime-sys-size-control-m-icon);
+  flex-shrink: 0;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.checkboxStack {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.fullWidthTrigger {
+  width: 100%;
+  justify-content: center;
+}
+
+.narrowColumn {
+  width: min(12rem, 100%);
+}
+
+.textLinkTrigger {
+  margin: 0;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-size: var(--prime-sys-size-control-m-text);
+  font-weight: var(--prime-sys-typography-weight-medium);
+  color: var(--prime-sys-color-content-accent);
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+  cursor: pointer;
+  text-align: inherit;
+}
+
+.textLinkTrigger:focus-visible {
+  outline: 2px solid var(--prime-sys-color-border-focus);
+  outline-offset: 2px;
+  border-radius: var(--prime-sys-shape-radius-s);
+}
+
+.panelTextMuted {
+  margin: 0;
+  max-width: 22rem;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.flushText {
+  margin: 0;
+  max-width: 18rem;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.triggerWide {
+  width: 14rem;
+  justify-content: space-between;
+}
+
+.formPanel {
+  width: min(22rem, 100vw);
+}
+
+.actionsRow {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-sys-spacing-x2);
+}

package/src/components/popover/examples/rich-content.tsx

@@ -0,0 +1,37 @@
+import { Badge, Button, Divider, Hint, Popover, Typography } from "prime-ui-kit";
+
+/**
+ * Rich panel: badges, section divider, supporting hint — still a lightweight non-modal surface.
+ */
+export default function RichContentExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root mode="ghost" variant="neutral">
+          Release notes
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom">
+        <div style={{ display: "flex", flexWrap: "wrap", gap: "var(--prime-sys-spacing-x2)" }}>
+          <Badge.Root color="green" variant="light">
+            Stable
+          </Badge.Root>
+          <Badge.Root color="blue" variant="stroke">
+            v2.4
+          </Badge.Root>
+        </div>
+        <Typography.Root as="p" variant="body-small" weight="semibold">
+          What changed
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-small">
+          Command menu now respects nested Select listboxes without closing the panel on outside
+          detection.
+        </Typography.Root>
+        <Divider.Root variant="text">Heads-up</Divider.Root>
+        <Hint.Root variant="default">
+          Prefer Modal when the flow must block the page or trap focus by default.
+        </Hint.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

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

@@ -0,0 +1,30 @@
+import { Button, Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+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) => (
+        <Popover.Root key={size}>
+          <Popover.Trigger asChild>
+            <Button.Root mode="stroke" variant="neutral">
+              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>
+        </Popover.Root>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,36 @@
+import { Button, Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * `defaultOpen` for initially visible panel; disabled trigger does not open the popover.
+ */
+export default function PopoverStatesExample() {
+  return (
+    <div className={styles.sizesRow}>
+      <Popover.Root defaultOpen>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" variant="neutral">
+            Starts open
+          </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>
+      </Popover.Root>
+
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root disabled mode="stroke" variant="neutral">
+            Trigger 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>
+      </Popover.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,101 @@
+# ProgressBar
+
+**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
+
+## Canonical
+
+- **`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.
+
+## 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
+
+```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
+
+| 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
+
+- [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.
+
+## LLM note
+
+- 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.

package/src/components/progress-bar/examples/indeterminate-busy-state.tsx

@@ -0,0 +1,21 @@
+import { Button, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/**
+ * `ProgressBar.Root` always requires a numeric `value` — it cannot represent a native indeterminate meter.
+ * For unknown duration, use loading affordances on the relevant control (and optional supporting text).
+ */
+export default function ProgressBarIndeterminateBusyExample() {
+  return (
+    <div className={s.stack}>
+      <Typography.Root variant="body-small" tone="muted">
+        Preparing your workspace…
+      </Typography.Root>
+      <Button.Root type="button" loading variant="neutral" mode="stroke">
+        <Button.Spinner />
+        Please wait
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/progress-bar/examples/labeled.tsx

@@ -0,0 +1,6 @@
+import { ProgressBar } from "prime-ui-kit";
+
+/** Visible label above the track; `aria-labelledby` references the label (playground: `snippets/progress/bar-label.tsx`). */
+export default function ProgressBarLabeledExample() {
+  return <ProgressBar.Root value={60} label="Profile completion" />;
+}

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

@@ -0,0 +1,22 @@
+/* Examples: layout only; colors/spacing from semantic tokens. */
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  min-width: 0;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+  max-width: 28rem;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x2);
+  margin-top: var(--prime-sys-spacing-s);
+}

package/src/components/progress-bar/examples/sizes.tsx

@@ -0,0 +1,13 @@
+import { ProgressBar } from "prime-ui-kit";
+
+/** Four sizes: track height and label scale from `--prime-sys-size-control-{s|m|l|xl}-*` (playground: `snippets/progress/bar-sizes.tsx`). */
+export default function ProgressBarSizesExample() {
+  return (
+    <>
+      <ProgressBar.Root size="s" value={30} label="Size s" />
+      <ProgressBar.Root size="m" value={40} label="Size m" />
+      <ProgressBar.Root size="l" value={50} label="Size l" />
+      <ProgressBar.Root size="xl" value={60} label="Size xl" />
+    </>
+  );
+}

package/src/components/progress-bar/examples/step-progress.tsx

@@ -0,0 +1,22 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Map the current step index and total steps to `value` / `max` so the bar matches “step k of n”. */
+export default function ProgressBarStepProgressExample() {
+  const currentStep = 2;
+  const totalSteps = 5;
+
+  return (
+    <div className={s.stack}>
+      <Typography.Root variant="body-large" weight="semibold">
+        Account setup
+      </Typography.Root>
+      <ProgressBar.Root
+        value={currentStep}
+        max={totalSteps}
+        label={`Step ${currentStep} of ${totalSteps}`}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,27 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Determinate upload: drive `value` from bytes transferred; keep filename and percent in surrounding copy. */
+export default function ProgressBarUploadExample() {
+  const [loaded, setLoaded] = React.useState(0);
+  const total = 100;
+
+  return (
+    <div className={s.card}>
+      <Typography.Root variant="body-small" tone="muted">
+        quarterly-report.pdf
+      </Typography.Root>
+      <ProgressBar.Root value={loaded} max={total} label={`Upload progress: ${loaded}%`} />
+      <div className={s.actions}>
+        <button type="button" onClick={() => setLoaded((n) => Math.max(0, n - 20))}>
+          −20%
+        </button>
+        <button type="button" onClick={() => setLoaded((n) => Math.min(total, n + 20))}>
+          +20%
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-bar/examples/values.tsx

@@ -0,0 +1,13 @@
+import { ProgressBar } from "prime-ui-kit";
+
+/** Determinate fill at 0%, 25%, 75%, and 100% without labels (playground: `snippets/progress/bar-values.tsx`). */
+export default function ProgressBarValuesExample() {
+  return (
+    <>
+      <ProgressBar.Root value={0} />
+      <ProgressBar.Root value={25} />
+      <ProgressBar.Root value={75} />
+      <ProgressBar.Root value={100} />
+    </>
+  );
+}

package/src/components/progress-bar/examples/wizard-composition.tsx

@@ -0,0 +1,18 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Stack heading, bar, and muted helper copy — typical block in a wizard or long-running task panel. */
+export default function ProgressBarWizardCompositionExample() {
+  return (
+    <div className={s.card}>
+      <Typography.Root variant="body-large" weight="semibold">
+        Generating report
+      </Typography.Root>
+      <ProgressBar.Root value={72} max={100} label="Collecting data" />
+      <Typography.Root variant="body-small" tone="muted">
+        Usually under five minutes; you can return to the task list.
+      </Typography.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,97 @@
+# ProgressCircle
+
+**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
+
+## Canonical
+
+- **Playground demos** mirror **`playground/snippets/progress/circle-*.tsx`** (`circle-sizes`, `circle-max-scale`, `circle-states`, `circle-controlled`, `circle-composition`, `circle-a11y-label`); package **`examples/`** follow the same scenarios.
+- **`ProgressCircle`** — circular fraction of a known maximum: **`ProgressCircle.Root`** only (`inline-flex` root, SVG ring + optional centered **`children`**).
+- **Semantics:** SVG has **`role="progressbar"`** with **`aria-valuenow`**, **`aria-valuemin={0}`**, **`aria-valuemax`** (effective max after clamping / safe fallback).
+- **`value`** (required) and **`max`** (default **`100`**) — progress is **fully controlled**; **`value`** is clamped to **`[0, max]`**; if **`max <= 0`**, the scale falls back to **`100`** internally.
+- **`label`** — optional accessible name on the SVG (**`aria-label`**); use when the center has no text or the visible center text does not describe the bar.
+- **`size`:** **`s` | `m` | `l` | `xl`** — diameter and stroke from **`progressCircle`** primitives.
+- **`children`** — optional centered slot (short number, percent, icon); omit for a ring-only indicator (then set **`label`** for a11y).
+- **No indeterminate mode**, no **`disabled` / `loading` / `error`** props — reflect those in surrounding UI or by freezing **`value`**.
+- **Not** a focusable control; **not** polymorphic (**no `asChild`**).
+
+## Extended
+
+### About
+
+Circular progress: an SVG ring showing **`value` / `max`**, with optional content inside the ring.
+
+- **When to use** — compact share of a known total (percent, steps, seats, quota) where a round indicator reads better than a bar.
+- **When to use** — with **`max`** when the scale is not 0–100 (months in a plan, steps in a wizard, large numeric caps).
+- **When to use** — **`children`** for the focal number or short label in the middle of the ring.
+- **When not to use** — indeterminate or endless spinners without a numeric fraction (no built-in indeterminate API).
+- **When not to use** — as the primary interactive target; pair with [Button](../button/COMPONENT.md) or links for actions.
+- **When not to use** — when a horizontal bar is clearer; see [ProgressBar](../progress-bar/COMPONENT.md).
+
+### Composition
+
+- **`ProgressCircle.Root`** — root **`div`** with **`data-size`**, inner size CSS variable, SVG (**`progressbar`**), then optional **`children`** wrapper centered over the ring.
+- Order: pass **`value`** / **`max`** / **`size`** / **`label`** on **`Root`**; put visual center content in **`children`** when needed.
+
+### Scenarios (see `examples/`; playground: `playground/snippets/progress/circle-*.tsx`)
+
+| Scenario | Approach |
+|----------|----------|
+| Sizes | Same **`value`** across **`size`** **`s`–`xl`** (diameter and stroke from **`progressCircle`**). → [`examples/sizes.tsx`](examples/sizes.tsx) |
+| Non‑100 scale | Same arc fraction for different **`max`** (percent, steps, large totals). → [`examples/max-scale.tsx`](examples/max-scale.tsx) |
+| Value clamping | Empty, partial, full ring; out-of-range **`value`** clamps to **`0`** and **`max`**. → [`examples/states.tsx`](examples/states.tsx) |
+| Controlled value | Drive **`value`** from parent state (polling, upload simulation). → [`examples/controlled.tsx`](examples/controlled.tsx) |
+| Composition | **`children`** for **`Typography`**, icons, short numeric copy. → [`examples/composition.tsx`](examples/composition.tsx) |
+| Accessible name | Set **`label`** when the center has no descriptive text ( **`aria-label`** on SVG). → [`examples/a11y-label.tsx`](examples/a11y-label.tsx) |
+| Dashboard KPI (extra) | Ring inside [Card](../card/COMPONENT.md) **`mini-media`** **`Card.Media`** — no dedicated circle snippet. → [`examples/dashboard-ring.tsx`](examples/dashboard-ring.tsx) |
+
+### Minimal example
+
+```tsx
+import { ProgressCircle } from "prime-ui-kit";
+
+export function Example() {
+  return <ProgressCircle.Root value={40} />;
+}
+```
+
+### Rules
+
+- Progress is **always prop-driven** — no internal stored progress.
+- **`value`** clamped to **`[0, max]`**; negatives → **`0`**, above **`max`** → **`max`**.
+- If **`max <= 0`**, internal scale uses **`100`** to avoid division by zero.
+- **`label`** maps to **`aria-label`** on the SVG; prefer visible **`children`** text that describes the bar when it fully names the task.
+- Root is **`inline-flex`** — align inside your own flex or grid row when pairing with captions.
+- One visual style; scale with **`size`** only.
+
+## API
+
+### ProgressCircle.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `number` | — | Yes | Current value; clamped to `[0, max]` |
+| max | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Diameter and stroke from `progressCircle` primitives |
+| label | `string` | — | No | Accessible name for the SVG (`aria-label`) |
+| children | `React.ReactNode` | — | No | Centered content inside the ring |
+| className | `string` | — | No | Extra class on the root `div` |
+| ref | `React.Ref<HTMLDivElement>` | — | No | Ref on the root `div` |
+
+## Related
+
+- [ProgressBar](../progress-bar/COMPONENT.md) — linear fraction when a horizontal bar fits better.
+- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple segments on one track.
+- [Card](../card/COMPONENT.md) — KPI tiles; **`mini-media`** **`Card.Media`** for rings or thin progress.
+- [Typography](../typography/COMPONENT.md) — captions and units beside or under the ring.
+
+## LLM note
+
+- **Playground circle snippets:** `circle-sizes`, `circle-max-scale`, `circle-states`, `circle-controlled`, `circle-composition`, `circle-a11y-label` under **`playground/snippets/progress/`** — keep **`COMPONENT.md`** and **`examples/`** aligned with them.
+- Export: **`import { ProgressCircle } from "prime-ui-kit"`** — **`ProgressCircle.Root`** only (object namespace).
+- **`ProgressCircleRootProps`**: **`value`** (required), **`max?`** (default 100), **`size?`** (default **`m`**), **`label?`**, **`children?`**, **`className?`**, **`ref`** → **`HTMLDivElement`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`**.
+- SVG: **`role="progressbar"`**, **`aria-valuenow`**, **`aria-valuemin={0}`**, **`aria-valuemax`** = effective max; **`aria-label`** from **`label`** when provided.
+- **No** indeterminate, **no** `disabled`/`loading`/`error` props — control **`value`** and surrounding UI instead.
+- **No** `asChild` / polymorphic root — fixed **`div`** + SVG + optional inner **`div`** for **`children`**.
+- When the center is empty or non-descriptive, require **`label`** for an accessible name.
+- Prefer [ProgressBar](../progress-bar/COMPONENT.md) for linear indeterminate or strip layouts unless the design specifically needs a ring.