prime-ui-kit 0.2.5 → 0.3.2

package/src/components/switch/examples/scenario-billing-annual.tsx

@@ -0,0 +1,27 @@
+import { Switch, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Billing: annual plan as a single on/off switch with savings context.
+ */
+export default function SwitchScenarioBillingAnnual() {
+  const [annual, setAnnual] = React.useState(false);
+
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="body-default" className={styles.muted}>
+        Choose how you are billed. Annual includes two months free on the Pro plan.
+      </Typography.Root>
+      <Switch.Root size="m" checked={annual} onCheckedChange={setAnnual} name="billing_cycle">
+        <Switch.Label>Bill annually</Switch.Label>
+        <Switch.Hint>
+          {annual
+            ? "You will be charged once per year at the discounted rate."
+            : "Switch on to save compared to twelve monthly charges."}
+        </Switch.Hint>
+      </Switch.Root>
+    </div>
+  );
+}

package/src/components/switch/examples/scenario-feature-flag.tsx

@@ -0,0 +1,30 @@
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled feature flag: parent owns state; hint explains rollout scope.
+ */
+export default function SwitchScenarioFeatureFlag() {
+  const [enabled, setEnabled] = React.useState(true);
+
+  return (
+    <div className={styles.stackDense}>
+      <Switch.Root
+        size="m"
+        checked={enabled}
+        onCheckedChange={setEnabled}
+        name="flag_new_dashboard"
+      >
+        <Switch.Label>New dashboard experience</Switch.Label>
+        <Switch.Hint>
+          Applies to this workspace only. Users may need to refresh after toggling.
+        </Switch.Hint>
+      </Switch.Root>
+      <p className={styles.muted} aria-live="polite">
+        Flag is <strong>{enabled ? "on" : "off"}</strong> for members on the next session.
+      </p>
+    </div>
+  );
+}

package/src/components/switch/examples/scenario-form-consent.tsx

@@ -0,0 +1,34 @@
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Form submit: native `name` / `value` with FormData; required consent switch.
+ */
+export default function SwitchScenarioFormConsent() {
+  const [message, setMessage] = React.useState<string | null>(null);
+
+  return (
+    <form
+      className={styles.form}
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        const terms = data.get("terms") === "on";
+        setMessage(
+          terms ? "Terms accepted — you can continue checkout." : "Please accept the terms.",
+        );
+      }}
+    >
+      <Switch.Root name="terms" required>
+        <Switch.Label>I agree to the Terms of Service and Privacy Policy</Switch.Label>
+        <Switch.Hint>Required to place an order.</Switch.Hint>
+      </Switch.Root>
+      <button type="submit" className={styles.formSubmit}>
+        Continue to payment
+      </button>
+      {message != null ? <p className={styles.formMessage}>{message}</p> : null}
+    </form>
+  );
+}

package/src/components/switch/examples/scenario-settings-toggle.tsx

@@ -0,0 +1,26 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Settings screen: independent notification toggles with short hints.
+ */
+export default function SwitchScenarioSettingsToggle() {
+  return (
+    <fieldset className={styles.settingsGroup}>
+      <legend className={styles.legend}>Notification preferences</legend>
+      <Switch.Root size="m" defaultChecked name="notify_email">
+        <Switch.Label>Email notifications</Switch.Label>
+        <Switch.Hint>Order status, receipts, and security alerts.</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" name="notify_push">
+        <Switch.Label>Push notifications</Switch.Label>
+        <Switch.Hint>Mobile alerts for time-sensitive updates only.</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" name="notify_marketing">
+        <Switch.Label>Tips and offers</Switch.Label>
+        <Switch.Hint>Optional product news; never required for core service.</Switch.Hint>
+      </Switch.Root>
+    </fieldset>
+  );
+}

package/src/components/tabs/COMPONENT.md

@@ -0,0 +1,141 @@
+# Tabs
+
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+
+## About
+
+Compound tabs: a `tablist` of triggers, an animated indicator, and one visible `tabpanel` at a time. Values on `Tabs.Tab` and `Tabs.Panel` must align so the active pair matches.
+
+**When to use**
+
+- Switching sections on one view (settings areas, product detail blocks, dashboard sub-views) without a full route change.
+- Controlled `value` / `onValueChange` when the active tab must follow the URL, client store, or a wizard step.
+- `orientation="vertical"` for a sidebar-style rail next to the main panel (see settings layout recipes in the kit).
+
+**When not to use**
+
+- Primary navigation between top-level pages — prefer links and routes (see [Breadcrumb](../breadcrumb/COMPONENT.md) for hierarchy).
+- Two to four lightweight mutually exclusive options without rich panels — consider [SegmentedControl](../segmented-control/COMPONENT.md).
+- Expecting inactive panel subtrees to stay mounted — hidden panels are not rendered (see Rules).
+
+## Composition
+
+- **`Tabs.Root`** — context wrapper (`div` with `data-orientation`, `data-size`). Place **`Tabs.List`** and **`Tabs.Panel`** in tree order (list first, then panels) for a typical reading order; panels may sit inside a layout wrapper as long as they remain under the same root.
+- **`Tabs.List`** — `role="tablist"` with `aria-orientation`, keyboard handling, indicator, and **`ControlSizeProvider`**. Children should be **`Tabs.Tab`** triggers only.
+- **`Tabs.Tab`** — `role="tab"` / `button type="button"`. Optional **`Tabs.Icon`** and **`Tabs.Label`**; `value` must match a **`Tabs.Panel`** `value`.
+- **`Tabs.Panel`** — `role="tabpanel"`; renders **only** when its `value` equals the root’s active value.
+
+### Canonical example
+
+```tsx
+import { Tabs, Typography } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Tabs.Root defaultValue="general" size="m">
+      <Tabs.List>
+        <Tabs.Tab value="general">
+          <Tabs.Label>General</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="privacy">
+          <Tabs.Label>Privacy</Tabs.Label>
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="general">
+        <Typography.Root as="p" variant="body-default" tone="muted">
+          Workspace name, locale, and default landing behavior.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="privacy">
+        <Typography.Root as="p" variant="body-default" tone="muted">
+          Data retention, export, and who can see activity in this project.
+        </Typography.Root>
+      </Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+### Extended examples
+
+- [`./examples/01-settings-vertical-rail.tsx`](./examples/01-settings-vertical-rail.tsx) — Settings: vertical tab rail with profile, security, and billing panels.
+- [`./examples/02-dashboard-subviews.tsx`](./examples/02-dashboard-subviews.tsx) — Dashboard: horizontal tabs with equal-width triggers across a card (`flex` on each tab).
+- [`./examples/03-tab-triggers-with-icons.tsx`](./examples/03-tab-triggers-with-icons.tsx) — Icon + label triggers using the kit **`Icon`** inside **`Tabs.Icon`**.
+- [`./examples/04-long-labels-narrow.tsx`](./examples/04-long-labels-narrow.tsx) — Long English labels in a narrow container; ellipsis on **`Tabs.Label`**.
+- [`./examples/05-controlled-active-tab.tsx`](./examples/05-controlled-active-tab.tsx) — Controlled `value` / `onValueChange` (e.g. sync with `?tab=` or store).
+
+**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and layout patterns; this page keeps the contract (rules + API tables) authoritative.
+
+## Rules
+
+- **Uncontrolled:** omit `value`, set `defaultValue` on `Tabs.Root` (implementation default for `defaultValue` is `""` if omitted). **Controlled:** pass `value` and `onValueChange`; state follows `useControllableState` semantics.
+- **Disabled tabs:** `disabled` on `Tabs.Tab` sets native `disabled`, `data-disabled`, and excludes the tab from arrow-key traversal; disabled targets are skipped.
+- **Keyboard** (focus inside `Tabs.List`): **ArrowLeft** / **ArrowRight** in horizontal mode, **ArrowUp** / **ArrowDown** in vertical mode; **Home** / **End** move to first / last **enabled** tab; focus moves to the newly selected tab after arrow navigation.
+- **Focus order:** the selected tab has `tabIndex={0}`; others use `tabIndex={-1}`.
+- **ARIA:** `aria-controls` / `aria-labelledby` wire tab buttons to panels; list `aria-orientation` mirrors `orientation`.
+- **`Tabs.Icon`** sets `aria-hidden="true"` on the wrapper span; ensure the tab still has a clear name (e.g. `Tabs.Label` or visible text).
+- **Inactive panels:** `Tabs.Panel` returns `null` when inactive—avoid putting expensive trees in panels without app-level lazy loading or conditional data fetching.
+- **No `asChild`:** each tab is always a `<button>`; there is no built-in URL synchronization.
+- **Pairs:** for every panel `value` you expose, provide a corresponding tab (and vice versa) so the tab/panel relationship stays consistent for assistive tech.
+- **Layout:** full-width or custom layout uses `className` and your own flex/grid CSS on the root, list, or tabs—there is no dedicated `fullWidth` prop on `Tabs`.
+
+## API
+
+### Tabs.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | No | Active tab id (controlled) |
+| defaultValue | `string` | `""` | No | Initial active tab when uncontrolled |
+| onValueChange | `(value: string) => void` | — | No | Called when the active tab changes |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | No | Tab list axis and arrow-key mapping |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger and panel typography scale |
+| children | `React.ReactNode` | — | Yes | `Tabs.List` and `Tabs.Panel` (and related structure) |
+| className | `string` | — | No | Class on the root `div` |
+
+### Tabs.List
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Typically `Tabs.Tab` elements |
+| className | `string` | — | No | Class on the tablist container |
+
+### Tabs.Tab
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Id matching the associated `Tabs.Panel` |
+| disabled | `boolean` | `false` | No | Non-interactive; skipped in keyboard roving |
+| children | `React.ReactNode` | — | Yes | Trigger content (e.g. `Tabs.Icon`, `Tabs.Label`) |
+| className | `string` | — | No | Class on the `button` |
+
+### Tabs.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon glyph |
+| className | `string` | — | No | Class on the `span` |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other span attributes |
+
+### Tabs.Label
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Label text |
+| className | `string` | — | No | Class on the `span` |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other span attributes |
+
+### Tabs.Panel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Must match the active `Tabs.Tab` `value` to render |
+| children | `React.ReactNode` | — | Yes | Panel body |
+| className | `string` | — | No | Class on the panel `div` |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)
+- [Breadcrumb](../breadcrumb/COMPONENT.md)
+- **Icon** — use inside `Tabs.Icon` for glyphs sized with the tab control tokens

package/src/components/tabs/examples/01-settings-vertical-rail.tsx

@@ -0,0 +1,49 @@
+import { Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Settings-style layout: vertical tab rail beside the active panel (narrow viewports can switch to
+ * horizontal or Accordion; see layout recipes in the kit skill).
+ */
+export default function TabsExampleSettingsVerticalRail() {
+  return (
+    <Tabs.Root
+      defaultValue="profile"
+      orientation="vertical"
+      size="m"
+      className={styles.settingsRow}
+    >
+      <Tabs.List>
+        <Tabs.Tab value="profile">
+          <Tabs.Label>Profile</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="security">
+          <Tabs.Label>Security</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="billing">
+          <Tabs.Label>Billing</Tabs.Label>
+        </Tabs.Tab>
+      </Tabs.List>
+      <div className={styles.settingsContent}>
+        <Tabs.Panel value="profile">
+          <div className={styles.stack}>
+            <Typography.Root as="p" variant="body-default" className={styles.body}>
+              Update your display name, avatar, and how your profile appears to teammates.
+            </Typography.Root>
+          </div>
+        </Tabs.Panel>
+        <Tabs.Panel value="security">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Passwords, two-factor authentication, and active sessions for this workspace.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="billing">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Plans, invoices, and payment methods. Changes apply at the start of the next cycle.
+          </Typography.Root>
+        </Tabs.Panel>
+      </div>
+    </Tabs.Root>
+  );
+}

package/src/components/tabs/examples/02-dashboard-subviews.tsx

@@ -0,0 +1,42 @@
+import { Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Dashboard sub-views: equal-width triggers across the card width via `flex` on each tab (no
+ * dedicated `fullWidth` prop on Tabs).
+ */
+export default function TabsExampleDashboardSubviews() {
+  return (
+    <div className={styles.surface}>
+      <Tabs.Root defaultValue="overview" className={styles.fullWidthRoot}>
+        <Tabs.List className={styles.fullWidthList}>
+          <Tabs.Tab value="overview" className={styles.flexTab}>
+            <Tabs.Label>Overview</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="metrics" className={styles.flexTab}>
+            <Tabs.Label>Metrics</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="activity" className={styles.flexTab}>
+            <Tabs.Label>Activity</Tabs.Label>
+          </Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="overview">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Snapshot cards and at-a-glance health for the current period.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="metrics">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Conversion, latency, and volume trends. Heavy charts belong here; inactive tabs unmount.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="activity">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Recent user and system events with filters applied from the toolbar above.
+          </Typography.Root>
+        </Tabs.Panel>
+      </Tabs.Root>
+    </div>
+  );
+}

package/src/components/tabs/examples/03-tab-triggers-with-icons.tsx

@@ -0,0 +1,49 @@
+import { Icon, Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Icon + label in each trigger; keep a visible `Tabs.Label` (or equivalent text) so the tab name is
+ * not only conveyed by the glyph.
+ */
+export default function TabsExampleTriggersWithIcons() {
+  return (
+    <Tabs.Root defaultValue="inbox">
+      <Tabs.List>
+        <Tabs.Tab value="inbox">
+          <Tabs.Icon>
+            <Icon name="field.email" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Inbox</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="library">
+          <Tabs.Icon>
+            <Icon name="nav.layoutGrid" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Library</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="vault">
+          <Tabs.Icon>
+            <Icon name="status.locked" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Vault</Tabs.Label>
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="inbox">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Messages and mentions for the signed-in user.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="library">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Collections and grids of assets linked to this project.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="vault">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Restricted credentials and secrets with stricter access rules.
+        </Typography.Root>
+      </Tabs.Panel>
+    </Tabs.Root>
+  );
+}

package/src/components/tabs/examples/04-long-labels-narrow.tsx

@@ -0,0 +1,35 @@
+import { Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Long tab labels: `Tabs.Label` supports shrinking and ellipsis in cramped horizontal space—keep a
+ * narrow `min-width: 0` chain on ancestors so truncation can apply.
+ */
+export default function TabsExampleLongLabelsNarrow() {
+  return (
+    <div className={styles.narrowShell}>
+      <Tabs.Root defaultValue="short">
+        <Tabs.List>
+          <Tabs.Tab value="short">
+            <Tabs.Label>Summary</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="long">
+            <Tabs.Label>Regulatory reporting &amp; compliance documentation workspace</Tabs.Label>
+          </Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="short">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Short label tab content.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="long">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            The trigger text truncates with an ellipsis when the list is narrower than the full
+            string.
+          </Typography.Root>
+        </Tabs.Panel>
+      </Tabs.Root>
+    </div>
+  );
+}

package/src/components/tabs/examples/05-controlled-active-tab.tsx

@@ -0,0 +1,48 @@
+import { Tabs, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled mode: drive `value` / `onValueChange` from routing, query params, or store so the
+ * active tab matches shareable URL state.
+ */
+export default function TabsExampleControlledActiveTab() {
+  const [active, setActive] = React.useState("details");
+
+  return (
+    <>
+      <Tabs.Root value={active} onValueChange={setActive}>
+        <Tabs.List>
+          <Tabs.Tab value="details">
+            <Tabs.Label>Details</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="shipping">
+            <Tabs.Label>Shipping</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="history">
+            <Tabs.Label>History</Tabs.Label>
+          </Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="details">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            SKU, price, and merchandising copy for this line item.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="shipping">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Carrier, service level, and estimated delivery window.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="history">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Status changes and notes from fulfillment.
+          </Typography.Root>
+        </Tabs.Panel>
+      </Tabs.Root>
+      <p className={styles.controlledCaption}>
+        Active tab id (for example sync with <code>?tab=</code>): <strong>{active}</strong>
+      </p>
+    </>
+  );
+}

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

@@ -0,0 +1,58 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.body {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.settingsRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-l);
+  align-items: flex-start;
+}
+
+.settingsContent {
+  flex: 1 1 0;
+  min-width: min(100%, 20rem);
+}
+
+.surface {
+  width: 100%;
+  max-width: min(100%, 36rem);
+  padding: var(--prime-sys-spacing-m);
+  border-radius: var(--prime-sys-shape-radius-m);
+  border: var(--prime-sys-unit-1px) solid var(--prime-sys-color-border-subtle);
+}
+
+.fullWidthRoot {
+  width: 100%;
+  min-width: 0;
+}
+
+.fullWidthList {
+  width: 100%;
+  min-width: 0;
+}
+
+.flexTab {
+  flex: 1 1 0;
+  min-width: 0;
+  justify-content: center;
+}
+
+.narrowShell {
+  width: 100%;
+  max-width: 12rem;
+  min-width: 0;
+}
+
+.controlledCaption {
+  margin: var(--prime-sys-spacing-s) 0 0;
+  color: var(--prime-sys-color-content-muted);
+  font-size: var(--prime-sys-typography-role-bodySmall-fontSize);
+}

package/src/components/tag/COMPONENT.md

@@ -0,0 +1,82 @@
+# Tag
+
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+
+## About
+
+A compact chip-style label: optional leading icon (`Tag.Icon`), optional removable close control when `onRemove` is set. Root is a `span` with `data-size` / `data-disabled`; the inner body wraps children in `ControlSizeProvider` so nested icons pick up the same control size tier.
+
+**When to use**
+
+- Filter chips and applied facets where each selection should be dismissible in one click.
+- Selected values (recipients, skills, topics) with optional removal.
+- Tight metadata labels (environment, version, channel) when a pill shape reads better than body text; add `Tag.Icon` when a small glyph clarifies meaning.
+
+**When not to use**
+
+- As a toggle or single-choice control — prefer [Checkbox](../checkbox/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), or [Select](../select/COMPONENT.md).
+- When the whole chip must navigate or submit a primary action — prefer [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
+- Expecting localized copy for the remove control without wrapping — the built-in remove `aria-label` is fixed to `"Remove"` in source; name the surrounding group (`aria-label` / `aria-labelledby`) for context.
+- As a numeric or status **badge** — prefer [Badge](../badge/COMPONENT.md) when the UI is count-only or notification-style.
+
+## Composition
+
+- **`Tag.Root`** — outer `span`; holds a **`span`** body with **`ControlSizeProvider`** around **`children`**, then an optional remove **`button`** when **`onRemove`** is defined. Put plain text, **`Tag.Icon`**, or other nodes inside **`Tag.Root`**; place **`Tag.Icon`** before text when both are used so the icon sits on the left.
+- **`Tag.Icon`** — wrapper **`span`** for the icon node; inherits size from the surrounding **`Tag.Root`** context.
+
+### Canonical example
+
+```tsx
+import { Tag } from "prime-ui-kit";
+
+export function Example() {
+  return <Tag.Root size="m">Design systems</Tag.Root>;
+}
+```
+
+### Extended examples
+
+- [`./examples/01-filter-chips.tsx`](./examples/01-filter-chips.tsx) — Catalog filters: applied facets as removable chips backed by a `Set` in state.
+- [`./examples/02-removable-selected-values.tsx`](./examples/02-removable-selected-values.tsx) — Selected skills: removable tags inside `fieldset` / `legend` so each “Remove” control has group context.
+- [`./examples/03-status-metadata.tsx`](./examples/03-status-metadata.tsx) — Status / release metadata: read-only chips with `Tag.Icon` + text, no `onRemove`.
+- [`./examples/04-tag-sizes.tsx`](./examples/04-tag-sizes.tsx) — Size ladder `s` through `xl` in one row.
+
+**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition patterns; this page keeps the contract (rules + API tables) authoritative.
+
+## Rules
+
+- Omit **`size`** to follow the nearest ancestor **`ControlSizeProvider`**; context **`xs`** maps to tag size **`s`**. With no provider and no **`size`**, the effective size is **`m`**.
+- **`onRemove`** is optional; when present, a **`type="button"`** remove control is rendered with **`aria-label="Remove"`** and **`aria-hidden`** on the cross SVG. **`disabled`** sets **`aria-disabled`** on the root and disables the remove button.
+- Without **`onRemove`**, there is no focusable control inside the tag; the root is not a button or link.
+- For lists of removable tags, name the group so “Remove” has context — e.g. **`fieldset`** + **`legend`** (as in `./examples`) or **`aria-label`** / **`aria-labelledby`** on a suitable wrapper.
+- **`Tag.Icon`** does not force **`aria-hidden`** on icons; if the icon is decorative, rely on adjacent text or set **`aria-hidden`** on the icon content yourself.
+- There is no **`variant`** prop; appearance follows **`size`** and whether removal is enabled.
+
+## API
+
+### Tag.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` or from `ControlSizeProvider` | No | Visual tier for height, radius, text, and nested icon scale |
+| onRemove | `() => void` | — | No | When set, renders the remove button on the right |
+| disabled | `boolean` | — | No | Disables removal and sets `aria-disabled` on the root |
+| children | `React.ReactNode` | — | No | Text, `Tag.Icon`, or other nodes |
+| className | `string` | — | No | Extra class on the root `span` |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other root attributes (`data-*`, `aria-*`, etc.) |
+
+### Tag.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon or other content |
+| className | `string` | — | No | Extra class on the wrapper |
+
+## Related
+
+- [Badge](../badge/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/tag/examples/01-filter-chips.tsx

@@ -0,0 +1,36 @@
+import { Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FILTER_IDS = ["In stock", "Ships today", "4+ stars", "Under $50"] as const;
+
+/**
+ * Catalog-style active filters: each chip removes itself from the applied set via `onRemove`.
+ */
+export default function TagExampleFilterChips() {
+  const [applied, setApplied] = React.useState<Set<string>>(
+    () => new Set(["In stock", "4+ stars"]),
+  );
+
+  const remove = (id: string) => {
+    setApplied((prev) => {
+      const next = new Set(prev);
+      next.delete(id);
+      return next;
+    });
+  };
+
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Active filters</legend>
+      <div className={styles.chipRow}>
+        {FILTER_IDS.filter((id) => applied.has(id)).map((id) => (
+          <Tag.Root key={id} size="m" onRemove={() => remove(id)}>
+            {id}
+          </Tag.Root>
+        ))}
+      </div>
+    </fieldset>
+  );
+}