prime-ui-kit 0.0.1

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

@@ -0,0 +1,25 @@
+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 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 defaultChecked name="notify_email">
+        <Switch.Label>Email notifications</Switch.Label>
+        <Switch.Hint>Order status, receipts, and security alerts.</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root name="notify_push">
+        <Switch.Label>Push notifications</Switch.Label>
+        <Switch.Hint>Mobile alerts for time-sensitive updates only.</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root 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/switch/examples/sizes.tsx

@@ -0,0 +1,23 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Ladder `s`–`xl`; mirrors `playground/snippets/switch/sizes.tsx`. */
+export default function SwitchSizesExample() {
+  return (
+    <div className={styles.stack}>
+      <Switch.Root size="s" defaultChecked>
+        <Switch.Label>Switch s</Switch.Label>
+      </Switch.Root>
+      <Switch.Root size="m" defaultChecked>
+        <Switch.Label>Switch m</Switch.Label>
+      </Switch.Root>
+      <Switch.Root size="l" defaultChecked>
+        <Switch.Label>Switch l</Switch.Label>
+      </Switch.Root>
+      <Switch.Root size="xl" defaultChecked>
+        <Switch.Label>Switch xl</Switch.Label>
+      </Switch.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,32 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Off, on, disabled, read-only, error; mirrors `playground/snippets/switch/states.tsx`. */
+export default function SwitchStatesExample() {
+  return (
+    <div className={styles.stack}>
+      <Switch.Root>
+        <Switch.Label>Switch off</Switch.Label>
+        <Switch.Hint>Switch hint</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root defaultChecked>
+        <Switch.Label>Switch on</Switch.Label>
+        <Switch.Hint>Switch hint</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root disabled>
+        <Switch.Label>Switch disabled off</Switch.Label>
+      </Switch.Root>
+      <Switch.Root defaultChecked disabled>
+        <Switch.Label>Switch disabled on</Switch.Label>
+      </Switch.Root>
+      <Switch.Root defaultChecked readOnly>
+        <Switch.Label>Switch readonly on</Switch.Label>
+      </Switch.Root>
+      <Switch.Root variant="error">
+        <Switch.Label>Switch error</Switch.Label>
+        <Switch.Error>Switch error message</Switch.Error>
+      </Switch.Root>
+    </div>
+  );
+}

package/src/components/switch/examples/variants.tsx

@@ -0,0 +1,19 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** `default` vs `error`; mirrors `playground/snippets/switch/variants.tsx`. */
+export default function SwitchVariantsExample() {
+  return (
+    <div className={styles.stack}>
+      <Switch.Root defaultChecked>
+        <Switch.Label>Обычный вид</Switch.Label>
+        <Switch.Hint>variant по умолчанию — default</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root defaultChecked variant="error">
+        <Switch.Label>Ошибка валидации</Switch.Label>
+        <Switch.Error>Отметьте согласие, чтобы продолжить</Switch.Error>
+      </Switch.Root>
+    </div>
+  );
+}

package/src/components/tabs/COMPONENT.md

@@ -0,0 +1,147 @@
+# 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">
+      <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>
+  );
+}
+```
+
+### Scenarios (playground + `examples/`)
+
+Live demos use **`playground/snippets/tabs/*.tsx`** (see **`playground/sections/TabsSection.tsx`**). The same scenarios have package-oriented copies under **`examples/`** (aligned with those snippets).
+
+| Scenario | Notes | Example |
+|----------|--------|---------|
+| Sizes | Four rows: `size` **`s`** / **`m`** / **`l`** / **`xl`**. First tab: **`Tabs.Icon`** + **`Tabs.Label`**; others **`Tabs.Label`** only. | [`./examples/06-sizes-s-m-l-xl.tsx`](./examples/06-sizes-s-m-l-xl.tsx) |
+| States | One **`Tabs.Tab`** with **`disabled`** — no click, skipped in arrow-key cycle. | [`./examples/07-horizontal-disabled.tsx`](./examples/07-horizontal-disabled.tsx) |
+| Orientation | **`orientation="vertical"`** — list beside panels; vertical arrow keys. | [`./examples/01-settings-vertical-rail.tsx`](./examples/01-settings-vertical-rail.tsx) |
+| Controlled | **`value`** + **`onValueChange`** on **`Tabs.Root`** (URL, store, wizard step). | [`./examples/05-controlled-active-tab.tsx`](./examples/05-controlled-active-tab.tsx) |
+| Composition | Several **`Tabs.Icon`** slots per trigger (left/right of **`Tabs.Label`**) and two icons in one tab. | [`./examples/03-tab-triggers-with-icons.tsx`](./examples/03-tab-triggers-with-icons.tsx) |
+| Full width | No **`fullWidth`** prop: **`className`** on root / **`Tabs.List`** / **`Tabs.Tab`** (`w-full`, **`flex-1`**, **`min-w-0`**) so triggers share width. | [`./examples/02-dashboard-subviews.tsx`](./examples/02-dashboard-subviews.tsx) |
+| Long labels | Narrow container; **`Tabs.Label`** truncates with ellipsis without wrapping the whole tab row. | [`./examples/04-long-labels-narrow.tsx`](./examples/04-long-labels-narrow.tsx) |
+
+**LLM note:** Prefer reading `./examples/*.tsx` for runnable scenarios; this page keeps 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 in controlled mode; must match **`value`** on one **`Tabs.Tab`**. |
+| defaultValue | `string` | `""` | No | Initial tab when uncontrolled (omit **`value`**). |
+| onValueChange | `(value: string) => void` | — | No | Fired when the user or keyboard changes the tab. |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | No | Tab list axis and arrow-key direction (**Left/Right** vs **Up/Down**). |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger height, type scale, padding, and icon size from one control token tier. |
+| children | `React.ReactNode` | — | Yes | **`Tabs.List`**, **`Tabs.Tab`**, **`Tabs.Panel`**, and layout wrappers under the same root. |
+| className | `string` | — | No | Extra class on the root wrapper (e.g. **`w-full`** on a card). |
+
+### Tabs.List
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | **`Tabs.Tab`** triggers; the active indicator is rendered inside the list. |
+| className | `string` | — | No | Class on **`role="tablist"`** (e.g. stretch to full width). |
+
+### Tabs.Tab
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Unique id; must match the associated **`Tabs.Panel`** **`value`**. |
+| disabled | `boolean` | `false` | No | Not selectable; omitted from arrow-key focus order. |
+| children | `React.ReactNode` | — | Yes | Button contents: **`Tabs.Icon`**, **`Tabs.Label`**, or custom markup. |
+| className | `string` | — | No | Class on the trigger (e.g. **`flex-1`**, **`min-w-0`** for full-width rows). |
+
+### Tabs.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon (e.g. kit **`Icon`**); wrapper uses **`aria-hidden`**. |
+| 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 | Tab label text; can ellipsis when space is tight. |
+| 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`**; otherwise the panel is not rendered (**`null`**). |
+| children | `React.ReactNode` | — | Yes | **`role="tabpanel"`** body below (or beside) the list. |
+| 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,44 @@
+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" 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,62 @@
+import { Icon, Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Multiple `Tabs.Icon` slots per trigger (left/right of `Tabs.Label`) and two icons in one tab —
+ * matches `playground/snippets/tabs/with-icons.tsx`. Keep a visible `Tabs.Label` for the accessible
+ * name.
+ */
+export default function TabsExampleTriggersWithIcons() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List>
+        <Tabs.Tab value="overview">
+          <Tabs.Icon>
+            <Icon name="nav.layoutGrid" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Overview</Tabs.Label>
+          <Tabs.Icon>
+            <Icon name="nav.chevronRight" tone="subtle" />
+          </Tabs.Icon>
+        </Tabs.Tab>
+        <Tabs.Tab value="dashboard">
+          <Tabs.Icon>
+            <Icon name="nav.layoutGrid" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Dashboard</Tabs.Label>
+          <Tabs.Icon>
+            <Icon name="nav.chevronRight" tone="subtle" />
+          </Tabs.Icon>
+        </Tabs.Tab>
+        <Tabs.Tab value="settings">
+          <Tabs.Icon>
+            <Icon name="nav.layoutGrid" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Icon>
+            <Icon name="field.email" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Settings</Tabs.Label>
+          <Tabs.Icon>
+            <Icon name="nav.chevronRight" tone="subtle" />
+          </Tabs.Icon>
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="overview">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Overview content.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="dashboard">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Dashboard content.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="settings">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Settings content.
+        </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/06-sizes-s-m-l-xl.tsx

@@ -0,0 +1,58 @@
+import { Icon, Tabs, type TabsSize, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const sizes: readonly TabsSize[] = ["s", "m", "l", "xl"];
+
+function TabsSizeGroup({ size }: { size: TabsSize }) {
+  return (
+    <div className={styles.sizesGroup}>
+      <p className={styles.sizesLabel}>{`size="${size}"`}</p>
+      <Tabs.Root defaultValue="a" size={size}>
+        <Tabs.List>
+          <Tabs.Tab value="a">
+            <Tabs.Icon>
+              <Icon name="nav.layoutGrid" tone="subtle" />
+            </Tabs.Icon>
+            <Tabs.Label>Alpha</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="b">
+            <Tabs.Label>Beta</Tabs.Label>
+          </Tabs.Tab>
+          <Tabs.Tab value="c">
+            <Tabs.Label>Gamma</Tabs.Label>
+          </Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="a">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Panel A — same structure at each size; only the control token tier changes.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="b">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Panel B.
+          </Typography.Root>
+        </Tabs.Panel>
+        <Tabs.Panel value="c">
+          <Typography.Root as="p" variant="body-default" className={styles.body}>
+            Panel C.
+          </Typography.Root>
+        </Tabs.Panel>
+      </Tabs.Root>
+    </div>
+  );
+}
+
+/**
+ * Four `size` rungs (`s`–`xl`): one tab row per size; first tab uses `Tabs.Icon` + `Tabs.Label`,
+ * the rest labels only (matches `playground/snippets/tabs/sizes.tsx`).
+ */
+export default function TabsExampleSizesLadder() {
+  return (
+    <div className={styles.sizesRow}>
+      {sizes.map((s) => (
+        <TabsSizeGroup key={s} size={s} />
+      ))}
+    </div>
+  );
+}

package/src/components/tabs/examples/07-horizontal-disabled.tsx

@@ -0,0 +1,40 @@
+import { Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Disabled `Tabs.Tab`: not clickable, skipped in arrow-key roving; panel exists but is unreachable
+ * until the tab could be enabled (matches `playground/snippets/tabs/horizontal-disabled.tsx`).
+ */
+export default function TabsExampleHorizontalDisabled() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List>
+        <Tabs.Tab value="overview">
+          <Tabs.Label>Overview</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="analytics">
+          <Tabs.Label>Analytics</Tabs.Label>
+        </Tabs.Tab>
+        <Tabs.Tab value="reports" disabled>
+          <Tabs.Label>Reports</Tabs.Label>
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="overview">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Overview panel content.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="analytics">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Analytics panel content.
+        </Typography.Root>
+      </Tabs.Panel>
+      <Tabs.Panel value="reports">
+        <Typography.Root as="p" variant="body-default" className={styles.body}>
+          Reports panel content (shown only if this tab becomes enabled).
+        </Typography.Root>
+      </Tabs.Panel>
+    </Tabs.Root>
+  );
+}