@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,206 @@
+---
+name: aircall-ds/migrate-tractor/dialog
+description: >
+  Migrate Tractor Modal (ModalDialog, ModalHeader, ModalTitle, ModalBody,
+  ModalFooter) to the @aircall/ds Dialog compound. Load when a file imports Modal*
+  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/dialog.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 dialog-specific steps below.
+
+## 1. Component mapping
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `Modal` (state owner + panel) | `Dialog` (state owner) + `DialogContent` (panel) |
+| `ModalHeader` | `DialogHeader` |
+| `ModalTitle` | `DialogTitle` |
+| `ModalBody` | — (plain children inside `DialogContent`, no wrapper) |
+| `ModalFooter` | `DialogFooter` |
+| — | `DialogTrigger` (uncontrolled open trigger) |
+| — | `DialogClose` (any button that closes the dialog) |
+| — | `DialogDescription` (optional accessible subtitle) |
+
+## 2. Imports
+
+```tsx
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  Button
+} from '@aircall/ds';
+```
+
+## 3. Before / After
+
+### Controlled (most common — replaces `<Modal isOpen={…} onClose={…}>`)
+
+```tsx
+// Before
+import { Modal, ModalHeader, ModalTitle, ModalBody, ModalFooter, Button } from '@aircall/tractor';
+
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} size="regular">
+  <ModalHeader>
+    <ModalTitle>Confirm delete</ModalTitle>
+  </ModalHeader>
+  <ModalBody>
+    <p>This will permanently remove the contact. Are you sure?</p>
+  </ModalBody>
+  <ModalFooter>
+    <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+    <Button variant="critical" onClick={onConfirm}>Delete</Button>
+  </ModalFooter>
+</Modal>
+
+// After
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose, Button } from '@aircall/ds';
+
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm delete</DialogTitle>
+      <DialogDescription>
+        This will permanently remove the contact.
+      </DialogDescription>
+    </DialogHeader>
+
+    <p className="text-sm">Are you sure?</p>
+
+    <DialogFooter>
+      <DialogClose render={<Button variant="outline" size="lg" />}>
+        Cancel
+      </DialogClose>
+      <Button variant="destructive" size="lg" onClick={onConfirm}>
+        Delete
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Key changes:
+- `isOpen` → `open`; `onClose(reason)` → `onOpenChange(boolean)`
+- `ModalBody` is removed — body content is plain children inside `DialogContent`
+- `DialogClose` wraps any button that should close the dialog; pass the DS `Button` via `render` and put the label as children of `DialogClose`, not of the inner Button
+- `variant="critical"` → `variant="destructive"` (Button)
+
+### Uncontrolled with a trigger
+
+```tsx
+// After
+<Dialog>
+  <DialogTrigger render={<Button size="lg" />}>Open settings</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Settings</DialogTitle>
+    </DialogHeader>
+    {/* body content */}
+    <DialogFooter>
+      <DialogClose render={<Button variant="outline" size="lg" />}>Close</DialogClose>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Size
+
+`Dialog` has no built-in `size` prop. For the Tractor `size="large"` case, set width on `DialogContent`:
+
+```tsx
+// Tractor: size="large"
+<DialogContent className="max-w-2xl">…</DialogContent>
+```
+
+### Hiding the default close button
+
+`DialogContent` renders a default "×" close button in the top-right. Hide it when you want to force the user to use a footer action:
+
+```tsx
+<DialogContent showCloseButton={false}>…</DialogContent>
+```
+
+---
+
+## 4. Common mistakes
+
+### Mistake 1 — Passing `onClose` instead of `onOpenChange`
+
+```tsx
+// ❌ Wrong — onClose is a Tractor prop; DS ignores it silently
+<Dialog open={isOpen} onClose={() => setIsOpen(false)}>…</Dialog>
+
+// ✅ Correct — onOpenChange receives the new boolean state
+<Dialog open={isOpen} onOpenChange={setIsOpen}>…</Dialog>
+```
+
+`onOpenChange` fires with `false` when the dialog closes (backdrop click, Escape, or `DialogClose`). Widen your handler if you were using the Tractor `reason` argument — DS does not pass a reason.
+
+Source: `packages/ds/src/components/dialog.tsx`
+
+### Mistake 2 — Keeping `ModalBody` or wrapping body content in `DialogBody`
+
+```tsx
+// ❌ Wrong — neither ModalBody nor DialogBody exists in @aircall/ds
+<DialogContent>
+  <DialogHeader>…</DialogHeader>
+  <DialogBody>
+    <p>Content here</p>
+  </DialogBody>
+  <DialogFooter>…</DialogFooter>
+</DialogContent>
+
+// ✅ Correct — body content is plain children between DialogHeader and DialogFooter
+<DialogContent>
+  <DialogHeader>…</DialogHeader>
+  <p className="text-sm">Content here</p>
+  <DialogFooter>…</DialogFooter>
+</DialogContent>
+```
+
+DS's `Dialog` is a compound with no `DialogBody` export. The body is just children of `DialogContent`. Remove `ModalBody` and render content directly.
+
+Source: `packages/ds/src/components/dialog.tsx`
+
+### Mistake 3 — Putting the label inside the `render` Button instead of `DialogClose`
+
+```tsx
+// ❌ Wrong — the label ends up inside the Button's children, not DialogClose's
+<DialogClose render={<Button variant="outline" size="lg">Cancel</Button>} />
+
+// ✅ Correct — label is a child of DialogClose; DialogClose clones it into the rendered Button
+<DialogClose render={<Button variant="outline" size="lg" />}>
+  Cancel
+</DialogClose>
+```
+
+`DialogClose` uses the Base UI `render` prop pattern: it renders the element you pass as `render`, merging its own click handler. The label must be the child of `DialogClose`, not of the inner Button.
+
+Source: `packages/ds/src/components/dialog.tsx`
+
+### Mistake 4 — Using `variant="critical"` on the Button
+
+```tsx
+// ❌ Wrong — critical is a Tractor variant; DS Button doesn't have it
+<Button variant="critical" onClick={onConfirm}>Delete</Button>
+
+// ✅ Correct — DS Button uses destructive
+<Button variant="destructive" size="lg" onClick={onConfirm}>Delete</Button>
+```
+
+DS renamed `critical` to `destructive` for Button (and other components). The Tractor prop is silently dropped; no TypeScript error is shown because the variant may fall through to the default style.
+
+Source: `packages/ds/src/components/dialog.tsx`

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

@@ -0,0 +1,226 @@
+---
+name: aircall-ds/migrate-tractor/divider
+description: >
+  Migrate Tractor Divider to the @aircall/ds Separator. Load when a file imports
+  Divider from @aircall/tractor. Maps orientation (vertical|horizontal), drops the
+  size and bg props, and replaces Box-level color overrides with Tailwind className.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:packages/ds/src/components/separator.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+| Tractor part | @aircall/ds part | Notes |
+| --- | --- | --- |
+| `<Divider>` | `<Separator>` | Name change; orientation prop is preserved |
+| `size` prop | _(removed)_ | DS Separator is always 1 px; no thickness control |
+| `bg` prop | `className` | Pass a Tailwind background utility to override the border color |
+| Extends `BoxProps` | Extends `SeparatorPrimitive.Props` | DS root is a Base UI element, not a styled Box |
+
+## 2. Verified DS export (`packages/ds/src/index.ts`)
+
+```
+Separator
+```
+
+## 3. Imports
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+```
+
+## 4. Prop changes
+
+| Tractor prop | DS prop | Action |
+| --- | --- | --- |
+| `orientation?: 'vertical' \| 'horizontal'` | `orientation?: 'vertical' \| 'horizontal'` | Same values — pass through as-is |
+| `size?: 'xSmall' \| 'small'` | _(removed)_ | Delete the prop; DS Separator is always 1 px thick |
+| `bg?: string` | `className` | Replace with a Tailwind `bg-*` utility on `className` |
+
+The DS `Separator` accepts all standard HTML attributes (`id`, `aria-*`, `data-*`, `style`, `className`) plus `orientation`. It does not accept `children`.
+
+### Default orientation difference
+
+Tractor's `Divider` defaulted to `orientation="vertical"`. The DS `Separator` defaults to `orientation="horizontal"`. Always pass `orientation` explicitly on both sides of the migration to avoid a silent layout change.
+
+## 5. Sizing behavior
+
+Tractor's `Divider` used a `size` prop to control thickness (`xSmall` = 1 px, `small` = 2 px). The DS `Separator` is always 1 px thick via Tailwind classes applied internally (`data-[orientation=horizontal]:h-px` / `data-[orientation=vertical]:w-px`). There is no thickness prop — if you need a 2 px separator, add `className="data-[orientation=horizontal]:h-0.5 data-[orientation=vertical]:w-0.5"`.
+
+## 6. Color behavior
+
+Tractor's `Divider` accepted a Tractor design-token string via `bg` (e.g. `"graphic-default"`, `"neutral-700"`). The DS `Separator` uses `bg-border` by default (mapped to the DS border token). To override, pass a Tailwind utility class via `className`:
+
+```tsx
+// Tractor custom color
+<Divider orientation="vertical" bg="neutral-700" />
+
+// DS equivalent
+<Separator orientation="vertical" className="bg-neutral-700" />
+```
+
+## 7. Before / After examples
+
+### 7a. Horizontal separator between sections (default use case)
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function SectionBreak() {
+  return <Divider orientation="horizontal" />;
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function SectionBreak() {
+  return <Separator orientation="horizontal" />;
+}
+```
+
+### 7b. Vertical separator between inline items
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function InlineActions() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+      <span>Calls</span>
+      <Divider orientation="vertical" />
+      <span>Contacts</span>
+    </div>
+  );
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function InlineActions() {
+  return (
+    <div className="flex items-center gap-2">
+      <span>Calls</span>
+      <Separator orientation="vertical" />
+      <span>Contacts</span>
+    </div>
+  );
+}
+```
+
+### 7c. Thin divider with `size="xSmall"` dropped
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function MenuDivider() {
+  return <Divider orientation="horizontal" size="xSmall" />;
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function MenuDivider() {
+  return <Separator orientation="horizontal" />;
+}
+```
+
+> Both `xSmall` (1 px) and DS default (1 px) are identical. Drop `size` without any replacement.
+
+### 7d. Custom color via `bg` → `className`
+
+**Before (Tractor):**
+```tsx
+import { Divider } from '@aircall/tractor';
+
+export function BoldDivider() {
+  return <Divider orientation="horizontal" size="small" bg="neutral-700" />;
+}
+```
+
+**After (DS):**
+```tsx
+import { Separator } from '@aircall/ds';
+
+export function BoldDivider() {
+  return (
+    <Separator
+      orientation="horizontal"
+      className="bg-neutral-700 data-[orientation=horizontal]:h-0.5"
+    />
+  );
+}
+```
+
+> `size="small"` (2 px) has no direct DS equivalent — use `data-[orientation=horizontal]:h-0.5` to restore the 2 px thickness.
+
+## 8. Common mistakes
+
+### Mistake 1: Relying on the default orientation matching Tractor's default
+
+```tsx
+// WRONG — Tractor default is "vertical"; DS default is "horizontal"; omitting orientation
+// silently changes the rendered layout
+<Separator />
+
+// CORRECT — always pass orientation explicitly
+<Separator orientation="vertical" />
+```
+
+Tractor's `Divider` defaulted to `orientation="vertical"`. The DS `Separator` defaults to `orientation="horizontal"` (matching the Base UI primitive default). Omitting the prop after renaming the component causes a horizontal line to appear where a vertical one was expected — no warning, no error.
+
+Source: `packages/ds/src/components/separator.tsx` — `orientation = 'horizontal'` is the destructured default.
+
+---
+
+### Mistake 2: Passing the `size` prop expecting thickness control
+
+```tsx
+// WRONG — DS Separator has no `size` prop; it spreads onto the DOM element as a string attribute
+<Separator orientation="horizontal" size="small" />
+
+// CORRECT — drop `size`; for 2 px thickness add a Tailwind class
+<Separator orientation="horizontal" className="data-[orientation=horizontal]:h-0.5" />
+```
+
+`SeparatorProps` extends `SeparatorPrimitive.Props`, which has no `size` field. Because `Separator` spreads unknown props onto the Base UI primitive, `size="small"` becomes a non-standard DOM attribute, triggering a React warning and failing strict DOM validation.
+
+Source: `packages/ds/src/components/separator.tsx` — `SeparatorProps` extends `SeparatorPrimitive.Props` with no additional fields.
+
+---
+
+### Mistake 3: Passing a Tractor design-token string to `bg` or `color`
+
+```tsx
+// WRONG — DS Separator has no `bg` prop; passing it spreads a raw string onto the DOM
+<Separator orientation="vertical" bg="graphic-default" />
+
+// CORRECT — use a Tailwind bg-* utility via className
+<Separator orientation="vertical" className="bg-border" />
+```
+
+Tractor's `Divider` was built on `Box`, which accepted Tractor design-token strings for `bg`. `Separator` is a Base UI element with no styled-system layer — there is no `bg` prop. Passing it results in `bg="graphic-default"` becoming an invalid HTML attribute on the rendered DOM element.
+
+Source: `packages/ds/src/components/separator.tsx` — root renders `<SeparatorPrimitive>` directly; `bg` is not in `SeparatorPrimitive.Props`.

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

@@ -0,0 +1,266 @@
+---
+name: aircall-ds/migrate-tractor/dropdown-menu
+description: >
+  Migrate Tractor Dropdown and ActionMenu to the @aircall/ds DropdownMenu compound.
+  Load when a file imports Dropdown, ActionMenu, or ActionMenuItem from @aircall/tractor.
+  Covers trigger render prop, destructive item variant, icon placement, and the Group-wraps-Label rule.
+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/dropdown-menu.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 dropdown-menu-specific steps below.
+
+## 1. Component mapping
+
+Tractor `Dropdown` (labelled button trigger) and `ActionMenu` (icon-only "•••" trigger) both map to the same DS `DropdownMenu` compound. The visual difference is achieved through the `Button` variant/size passed to `DropdownMenuTrigger`'s `render` prop.
+
+| Tractor part | DS compound part | Role |
+| --- | --- | --- |
+| `<Dropdown>` / `<ActionMenu>` | `<DropdownMenu>` | State owner (open, modal) |
+| _(trigger button)_ | `<DropdownMenuTrigger>` | Clickable trigger — accepts any button via `render` |
+| `<DropdownItem>` / `<ActionMenuItem>` | `<DropdownMenuItem>` | Individual action item |
+| _(no equivalent)_ | `<DropdownMenuContent>` | Floating panel container |
+| _(no equivalent)_ | `<DropdownMenuGroup>` | Required wrapper around a labelled section |
+| _(no equivalent)_ | `<DropdownMenuLabel>` | Section heading — must be inside `DropdownMenuGroup` |
+| _(no equivalent)_ | `<DropdownMenuSeparator>` | Horizontal rule between sections |
+| _(no equivalent)_ | `<DropdownMenuAddon>` | Trailing right-aligned slot inside an item |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+DropdownMenu, DropdownMenuContent, DropdownMenuGroup,
+DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator,
+DropdownMenuTrigger, DropdownMenuAddon,
+DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent,
+DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem,
+DropdownMenuPortal, DropdownMenuShortcut,
+Button
+```
+
+## 3. Imports
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+```
+
+For ActionMenu (icon trigger + icon items), also import from `@aircall/react-icons`:
+
+```tsx
+import { MoreVerticalFill, EditPencilFill, DeleteTrashFill } from '@aircall/react-icons';
+```
+
+## 4. Prop and pattern changes
+
+| Tractor | DS | Notes |
+| --- | --- | --- |
+| `<Dropdown label="Options">` | `<DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>Options</DropdownMenuTrigger>` | Trigger button is composed via `render` prop |
+| `<ActionMenu>` | `<DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}><MoreVerticalFill /></DropdownMenuTrigger>` | Icon-only trigger uses `size="icon"` |
+| `<ActionMenuItem variant="critical">` | `<DropdownMenuItem variant="destructive">` | Use `variant` prop, not `className` |
+| `icon={EditOutlined}` on `ActionMenuItem` | Icon as first child of `DropdownMenuItem` | Render icon directly inside the item |
+| `<DropdownSection label="X">` | `<DropdownMenuGroup><DropdownMenuLabel>X</DropdownMenuLabel>…</DropdownMenuGroup>` | Label must be inside a `DropdownMenuGroup` |
+
+## 5. Before / After — plain Dropdown
+
+### Before (Tractor)
+
+```tsx
+import { Dropdown, DropdownItem } from '@aircall/tractor';
+
+<Dropdown label="Options">
+  <DropdownItem onClick={handleEdit}>Edit</DropdownItem>
+  <DropdownItem onClick={handleDelete}>Delete</DropdownItem>
+</Dropdown>
+```
+
+### After (DS)
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>
+    Options
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onClick={handleEdit}>Edit</DropdownMenuItem>
+    <DropdownMenuItem onClick={handleDelete}>Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## 6. Before / After — ActionMenu (icon trigger + icon items)
+
+### Before (Tractor)
+
+```tsx
+import { ActionMenu, ActionMenuItem } from '@aircall/tractor';
+
+<ActionMenu>
+  <ActionMenuItem icon={EditOutlined} onClick={handleEdit}>Edit</ActionMenuItem>
+  <ActionMenuItem icon={DeleteOutlined} variant="critical" onClick={handleDelete}>Delete</ActionMenuItem>
+</ActionMenu>
+```
+
+### After (DS)
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+import { MoreVerticalFill, EditPencilFill, DeleteTrashFill } from '@aircall/react-icons';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}>
+    <MoreVerticalFill className="size-4" />
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onClick={handleEdit}>
+      <EditPencilFill className="mr-2 size-4" />
+      Edit
+    </DropdownMenuItem>
+    <DropdownMenuItem variant="destructive" onClick={handleDelete}>
+      <DeleteTrashFill className="mr-2 size-4" />
+      Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## 7. Sections with labels
+
+`DropdownMenuLabel` must be placed inside a `DropdownMenuGroup` alongside its items. A label as a direct child of `DropdownMenuContent` is not accessibility-correct in Base UI.
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Button,
+} from '@aircall/ds';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>
+    Account
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuGroup>
+      <DropdownMenuLabel>Account</DropdownMenuLabel>
+      <DropdownMenuItem>Profile</DropdownMenuItem>
+      <DropdownMenuItem>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## 8. Common Mistakes
+
+### Mistake 1 — Using `className="text-destructive"` instead of `variant="destructive"`
+
+```tsx
+// Wrong
+<DropdownMenuItem className="text-destructive" onClick={handleDelete}>
+  Delete
+</DropdownMenuItem>
+
+// Correct
+<DropdownMenuItem variant="destructive" onClick={handleDelete}>
+  Delete
+</DropdownMenuItem>
+```
+
+`DropdownMenuItem` has a first-class `variant` prop (`'default' | 'destructive'`). Using `variant="destructive"` applies the correct destructive text colour, hover background, and dark-mode overrides via `data-[variant=destructive]` selectors. A bare `className="text-destructive"` only sets the text colour and loses the focus-state and dark-mode styling baked into the variant.
+Source: `packages/ds/src/components/dropdown-menu.tsx`
+
+---
+
+### Mistake 2 — Placing `DropdownMenuLabel` as a direct child of `DropdownMenuContent`
+
+```tsx
+// Wrong
+<DropdownMenuContent>
+  <DropdownMenuLabel>Account</DropdownMenuLabel>
+  <DropdownMenuItem>Profile</DropdownMenuItem>
+</DropdownMenuContent>
+
+// Correct
+<DropdownMenuContent>
+  <DropdownMenuGroup>
+    <DropdownMenuLabel>Account</DropdownMenuLabel>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+  </DropdownMenuGroup>
+</DropdownMenuContent>
+```
+
+`DropdownMenuLabel` renders a Base UI `MenuPrimitive.GroupLabel`, which must be a sibling of its items inside a `MenuPrimitive.Group`. Placing it directly in `DropdownMenuContent` breaks the ARIA group association that screen readers depend on.
+Source: `packages/ds/src/components/dropdown-menu.tsx`
+
+---
+
+### Mistake 3 — Omitting the `render` prop on `DropdownMenuTrigger`
+
+```tsx
+// Wrong
+<DropdownMenuTrigger>
+  Options
+</DropdownMenuTrigger>
+
+// Correct
+<DropdownMenuTrigger render={<Button variant="outline" size="lg" />}>
+  Options
+</DropdownMenuTrigger>
+```
+
+Without a `render` prop, `DropdownMenuTrigger` renders a plain unstyled `<button>`. In the DS, trigger appearance is composed by passing a `Button` via the Base UI `render` prop — the button's variant and size control the visual style. This follows the DS-wide `render` prop pattern that replaces the old `asChild` prop.
+Source: `packages/ds/src/components/dropdown-menu.tsx`
+
+---
+
+### Mistake 4 — Passing icon as a prop instead of rendering it as a child
+
+```tsx
+// Wrong
+import { ActionMenu, ActionMenuItem } from '@aircall/tractor';
+<ActionMenuItem icon={EditOutlined}>Edit</ActionMenuItem>
+
+// Correct
+import { DropdownMenuItem } from '@aircall/ds';
+import { EditPencilFill } from '@aircall/react-icons';
+<DropdownMenuItem>
+  <EditPencilFill className="mr-2 size-4" />
+  Edit
+</DropdownMenuItem>
+```
+
+Tractor `ActionMenuItem` accepted an `icon` prop. DS `DropdownMenuItem` has no `icon` prop — the icon is placed as the first child. The `[&_svg:not([class*='size-'])]:size-4` selector on the item auto-sizes icon children that lack an explicit size class.
+Source: `packages/ds/src/components/dropdown-menu.tsx`