@aircall/ds 0.14.0 → 0.15.0

package/skills/aircall-ds/migrate-tractor/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: aircall-ds/migrate-tractor
+description: >
+  Migrate a file from @aircall/tractor to @aircall/ds. Load FIRST when converting
+  Tractor components (Modal, Banner, Select, Button, Typography, Flex, Tooltip, Tag,
+  Dropdown, Form, …) to @aircall/ds. Carries the cross-cutting rules (import form,
+  prop renames, the render prop, data-attribute shape) and a lookup table mapping
+  each Tractor component to its @aircall/ds target and the recipe skill to load next.
+type: core
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/01-global-rules.md"
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/04-lookup.md"
+---
+
+# Migrating from @aircall/tractor to @aircall/ds
+
+Load this skill first for any Tractor → DS migration. It gives the cross-cutting
+rules that apply to every component and a lookup table to find the DS replacement.
+Then load the component-specific recipe skill from the `recipe to load` column.
+
+## How to run this migration (end-to-end)
+
+This skill and its recipes cover *converting code*. The full migration is a repeatable
+loop — do it incrementally, one file/screen at a time, shipping each green:
+
+0. **Set up once** — load `@aircall/ds#aircall-ds/setup` and do the wiring before any
+   conversion: install `@aircall/ds` + `@aircall/react-icons` (>= 0.4.0), import the
+   precompiled `globals.css`, mount the root providers (incl. `DsI18nProvider` under
+   react-i18next + `NotificationQueueProvider`), keep `TractorProvider` mounted for
+   cohabitation, and add the jsdom test shims (selector guard for DS popups +
+   Switch-via-hidden-checkbox). DS and Tractor run side by side until the last Tractor
+   import is gone. (This skill `requires` setup so it loads automatically — but do the
+   install/provider/jest wiring first.)
+1. **Inventory** — list the file's `@aircall/tractor` and `@aircall/icons` imports. Each
+   maps to a row in the lookup table below, or to `@aircall/ds#aircall-ds/migrate-icons`
+   for icons.
+2. **Migrate** — apply the cross-cutting rules (§1–§3), then load the per-component recipe
+   from the `recipe to load` column for each component; use `migrate-icons` for icons.
+3. **Verify green** — `tsc --noEmit`, the test suite (DS popups/Switch need the setup jsdom
+   shims), and biome/lint. Re-screenshot if the screen changed visually.
+4. **Repeat** per file/screen until no `@aircall/tractor` / `@aircall/icons` imports remain,
+   then drop them from `package.json`.
+
+## 1. Imports
+
+Always import from the top-level package only:
+
+```tsx
+import { Button, Dialog, Input } from '@aircall/ds';
+```
+
+Subpath imports (`@aircall/ds/components/button`) work only inside the hydra monorepo
+and break in external apps. Use the root form everywhere.
+
+## 2. Drop styled-components
+
+Remove `styled()` wrappers, `fromTheme`, `getColor`/`getSpace`/`getRadii`/`getShadow`,
+and `useTheme()`. Replace them with Tailwind classes on the DS component's `className`
+or a plain `<div>`:
+
+```tsx
+// Before
+const Styled = styled(Button)`font-size: ${fromTheme('typography.variants.body.fontSize')};`;
+<Box mx={2} my={4} bg="primary.500" />
+
+// After
+<Button className="text-sm" />
+<div className="mx-2 my-4 bg-primary" />
+```
+
+The migration is progressive — Tractor and DS can coexist. Remove `TractorProvider`
+only when the last `@aircall/tractor` import is gone.
+
+## 3. Standard prop renames
+
+These apply to every component that had them in Tractor:
+
+| Tractor | DS |
+| --- | --- |
+| `isOpen` | `open` |
+| `onClose` | `onOpenChange` (receives `boolean`) |
+| `onChange` (value-based: Select, Tabs, RadioGroup, Slider, ToggleGroup) | `onValueChange` |
+| `onChange` (boolean: Checkbox, Switch) | `onCheckedChange` |
+| `validationStatus="error"` | `aria-invalid={true}` |
+| `variant="critical"` | `variant="destructive"` (Button) |
+| `as="…"` | `render={<Element />}` |
+
+> `onValueChange` for Select receives `(value: string | null, event)` — `null` when
+> cleared. Widen your handler to accept `null`.
+
+## 4. The `render` prop (replaces `asChild`)
+
+When a Trigger or Close must render as a custom element, pass it to `render`:
+
+```tsx
+<DialogTrigger render={<Button variant="outline" />}>Open</DialogTrigger>
+```
+
+Affected: Trigger/Close on Dialog, Sheet, Popover, Tooltip, DropdownMenu, Collapsible,
+Drawer, plus `Button`, `Badge`, `Item`, `PaginationLink`, and Sidebar subcomponents.
+
+Drawer is Base UI (via Coss UI) — same `render` rule applies. Its body wrapper is
+`DrawerPopup` (not `DrawerContent`), and Tractor's `direction` becomes `position`.
+
+## 5. Labels live inside Groups
+
+For `DropdownMenu` and `Select`, `Label` must be a child of a `*Group`:
+
+```tsx
+<DropdownMenuContent>
+  <DropdownMenuGroup>
+    <DropdownMenuLabel>Account</DropdownMenuLabel>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+  </DropdownMenuGroup>
+</DropdownMenuContent>
+```
+
+## 6. Data attributes in Tailwind classes
+
+DS uses single-key data attributes for state (not Radix `[state=…]` form):
+
+| Use | Not |
+| --- | --- |
+| `data-open:animate-in` | `data-[state=open]:animate-in` |
+| `data-checked:bg-primary` | `data-[state=checked]:bg-primary` |
+| `data-disabled:opacity-50` | `data-[disabled]:opacity-50` |
+
+**Orientation is the exception** — it's a value attribute, not a flag. Style with
+`data-[orientation=horizontal]:` / `data-[orientation=vertical]:` (Tabs, Slider,
+Separator).
+
+**Collapsible asymmetry:** Root uses `data-open` / `data-closed`; Trigger uses
+`data-panel-open` (no closed counterpart).
+
+## 7. Size baselines
+
+> These are recommended starting points. Verify with design — pixel sizes have shifted
+> between Tractor and DS, so a verbatim same-size match isn't always possible.
+
+**Button** (DS heights: `sm`=24px, `default`=32px, `lg`=40px):
+
+| Tractor | DS | Diff |
+| --- | --- | --- |
+| `xSmall` (28px) | `size="default"` (32px) | +4px |
+| `small` (40px) | `size="lg"` (40px) | exact |
+| `regular` (48px, default) | `size="lg"` (40px) | -8px |
+| `large` (56px) | `className="h-14"` | no built-in size |
+
+**Icon Button** (DS sizes: `icon-sm`=24px, `icon`=32px, `icon-lg`=40px):
+
+| Tractor IconButton | DS |
+| --- | --- |
+| Default (24px) | `size="icon"` |
+| Smaller than default | `size="icon-sm"` |
+| Larger than default | `size="icon-lg"` |
+
+**Select Trigger** has two sizes: `default` (40px) and `sm` (32px). Use `default`
+for any Tractor `regular` / `small`.
+
+**Avatar** (DS sizes: `xs`=20px, `sm`=24px, `default`=32px, `lg`=40px, `xl`=48px):
+
+| Tractor | DS |
+| --- | --- |
+| `small` (24px) | `sm` |
+| `regular` (32px) | `default` |
+| `large` (48px) | `xl` |
+| `xLarge` (64px) | `xl` (-16px, no 64px size) |
+
+**Toggle / ToggleGroupItem**: same heights as Button (`sm`/`default`/`lg`).
+
+**No `size` prop:** Input, Textarea, Switch, Checkbox, RadioGroup, Slider. Drop the
+Tractor `size` prop entirely.
+
+## 8. Variant naming
+
+Tractor used `variant` + `mode`. DS uses a single `variant`.
+
+| Tractor | DS |
+| --- | --- |
+| `critical` | `destructive` (Button) or `error` (Alert) |
+| `informative` | `info` (Alert) |
+| `primary` + `mode="fill"` | `default` (Button) |
+| `primary` + `mode="outline"` | `outline` (Button) |
+| `primary` + `mode="ghost"` | `ghost` (Button) |
+| `primary` + `mode="link"` | `link` (Button) |
+
+Each DS component has its own variant set — check the lookup table below.
+
+## 9. Icons
+
+`@aircall/icons` → `@aircall/react-icons`. The `<Icon component={X} />` wrapper is
+gone; import the icon directly:
+
+```tsx
+// Before
+import { AddOutlined, Icon } from '@aircall/tractor';
+<Icon component={AddOutlined} mr={2} />
+
+// After
+import { AddCircleFill } from '@aircall/react-icons';
+<AddCircleFill className="mr-2 size-4" />
+```
+
+Some names differ significantly (e.g. `InfoCircleFilled` → `InformationCircleFill`,
+`PlayFilled` → `ControlPlayFill`).
+
+## 10. Forms & validation
+
+A Tractor `Form`/`FormItem` that collects and submits data migrates to **`@aircall/blocks` `useForm` + the `Form*Field` wrappers** — do NOT keep field values in React `useState`, and do NOT hand-wire the ds `Field`/`Input` primitives. The form owns state, validation, dirty/`canSubmit`/`isSubmitting`, and errors (which drive `SubmitButton`/`CardSaveBar`). Use the bare ds `Field` primitives only for non-form display. See `@aircall/ds#aircall-ds/migrate-tractor/form-and-field` and `@aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard`.
+
+Field-level validation state is `aria-invalid` — DS components style themselves from it:
+
+```tsx
+<Input aria-invalid={hasError} />
+```
+
+## 11. Cleanup items
+
+- **Base font size**: Tractor used 14px. DS uses 16px. Remove any `font-size: 14px`
+  on `html` or `body` — DS's `globals.css` already sets the correct base.
+- **SVG workarounds**: Remove any `svg { display: block; line-height: 0; }` global CSS.
+
+---
+
+## Component lookup table
+
+Grep your code for `@aircall/tractor` imports. For each component, find the row below.
+Then load the listed recipe skill (if `available`) for the detailed swap.
+
+| Tractor component | @aircall/ds target | recipe to load | status |
+| --- | --- | --- | --- |
+| `Accordion` (+ `AccordionSection`) | `Accordion` + `AccordionItem` + `AccordionTrigger` + `AccordionContent` | `@aircall/ds#aircall-ds/migrate-tractor/accordion` | available |
+| `ActionMenu` | `DropdownMenu` (compound) | `@aircall/ds#aircall-ds/migrate-tractor/dropdown-menu` | available |
+| `AudioPlayer` | — (no DS equivalent yet) | — | not-yet |
+| `Avatar` (+ `QuickAvatar`) | `Avatar` + `AvatarImage` + `AvatarFallback` | `@aircall/ds#aircall-ds/migrate-tractor/avatar` | available |
+| `Badge` | `AvatarBadge` (status dot on avatar); `Badge` (label/tag style) | `@aircall/ds#aircall-ds/migrate-tractor/badge` | available |
+| `Banner` (+ `BannerHeading`/`BannerIcon`/`BannerSuffix`) | `Alert` (rounded card) / `Banner` (inline full-width) | `@aircall/ds#aircall-ds/migrate-tractor/alert` | available |
+| `BannerButton` | `Button` inside `BannerAction` | `@aircall/ds#aircall-ds/migrate-tractor/alert` | available |
+| `Box` | native `<div>` + Tailwind classes | `@aircall/ds#aircall-ds/migrate-tractor/styling` | available |
+| `Button` | `Button` | `@aircall/ds#aircall-ds/migrate-tractor/button` | available |
+| `Checkbox` | `Checkbox` + `<Label>` | — | not-yet |
+| `ComboBox` | `Combobox` (compound) | `@aircall/ds#aircall-ds/migrate-tractor/combobox` | available |
+| `CounterBadge` | `CounterBadge` | `@aircall/ds#aircall-ds/migrate-tractor/badge` | available |
+| `DatePicker` | `Calendar` + your own `Popover` trigger | — | not-yet |
+| `Divider` | `Separator` | `@aircall/ds#aircall-ds/migrate-tractor/divider` | available |
+| `Drawer` | `Drawer` (compound, `DrawerPopup` body) | `@aircall/ds#aircall-ds/migrate-tractor/sheet-vs-drawer` | available |
+| `Dropdown` | `DropdownMenu` (compound) | `@aircall/ds#aircall-ds/migrate-tractor/dropdown-menu` | available |
+| `Flex` | native `<div className="flex …">` + Tailwind | `@aircall/ds#aircall-ds/migrate-tractor/styling` | available |
+| `FlagIcon` | `CountryFlag` (prop: `countryIsoCode`) | — | not-yet |
+| `Form` | native `<form>` + `Field` per row | `@aircall/ds#aircall-ds/migrate-tractor/form-and-field` | available |
+| `FormItem` | `Field` + `FieldLabel` + `FieldDescription` + `FieldError` | `@aircall/ds#aircall-ds/migrate-tractor/form-and-field` | available |
+| `Gauge` | `Gauge` (8-segment audio meter) | `@aircall/ds#aircall-ds/migrate-tractor/gauge` | available |
+| `Grid` | native `<div className="grid …">` + Tailwind | `@aircall/ds#aircall-ds/migrate-tractor/styling` | available |
+| `Icon` | direct icon import from `@aircall/react-icons` | `@aircall/ds#aircall-ds/migrate-icons` | available |
+| `IconButton` | `Button` with `size` `icon` / `icon-sm` / `icon-lg` | `@aircall/ds#aircall-ds/migrate-tractor/button` | available |
+| `Link` | `Link` | `@aircall/ds#aircall-ds/migrate-tractor/link` | available |
+| `List` (+ `ListItem`) | `ItemGroup` + `Item` + `ItemMedia`/`ItemContent`/`ItemActions` | `@aircall/ds#aircall-ds/migrate-tractor/item` | available |
+| `Menu` (+ `MenuItem`) | standalone list → `ItemGroup` + `Item`; **inside a `Dropdown`/`ActionMenu`** → `DropdownMenuContent` + `DropdownMenuItem` | `@aircall/ds#aircall-ds/migrate-tractor/item` (standalone) or `@aircall/ds#aircall-ds/migrate-tractor/dropdown-menu` (in a Dropdown) | available |
+| `Modal` | `Dialog` (compound) | `@aircall/ds#aircall-ds/migrate-tractor/dialog` | available |
+| `PasswordInput` | `InputGroup` recipe | `@aircall/ds#aircall-ds/migrate-tractor/input` | available |
+| `Popover` | `Popover` + `PopoverTrigger` + `PopoverContent` | `@aircall/ds#aircall-ds/migrate-tractor/popover` | available |
+| `Progress` | `Progress` (compound: `ProgressTrack` + `ProgressIndicator`) | — | not-yet |
+| `QuickAvatar` | `Avatar` (same as Avatar row) | `@aircall/ds#aircall-ds/migrate-tractor/avatar` | available |
+| `Radio` + `RadioGroup` | `RadioGroup` + `RadioGroupItem` | — | not-yet |
+| `SegmentedControl` | `Tabs` (with panel) or `ToggleGroup` (visual only) | `@aircall/ds#aircall-ds/migrate-tractor/tabs` | available |
+| `Select` + `SelectOption` | `Select` (compound: `SelectTrigger` + `SelectValue` + `SelectContent` + `SelectGroup` + `SelectItem`) | `@aircall/ds#aircall-ds/migrate-tractor/select` | available |
+| `SidenavDropdown` | `Sidebar` + `Collapsible` (compose) | — | not-yet |
+| `SidenavItem` | `Sidebar*` family | — | not-yet |
+| `Skeleton` | `Skeleton` — size via Tailwind (`className="h-4 w-32"`) | `@aircall/ds#aircall-ds/migrate-tractor/skeleton` | available |
+| `Slider` | `Slider` (`onValueChange`, value is `number[]`, no `size`) | — | not-yet |
+| `Spacer` | `<div className="flex flex-col gap-*">` or `FieldGroup` | `@aircall/ds#aircall-ds/migrate-tractor/styling` | available |
+| `SpinnerOutlined` | `Spinner` (sizes: `sm`/`default`/`lg`/`xl`, always animated) | — | not-yet |
+| `Tab` (+ `Tab.Item`/`TabList`/`TabPanel`) | `Tabs` + `TabsTrigger` + `TabsList` + `TabsContent` | `@aircall/ds#aircall-ds/migrate-tractor/tabs` | available |
+| `Table` (+ `ActionBar`) | `DataTable` (data-driven) or `Table` primitive (static) | `@aircall/ds#aircall-ds/migrate-tractor/data-table` | available |
+| `Tag` | `Badge` (`color` + `tone` props; `legacyColor` for custom hex) | `@aircall/ds#aircall-ds/migrate-tractor/badge` | available |
+| `Textarea` | `Textarea` (no `size`, use `aria-invalid`) | — | not-yet |
+| `TextFieldInput` | `Input` (no `sizing`, 40px fixed, use `aria-invalid`) | `@aircall/ds#aircall-ds/migrate-tractor/input` | available |
+| `Toggle` | `Switch` (`onCheckedChange`, no `size`) | — | not-yet |
+| `ToggleGroup` / `TabToggle` | `ToggleGroup` (`multiple` boolean; value always `string[]`) | — | not-yet |
+| `Tooltip` | `Tooltip` (compound) + `TooltipProvider` at app root | `@aircall/ds#aircall-ds/migrate-tractor/tooltip` | available |
+| `Tree` | `DataTree` (data-driven) or `Tree` primitive | `@aircall/ds#aircall-ds/migrate-tractor/tree` | available |
+| `TreeSelect` | no turn-key equivalent — `DataTree` inside a `Popover` | `@aircall/ds#aircall-ds/migrate-tractor/tree` | available |
+| `Typography` | native HTML + Tailwind text classes | `@aircall/ds#aircall-ds/migrate-tractor/styling` | available |
+| `useToast` | `toast` from `sonner` + `<Toaster />` at app root | `@aircall/ds#aircall-ds/migrate-tractor/toast` | available |
+| `WhatsAppTemplatePreview` | — (no DS equivalent) | — | not-yet |
+
+---
+
+## Facts easy to get wrong
+
+These APIs do not exist in DS. Do not propose them.
+
+- `<Input sizing="lg" />` — Input has **no** `sizing`/`size` prop. It is 40px, period.
+- `<Textarea size="…" />` — no size prop.
+- `<Switch size="…" />` — no size prop.
+- `<Checkbox size="…" />` — no size prop.
+- `<RadioGroup size="…" />` — no size prop.
+- `<Slider size="…" />` — no size prop.
+- `<Tabs size="…" />` / `<TabsList variant="…" />` — no such props.
+- `<Badge variant="destructive" | "success" | "warning" | "info" />` — Badge has only
+  `default`, `secondary`, `outline`. For semantic colors use `Alert`, `CounterBadge`,
+  or `className` with a semantic token.
+- `<Alert variant="destructive" />` — Alert's error variant is `error`, not
+  `destructive`. Full set: `default` / `info` / `success` / `warning` / `error`.
+- `<CounterBadge count={…} max={…} />` — no `count`/`max` props. Pass the already-
+  capped value as children. Variants: `default` / `secondary` / `ghost`.
+- `<TooltipProvider delayDuration={…} />` — Base UI prop is `delay`, default `0`.
+  `delayDuration` is silently ignored.
+- Subpath imports like `@aircall/ds/components/<name>` — never propose. Always use
+  `import { X } from '@aircall/ds'`.

package/skills/aircall-ds/migrate-tractor/accordion/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: aircall-ds/migrate-tractor/accordion
+description: >
+  Migrate Tractor Accordion and AccordionSection to the @aircall/ds Accordion
+  compound (AccordionItem, AccordionTrigger, AccordionContent). Load when a file
+  imports Accordion or AccordionSection from @aircall/tractor.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/accordion.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the accordion-specific steps below.
+
+## 1. Component mapping
+
+Tractor `Accordion` accepted `AccordionSection` children that bundled header, chevron, and body in a single component. DS splits each section into three named parts:
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `Accordion` | `Accordion` (state owner) |
+| `AccordionSection` | `AccordionItem` + `AccordionTrigger` + `AccordionContent` |
+| _(built into AccordionSection)_ | `AccordionTrigger` (header + built-in chevron) |
+| _(built into AccordionSection)_ | `AccordionContent` (body panel) |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Accordion, AccordionItem, AccordionTrigger, AccordionContent
+```
+
+All names used in the Before/After section below exist in the published public API.
+
+## 3. Imports
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@aircall/ds';
+```
+
+## 4. Prop changes
+
+| Tractor | DS | Notes |
+| --- | --- | --- |
+| _(implicit — one open at a time)_ | default (no extra prop needed) | Single-open is the DS default |
+| _(allowMultiple or equivalent)_ | `multiple` on `<Accordion>` | Boolean — allows multiple items open simultaneously |
+| _(section key)_ | `value` on `<AccordionItem>` | Required; `number` or `string`; index works for static lists |
+| _(section disabled)_ | `disabled` on `<AccordionItem>` | Disables the trigger and keeps the panel closed |
+| `defaultExpanded` / open sections | `defaultValue` on `<Accordion>` | Always an array, even in single-open mode: `defaultValue={[0]}` |
+| controlled open | `value` + `onValueChange` on `<Accordion>` | `value` is an array; `onValueChange` receives `(number \| string)[]` |
+
+## 5. Before / After
+
+### Static list (most common)
+
+```tsx
+// Before
+import { Accordion, AccordionSection } from '@aircall/tractor';
+
+<Accordion>
+  <AccordionSection title="General">
+    <p>General settings content.</p>
+  </AccordionSection>
+  <AccordionSection title="Billing">
+    <p>Billing details content.</p>
+  </AccordionSection>
+</Accordion>
+
+// After
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@aircall/ds';
+
+<Accordion defaultValue={[0]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>
+      <p>General settings content.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1}>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>
+      <p>Billing details content.</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Key changes:
+- Each `AccordionSection` becomes three components: `AccordionItem` (identity + state), `AccordionTrigger` (header label), `AccordionContent` (body)
+- `title` prop on `AccordionSection` becomes the children of `AccordionTrigger`
+- Every `AccordionItem` requires a `value` prop — the index is fine for static lists
+- `defaultValue` is always an array on `Accordion`
+
+### Dynamic list (map over data)
+
+```tsx
+// Before
+import { Accordion, AccordionSection } from '@aircall/tractor';
+
+<Accordion>
+  {sections.map(section => (
+    <AccordionSection key={section.id} title={section.title}>
+      {section.body}
+    </AccordionSection>
+  ))}
+</Accordion>
+
+// After
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@aircall/ds';
+
+<Accordion defaultValue={[0]}>
+  {sections.map((section, index) => (
+    <AccordionItem key={section.id} value={index}>
+      <AccordionTrigger>{section.title}</AccordionTrigger>
+      <AccordionContent>{section.body}</AccordionContent>
+    </AccordionItem>
+  ))}
+</Accordion>
+```
+
+### Multiple sections open simultaneously
+
+```tsx
+// After — allow more than one panel open at a time
+<Accordion multiple defaultValue={[0, 1]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1}>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Billing details content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Controlled
+
+```tsx
+// After — controlled open state
+const [openSections, setOpenSections] = React.useState<number[]>([0]);
+
+<Accordion value={openSections} onValueChange={setOpenSections}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1}>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Billing details content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Disabled section
+
+```tsx
+// After — disable one item
+<Accordion defaultValue={[0]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value={1} disabled>
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Billing details content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Width / spacing
+
+`Accordion` has no layout props. Apply width via `className`:
+
+```tsx
+<Accordion defaultValue={[0]} className="w-[450px]">
+  ...
+</Accordion>
+```
+
+---
+
+## 6. Common Mistakes
+
+### Mistake 1 — Adding a custom chevron inside `AccordionTrigger`
+
+```tsx
+// Wrong — AccordionTrigger renders its own chevron; adding another doubles it
+<AccordionTrigger>
+  General
+  <ChevronDownIcon />
+</AccordionTrigger>
+
+// Correct — pass only the header label as children
+<AccordionTrigger>General</AccordionTrigger>
+```
+
+`AccordionTrigger` internally renders a `ChevronDownIcon` / `ChevronUpIcon` pair that swaps on open/close state. Adding your own icon duplicates it visually. Pass only the label text (or non-icon content) as children.
+
+Source: `packages/ds/src/components/accordion.tsx`
+
+---
+
+### Mistake 2 — Passing `defaultValue` / `value` as a scalar instead of an array
+
+```tsx
+// Wrong — scalar causes a TypeScript error and the panel does not open
+<Accordion defaultValue={0}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+// Correct — always wrap in an array, even for a single default item
+<Accordion defaultValue={[0]}>
+  <AccordionItem value={0}>
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General settings content.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Both `defaultValue` and `value` on `Accordion` are typed as `(number | string)[]`. Passing a bare scalar is a type error and the Base UI primitive will not open the panel.
+
+Source: `packages/ds/src/components/accordion.tsx`
+
+---
+
+### Mistake 3 — Omitting the `value` prop on `AccordionItem`
+
+```tsx
+// Wrong — AccordionItem without value cannot be identified for open/close state
+<AccordionItem>
+  <AccordionTrigger>General</AccordionTrigger>
+  <AccordionContent>General settings content.</AccordionContent>
+</AccordionItem>
+
+// Correct — every AccordionItem needs a unique value
+<AccordionItem value={0}>
+  <AccordionTrigger>General</AccordionTrigger>
+  <AccordionContent>General settings content.</AccordionContent>
+</AccordionItem>
+```
+
+`value` is required by the Base UI Accordion primitive to track which items are open. Without it the item cannot be matched against `defaultValue` / `value` on the root `Accordion`, so the panel stays permanently closed and toggling has no effect.
+
+Source: `packages/ds/src/components/accordion.tsx`
+
+---
+
+### Mistake 4 — Using `type="multiple"` instead of the `multiple` boolean
+
+```tsx
+// Wrong — type prop does not exist on DS Accordion; silently ignored
+<Accordion type="multiple" defaultValue={[0, 1]}>
+  ...
+</Accordion>
+
+// Correct — DS uses a boolean `multiple` prop (same convention as ToggleGroup)
+<Accordion multiple defaultValue={[0, 1]}>
+  ...
+</Accordion>
+```
+
+Tractor (and some other libraries) use `type="single" | "multiple"` to control this behavior. DS uses the simpler boolean `multiple` prop. Passing `type="multiple"` is silently ignored — the accordion reverts to single-open mode with no TypeScript error.
+
+Source: `packages/ds/src/components/accordion.tsx`