prime-ui-kit 0.3.2 → 0.4.0

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 size="m">
+        <Switch.Label>Switch off</Switch.Label>
+        <Switch.Hint>Switch hint</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" defaultChecked>
+        <Switch.Label>Switch on</Switch.Label>
+        <Switch.Hint>Switch hint</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" disabled>
+        <Switch.Label>Switch disabled off</Switch.Label>
+      </Switch.Root>
+      <Switch.Root size="m" defaultChecked disabled>
+        <Switch.Label>Switch disabled on</Switch.Label>
+      </Switch.Root>
+      <Switch.Root size="m" defaultChecked readOnly>
+        <Switch.Label>Switch readonly on</Switch.Label>
+      </Switch.Root>
+      <Switch.Root size="m" 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 size="m" defaultChecked>
+        <Switch.Label>Обычный вид</Switch.Label>
+        <Switch.Hint>variant по умолчанию — default</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" defaultChecked variant="error">
+        <Switch.Label>Ошибка валидации</Switch.Label>
+        <Switch.Error>Отметьте согласие, чтобы продолжить</Switch.Error>
+      </Switch.Root>
+    </div>
+  );
+}

package/src/components/tabs/COMPONENT.md

@@ -56,15 +56,21 @@ export function Example() {
 }
 ```
 
-### Extended examples
+### Scenarios (playground + `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).
+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).
 
-**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.
+| 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
 
@@ -85,35 +91,35 @@ export function Example() {
 
 | 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` |
+| 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 | Typically `Tabs.Tab` elements |
-| className | `string` | — | No | Class on the tablist container |
+| 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 | 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` |
+| 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 glyph |
+| 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 |
 
@@ -121,7 +127,7 @@ export function Example() {
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Label text |
+| 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 |
 
@@ -129,8 +135,8 @@ export function Example() {
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| value | `string` | — | Yes | Must match the active `Tabs.Tab` `value` to render |
-| children | `React.ReactNode` | — | Yes | Panel body |
+| 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

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

@@ -3,45 +3,58 @@ 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.
+ * 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="inbox">
+    <Tabs.Root defaultValue="overview">
       <Tabs.List>
-        <Tabs.Tab value="inbox">
+        <Tabs.Tab value="overview">
           <Tabs.Icon>
-            <Icon name="field.email" tone="subtle" />
+            <Icon name="nav.layoutGrid" tone="subtle" />
+          </Tabs.Icon>
+          <Tabs.Label>Overview</Tabs.Label>
+          <Tabs.Icon>
+            <Icon name="nav.chevronRight" tone="subtle" />
           </Tabs.Icon>
-          <Tabs.Label>Inbox</Tabs.Label>
         </Tabs.Tab>
-        <Tabs.Tab value="library">
+        <Tabs.Tab value="dashboard">
           <Tabs.Icon>
             <Icon name="nav.layoutGrid" tone="subtle" />
           </Tabs.Icon>
-          <Tabs.Label>Library</Tabs.Label>
+          <Tabs.Label>Dashboard</Tabs.Label>
+          <Tabs.Icon>
+            <Icon name="nav.chevronRight" tone="subtle" />
+          </Tabs.Icon>
         </Tabs.Tab>
-        <Tabs.Tab value="vault">
+        <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="status.locked" tone="subtle" />
+            <Icon name="nav.chevronRight" tone="subtle" />
           </Tabs.Icon>
-          <Tabs.Label>Vault</Tabs.Label>
         </Tabs.Tab>
       </Tabs.List>
-      <Tabs.Panel value="inbox">
+      <Tabs.Panel value="overview">
         <Typography.Root as="p" variant="body-default" className={styles.body}>
-          Messages and mentions for the signed-in user.
+          Overview content.
         </Typography.Root>
       </Tabs.Panel>
-      <Tabs.Panel value="library">
+      <Tabs.Panel value="dashboard">
         <Typography.Root as="p" variant="body-default" className={styles.body}>
-          Collections and grids of assets linked to this project.
+          Dashboard content.
         </Typography.Root>
       </Tabs.Panel>
-      <Tabs.Panel value="vault">
+      <Tabs.Panel value="settings">
         <Typography.Root as="p" variant="body-default" className={styles.body}>
-          Restricted credentials and secrets with stricter access rules.
+          Settings content.
         </Typography.Root>
       </Tabs.Panel>
     </Tabs.Root>

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>
+  );
+}

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

@@ -56,3 +56,24 @@
   color: var(--prime-sys-color-content-muted);
   font-size: var(--prime-sys-typography-role-bodySmall-fontSize);
 }
+
+.sizesRow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x6);
+  align-items: stretch;
+  width: 100%;
+}
+
+.sizesGroup {
+  width: 100%;
+  min-width: 0;
+}
+
+.sizesLabel {
+  margin: 0 0 var(--prime-sys-spacing-x2);
+  font-size: var(--prime-sys-size-control-s-supportText);
+  font-weight: var(--prime-sys-typography-weight-medium);
+  line-height: var(--prime-sys-typography-body-lineHeight);
+  color: var(--prime-sys-color-content-secondary);
+}

package/src/components/tag/COMPONENT.md

@@ -34,14 +34,29 @@ export function Example() {
 }
 ```
 
-### Extended examples
+### Scenarios (playground + `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.
+Live demos use **`playground/snippets/tag/*.tsx`** (see **`playground/sections/TagSection.tsx`**). The table lists the same scenarios with package-oriented copies under **`examples/`** (aligned with those snippets; playground uses `@/` imports and shared `playground.css` layout classes).
 
-**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.
+| Scenario | Snippet | Package example |
+|----------|---------|-----------------|
+| Sizes | [`playground/snippets/tag/sizes.tsx`](../../../playground/snippets/tag/sizes.tsx) | [`examples/sizes.tsx`](./examples/sizes.tsx) |
+| States | [`playground/snippets/tag/states.tsx`](../../../playground/snippets/tag/states.tsx) | [`examples/states.tsx`](./examples/states.tsx) |
+| Composition | [`playground/snippets/tag/composition.tsx`](../../../playground/snippets/tag/composition.tsx) | [`examples/composition.tsx`](./examples/composition.tsx) |
+| Basic | [`playground/snippets/tag/basic.tsx`](../../../playground/snippets/tag/basic.tsx) | [`examples/basic.tsx`](./examples/basic.tsx) |
+| Removable (dismiss + restore) | [`playground/snippets/tag/removable.tsx`](../../../playground/snippets/tag/removable.tsx) | [`examples/removable.tsx`](./examples/removable.tsx) |
+| With icon | [`playground/snippets/tag/with-icon.tsx`](../../../playground/snippets/tag/with-icon.tsx) | [`examples/with-icon.tsx`](./examples/with-icon.tsx) |
+| Controlled list | [`playground/snippets/tag/controlled.tsx`](../../../playground/snippets/tag/controlled.tsx) | [`examples/controlled.tsx`](./examples/controlled.tsx) |
+| Disabled | [`playground/snippets/tag/disabled.tsx`](../../../playground/snippets/tag/disabled.tsx) | [`examples/disabled.tsx`](./examples/disabled.tsx) |
+| Context `size` | [`playground/snippets/tag/context-size.tsx`](../../../playground/snippets/tag/context-size.tsx) | [`examples/context-size.tsx`](./examples/context-size.tsx) |
+
+**Additional extended examples** (richer layout / copy, same building blocks):
+
+- [`./examples/01-filter-chips.tsx`](./examples/01-filter-chips.tsx) — Catalog filters: applied facets as removable chips backed by a `Set` in state (`fieldset` + `legend`).
+- [`./examples/02-removable-selected-values.tsx`](./examples/02-removable-selected-values.tsx) — Selected skills: removable tags in a named group for remove-button context.
+- [`./examples/03-status-metadata.tsx`](./examples/03-status-metadata.tsx) — Release-style metadata: read-only chips with `Tag.Icon` + text, no `onRemove`.
+
+**LLM note:** Prefer reading runnable files under `./examples/*.tsx` and matching `playground/snippets/tag/*.tsx` for prop combinations; this page keeps the contract (rules + API tables) authoritative.
 
 ## Rules
 

package/src/components/tag/examples/basic.tsx

@@ -0,0 +1,14 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Static labels without icon or `onRemove` — typical tech stack or category chips. */
+export default function TagExampleBasic() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>React</Tag.Root>
+      <Tag.Root>TypeScript</Tag.Root>
+      <Tag.Root>prime-ui-kit</Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/composition.tsx

@@ -0,0 +1,19 @@
+import { Icon, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Leading `Tag.Icon`, label-only, and label with `onRemove`; icon scale follows `size` via context. */
+export default function TagExampleComposition() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>
+        <Tag.Icon>
+          <Icon name="field.email" />
+        </Tag.Icon>
+        <span>Newsletter</span>
+      </Tag.Root>
+      <Tag.Root>Label only</Tag.Root>
+      <Tag.Root onRemove={() => undefined}>Removable</Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/context-size.tsx

@@ -0,0 +1,17 @@
+import { ControlSizeProvider, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Omit `size` on `Tag.Root` to inherit from `ControlSizeProvider`. */
+export default function TagExampleContextSize() {
+  return (
+    <div className={styles.chipRow}>
+      <ControlSizeProvider value="s">
+        <Tag.Root>No size — from context s</Tag.Root>
+      </ControlSizeProvider>
+      <ControlSizeProvider value="l">
+        <Tag.Root>No size — from context l</Tag.Root>
+      </ControlSizeProvider>
+    </div>
+  );
+}

package/src/components/tag/examples/controlled.tsx

@@ -0,0 +1,31 @@
+import { Button, Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INITIAL = ["Photo", "Video", "Documents"] as const;
+
+/** Removable tags driven by array state; empty state shows a reset button. */
+export default function TagExampleControlled() {
+  const [active, setActive] = React.useState<string[]>([...INITIAL]);
+
+  return (
+    <div className={styles.chipRow}>
+      {active.map((label) => (
+        <Tag.Root key={label} onRemove={() => setActive((prev) => prev.filter((x) => x !== label))}>
+          {label}
+        </Tag.Root>
+      ))}
+      {active.length === 0 ? (
+        <Button.Root
+          variant="neutral"
+          mode="stroke"
+          size="m"
+          onClick={() => setActive([...INITIAL])}
+        >
+          Reset filters
+        </Button.Root>
+      ) : null}
+    </div>
+  );
+}

package/src/components/tag/examples/disabled.tsx

@@ -0,0 +1,15 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** `disabled` alone and with `onRemove` (remove control is not actionable). */
+export default function TagExampleDisabled() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root disabled>Read-only</Tag.Root>
+      <Tag.Root disabled onRemove={() => undefined}>
+        Cannot remove
+      </Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/removable.tsx

@@ -0,0 +1,22 @@
+import { Button, Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** One tag dismisses from state; a stroke button restores it; second row shows static remove UI. */
+export default function TagExampleRemovable() {
+  const [withRemove, setWithRemove] = React.useState(true);
+
+  return (
+    <div className={styles.chipRow}>
+      {withRemove ? (
+        <Tag.Root onRemove={() => setWithRemove(false)}>Dismiss me</Tag.Root>
+      ) : (
+        <Button.Root variant="neutral" mode="stroke" size="m" onClick={() => setWithRemove(true)}>
+          Show tag again
+        </Button.Root>
+      )}
+      <Tag.Root onRemove={() => undefined}>Static remove UI</Tag.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,15 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Size ladder `s` → `xl`; height, radius, type, and icon tier follow control tokens. */
+export default function TagExampleSizes() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root size="s">Tag s</Tag.Root>
+      <Tag.Root size="m">Tag m</Tag.Root>
+      <Tag.Root size="l">Tag l</Tag.Root>
+      <Tag.Root size="xl">Tag xl</Tag.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,17 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Default, removable (`onRemove`), `disabled`, and disabled with remove (inactive close control). */
+export default function TagExampleStates() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>Default</Tag.Root>
+      <Tag.Root onRemove={() => undefined}>With remove</Tag.Root>
+      <Tag.Root disabled>Disabled</Tag.Root>
+      <Tag.Root disabled onRemove={() => undefined}>
+        Disabled, remove inactive
+      </Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/with-icon.tsx

@@ -0,0 +1,23 @@
+import { Icon, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Two tags with leading icons and text. */
+export default function TagExampleWithIcon() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>
+        <Tag.Icon>
+          <Icon name="status.locked" />
+        </Tag.Icon>
+        <span>Secured</span>
+      </Tag.Root>
+      <Tag.Root>
+        <Tag.Icon>
+          <Icon name="field.email" />
+        </Tag.Icon>
+        <span>Newsletter</span>
+      </Tag.Root>
+    </div>
+  );
+}