@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,277 @@
+---
+name: aircall-ds/migrate-tractor/button
+description: >
+  Migrate Tractor Button and IconButton to the @aircall/ds Button. Load when a file
+  imports Button or IconButton from @aircall/tractor. Maps Tractor variant/mode/size
+  to the ds Button variant/size (default|outline|secondary|ghost|destructive|link;
+  default|sm|lg|icon|icon-sm|icon-lg) and the block prop.
+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/button.tsx"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the button-specific steps below.
+
+## 1. Component mapping
+
+Tractor had two separate components: `Button` (text + optional icon) and `IconButton` (icon-only, square). DS unifies both into a single `Button` component — the `size` prop controls the icon-only square shape.
+
+| Tractor component | DS replacement | Notes |
+| --- | --- | --- |
+| `<Button>` | `<Button>` | Drop-in with prop renames (see tables below) |
+| `<IconButton component={X}>` | `<Button size="icon"><X /></Button>` | Icon becomes a child; `component` prop is removed |
+
+## 2. Verified DS export (`packages/ds/src/index.ts`)
+
+```
+Button, buttonVariants
+```
+
+## 3. Imports
+
+```tsx
+import { Button } from '@aircall/ds';
+import { SomeIcon } from '@aircall/react-icons';
+```
+
+Never import icons from `lucide-react` directly — always use `@aircall/react-icons`.
+
+## 4. Variant mapping (Tractor → DS)
+
+Tractor had two orthogonal props — `variant` (color role) and `mode` (fill style). DS collapses both into a single `variant` prop. Use the combined (variant × mode) pair to pick the DS variant.
+
+| Tractor `variant` | Tractor `mode` | DS `variant` |
+| --- | --- | --- |
+| `primary` | _(default / filled)_ | `default` |
+| `primary` | `outline` | `outline` |
+| `secondary` | _(default / filled)_ | `secondary` |
+| `secondary` | `outline` | `outline` |
+| `secondary` | `ghost` | `ghost` |
+| `danger` | _(default / filled)_ | `destructive` |
+| `danger` | `ghost` | `ghost` + `className="text-destructive"` |
+| _(no equivalent)_ | _(no equivalent)_ | `link` |
+
+> When both `variant` and `mode` appear on the same Tractor button, derive the DS variant from the **combination**, not from either prop alone. Dropping `mode` without updating `variant` is the most common migration error.
+
+> `danger` + `ghost` has no single DS variant: DS `destructive` is filled-only. Map to `ghost` and add `className="text-destructive"` to keep the destructive color — plain `ghost` silently loses it.
+
+## 5. Size mapping (Tractor → DS)
+
+| Tractor `size` | DS `size` | Note |
+| --- | --- | --- |
+| `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-only button)_ | `icon` | size-8 |
+| _(icon-only, small)_ | `icon-sm` | size-6 |
+| _(icon-only, large)_ | `icon-lg` | size-10 |
+
+## 6. Other prop changes
+
+| Tractor prop | DS equivalent | Notes |
+| --- | --- | --- |
+| `block` | `block` | Identical — `true` makes the button full-width |
+| `component={X}` (IconButton) | _(removed)_ | Icon becomes a JSX child instead |
+| `isLoading` | _(removed)_ | Render your own spinner as a child |
+| `leftIcon` / `rightIcon` | _(removed)_ | Pass the icon as a child; position is inferred from DOM order |
+| `as` | `render` | Base UI render-prop pattern (see cross-cutting skill) |
+
+## 7. Before / After examples
+
+### 7a. Standard button (variant + mode → DS variant)
+
+**Before (Tractor):**
+```tsx
+import { Button } from '@aircall/tractor';
+
+<Button variant="secondary" mode="outline" size="small">
+  Cancel
+</Button>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+
+<Button variant="outline" size="lg">
+  Cancel
+</Button>
+```
+
+> Tractor `small` = 40px → DS `size="lg"` = 40px (exact match). Do not use `size="sm"` (32px).
+
+### 7b. Primary button with icon child
+
+**Before (Tractor):**
+```tsx
+import { Play } from '@aircall/react-icons';
+import { Button } from '@aircall/tractor';
+
+<Button variant="primary" size="small" onClick={onLaunch}>
+  <Icon component={Play} size={16} />
+  Launch
+</Button>
+```
+
+**After (DS):**
+```tsx
+import { Play } from '@aircall/react-icons';
+import { Button } from '@aircall/ds';
+
+<Button variant="default" size="lg" onClick={onLaunch}>
+  <Play />
+  Launch
+</Button>
+```
+
+> Tractor `small` = 40px → DS `size="lg"` = 40px (exact match).
+
+> DS sizes SVGs automatically via `[&_svg:not([class*='size-'])]:size-4`. Do not pass a `size` prop to the icon.
+
+### 7c. IconButton → icon-only Button
+
+**Before (Tractor):**
+```tsx
+import { MoreVertical } from '@aircall/react-icons';
+import { IconButton } from '@aircall/tractor';
+
+<IconButton
+  component={MoreVertical}
+  aria-label="More actions"
+  disabled={isLoading}
+/>
+```
+
+**After (DS):**
+```tsx
+import { MoreVertical } from '@aircall/react-icons';
+import { Button } from '@aircall/ds';
+
+<Button size="icon" aria-label="More actions" disabled={isLoading}>
+  <MoreVertical />
+</Button>
+```
+
+### 7d. Ghost icon-only button (mode + variant combination)
+
+**Before (Tractor):**
+```tsx
+import { Pause } from '@aircall/react-icons';
+import { Button } from '@aircall/tractor';
+
+<Button mode="ghost" variant="secondary" size="xSmall" aria-label="Pause">
+  <Pause />
+</Button>
+```
+
+**After (DS):**
+```tsx
+import { Pause } from '@aircall/react-icons';
+import { Button } from '@aircall/ds';
+
+<Button variant="ghost" size="icon-sm" aria-label="Pause">
+  <Pause />
+</Button>
+```
+
+### 7e. Link-style button using `render` prop
+
+**Before (Tractor):**
+```tsx
+import { Button } from '@aircall/tractor';
+import { Link } from 'react-router-dom';
+
+<Button as={Link} to="/settings" variant="secondary" mode="ghost">
+  Settings
+</Button>
+```
+
+**After (DS):**
+```tsx
+import { Button } from '@aircall/ds';
+import { Link } from 'react-router-dom';
+
+<Button variant="ghost" render={<Link to="/settings" />}>
+  Settings
+</Button>
+```
+
+## 8. Common mistakes
+
+### Mistake 1: Keeping `mode` as a separate prop
+
+```tsx
+// WRONG — DS Button has no `mode` prop; it is silently ignored
+<Button variant="secondary" mode="outline">Cancel</Button>
+
+// CORRECT — fold mode into variant
+<Button variant="outline">Cancel</Button>
+```
+
+**Mechanism:** DS collapses Tractor's orthogonal (variant × mode) space into a single `variant`. Passing `mode` passes an unknown prop that does nothing — the button renders with the `secondary` fill instead of the outline style.
+
+`Source: packages/ds/src/components/button.tsx` — `buttonVariants` has no `mode` key.
+
+---
+
+### Mistake 2: Icon-only button without an `icon*` size
+
+```tsx
+// WRONG — size="default" gives h-8 px-2 padding; the button won't be square
+<Button aria-label="More actions">
+  <MoreVertical />
+</Button>
+
+// CORRECT — icon-only buttons must use size="icon", "icon-sm", or "icon-lg"
+<Button size="icon" aria-label="More actions">
+  <MoreVertical />
+</Button>
+```
+
+**Mechanism:** The `icon` sizes set `size-8` (width AND height), producing a square. Non-icon sizes add horizontal padding and a fixed height only — the button will be wider than it is tall, misaligning the icon visually.
+
+`Source: packages/ds/src/components/button.tsx` — `size.icon = 'size-8'`, `size.default = 'h-8 gap-1.5 px-2 …'`.
+
+---
+
+### Mistake 3: Using `as` instead of `render` for polymorphic buttons
+
+```tsx
+// WRONG — DS Button is Base UI, not Radix; it has no `as` prop
+<Button as={Link} to="/settings" variant="ghost">Settings</Button>
+
+// CORRECT — use the Base UI `render` prop
+<Button render={<Link to="/settings" />} variant="ghost">Settings</Button>
+```
+
+**Mechanism:** Base UI primitives replaced Radix UI in `@aircall/ds`. The `asChild`/`as` pattern from Radix is gone; Base UI uses a `render` prop that accepts a JSX element. Additional props (like `to`) go on the element passed to `render`, not on `Button` itself.
+
+`Source: packages/ds/src/components/button.tsx` — `Button` extends `ButtonPrimitive.Props` from `@base-ui/react/button`, which exposes `render`.
+
+---
+
+### Mistake 4: Passing a `size` number to the icon child
+
+```tsx
+// WRONG — explicit size prop overrides DS auto-sizing and breaks icon-lg layout
+<Button size="lg">
+  <Play size={16} />
+  Launch
+</Button>
+
+// CORRECT — let DS size the icon automatically
+<Button size="lg">
+  <Play />
+  Launch
+</Button>
+```
+
+**Mechanism:** DS applies `[&_svg:not([class*='size-'])]:size-4` (or `size-6` for `lg`/`icon-lg`) to auto-size SVGs. A `size` attribute on the icon sets an inline `width`/`height` that wins over Tailwind utility classes, locking the icon to the wrong size.
+
+`Source: packages/ds/src/components/button.tsx` — base class includes `[&_svg:not([class*='size-'])]:size-4`.

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

@@ -0,0 +1,278 @@
+---
+name: aircall-ds/migrate-tractor/card
+description: >
+  Migrate bespoke hand-rolled card components (plain div/Box with border/shadow/
+  padding) to the @aircall/ds Card compound (Card, CardHeader, CardTitle,
+  CardDescription, CardAction, CardContent, CardFooter). Load when a file
+  contains an in-app card implementation or imports card-like primitives 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/card.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+Tractor had no `Card` component. Apps grew bespoke card implementations — `<div>` or Tractor `<Box>` elements with hand-rolled borders, shadows, padding, and per-use-case variations. DS `Card` is the single component to unify all of them.
+
+| App pattern (Tractor-era) | @aircall/ds |
+| --- | --- |
+| Root `<div>` / `<Box>` with border, shadow, radius, bg, padding | `Card` |
+| Title element inside the card header region | `CardTitle` (inside `CardHeader`) |
+| Subtitle / description element | `CardDescription` (inside `CardHeader`) |
+| Header region (`<div>` wrapping title + subtitle) | `CardHeader` |
+| Top-right control (icon button, menu trigger) | `CardAction` (inside `CardHeader`) |
+| Body / content region | `CardContent` |
+| Footer / actions region | `CardFooter` |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle
+```
+
+## 3. Imports
+
+```tsx
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Button
+} from '@aircall/ds';
+import { MoreVertical } from '@aircall/react-icons';
+```
+
+Never import icons from `lucide-react` directly — always use `@aircall/react-icons`.
+
+## 4. Size prop
+
+`Card` accepts a `size` prop (`"default" | "sm"`). Setting it on the root propagates via `data-size` + Tailwind group selectors to **all** sub-components — padding, gap, and title font size all scale together. Never add per-part `p-*` overrides to achieve a compact variant; use `size="sm"` instead.
+
+| DS `size` | Padding | Gap | Title size |
+| --- | --- | --- | --- |
+| `"default"` (omit prop) | `py-4` / `px-4` | `gap-4` | `text-base` |
+| `"sm"` | `py-3` / `px-3` | `gap-3` | `text-sm` |
+
+## 5. Before / After
+
+### 5a. Basic card — replacing a bespoke surface
+
+**Before (Tractor-era bespoke component):**
+```tsx
+import { Box, Typography } from '@aircall/tractor';
+
+<Box
+  className="rounded-xl border border-neutral-200 bg-white p-4 shadow-sm"
+  display="flex"
+  flexDirection="column"
+  gap="space-16"
+>
+  <Box display="flex" flexDirection="column" gap="space-4">
+    <Typography variant="headingSmall">Card title</Typography>
+    <Typography variant="bodySmall" color="neutral.600">
+      A short supporting description.
+    </Typography>
+  </Box>
+  <Box>
+    <p>Card body content goes here.</p>
+  </Box>
+  <Box display="flex" justifyContent="flex-end">
+    <Button variant="primary" size="small">Action</Button>
+  </Box>
+</Box>
+```
+
+**After (DS):**
+```tsx
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Button } from '@aircall/ds';
+
+<Card className="w-[350px]">
+  <CardHeader>
+    <CardTitle>Card title</CardTitle>
+    <CardDescription>A short supporting description.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">Card body content goes here.</p>
+  </CardContent>
+  <CardFooter>
+    <Button variant="default" size="lg">Action</Button>
+  </CardFooter>
+</Card>
+```
+
+Key changes:
+- Delete all hand-rolled surface styles (border, shadow, radius, bg, padding) — `Card` owns all of it.
+- Map title/subtitle to `CardTitle` + `CardDescription` inside `CardHeader`.
+- Map body to `CardContent`; actions to `CardFooter`.
+- `CardFooter` renders with `border-t bg-muted/50` by default (distinct action bar). For a plain footer add `className="bg-transparent border-none"`.
+
+### 5b. Compact card using `size="sm"`
+
+**Before:**
+```tsx
+import { Box, Typography } from '@aircall/tractor';
+
+<Box className="rounded-xl border border-neutral-200 bg-white p-3 shadow-sm flex flex-col gap-3">
+  <Typography variant="headingXSmall">Compact card</Typography>
+  <p className="text-xs">Body content.</p>
+</Box>
+```
+
+**After:**
+```tsx
+import { Card, CardContent, CardHeader, CardTitle } from '@aircall/ds';
+
+<Card size="sm">
+  <CardHeader>
+    <CardTitle>Compact card</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">Body content.</p>
+  </CardContent>
+</Card>
+```
+
+Setting `size="sm"` on `Card` scales all sub-components — no per-part padding overrides needed.
+
+### 5c. Card with a header action
+
+**Before:**
+```tsx
+import { Box, Typography } from '@aircall/tractor';
+import { IconButton } from '@aircall/tractor';
+import { MoreVertical } from '@aircall/react-icons';
+
+<Box className="rounded-xl border bg-white p-4 relative">
+  <Box display="flex" justifyContent="space-between" alignItems="flex-start">
+    <Typography variant="headingSmall">With action</Typography>
+    <IconButton component={MoreVertical} aria-label="Open menu" />
+  </Box>
+</Box>
+```
+
+**After:**
+```tsx
+import { Card, CardAction, CardHeader, CardTitle, Button } from '@aircall/ds';
+import { MoreVertical } from '@aircall/react-icons';
+
+<Card>
+  <CardHeader>
+    <CardTitle>With action</CardTitle>
+    <CardAction>
+      <Button variant="ghost" size="icon" aria-label="Open menu">
+        <MoreVertical />
+      </Button>
+    </CardAction>
+  </CardHeader>
+</Card>
+```
+
+`CardAction` must live **inside** `CardHeader` — the header is a CSS grid that auto-places it in the top-right (`col-start-2 row-span-2`). Rendered elsewhere it loses positioning entirely.
+
+---
+
+## 6. Common mistakes
+
+### Mistake 1 — Keeping hand-rolled surface styles on the root element
+
+```tsx
+// ❌ Wrong — double-styles the surface; shadow and border clash with Card's ring
+<Card className="border border-neutral-200 rounded-xl shadow-sm bg-white p-4">
+  <CardContent>Content</CardContent>
+</Card>
+
+// ✅ Correct — Card owns border, radius, bg, and padding; only true one-offs belong in className
+<Card className="w-[350px]">
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+`Card` already applies `rounded-xl border bg-card py-4` (plus ring, text color, and overflow). Adding these again creates double borders and mismatched shadows that diverge from the design token.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 2 — Placing `CardAction` outside `CardHeader`
+
+```tsx
+// ❌ Wrong — CardAction is not positioned; it renders inline with body content
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardAction>
+    <Button variant="ghost" size="icon" aria-label="Menu"><MoreVertical /></Button>
+  </CardAction>
+  <CardContent>Body</CardContent>
+</Card>
+
+// ✅ Correct — CardAction inside CardHeader uses the header grid to pin top-right
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardAction>
+      <Button variant="ghost" size="icon" aria-label="Menu"><MoreVertical /></Button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>Body</CardContent>
+</Card>
+```
+
+`CardHeader` uses `grid auto-rows-min has-data-[slot=card-action]:grid-cols-[1fr_auto]`. `CardAction` carries `data-slot="card-action"` and is placed via `col-start-2 row-span-2`. Outside `CardHeader`, no grid parent exists and the action renders in normal flow.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 3 — Using per-part padding overrides instead of `size="sm"`
+
+```tsx
+// ❌ Wrong — overriding padding per part breaks the sizing contract and diverges from tokens
+<Card>
+  <CardHeader className="px-3 py-2">
+    <CardTitle className="text-sm">Compact</CardTitle>
+  </CardHeader>
+  <CardContent className="px-3">Body</CardContent>
+</Card>
+
+// ✅ Correct — size="sm" on the root scales all sub-components consistently
+<Card size="sm">
+  <CardHeader>
+    <CardTitle>Compact</CardTitle>
+  </CardHeader>
+  <CardContent>Body</CardContent>
+</Card>
+```
+
+`Card` propagates `data-size="sm"` to sub-components via the `group/card` modifier. Each part responds with `group-data-[size=sm]/card:px-3`, `group-data-[size=sm]/card:py-3`, and `group-data-[size=sm]/card:text-sm`. Overriding padding individually bypasses this mechanism and produces inconsistent spacing.
+
+Source: `packages/ds/src/components/card.tsx`
+
+### Mistake 4 — Adding bottom padding to `Card` when a footer is present
+
+```tsx
+// ❌ Wrong — adds visible gap between footer and card bottom edge
+<Card className="pb-4">
+  <CardContent>Body</CardContent>
+  <CardFooter>Actions</CardFooter>
+</Card>
+
+// ✅ Correct — Card auto-removes bottom padding when CardFooter is present
+<Card>
+  <CardContent>Body</CardContent>
+  <CardFooter>Actions</CardFooter>
+</Card>
+```
+
+`Card` uses `has-data-[slot=card-footer]:pb-0` to remove its own bottom padding when a `CardFooter` is present, so the footer's rounded corners (`rounded-b-xl`) flush with the card edge. Forcing `pb-4` overrides this and leaves a visible gap.
+
+Source: `packages/ds/src/components/card.tsx`