@wallarm-org/claude-design 0.0.0-stage → 4.9.0

package/dist/project/README.md

@@ -0,0 +1,265 @@
+Generated from wallarm/design-system — change it in code and run /claude-design-sync there.
+
+# Wallarm Design System
+
+Wallarm's product UI system uses the real library components, semantic tokens and Geist fonts. Build with components first, style with semantic tokens second, and reach for primitives last. The generated canvas bundle uses the page's React 18 runtime.
+
+## Rules
+
+These are the design system's own rules (`src/guidelines/rules.md`), embedded at build time. On the canvas, read `get_guideline` as "the pattern guide": they ship in the npm package under `dist/guidelines/` (`rules.md`, `foundations/`, `patterns/`) and through the MCP server's `get_guideline` tool.
+
+Every numeric utility is in px, not 4px steps: p-16 is 16px, p-4 is 4px. Translate Tailwind habits (p-4 → p-16, gap-6 → gap-24, w-64 → w-256).
+
+Before composing a screen, call get_guideline for the pattern (app shell, list page, table, drawer, form, dialog, filters, empty state, settings, auth). Wrong → right:
+
+- p-5, gap-3, p-10 → stay on the scale: 1, 2, 4, 6, 8, 12, 16, 20, 24, 28, 32, 40, 48, 64…
+- space-y-4, margins per child → <VStack gap={16}>, <HStack gap={8}>
+- Padded page wrapper → Page > PageHeader / PageToolbar / PageContent own the 24px gutter
+- p-* on Card, DrawerBody, DialogBody, PageToolbar, Table → none; they own their padding
+- className on Text, Heading, Field, Drawer/Dialog Header/Body/Footer → wrap in your own element
+- Raw <h1>, <p>, <label> → <Heading as="h2" size="lg">, <Text size="sm">, Field
+- <Text> default (16px) for body → size="sm" (md is only an alias of sm)
+- leading-none (0px), leading-5 (5px) → leading-sm or leading-20
+- weight="semibold" → weight is light|regular|medium|bold (medium = 450)
+- bg-primary, text-muted, bg-card, bg-white, text-gray-500 → bg-bg-primary, text-text-secondary, bg-bg-surface-1
+- text-error, bg-red-500 → danger tokens; categorical color → Badge color
+- dark: variant, setting data-theme → semantic tokens, useTheme().setTheme()
+- rounded-lg, rounded, rounded-[15px] → rounded-8 (controls), rounded-12 (panels)
+- shadow-* on DS components, z-* on overlays → never; they own both
+- focus:ring → focus-visible:ring-3 ring-focus-primary outline-none
+- size, DIALOG_SIZES, DRAWER_SIZES → width: Dialog 400 confirm, 560 default, 960 picker; Drawer 640 default, 700 Timeline form
+- Dialog, useToast from the root → @wallarm-org/design-system/Dialog, /Toast
+- Field invalid → error on the control + FieldError
+- Hand-built side menu → RemoteShell config={NavConfig}
+- ConfirmDialog, FilterBar, Combobox → compose Dialog parts, PageToolbar + FilterDropdown, Select + useSelectSearch
+- data-slot in tests → data-testid
+
+## Screen sampler
+
+[`sampler.dc.html`](sampler.dc.html) is one canonical 1440-wide screen built only from this system through `x-import`: `AppShell`, a resource list `Page` with `PageHeader` and its create action, a `PageToolbar` with search and status tabs, an entity `Table` with a status `Badge` column and an always-visible actions column, a no-results `EmptyState`, and a detail `Drawer` opened by `open` with an empty nested table. It follows the `resource-list-page`, `entity-table` and `detail-drawer` pattern guides. Start a screen from it rather than from raw `div`s; the export checks that every class it uses exists in `components/bundle.css`.
+
+## Content
+
+- Use sentence case for buttons, labels, titles, menu items and column headers.
+- Label actions with a verb and object: `Delete rule` still reads out of context.
+- Keep field labels short. Reword long labels and table headers instead of truncating them.
+- Use one primary button per view. Reserve destructive actions for changes that are hard to undo.
+- Pair status colour with an icon or a word.
+
+## Color
+
+- Use semantic families: `color-text-*`, `color-icon-*`, `color-bg-*`, `color-border-*`, `color-states-*` and `color-component-*`. Their values switch between light and dark themes.
+- Wallarm orange marks the primary action and brand moments. Use `color-*-ai` for assistant content and AI-generated results.
+- Use `text-text-primary` for readable body text and `text-text-secondary` for supporting copy. Hint and tertiary colours are not suitable for essential information.
+- Start with `bg-bg-page-bg`, then layer surfaces with `bg-bg-surface-1` through `bg-bg-surface-5`.
+- Soft status fills use `color-bg-<status>`, solid fills use `color-bg-fill-<status>`. The `-alt` families are for inverted surfaces; `-fixed` values stay the same in both themes.
+- Interaction state tokens describe overlays on resting fills. Focus tokens supply visible rings.
+- Keep syntax token mappings unchanged. Use badge palettes through `Badge`, `Tag` and `NumericBadge`.
+- Check contrast in the actual design, especially orange, success green and muted text at small sizes.
+
+## Type
+
+- Geist Variable is the UI font; Geist Mono is for code and identifiers. Geist Pixel is reserved for display moments and splash art.
+- The bundle's reset leaves raw `h1`–`h6`, `p`, `ul`, `ol` and `li` with no size, margin or list style; use `List` where one fits, and `Code` for code.
+- Prefer `Text`, `Heading` and `Code` over raw typography classes. Use the size and weight choices documented on their cards.
+- Use paired size and line-height tokens. `body-*`, `heading-*`, `display-*` and `code-*` are type-style names in the token document, not CSS classes — `class="body-sm"` renders nothing. Use `Text`, `Heading` or `Code`, or the `text-<size>` utility named in each style's usage ("Tailwind: text-sm font-sans-display"). The `text-<size>` utilities (`text-xs`, `text-sm`, `text-md`, `text-base`, `text-lg`…) use this system's type tokens, not Tailwind's defaults, and `text-<colour>` takes a semantic token such as `text-text-secondary`.
+
+## Spacing, radius, elevation
+
+- The 1px base covers sizing too: `w-`, `h-`, `size-`, `min-/max-w-`, `inset-`, `top-`/`right-`/`bottom-`/`left-`. The full scale: 0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 28, 32, 36, 40, 44, 48, 56, 64, 80, 96, 112, 128, 144.
+- The CSS is precompiled: only the classes listed in [`components/UTILITIES.md`](components/UTILITIES.md) exist. There is no JIT and no arbitrary values (`p-[13px]`, `w-[420px]`), and a missing class silently renders nothing. For any other value use an inline style with a token: `style="gap: var(--spacing-16)"`.
+
+| Tailwind habit | Here |
+| --- | --- |
+| `p-1` / `p-2` / `p-3` / `p-4` | `p-4` / `p-8` / `p-12` / `p-16` |
+| `p-6` / `p-8` / `p-12` | `p-24` / `p-32` / `p-48` |
+| `gap-2` / `gap-4` / `gap-6` / `gap-8` | `gap-8` / `gap-16` / `gap-24` / `gap-32` |
+| `mt-6` | `mt-24` |
+| `w-64` / `w-80` / `w-96` | `w-256` / `w-320` / `style="width: 384px"` (`w-384` is not compiled) |
+| `h-10` / `size-8` | `h-40` / `size-32` |
+| `rounded-md` | `rounded-6` (compact items; pills `rounded-full`) |
+- Use the shadow scale for elevation on your own elements.
+- Components supply motion; respect `prefers-reduced-motion`.
+
+## Layout on a canvas
+
+- Start from the [screen sampler](#screen-sampler). `AppShell` is the frame; `Card` → `CardHeader` / `CardContent` / `CardFooter` groups content.
+- A number prop such as `gap` is a `{{hole}}` from `renderVals()`: `gap="{{rowGap}}"` with `rowGap: 6`.
+- When a raw grid is unavoidable, use the layout kit: `grid grid-cols-4 gap-16`, `md:grid-cols-2`, `col-span-2`, `w-1/3`, `max-w-7xl`, `divide-y divide-border-primary-light`, `first:`/`last:` padding and border resets. Give flex and grid children `min-w-0` so they can shrink.
+- Responsive variants (`sm:`, `md:`, `lg:`, `xl:`) follow the viewport, not the artboard.
+- Check the console: in development the canvas warns once for each class that has no CSS.
+
+## Iconography
+
+- Use the supplied icon library. Missing icons should be added in Figma and synced through the repository.
+- Icons use `currentColor`: apply `text-icon-primary`, `text-icon-secondary` or a status icon token. Sizes are `icon-xs`, `icon-sm`, `icon-md`, `icon-lg`, `icon-xl` and `icon-2xl`; `icon-md` is 16px.
+- Third-party brand icons retain their brand colours.
+
+## Logo
+
+- Use `Logo` with `type="full"`, `"icon"` or `"wordmark"`. Its `default` colour follows the theme; `white` keeps the orange mark, and `full-white` makes the whole logo white.
+- Never stretch the logo, rebuild its wordmark from text or invent a mark colour.
+
+## Accessibility
+
+- Prefer semantic elements and the supplied composite controls for keyboard and ARIA behaviour.
+- Label every form control. Place `FieldLabel` with its `Field` and use explicit accessible names on icon-only actions.
+- Keep visible focus and verify keyboard navigation. Put analytics and test attributes on the actual interactive component.
+
+## Consuming this system
+
+The namespace is **WallarmDS**. Read a component's guide before using its props and composition. Names are flat: `WallarmDS.DialogContent`, not `WallarmDS.Dialog.Content`.
+
+### Runtime and load order
+
+Load `tokens.css` → `components/bundle.css` → `components/bundle.js`. The page supplies React 18 and ReactDOM before the bundle; use that runtime. The bundle assigns `window.WallarmDS`. Font files are under `fonts/` and are declared by `tokens.css`.
+
+On a Design canvas, choose **Wallarm Design System** and mount a component with `x-import`. On a regular React page, use the corresponding React component and camelCase props. The concatenated `components/index.d.ts` is API documentation for the artifact, not a standalone installable TypeScript package.
+
+### Canvas props and values
+
+`component-from-global-scope` names the global component. Canvas attribute names are kebab-case: `default-open`, `on-value-change`, `class-name`. Strings can be written directly. Booleans, numbers, arrays, objects and callbacks must be values from a classic JavaScript `renderVals()` function, passed through `{{holes}}`; `loading="false"` would be a string. Combine example values into the canvas's one `renderVals()` function. Nested `x-import` nodes become React children. Scripts use classic JavaScript: no JSX, TypeScript or module imports.
+
+### Root, dark artboards and overlays
+
+Wrap each artboard with `WallarmDS.Root`. It scopes semantic tokens and portal content without changing the page's `html` theme or localStorage. Set `theme="dark"` on it for a dark artboard (`theme="light"` is the default).
+
+Keep Dialog, DropdownMenu, Popover and other overlay parts inside that Root. To show an overlay in a static composition, use the component's full composition from its guide and open it by the prop it has:
+
+- DropdownMenu, Select, Tooltip, Calendar, FilterDropdown: `default-open="{{shown}}"` with `shown: true`.
+- Dialog, Drawer, Popover, SearchModal: no `default-open`; pass `open="{{shown}}"` with `shown: true`, plus `on-open-change` from `DCLogic` state when the prototype should close.
+
+Do not substitute ThemeProvider: it changes the page-level theme.
+
+### Icons
+
+Icons are under `WallarmDS.Icons.`; the icon name is the one the story imports. Do not draw replacements for existing icons.
+
+## From a Storybook story to an artboard
+
+Component guides carry every Storybook story verbatim. They are reference: read a story, then write your own artboard (`<x-dc>` markup plus one classic-JS `class Component extends DCLogic` whose `renderVals()` returns the values for `{{holes}}`). Do not define `window.X` components or import anything.
+
+- `import { X } from '@wallarm-org/design-system'` → `WallarmDS.X` in `x-import`; icons → `WallarmDS.Icons.X` (or the icon prop by name).
+- JSX element → `<x-import component-from-global-scope="WallarmDS.X">`; camelCase props → kebab-case attributes; non-string values → `{{hole}}` from `renderVals()`.
+- `useState` / `useReducer` → `this.state` + `this.setState` in `DCLogic`; event handlers → methods returned from `renderVals()`.
+- Fixture/mock data → constants in the artboard's script (shape copied from the shipped mock, values the screen's own).
+- Render-prop props (`cell`, `header`, `renderMenuAction`, `renderExpandedRow`, …) → build the element in `renderVals()` with `React.createElement(WallarmDS.X, props, …children)` (`var h = React.createElement;`). JSX is not available on the canvas; `React` is the page's React 18 global.
+- Storybook-only parts are ignored: `fn()`, `args` controls, decorators, `play`.
+- Everything inside `WallarmDS.Root`.
+
+Hooks cannot run in `renderVals()`. Use the design system's non-hook path instead: `useChartTimeFormatters` → `WallarmDS.formatChartDate`, `formatChartDateTime`, `formatChartHour`, `formatChartTimezone`; `useToast` → `WallarmDS.toaster.create(...)` from a `DCLogic` handler. `useMemo` / `useCallback` → plain computation in `renderVals()`; `useEffect` → a `DCLogic` lifecycle method such as `componentDidMount`.
+
+### Worked translations
+
+From `Button/Button.stories.tsx#Basic` (the `args` spread and `data-testid` are Storybook-only):
+
+```tsx
+<Button {...args} data-testid='button'>
+  Button
+</Button>
+```
+
+```html
+<x-import component-from-global-scope="WallarmDS.Root">
+  <x-import component-from-global-scope="WallarmDS.Button">Button</x-import>
+</x-import>
+```
+
+From `Table/Table.stories.tsx#MasterCellWithDrawer`: the first column's `cell` is a render prop, and `activeRowId` state moves to `this.state`. The excerpt is abridged, not verbatim: the story's sorting, `className` and `Drawer` are omitted.
+
+```tsx
+const [activeRowId, setActiveRowId] = useState<string | null>(null);
+// …
+cell: ({ row }) => <Text size='xs'>{row.original.objectName}</Text>,
+// …
+<Table data={data} columns={columns} getRowId={row => row.id}
+  onMasterCellClick={handleMasterCellClick} activeRowId={activeRowId} />
+```
+
+```html
+<x-import component-from-global-scope="WallarmDS.Root">
+  <x-import component-from-global-scope="WallarmDS.Table"
+    data="{{data}}" columns="{{columns}}" get-row-id="{{getRowId}}"
+    on-master-cell-click="{{onMasterCellClick}}" active-row-id="{{activeRowId}}"></x-import>
+</x-import>
+```
+
+```js
+class Component extends DCLogic {
+  constructor(props) {
+    super(props);
+    this.state = { activeRowId: null };
+  }
+  renderVals() {
+    var h = React.createElement;
+    var self = this;
+    var columns = securityColumns.map(function (col, i) {
+      return i === 0
+        ? Object.assign({}, col, {
+            cell: function (ctx) {
+              return h(WallarmDS.Text, { size: 'xs' }, ctx.row.original.objectName);
+            },
+          })
+        : col;
+    });
+    return {
+      data: securityEvents, // constants copied from the story's mock
+      columns: columns,
+      getRowId: function (row) { return row.id; },
+      activeRowId: this.state.activeRowId,
+      onMasterCellClick: function (rowId) {
+        self.setState({ activeRowId: self.state.activeRowId === rowId ? null : rowId });
+      },
+    };
+  }
+}
+```
+
+The artifact exposes public component-subpath exports as canvas globals too, including Dialog, CodeEditor and CodeSnippet families that are absent from the npm root barrel. This does not add npm root exports. Root is a canvas-only helper. Product applications use the package's existing root or component subpath imports and compose their own providers.
+
+## Not synced
+
+This is the separate Claude Design build; the npm package still targets React 19.
+
+- BulkBar: no Storybook story; props only.
+- Checkmark: internal primitive; no guide.
+- CodeEditor/HttpResponseWithShiki: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- CodeEditor/Languages: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- CodeEditor/SyntaxErrors: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- CodeSnippet/HTMLWithHighlightJs: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- CodeSnippet/HTTPResponseWithShiki: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- CodeSnippet/JSONWithShiki: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- CodeSnippet/WithFoldingAndShowMore: preview omitted; Shiki/highlight.js adapters are not bundled (source in guide).
+- Contextual :root[data-frame-style='branded'] overrides remain in bundle.css.
+- Contextual :root[data-theme='dark'][data-frame-style='branded'] overrides remain in bundle.css.
+- DateFormatProvider: provider; use WallarmDS.Root on the canvas.
+- NavRail: no Storybook story; props only.
+- Shiki and highlight.js adapters are excluded; use the Prism adapter.
+- ThemeProvider: provider; use WallarmDS.Root on the canvas.
+- TopHeader: no Storybook story; props only.
+- app-shell-ambient-grain-blend: theme-dependent component values cannot be represented; retained in bundle.css.
+- app-shell-ambient-grain-opacity: theme-dependent component values cannot be represented; retained in bundle.css.
+- color-component-app-shell-ambient-header: context-dependent color-mix retained in bundle.css (light); retained in bundle.css.
+- color-component-app-shell-ambient-lift-soft: context-dependent color-mix retained in bundle.css (light); retained in bundle.css.
+- color-component-app-shell-ambient-lift: context-dependent color-mix retained in bundle.css (light); retained in bundle.css.
+- color-component-app-shell-ambient-shade-soft: context-dependent color-mix retained in bundle.css (light); retained in bundle.css.
+- color-component-app-shell-ambient-shade: context-dependent color-mix retained in bundle.css (light); retained in bundle.css.
+- color-data-viz-1: source placeholder omitted.
+- color-transparent: unsupported color value "transparent" (light); retained in bundle.css.
+- drawer-level-ratio: unsupported component value; retained in bundle.css.
+- src/guidelines/patterns/app-layout.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/auth-page.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/confirmation-dialogs.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/create-edit-forms.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/detail-drawer.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/empty-states.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/entity-table.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/feedback-toasts.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/filtering.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/resource-list-page.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/guidelines/patterns/settings-page.stories.tsx: pattern story, not a component; the screen sampler covers the patterns on a canvas.
+- src/icons/module/Icons.stories.tsx: icon gallery story, not a component; use `WallarmDS.Icons.<Name>`.
+- src/theme/Pixel.stories.tsx: theme gallery story, not a component; see tokens.css.
+- temp-token: source placeholder omitted.
+
+Generated component guides and types are derived from repository source and build metadata. Change them in wallarm/design-system and run /claude-design-sync there.

package/dist/project/components/Accordion/README.md

@@ -0,0 +1,354 @@
+Stacks sections behind their own headers and opens each on demand — reach for `Tabs` when a few primary sections get switched between often, and leave content on the page when people read most of it anyway. `primary` and `secondary` are inline rows for grouping; `section` is the bordered panel, and the only variant with room for `AccordionActions`.
+
+## Props as canvas attributes
+
+Use kebab-case attribute names. Pass non-string values through renderVals holes, including booleans. The full emitted API is in `components/index.d.ts`.
+
+| Attribute | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `"primary" \| "secondary" \| "section"` | no | `primary` | Visual variant of the accordion |
+| `multiple` | `boolean \| undefined` | no | `false` | Whether multiple items can be expanded at the same time |
+| `collapsible` | `boolean \| undefined` | no | `true` | Whether an expanded item can be collapsed (when `multiple` is false) |
+| `value` | `string[] \| undefined` | no | — | Controlled expanded item values |
+| `default-value` | `string[] \| undefined` | no | — | Initial expanded item values for uncontrolled usage |
+| `on-value-change` | `complex` | no | — | Callback fired when expanded items change |
+| `disabled` | `boolean \| undefined` | no | — | Disable all interaction |
+| `data-testid` | `string \| undefined` | no | — |  |
+
+## Sub-components
+
+- `WallarmDS.AccordionActions` — `AccordionActionsProps` in the declaration bundle.
+- `WallarmDS.AccordionContent` — `AccordionContentProps` in the declaration bundle.
+- `WallarmDS.AccordionItem` — `AccordionItemProps` in the declaration bundle.
+- `WallarmDS.AccordionTrigger` — `AccordionTriggerProps` in the declaration bundle.
+
+## Stories
+
+### Primary
+
+The default variant — a 40px row with the chevron ahead of the title and a hover
+fill across the full width. Opening one section closes the other: `multiple` is
+off unless you ask for it.
+
+Source: Accordion/Accordion.stories.tsx#Primary
+
+### Secondary
+
+A 24px row in small medium-weight muted type with no hover fill, for dense or
+nested groups where the header should sit behind the content it labels.
+
+Source: Accordion/Accordion.stories.tsx#Secondary
+
+### Section
+
+`section` draws each item as a bordered panel row — title left, chevron right —
+and the title takes inline content, here a `NumericBadge` carrying a count.
+
+Source: Accordion/Accordion.stories.tsx#Section
+
+### SectionWithActions
+
+`AccordionActions` renders beside the trigger rather than inside it, so buttons in
+the header act on the section without toggling it open.
+
+Source: Accordion/Accordion.stories.tsx#SectionWithActions
+
+### LongTitlePrimary
+
+Titles truncate to one line rather than wrapping — the row is a fixed height, so
+reword a long header instead of relying on the ellipsis.
+
+Source: Accordion/Accordion.stories.tsx#LongTitlePrimary
+
+### LongTitleSecondary
+
+The same 320px column at `secondary` size, where smaller type and no row padding
+leave a little more of the title visible before the ellipsis.
+
+Source: Accordion/Accordion.stories.tsx#LongTitleSecondary
+
+### Multiple
+
+`multiple` keeps several sections open at once, for when people reference sections
+on their own terms — not when the sections have to be read side by side, which is
+a layout rather than an accordion.
+
+Source: Accordion/Accordion.stories.tsx#Multiple
+
+### Disabled
+
+`disabled` on a single `AccordionItem` fades the row and blocks its toggle while the
+rest stay live; the same prop on `Accordion` locks every row at once.
+
+Source: Accordion/Accordion.stories.tsx#Disabled
+
+## Story sources
+
+### Accordion/Accordion.stories.tsx
+
+```tsx
+import { fn } from 'storybook/test';
+import type { Meta, StoryFn } from 'storybook-react-rsbuild';
+import { Button } from '../Button';
+import { NumericBadge } from '../NumericBadge';
+import { Text } from '../Text';
+import { Accordion, type AccordionProps } from './Accordion';
+import { AccordionActions } from './AccordionActions';
+import { AccordionContent } from './AccordionContent';
+import { AccordionItem } from './AccordionItem';
+import { AccordionTrigger } from './AccordionTrigger';
+
+const DESCRIPTION = [
+  'Stacks sections behind their own headers and opens each on demand — reach for `Tabs` when a few primary sections get switched between often, and leave content on the page when people read most of it anyway.',
+  '`primary` and `secondary` are inline rows for grouping; `section` is the bordered panel, and the only variant with room for `AccordionActions`.',
+].join(' ');
+
+const meta = {
+  title: 'Data Display/Accordion',
+  component: Accordion,
+  subcomponents: {
+    AccordionItem,
+    AccordionTrigger,
+    AccordionActions,
+    AccordionContent,
+  },
+  parameters: {
+    layout: 'centered',
+    docs: { description: { component: DESCRIPTION } },
+  },
+  args: { onValueChange: fn() },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'section'],
+    },
+    multiple: { control: 'boolean' },
+    collapsible: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    defaultValue: { control: 'object' },
+  },
+} satisfies Meta<typeof Accordion>;
+
+export default meta;
+
+const sampleText =
+  'The accordion component delivers large amounts of content in a small space through progressive disclosure. The user gets key details about the underlying content and can choose to expand that content within the constraints of the accordion.';
+
+/**
+ * The default variant — a 40px row with the chevron ahead of the title and a hover
+ * fill across the full width. Opening one section closes the other: `multiple` is
+ * off unless you ask for it.
+ */
+export const Primary: StoryFn<AccordionProps> = args => (
+  <div className='w-440'>
+    <Accordion {...args} variant='primary' data-testid='accordion-primary'>
+      <AccordionItem value='1'>
+        <AccordionTrigger>Title</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='2'>
+        <AccordionTrigger>Title</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+/**
+ * A 24px row in small medium-weight muted type with no hover fill, for dense or
+ * nested groups where the header should sit behind the content it labels.
+ */
+export const Secondary: StoryFn<AccordionProps> = args => (
+  <div className='w-440'>
+    <Accordion {...args} variant='secondary' data-testid='accordion-secondary'>
+      <AccordionItem value='1'>
+        <AccordionTrigger>Title</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='2'>
+        <AccordionTrigger>Title</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+/**
+ * `section` draws each item as a bordered panel row — title left, chevron right —
+ * and the title takes inline content, here a `NumericBadge` carrying a count.
+ */
+export const Section: StoryFn<AccordionProps> = args => (
+  <div className='w-440'>
+    <Accordion {...args} variant='section' defaultValue={['1']} data-testid='accordion-section'>
+      <AccordionItem value='1'>
+        <AccordionTrigger>
+          Title <NumericBadge>2</NumericBadge>
+        </AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='2'>
+        <AccordionTrigger>
+          Title <NumericBadge>2</NumericBadge>
+        </AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+/**
+ * `AccordionActions` renders beside the trigger rather than inside it, so buttons in
+ * the header act on the section without toggling it open.
+ */
+export const SectionWithActions: StoryFn<AccordionProps> = args => (
+  <div className='w-560'>
+    <Accordion
+      {...args}
+      variant='section'
+      defaultValue={['1']}
+      data-testid='accordion-section-actions'
+    >
+      <AccordionItem value='1'>
+        <AccordionTrigger>
+          Title <NumericBadge>2</NumericBadge>
+        </AccordionTrigger>
+        <AccordionActions>
+          <Button variant='ghost' size='small'>
+            Delete
+          </Button>
+          <Button variant='outline' size='small'>
+            Edit
+          </Button>
+        </AccordionActions>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='2'>
+        <AccordionTrigger>
+          Title <NumericBadge>2</NumericBadge>
+        </AccordionTrigger>
+        <AccordionActions>
+          <Button variant='ghost' size='small'>
+            Delete
+          </Button>
+          <Button variant='outline' size='small'>
+            Edit
+          </Button>
+        </AccordionActions>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+const longTitleText =
+  'A really long title that should truncate gracefully without breaking the layout';
+
+/**
+ * Titles truncate to one line rather than wrapping — the row is a fixed height, so
+ * reword a long header instead of relying on the ellipsis.
+ */
+export const LongTitlePrimary: StoryFn<AccordionProps> = args => (
+  <div className='w-320'>
+    <Accordion {...args} variant='primary' data-testid='accordion-long-title-primary'>
+      <AccordionItem value='1'>
+        <AccordionTrigger>{longTitleText}</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+/**
+ * The same 320px column at `secondary` size, where smaller type and no row padding
+ * leave a little more of the title visible before the ellipsis.
+ */
+export const LongTitleSecondary: StoryFn<AccordionProps> = args => (
+  <div className='w-320'>
+    <Accordion {...args} variant='secondary' data-testid='accordion-long-title-secondary'>
+      <AccordionItem value='1'>
+        <AccordionTrigger>{longTitleText}</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+/**
+ * `multiple` keeps several sections open at once, for when people reference sections
+ * on their own terms — not when the sections have to be read side by side, which is
+ * a layout rather than an accordion.
+ */
+export const Multiple: StoryFn<AccordionProps> = args => (
+  <div className='w-440'>
+    <Accordion
+      {...args}
+      variant='section'
+      multiple
+      defaultValue={['1', '2']}
+      data-testid='accordion-multiple'
+    >
+      <AccordionItem value='1'>
+        <AccordionTrigger>Section A</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='2'>
+        <AccordionTrigger>Section B</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='3'>
+        <AccordionTrigger>Section C</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+/**
+ * `disabled` on a single `AccordionItem` fades the row and blocks its toggle while the
+ * rest stay live; the same prop on `Accordion` locks every row at once.
+ */
+export const Disabled: StoryFn<AccordionProps> = args => (
+  <div className='w-440'>
+    <Accordion {...args} variant='primary' data-testid='accordion-disabled'>
+      <AccordionItem value='1'>
+        <AccordionTrigger>Available</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value='2' disabled>
+        <AccordionTrigger>Disabled item</AccordionTrigger>
+        <AccordionContent>
+          <Text>{sampleText}</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+```

package/dist/project/components/Accordion/preview.html

@@ -0,0 +1,2 @@
+<!-- @dsCard group="Data Display" height=480 -->
+<!doctype html><html><head><meta charset="utf-8"></head><body><div id="preview"></div><script src="./stories.js"></script><script>window.WallarmPreview.mount(document.getElementById('preview'));</script></body></html>