@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,346 @@
+---
+name: aircall-ds/migrate-icons
+description: >
+  Migrate icons from @aircall/icons to @aircall/react-icons — the old→new name map,
+  color/size → Tailwind, custom & brand icons. Works standalone (an icons-only swap)
+  or inside a Tractor migration (also drops Tractor's <Icon> wrapper). Load when a file
+  imports any named icon from @aircall/icons, or Icon from @aircall/tractor.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/06-react-icons.md"
+---
+
+Migrate icons from `@aircall/icons` to `@aircall/react-icons`. This is **independent of
+the Tractor migration** — run it on its own for an icons-only swap, or as part of
+`aircall-ds/migrate-tractor`. The name / color / size mappings below apply whether an
+icon is rendered directly (`<SomeIcon />`) or through Tractor's `<Icon component={…} />`
+wrapper; when it was wrapped in Tractor's `<Icon>`, also remove that wrapper (see §1 and §7).
+
+> **Upgrade `@aircall/react-icons` to `>= 0.4.0` as part of this migration.** `@aircall/ds`
+> itself imports flags (`CountryFlag` → `FlagUs`, …) from it; an older version (≤ 0.3.0)
+> breaks the ds bundle at build time, not just your own icon imports. `pnpm add @aircall/react-icons@latest`.
+
+## 1. What changes
+
+| Tractor part | @aircall/react-icons part |
+| --- | --- |
+| `import { Icon } from '@aircall/tractor'` | _(removed — no wrapper needed)_ |
+| `import { SomeIcon } from '@aircall/icons'` | `import { NewName } from '@aircall/react-icons'` |
+| `<Icon component={SomeIcon} size={N} color="primary.500" />` | `<NewName className="size-N text-primary" />` |
+| `color="…"` (Tractor token) | `text-*` Tailwind class (see color table) |
+| `size={N}` (number) | `size-N` Tailwind class (`size-4`=16px, `size-5`=20px, `size-6`=24px) |
+
+`@aircall/react-icons` re-exports all lucide icons plus a set of Aircall custom icons. Never import from `lucide-react` directly.
+
+## 2. Color mapping
+
+| Tractor `color` value | Tailwind class |
+| --- | --- |
+| `primary.500` | `text-primary` |
+| `critical.500` | `text-destructive` |
+| `success.500` | `text-success` |
+| `warning.500` | `text-warning` |
+| `informative.500` | `text-info` |
+| `text.base` | `text-foreground` |
+| `text.secondary` | `text-muted-foreground` |
+
+## 3. Size mapping
+
+| Tractor `size` | Tailwind class | px |
+| --- | --- | --- |
+| `16` | `size-4` | 16px |
+| `20` | `size-5` | 20px |
+| `24` | `size-6` | 24px |
+
+## 4. Icon name mapping (selected)
+
+This is a representative sample. For the full table consult the icon name tables in the migration guide.
+
+### Phone & Calls
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `CallFilled`, `CallOutlined`, `CallCircleFilled` | `Phone` | lucide |
+| `HangUpFilled` | `PhoneDecline` | custom |
+| `HangUpOutlined` | `PhoneOff` | lucide |
+| `MissedInboundFilled` | `PhoneMissed` | lucide |
+| `TransferFilled`, `TransferredOutlined` | `Forward` | lucide |
+| `VoicemailOutlined` | `Voicemail` | lucide |
+| `VoicemailDrop` | `VoicemailDrop` | custom |
+| `RingingFilled`, `CircledPhoneCallingFilled` | `PhoneCall` | lucide |
+| `KeypadFilled`, `KeypadOutlined` | `Keypad` | custom |
+| `ConferenceFilled`, `ConferenceOutlined` | `Conference` | custom |
+
+### Actions
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `CloseOutlined`, `CloseCircleFilled` | `X` | lucide |
+| `CheckOutlined`, `TickOutlined` | `Check` | lucide |
+| `SearchOutlined` | `Search` | lucide |
+| `EditFilled`, `EditOutlined` | `Pencil` | lucide |
+| `TrashFilled`, `TrashOutlined` | `Trash2` | lucide |
+| `CopyFilled`, `CopyOutlined` | `Copy` | lucide |
+| `FilterOutlined`, `FilterFilled` | `ListFilter` | lucide |
+| `AddCircleFilled`, `PlusCircleFilled` | `Plus` | lucide |
+
+### Arrows & Navigation
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `ChevronDownOutlined`, `ArrowDownFilled` | `ChevronDown` | lucide |
+| `ChevronLeftOutlined` | `ChevronLeft` | lucide |
+| `ChevronRightOutlined`, `ArrowRightFilled` | `ChevronRight` | lucide |
+| `ChevronUpOutlined`, `ArrowUpFilled` | `ChevronUp` | lucide |
+| `SendFilled`, `SendOutlined` | `Send` | lucide |
+| `RefreshOutlined` | `RefreshCw` | lucide |
+
+### Audio & Video
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `PlayFilled`, `PlayOutlined` | `Play` | lucide |
+| `PauseFilled`, `PauseOutlined`, `HoldFilled` | `Pause` | lucide |
+| `MicOnFilled`, `MicOnOutlined` | `Mic` | lucide |
+| `MicOffFilled`, `MicOffOutlined` | `MicOff` | lucide |
+| `SoundHighFilled`, `SoundHighOutlined` | `Volume2` | lucide |
+| `HeadsetFilled`, `HeadsetOutlined` | `Headset` | lucide |
+| `ReplayFilled`, `ReplayOutlined` | `Replay` | custom |
+
+### Users & Contacts
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `UserFilled`, `UserOutlined` | `UserRound` | lucide |
+| `PeopleFilled`, `PeopleOutlined` | `UsersRound` | lucide |
+| `ContactsFilled`, `ContactsOutlined` | `ContactRound` | lucide |
+| `AssignedFilled`, `AssignedOutlined` | `Assigned` | custom |
+| `CompanyFilled`, `CompanyOutlined` | `Building` | lucide |
+
+### Feedback & Status
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `InformationFilled`, `InformationOutlined` | `Info` | lucide |
+| `WarningFilled`, `WarningOutlined` | `AlertTriangle` | lucide |
+| `NotificationOnFilled`, `NotificationOnOutlined` | `Bell` | lucide |
+| `StarOutlined` | `Star` | lucide |
+| `StarFilled` | `StarFilled` | custom |
+
+### Messages & SMS
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `MessageFilled`, `SmsInboundFilled` | `MessageSquare` | lucide |
+| `EmailFilled`, `MailOutlined` | `Mail` | lucide |
+| `InboxFilled`, `InboxOutlined` | `Inbox` | lucide |
+| `ChatFilled`, `ChatOutlined` | `MessagesSquare` | lucide |
+
+### System & Settings
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `SettingsFilled`, `SettingsOutlined` | `Settings` | lucide |
+| `MenuVerticalFilled`, `MenuVerticalOutlined` | `MoreVertical` | lucide |
+| `MenuHorizontalFilled`, `MenuHorizontalOutlined` | `MoreHorizontal` | lucide |
+| `SpinnerOutlined` | `Loader2` | lucide |
+
+### Analytics & AI
+
+| Old (`@aircall/icons`) | New (`@aircall/react-icons`) | Source |
+| --- | --- | --- |
+| `SparklesFilled`, `LivePromptFilled`, `MagicFilled` | `AiAssist` | custom |
+| `AIAgent`, `VirtualAgentFilled` | `AiAgents` | custom |
+| `MonitoringFilled`, `AnalyticsFilled` | `BarChartBig` | lucide |
+| `ActivityFilled`, `BoltFilled` | `Zap` | lucide |
+
+## 5. Icons with no equivalent
+
+A small number of old icons have no direct mapping. Handle them as noted:
+
+| Old icon | Action |
+| --- | --- |
+| `PlayPauseFilled`, `PlayPauseOutlined` | Use `Play` or `Pause` contextually — no combined equivalent |
+| `Speed100XFilled`, `Speed125XFilled`, `Speed150XFilled`, `Speed200XFilled` | Render as text or a custom badge — no icon equivalent |
+| `AIMessageFilled` | No equivalent — treat as custom SVG until a replacement ships |
+| `OnboardingFilled` | Use `Flag` or `Rocket` as a placeholder; confirm with design |
+
+## 6. Brand / platform icons (not in @aircall/react-icons)
+
+Keep these as separate inline SVGs or local wrappers — they are not in `@aircall/react-icons`:
+
+- **Aircall brand**: `AircallIcon`, `AircallLogo`, `AircallLogoFull`, logo-mark variants
+- **OS / platform**: `AppleFilled`, `AndroidFilled`, `WindowsFilled`, `MacFilled`
+- **Browsers**: `ChromeFilled`, `EdgeFilled`, `FirefoxFilled`
+- **Messaging**: `WhatsappFilled`, `WhatsappOutlined` — use the existing `WhatsAppIcon.tsx` in `packages/aw-ui`
+- **Text badges**: `BetaOutlined` — keep as a custom SVG or badge component
+
+## 7. Before / After examples
+
+### 7a. Basic icon with color and size
+
+**Before (Tractor + @aircall/icons):**
+```tsx
+import { Icon } from '@aircall/tractor';
+import { CallFilled } from '@aircall/icons';
+
+<Icon component={CallFilled} size={24} color="primary.500" />
+```
+
+**After (@aircall/react-icons + Tailwind):**
+```tsx
+import { Phone } from '@aircall/react-icons';
+
+<Phone className="size-6 text-primary" />
+```
+
+### 7b. Icon inside a button (critical color)
+
+**Before (Tractor + @aircall/icons):**
+```tsx
+import { Icon } from '@aircall/tractor';
+import { TrashFilled } from '@aircall/icons';
+import { Button } from '@aircall/tractor';
+
+<Button variant="danger" size="small">
+  <Icon component={TrashFilled} size={16} color="critical.500" />
+  Delete
+</Button>
+```
+
+**After (@aircall/ds + @aircall/react-icons):**
+```tsx
+import { Trash2 } from '@aircall/react-icons';
+import { Button } from '@aircall/ds';
+
+<Button variant="destructive" size="lg">
+  <Trash2 />
+  Delete
+</Button>
+```
+
+> When an icon sits inside a DS `Button`, omit the `size-*` class — the Button's `[&_svg]:size-4` rule sizes it automatically.
+
+### 7c. Icon with muted color (secondary text)
+
+**Before (Tractor + @aircall/icons):**
+```tsx
+import { Icon } from '@aircall/tractor';
+import { ClockFilled } from '@aircall/icons';
+
+<Icon component={ClockFilled} size={20} color="text.secondary" />
+```
+
+**After (@aircall/react-icons + Tailwind):**
+```tsx
+import { Clock } from '@aircall/react-icons';
+
+<Clock className="size-5 text-muted-foreground" />
+```
+
+### 7d. Custom Aircall icon
+
+**Before (Tractor + @aircall/icons):**
+```tsx
+import { Icon } from '@aircall/tractor';
+import { VoicemailDrop } from '@aircall/icons';
+
+<Icon component={VoicemailDrop} size={24} />
+```
+
+**After (@aircall/react-icons):**
+```tsx
+import { VoicemailDrop } from '@aircall/react-icons';
+
+<VoicemailDrop className="size-6" />
+```
+
+> Aircall custom icons are also re-exported from `@aircall/react-icons`. The import source changes but the component name stays the same for custom icons that survived into the new package.
+
+## 8. Common mistakes
+
+### Mistake 1: Keeping the Tractor `<Icon>` wrapper
+
+```tsx
+// WRONG — @aircall/ds has no Icon component; wrapper is unused
+import { Icon } from '@aircall/tractor';
+import { Phone } from '@aircall/react-icons';
+
+<Icon component={Phone} size={24} color="primary.500" />
+
+// CORRECT — use the icon component directly with Tailwind classes
+import { Phone } from '@aircall/react-icons';
+
+<Phone className="size-6 text-primary" />
+```
+
+**Mechanism:** `@aircall/react-icons` exports standard SVG React components. The Tractor `Icon` wrapper was a thin adapter that forwarded `size` and `color` as `width`/`height`/`fill` attributes. Without it, those props are simply ignored — or worse, they pass unknown attributes to the SVG element.
+
+Source: `@aircall/react-icons` re-exports lucide + Aircall icons as plain SVG components with no wrapper.
+
+---
+
+### Mistake 2: Using the old `@aircall/icons` name unchanged
+
+```tsx
+// WRONG — old name does not exist in @aircall/react-icons; TS compile error
+import { CallFilled } from '@aircall/react-icons';
+
+// CORRECT — lucide consolidates filled/outlined variants; use the new name
+import { Phone } from '@aircall/react-icons';
+```
+
+**Mechanism:** `@aircall/react-icons` intentionally consolidates `*Filled`/`*Outlined` variants into a single icon name (e.g. `CallFilled` + `CallOutlined` → `Phone`). The visual distinction (filled vs stroke) is gone by design — lucide icons are all stroke-outlined. Importing the old name compiles to `undefined` and renders nothing.
+
+Source: `@aircall/react-icons` re-exports lucide + Aircall icons; custom icons live in `packages/react-icons/src/generated/custom`.
+
+---
+
+### Mistake 3: Using a `color` or `size` number prop instead of Tailwind classes
+
+```tsx
+// WRONG — color and size number are Tractor Icon props, not valid SVG props
+import { Mic } from '@aircall/react-icons';
+
+<Mic size={24} color="primary.500" />
+
+// CORRECT — use Tailwind utility classes
+import { Mic } from '@aircall/react-icons';
+
+<Mic className="size-6 text-primary" />
+```
+
+**Mechanism:** lucide-react icons accept a `size` prop and a `color` prop via the lucide component API — but `@aircall/react-icons` wraps them in a way that Tailwind classes are the intended styling mechanism. Using Tractor color tokens like `"primary.500"` as a CSS value produces an invalid color string that browsers ignore silently, and the icon renders in the inherited color instead of the intended one.
+
+Source: `@aircall/react-icons` re-exports lucide + Aircall icons; Tailwind design tokens (`text-primary`, `text-destructive`, etc.) are the authoritative color system in `@aircall/ds`.
+
+---
+
+### Mistake 4: Importing icons directly from `lucide-react`
+
+```tsx
+// WRONG — bypasses the Aircall icon layer; icon swaps or overrides won't apply
+import { Phone } from 'lucide-react';
+
+// CORRECT — always route through @aircall/react-icons
+import { Phone } from '@aircall/react-icons';
+```
+
+**Mechanism:** `@aircall/react-icons` is the single source of truth for all icons — it re-exports lucide icons and adds Aircall custom icons. Importing from `lucide-react` directly means any future override, version pin, or custom replacement in `@aircall/react-icons` won't be picked up. It also breaks tree-shaking assumptions and makes it harder to audit icon usage across the codebase.
+
+Source: `@aircall/react-icons` re-exports lucide + Aircall icons as the canonical icon surface for Aircall apps.
+
+## 9. Migration checklist
+
+- [ ] Swap `@aircall/icons` → `@aircall/react-icons` in `package.json`
+- [ ] Remove `import { Icon } from '@aircall/tractor'` — no wrapper needed
+- [ ] Rename icons per the tables above (many `*Filled`/`*Outlined` pairs merge into one name)
+- [ ] Replace `color="…"` with `className="text-*"` using the color table
+- [ ] Replace `size={N}` with `className="size-N"` (or omit when inside a DS `Button`)
+- [ ] Run `pnpm tsc --noEmit` — missing exports surface as TS compile errors
+- [ ] Keep brand/platform icons (Aircall logo, OS, browser, WhatsApp) as separate assets
+- [ ] For icons marked "validate usage", confirm the new shape is visually correct in context

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'`.