prime-ui-kit 0.2.5 → 0.3.2

package/dist/tokens/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../tokens/semantic.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAwGvB,2FAA2F;;;;;;;;;;;;;;;;;;QAkB3F;;WAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA2FH;;;;;;WAMG;;YAED,yEAAyE;;;;;YAKzE,sEAAsE;;;;;YAKtE,sEAAsE;;;;;YAKtE,qEAAqE;;;;;YAKrE,mEAAmE;;;;;YAKnE,+FAA+F;;;;;YAK/F,mEAAmE;;;;;YAKnE,4EAA4E;;;;;YAK5E,6DAA6D;;;;;YAK7D,0GAA0G;;;;;YAK1G,+CAA+C;;;;;YAK/C,8CAA8C;;;;;;;;;;;;;;;;;;;;;;;IAuBlD;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;IAwBH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAsCD;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAkHH,wEAAwE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAuExE,yGAAyG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAsEzG,mFAAmF;;;;;;;;;;;;;;;;;;;;;;;;;;;QA2BnF,2FAA2F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmC3F,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;CAuBzD,CAAC"}

package/dist/tokens/themes/dark.d.ts

@@ -0,0 +1,143 @@
+export declare const darkThemeOverrides: {
+    readonly color: {
+        readonly status: {
+            readonly information: {
+                readonly background: "{color.blue.950}";
+                readonly backgroundEmphasis: "{color.blue.500}";
+                readonly foreground: "{color.blue.200}";
+                readonly border: "{color.blue.800}";
+            };
+            readonly warning: {
+                readonly background: "{color.orange.950}";
+                readonly backgroundEmphasis: "{color.orange.500}";
+                readonly foreground: "{color.orange.200}";
+                readonly border: "{color.orange.800}";
+            };
+            readonly success: {
+                readonly background: "{color.green.950}";
+                readonly backgroundEmphasis: "{color.green.500}";
+                readonly foreground: "{color.green.200}";
+                readonly border: "{color.green.800}";
+            };
+            readonly away: {
+                readonly background: "{color.yellow.950}";
+                readonly backgroundEmphasis: "{color.yellow.500}";
+                readonly foreground: "{color.yellow.200}";
+                readonly border: "{color.yellow.800}";
+            };
+            readonly feature: {
+                readonly background: "{color.purple.950}";
+                readonly backgroundEmphasis: "{color.purple.500}";
+                readonly foreground: "{color.purple.200}";
+                readonly border: "{color.purple.800}";
+            };
+            readonly verified: {
+                readonly background: "{color.sky.950}";
+                readonly backgroundEmphasis: "{color.sky.500}";
+                readonly foreground: "{color.sky.200}";
+                readonly border: "{color.sky.800}";
+            };
+            readonly error: {
+                readonly background: "{color.red.950}";
+                readonly backgroundEmphasis: "{color.red.500}";
+                readonly foreground: "{color.red.200}";
+                readonly border: "{color.red.800}";
+            };
+        };
+        readonly surface: {
+            readonly default: "{color.gray.950}";
+            readonly raised: "{color.gray.900}";
+            readonly elevated: "{color.gray.800}";
+            readonly accentSoft: "{color.gray.800}";
+            readonly dangerSoft: "{color.red.950}";
+            readonly overlay: "{color.overlay.scrimDark}";
+        };
+        readonly content: {
+            readonly primary: "{color.gray.50}";
+            readonly secondary: "{color.gray.300}";
+            readonly muted: "{color.gray.400}";
+            readonly disabled: "{color.gray.600}";
+            readonly inverse: "{color.gray.950}";
+            readonly accent: "{color.gray.200}";
+            readonly danger: "{color.red.200}";
+        };
+        readonly border: {
+            readonly subtle: "{color.gray.800}";
+            readonly separator: "{color.gray.500}";
+            readonly strong: "{color.gray.600}";
+            readonly emphasis: "{color.gray.50}";
+            readonly muted: "{color.gray.700}";
+            readonly accent: "{color.gray.500}";
+            readonly danger: "{color.red.400}";
+            readonly disabled: "{color.gray.800}";
+            readonly inverse: "{color.white}";
+        };
+        readonly action: {
+            readonly primaryBackground: "{color.gray.50}";
+            readonly primaryBackgroundHover: "{color.gray.200}";
+            readonly primaryForeground: "{color.gray.950}";
+            readonly primarySoftBackground: "color-mix(in srgb, var(--prime-ref-color-gray-50) 42%, var(--prime-ref-color-gray-950))";
+            readonly primarySoftForeground: "{color.gray.50}";
+            readonly neutralBackground: "{color.gray.900}";
+            readonly neutralBackgroundHover: "{color.gray.800}";
+            readonly neutralForeground: "{color.gray.50}";
+            readonly errorBackground: "{color.red.500}";
+            readonly errorBackgroundHover: "{color.red.600}";
+            readonly errorForeground: "{color.white}";
+        };
+        readonly focus: {
+            readonly ring: "{color.gray.100}";
+        };
+        readonly field: {
+            readonly bg: "{color.gray.900}";
+            readonly text: "{color.gray.50}";
+            readonly placeholder: "{color.gray.500}";
+            readonly border: "{color.gray.700}";
+            readonly borderHover: "{color.gray.600}";
+            readonly borderFocus: "{color.gray.300}";
+            readonly borderError: "{color.red.400}";
+        };
+        readonly tooltip: {
+            readonly background: "{color.gray.100}";
+            readonly foreground: "{color.gray.950}";
+            readonly border: "{color.gray.300}";
+        };
+        readonly dataTable: {
+            readonly dividerVertical: "color-mix(in srgb, var(--prime-sys-color-border-subtle) 78%, transparent)";
+            readonly dividerHorizontal: "color-mix(in srgb, var(--prime-sys-color-border-subtle) 86%, transparent)";
+            readonly headBackground: "{color.surface.elevated}";
+            readonly rowBackground: "{color.surface.default}";
+        };
+        readonly badge: {
+            readonly grayFilled: {
+                readonly background: "{color.gray.500}";
+            };
+            readonly pink: {
+                readonly backgroundSoft: "{color.pink.950}";
+                readonly foregroundOnSoft: "{color.pink.200}";
+                readonly backgroundEmphasis: "{color.pink.500}";
+                readonly border: "{color.pink.800}";
+            };
+            readonly teal: {
+                readonly backgroundSoft: "{color.teal.950}";
+                readonly foregroundOnSoft: "{color.teal.200}";
+                readonly backgroundEmphasis: "{color.teal.500}";
+                readonly border: "{color.teal.800}";
+            };
+        };
+    };
+    readonly elevation: {
+        readonly shadow: {
+            readonly surface: "0 1px 2px rgba(8, 10, 14, 0.35)";
+            readonly modal: "0 24px 48px rgba(8, 10, 14, 0.45)";
+            readonly tooltip: "0 14px 30px rgba(8, 10, 14, 0.5), 0 4px 10px rgba(8, 10, 14, 0.4)";
+            readonly buttonFocus: "0 0 0 2px rgba(244, 244, 245, 0.28)";
+            readonly primaryFocus: "0 0 0 2px rgba(244, 244, 245, 0.4)";
+            readonly errorFocus: "0 0 0 2px rgba(248, 113, 113, 0.38)";
+            readonly fancyButtonNeutral: "0 1px 2px rgba(8, 10, 14, 0.45), 0 0 0 1px var(--prime-sys-color-content-primary)";
+            readonly fancyButtonPrimary: "0 1px 2px rgba(8, 10, 14, 0.45), 0 0 0 1px var(--prime-sys-color-action-primaryBackground)";
+            readonly fancyButtonError: "0 1px 2px rgba(8, 10, 14, 0.45), 0 0 0 1px var(--prime-sys-color-action-errorBackground)";
+        };
+    };
+};
+//# sourceMappingURL=dark.d.ts.map

package/dist/tokens/themes/dark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dark.d.ts","sourceRoot":"","sources":["../../../tokens/themes/dark.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJrB,CAAC"}

package/dist/tokens/themes/light.d.ts

@@ -0,0 +1,16 @@
+export declare const lightThemeOverrides: {
+    readonly color: {
+        readonly focus: {
+            readonly ring: "{color.gray.950}";
+        };
+    };
+    readonly elevation: {
+        readonly shadow: {
+            readonly tooltip: "0 12px 28px rgba(15, 17, 21, 0.22), 0 4px 10px rgba(15, 17, 21, 0.16)";
+            readonly buttonFocus: "0 0 0 2px rgba(15, 17, 21, 0.14)";
+            readonly primaryFocus: "0 0 0 2px rgba(15, 17, 21, 0.2)";
+            readonly errorFocus: "0 0 0 2px rgba(220, 38, 38, 0.2)";
+        };
+    };
+};
+//# sourceMappingURL=light.d.ts.map

package/dist/tokens/themes/light.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light.d.ts","sourceRoot":"","sources":["../../../tokens/themes/light.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;CActB,CAAC"}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.2.5",
+  "version": "0.3.2",
   "description": "React 19 UI kit: CSS Modules, semantic design tokens (--prime-sys-*), composable components — forms, modals, selects, tables, navigation, overlays. TypeScript, ESM, a11y-oriented.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "keywords": [
     "a11y",
     "accessible",
@@ -59,7 +62,11 @@
   "homepage": "https://github.com/esurkov1/prime-ui#readme",
   "files": [
     "dist",
-    "src/styles",
+    "src/styles/*.css",
+    "src/components/**/COMPONENT.md",
+    "src/layout/**/COMPONENT.md",
+    "src/components/**/examples/**",
+    "src/layout/**/examples/**",
     "LICENSE"
   ],
   "publishConfig": {
@@ -80,7 +87,6 @@
     "@vitest/coverage-v8": "^4.1.0",
     "jsdom": "latest",
     "esbuild": "^0.27.0",
-    "tsup": "latest",
     "typescript": "^5",
     "vite": "^7",
     "vitest": "latest"
@@ -109,8 +115,10 @@
     "./components.css": "./dist/components/index.css"
   },
   "scripts": {
+    "clean": "rm -rf dist .dts-stage coverage playground/dist",
     "tokens:build": "bun run scripts/build-tokens.ts",
-    "build": "bun run tokens:build && tsup --dts-only --config tsup.dts.config.ts && bun run scripts/rm-dist.ts && bun run scripts/bundle-lib.ts && bun run scripts/copy-dts-to-dist.ts",
+    "build": "bun run tokens:build && bun run scripts/bundle-lib.ts",
+    "prepublishOnly": "bun run clean && bun run build",
     "dev": "bun run scripts/bundle-lib.ts --watch",
     "playground:dev": "vite playground --config playground/vite.config.ts",
     "check": "biome check .",

package/src/components/accordion/COMPONENT.md

@@ -0,0 +1,190 @@
+# Accordion
+
+**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 compound disclosure pattern: each item has a header trigger and expandable body content, with optional height animation. Use it to stack optional sections (FAQ, settings groups, legal blocks) without leaving the page.
+
+**When to use**
+
+- Long pages where users open only the sections they need: FAQs, delivery and return copy, grouped settings, order or project detail blocks, knowledge-base articles, sidebars and narrow columns.
+- One-at-a-time expansion (`type="single"`) or several open panels (`type="multiple"`) when comparing sections side by side.
+- Visual density control via `layout="grouped"` (single frame) vs `layout="separate"` (card-like items).
+
+**When not to use**
+
+- Switching one shared panel with a horizontal tab list — prefer [Tabs](../tabs/COMPONENT.md).
+- When every section must stay visible without extra interaction.
+- Deep hierarchical navigation — prefer a flat list, tree, or separate routes instead of nested accordions.
+- Very heavy bodies inside animated panels (large lists, charts) if `ResizeObserver`-driven height updates become costly.
+
+## Composition
+
+- **`Accordion.Root`** wraps all items and supplies `size`, `type`, `layout`, and open-state (`value` / `defaultValue` / `onValueChange`).
+- Per item the order is: **`Accordion.Item`** (required `value`) → **`Accordion.Header`** → **`Accordion.Trigger`** (native `button`) as a **direct** child of the header → **`Accordion.Content`** as a **sibling** of the header (same item), not nested inside the trigger.
+- Put label text, optional **`Accordion.Icon`**, and optional **`Accordion.Arrow`** inside the trigger as needed.
+- **`Accordion.Content`** renders an outer **`section`** (ARIA region) and an inner padded block; `className` applies to the inner block; `style` is merged onto the outer node with the animation height variable.
+
+### Canonical example
+
+```tsx
+import { Accordion, LinkButton, Typography } from "prime-ui-kit";
+import { Package, ShieldCheck, Truck } from "lucide-react";
+
+export function Example() {
+  return (
+    <Accordion.Root type="single" size="m" layout="grouped" defaultValue="delivery" collapsible>
+      <Accordion.Item value="delivery">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Truck} />
+            <span>Delivery &amp; tracking</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" tone="muted">
+            Orders ship within one business day. Tracking links are sent by email when the carrier
+            scans the package.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="returns">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Package} />
+            <span>Returns</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" tone="muted">
+            Unopened items in original packaging are returnable within 30 days. Opened goods may
+            qualify for store credit—see the policy for exceptions.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="compliance">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={ShieldCheck} />
+            <span>Compliance</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" tone="muted">
+            We process card data in line with PCI DSS. For regional privacy questions, read the
+            notices linked below.
+          </Typography.Root>
+          <LinkButton.Root href="#" size="s">
+            Privacy &amp; data processing
+          </LinkButton.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}
+```
+
+### Extended examples
+
+- [`./examples/01-faq-marketing.tsx`](./examples/01-faq-marketing.tsx) — Marketing FAQ: single panel, grouped layout, icons and chevron on each trigger.
+- [`./examples/02-settings-panels.tsx`](./examples/02-settings-panels.tsx) — Account settings: `type="multiple"` and `layout="separate"` so several sections stay open as cards.
+- [`./examples/03-checkout-order-summary.tsx`](./examples/03-checkout-order-summary.tsx) — Checkout: custom `Accordion.Arrow` icons plus policy links in the panel body.
+- [`./examples/04-api-docs-sections.tsx`](./examples/04-api-docs-sections.tsx) — API docs: controlled `value` / `onValueChange` for syncing open section with routing or in-page navigation.
+- [`./examples/05-knowledge-base-categories.tsx`](./examples/05-knowledge-base-categories.tsx) — Support hub: `collapsible={false}` and a disabled item for plan-gated content.
+
+**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
+
+- Use **`type="single"`** for at most one open item, **`type="multiple"`** for any subset open; `defaultValue` is a string or string array matching the type.
+- **Controlled:** pass **`value`** (`string` or `string[]`); updates go through **`onValueChange`**. In `single`, the callback receives a string; closing the open item yields **`""`**. In `multiple`, the callback receives the open id array.
+- **Uncontrolled:** omit `value` and optionally set **`defaultValue`**.
+- **`collapsible`** applies only to **`type="single"`**; set **`collapsible={false}`** to keep at least one item open once opened (cannot collapse to none).
+- **`disabled`** on **`Accordion.Item`** disables the trigger and blocks toggling for that item.
+- **`Accordion.Trigger`:** custom **`onClick`** runs first; call **`preventDefault()`** on the event if you need to cancel the built-in toggle. Prefer **`type="button"`** (default) inside forms.
+- **`Accordion.Arrow`** icons use **`aria-hidden`**; the accessible name must come from trigger text (or an explicit label pattern you add).
+- Keyboard: trigger is a button — **Enter** / **Space** activate; focus ring follows **`focus-visible`** from the theme.
+- **`data-state`** is **`open` | `closed`** on item, trigger, and content wrapper; **`data-disabled`** when the item is disabled.
+- **`AccordionContentProps`** is typed from **`HTMLDivElement`** attributes even though the outer DOM node is **`section`** — target the real **`section`** in tests and CSS when needed.
+
+## API
+
+### Accordion.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"single" \| "multiple"` | `"single"` | No | One open item vs many. |
+| value | `string \| string[]` | — | No | Controlled open value(s). |
+| defaultValue | `string \| string[]` | — | No | Initial open value(s) when uncontrolled. |
+| onValueChange | `(value: string \| string[]) => void` | — | No | `single`: string (empty string if none open). `multiple`: string array. |
+| collapsible | `boolean` | `true` | No | `single` only: if `false`, the open item cannot be closed to leave none open. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger, icons, and content spacing. |
+| layout | `"grouped" \| "separate"` | `"grouped"` | No | Shared frame vs card-like items. |
+| className | `string` | — | No | Root wrapper class. |
+| children | `React.ReactNode` | — | No | `Accordion.Item` nodes. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Passed to the root `div`. |
+
+### Accordion.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Unique id among siblings under one root. |
+| disabled | `boolean` | `false` | No | Item cannot open; trigger disabled. |
+| className | `string` | — | No | Item wrapper class. |
+| children | `React.ReactNode` | — | No | Header + content. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Passed to the item `div`. |
+
+### Accordion.Header
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Header class. |
+| children | `React.ReactNode` | — | No | Typically one `Accordion.Trigger`. |
+| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Rendered as `h3`. |
+
+### Accordion.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Prefer `button` in forms. |
+| className | `string` | — | No | Button class. |
+| children | `React.ReactNode` | — | No | Label and optional icon/arrow slots. |
+| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | `onClick` invoked before internal toggle. |
+
+### Accordion.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `"div"` | No | Polymorphic element for the icon wrapper. |
+| className | `string` | — | No | Wrapper class. |
+| children | `React.ReactNode` | — | No | Icon content when using a text-only element. |
+| …rest | Depends on `as` | — | No | Props for the chosen element (except `as` / `className`). |
+
+### Accordion.Arrow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| openIcon | `React.ElementType` | `ChevronDown` | No | Default chevron rotates when closed vs open; or paired with `closeIcon`. |
+| closeIcon | `React.ElementType` | — | No | If set and differs from `openIcon`, shows two icons without rotation. |
+| className | `string` | — | No | `span` wrapper class. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Icons are `aria-hidden`. |
+
+### Accordion.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the inner padded block. |
+| style | `React.CSSProperties` | — | No | Merged on the outer `section` with the animated height CSS variable. |
+| children | `React.ReactNode` | — | No | Panel body. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Spread on the outer `section`; `aria-labelledby` / `aria-hidden` come from context. |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md) — body copy inside `Accordion.Content`.
+- [Button](../button/COMPONENT.md) — external actions coordinated with controlled `value` on the root.
+- [Tabs](../tabs/COMPONENT.md) — alternative when one panel switches without a vertical stack of headers.
+- [Modal](../modal/COMPONENT.md) and [Drawer](../drawer/COMPONENT.md) — often host accordions in limited vertical space.

package/src/components/accordion/examples/01-faq-marketing.tsx

@@ -0,0 +1,62 @@
+import { CreditCard, Package, Truck } from "lucide-react";
+import { Accordion, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * FAQ-style marketing page: single expansion, grouped frame, triggers with icons and chevron.
+ */
+export default function AccordionExampleFaqMarketing() {
+  return (
+    <Accordion.Root type="single" size="m" layout="grouped" defaultValue="shipping">
+      <Accordion.Item value="shipping">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Truck} />
+            <span>When will my order ship?</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <Typography.Root as="p" variant="body-default" className={styles.lead}>
+              Most in-stock orders leave our warehouse within one business day. You will receive a
+              tracking link by email as soon as the carrier scans the package.
+            </Typography.Root>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="returns">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Package} />
+            <span>What is your return policy?</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Unopened items in original packaging can be returned within 30 days for a full refund.
+            Opened consumables may be eligible for store credit—contact support with your order
+            number.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="payment">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={CreditCard} />
+            <span>Which payment methods do you accept?</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            We accept major cards, digital wallets, and purchase orders for approved business
+            accounts. All transactions are processed over encrypted connections.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/02-settings-panels.tsx

@@ -0,0 +1,67 @@
+import { Bell, Lock, User } from "lucide-react";
+import { Accordion, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Account settings: compare several open sections at once with `type="multiple"` and card-like
+ * `layout="separate"`.
+ */
+export default function AccordionExampleSettingsPanels() {
+  return (
+    <Accordion.Root
+      type="multiple"
+      size="m"
+      layout="separate"
+      defaultValue={["profile", "notifications"]}
+    >
+      <Accordion.Item value="profile">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={User} />
+            <span>Profile</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <Typography.Root as="p" variant="body-default" className={styles.lead}>
+              Update your display name, avatar, and public contact details. Changes apply across all
+              signed-in devices after you save.
+            </Typography.Root>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="notifications">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Bell} />
+            <span>Notifications</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Choose email, push, and in-app channels. Digest mode bundles low-priority updates into
+            one daily summary.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="security">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Lock} />
+            <span>Security</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Manage passwords, two-factor authentication, and active sessions. We recommend enabling
+            an authenticator app for administrator roles.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/03-checkout-order-summary.tsx

@@ -0,0 +1,87 @@
+import { Minus, Plus } from "lucide-react";
+import { Accordion, LinkButton, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Checkout flow: custom open/close icons on the arrow, dense copy, and a policy link in the body.
+ */
+export default function AccordionExampleCheckoutOrderSummary() {
+  return (
+    <Accordion.Root type="single" size="m" layout="grouped" defaultValue="totals">
+      <Accordion.Item value="totals">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Order totals</span>
+            <Accordion.Arrow openIcon={Plus} closeIcon={Minus} />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-default">
+                Subtotal
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-default">
+                $124.00
+              </Typography.Root>
+            </div>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-default" tone="muted">
+                Estimated tax
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-default" tone="muted">
+                $9.92
+              </Typography.Root>
+            </div>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-small" weight="semibold">
+                Due today
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-small" weight="semibold">
+                $133.92
+              </Typography.Root>
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="delivery">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Delivery window</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Arrives Tuesday–Thursday depending on carrier volume. You can reschedule from the
+            confirmation email.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="terms">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Terms &amp; privacy</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.stack}>
+            <Typography.Root as="p" variant="body-small" className={styles.lead}>
+              By placing this order you agree to our terms of sale and refund policy.
+            </Typography.Root>
+            <div className={styles.actions}>
+              <LinkButton.Root href="#" size="s">
+                Terms of sale
+              </LinkButton.Root>
+              <LinkButton.Root href="#" size="s">
+                Privacy policy
+              </LinkButton.Root>
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}