prime-ui-kit 0.0.1

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

@@ -0,0 +1,143 @@
+{
+  "name": "prime-ui-kit",
+  "version": "0.0.1",
+  "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",
+    "component-library",
+    "composable",
+    "css-modules",
+    "css-variables",
+    "dark-mode",
+    "data-table",
+    "datepicker",
+    "design-system",
+    "design-tokens",
+    "dialog",
+    "drawer",
+    "dropdown",
+    "esm",
+    "forms",
+    "framer-motion",
+    "light-mode",
+    "lucide-react",
+    "modal",
+    "nextjs",
+    "notifications",
+    "npm-package",
+    "popover",
+    "prime-ui",
+    "prime-ui-kit",
+    "react",
+    "react-19",
+    "react-aria",
+    "react-components",
+    "react-day-picker",
+    "react-ui",
+    "reactjs",
+    "remix",
+    "select",
+    "sidebar",
+    "table",
+    "theming",
+    "toast",
+    "tooltip",
+    "typescript",
+    "ui-components",
+    "ui-kit",
+    "vite"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/esurkov1/prime-ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/esurkov1/prime-ui/issues"
+  },
+  "homepage": "https://github.com/esurkov1/prime-ui#readme",
+  "files": [
+    "dist",
+    "src/styles/*.css",
+    "src/components/**/COMPONENT.md",
+    "src/layout/**/COMPONENT.md",
+    "src/components/**/examples/**",
+    "src/layout/**/examples/**",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "date-fns": "^4.1.0",
+    "react-day-picker": "^9.14.0",
+    "react-aria-components": "^1.16.0",
+    "@biomejs/biome": "latest",
+    "@testing-library/jest-dom": "latest",
+    "@testing-library/react": "latest",
+    "@testing-library/user-event": "latest",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^5",
+    "@vitest/coverage-v8": "^4.1.0",
+    "jsdom": "latest",
+    "esbuild": "^0.27.0",
+    "typescript": "^5",
+    "vite": "^7",
+    "vitest": "latest"
+  },
+  "peerDependencies": {
+    "date-fns": "^4.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-aria-components": "^1.16.0",
+    "react-day-picker": "^9.14.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./styles.css": "./src/styles/globals.css",
+    "./tokens.css": "./src/styles/tokens.css",
+    "./theme-light.css": "./src/styles/theme-light.css",
+    "./theme-dark.css": "./src/styles/theme-dark.css",
+    "./bundle.css": "./dist/index.css",
+    "./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 && 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 .",
+    "check:ci": "biome ci .",
+    "check:fix": "biome check . --write --unsafe",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "bun run check:ci && bun run typecheck && bun run test && bun run build",
+    "verify:quick": "bun run check:ci && bun run typecheck && bun run test",
+    "verify:tokens": "bun run tokens:build && git diff --exit-code -- src/styles/tokens.css src/styles/theme-light.css src/styles/theme-dark.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "type": "module",
+  "dependencies": {
+    "framer-motion": "^12.38.0",
+    "lucide-react": "^0.577.0",
+    "react-router-dom": "^7.13.1"
+  }
+}

package/src/components/accordion/COMPONENT.md

@@ -0,0 +1,213 @@
+# 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
+
+Single open section at a time, **`layout="grouped"`** (one frame), **`Accordion.Icon as={LucideIcon}`** plus **`Accordion.Arrow`** on each trigger, and rich body copy with a **`LinkButton`**. For **`size`** steps, **`type="multiple"`** / **`layout="separate"`**, disabled and **`collapsible={false}`**, controlled **`value`**, **`Accordion.Arrow`** with **`openIcon` / `closeIcon`**, **`Accordion.Icon as="span"`**, and full-bleed width in preview, see the runnable **`./examples/*.tsx`** files and the playground snippets listed below (full source in those files—avoid duplicating long demos here).
+
+**Imports:** in this repo use the **`@/…`** paths shown; published apps import the same components from **`prime-ui-kit`**.
+
+```tsx
+import { Accordion } from "@/components/accordion/Accordion";
+import { LinkButton } from "@/components/link-button/LinkButton";
+import { Typography } from "@/components/typography/Typography";
+import { Package, ShieldCheck, Truck } from "lucide-react";
+
+export function Example() {
+  return (
+    <Accordion.Root type="single" 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>
+  );
+}
+```
+
+### Examples (source)
+
+| File | Intent |
+|------|--------|
+| [`./examples/01-faq-marketing.tsx`](./examples/01-faq-marketing.tsx) | FAQ: `type="single"`, `layout="grouped"`, **`Accordion.Icon as={Icon}`** + default chevron (**aligns with** `playground/snippets/accordion/composition.tsx`). |
+| [`./examples/02-settings-panels.tsx`](./examples/02-settings-panels.tsx) | Settings: **`type="multiple"`**, **`layout="separate"`**, **`defaultValue`** as string array (**aligns with** `playground/snippets/accordion/variants-layout-type.tsx`). |
+| [`./examples/03-checkout-order-summary.tsx`](./examples/03-checkout-order-summary.tsx) | Checkout: **`Accordion.Arrow openIcon` / `closeIcon`** (plus default chevron on another item) and links in the body (**aligns with** `playground/snippets/accordion/features-arrow.tsx`). |
+| [`./examples/04-api-docs-sections.tsx`](./examples/04-api-docs-sections.tsx) | Controlled **`value`** + **`onValueChange`** with `type="single"` (**aligns with** `playground/snippets/accordion/controlled.tsx`). |
+| [`./examples/05-knowledge-base-categories.tsx`](./examples/05-knowledge-base-categories.tsx) | **`collapsible={false}`**, **`Accordion.Item disabled`**, **`defaultValue`** (**aligns with** `playground/snippets/accordion/states.tsx`). |
+
+### Playground snippets
+
+Demos wired from [`playground/sections/AccordionSection.tsx`](../../../playground/sections/AccordionSection.tsx) (Russian copy; same public API as this doc):
+
+| Snippet | Intent |
+|---------|--------|
+| [`playground/snippets/accordion/sizes.tsx`](../../../playground/snippets/accordion/sizes.tsx) | **`size`**: `s` / `m` / `l` / `xl` ladder. |
+| [`playground/snippets/accordion/variants-layout-type.tsx`](../../../playground/snippets/accordion/variants-layout-type.tsx) | **`layout`** `grouped` vs `separate`; **`type="multiple"`** with array **`defaultValue`**. |
+| [`playground/snippets/accordion/states.tsx`](../../../playground/snippets/accordion/states.tsx) | **`disabled`**, initial **`defaultValue`**, **`collapsible={false}`** in `single`. |
+| [`playground/snippets/accordion/controlled.tsx`](../../../playground/snippets/accordion/controlled.tsx) | External buttons + **`value` / `onValueChange`**. |
+| [`playground/snippets/accordion/composition.tsx`](../../../playground/snippets/accordion/composition.tsx) | Trigger row: **`Accordion.Icon as={Icon}`**, label in **`span`**, **`Accordion.Arrow`**. |
+| [`playground/snippets/accordion/full-width.tsx`](../../../playground/snippets/accordion/full-width.tsx) | Root fills preview column (**`examplePreviewBleed`** in playground). |
+| [`playground/snippets/accordion/icon-as.tsx`](../../../playground/snippets/accordion/icon-as.tsx) | **`Accordion.Icon as="span"`** with arbitrary child markup (e.g. Lucide as child). |
+| [`playground/snippets/accordion/features-arrow.tsx`](../../../playground/snippets/accordion/features-arrow.tsx) | **`openIcon` / `closeIcon`** vs default rotating chevron. |
+
+**LLM note:** Prefer reading **`./examples/*.tsx`** and the **`playground/snippets/accordion/*.tsx`** files for full markup and prop combinations; 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,63 @@
+import { CreditCard, Package, Truck } from "lucide-react";
+import { Accordion } from "@/components/accordion/Accordion";
+import { Typography } from "@/components/typography/Typography";
+
+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" 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,63 @@
+import { Bell, Lock, User } from "lucide-react";
+import { Accordion } from "@/components/accordion/Accordion";
+import { Typography } from "@/components/typography/Typography";
+
+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" 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>
+  );
+}