@aircall/ds 0.14.0 → 0.15.0

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

@@ -0,0 +1,274 @@
+---
+name: aircall-ds/migrate-tractor/badge
+description: >
+  Migrate Tractor Tag and CounterBadge to @aircall/ds Badge, CounterBadge, BadgeGroup,
+  and BadgeGroupCount. Load when a file imports Tag or CounterBadge from @aircall/tractor.
+  Maps Tractor variant (grey/primary/blue/red/yellow/green/purple/pink/dark* prefixes)
+  to the DS color + tone two-axis model, and Tractor status Badge (dot) to AvatarBadge.
+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/badge.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+Tractor's badge surface had three distinct concepts that map to different DS components:
+
+| Tractor component | DS replacement | Notes |
+| --- | --- | --- |
+| `<Tag>` | `<Badge>` | Color model changes from single `variant` to `color` + `tone` |
+| `<CounterBadge>` | `<CounterBadge>` | No `max` prop — cap the value yourself before passing as children |
+| `<Badge>` (status dot) | `<AvatarBadge>` | Tractor's dot-indicator badge is unrelated to DS `Badge`; see the avatar skill |
+| _(grouping)_ | `<BadgeGroup>` + `<BadgeGroupCount>` | Wraps multiple badges; `BadgeGroupCount` renders the overflow "+N" chip |
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Badge, BadgeGroup, BadgeGroupCount
+CounterBadge, counterBadgeVariants
+AvatarBadge
+Chip, ChipRemove
+```
+
+## 3. Imports
+
+```tsx
+import { Badge, BadgeGroup, BadgeGroupCount, CounterBadge } from '@aircall/ds';
+```
+
+Icons inside badges import from `@aircall/react-icons` — never from `lucide-react` directly.
+
+## 4. `Tag` variant → `Badge` color + tone
+
+DS Badge uses two orthogonal props instead of Tractor's single `variant`:
+
+- `color`: `charcoal` (default) · `red` · `green` · `blue` · `purple` · `yellow` · `pink`
+- `tone`: `dark` · `medium-dark` · `medium-light` · `light` (default)
+
+| Tractor `variant` | DS `color` | DS `tone` |
+| --- | --- | --- |
+| `grey` / `white` | `charcoal` | `light` |
+| `secondary` | `charcoal` | `medium-light` |
+| `lightSecondary` | `charcoal` | `light` |
+| `darkSecondary` | `charcoal` | `medium-dark` |
+| `primary` | `green` | `medium-light` |
+| `lightPrimary` | `green` | `light` |
+| `darkPrimary` | `green` | `dark` |
+| `blue` | `blue` | `medium-light` |
+| `darkBlue` | `blue` | `dark` |
+| `red` | `red` | `medium-light` |
+| `darkRed` | `red` | `dark` |
+| `yellow` | `yellow` | `medium-light` |
+| `darkYellow` | `yellow` | `dark` |
+| `green` | `green` | `medium-light` |
+| `darkGreen` | `green` | `dark` |
+| `purple` | `purple` | `medium-light` |
+| `darkPurple` | `purple` | `dark` |
+| `pink` | `pink` | `medium-light` |
+
+> The base color variant maps to `medium-light`; `dark*` variants map to `dark` or `medium-dark`. `light*` variants map to `light`. Pick the tone that best matches the surface.
+
+### Hard-coded hex colors (`bg` prop)
+
+When Tractor used a hard-coded hex (e.g. `bg="#0761B5"`), pass it via `legacyColor` — DS resolves it to the nearest `color` + `tone` at render time from an internal map. Unknown hexes fall back to `charcoal` / `dark`.
+
+```tsx
+<Badge legacyColor="#0761B5">Sales</Badge>
+```
+
+## 5. Size mapping
+
+| Tractor `size` | DS `size` |
+| --- | --- |
+| `xSmall` | `default` (20px) |
+| `small` | `default` (20px) |
+| `regular` (default) | `default` (20px) |
+| `large` | `lg` (24px) |
+
+DS has no `mode` prop (`outline` / `fill`). Use a lighter `tone` (e.g. `light`) to approximate the old outline look.
+
+## 6. CounterBadge
+
+DS `CounterBadge` has no `max` prop. Cap the displayed value yourself before passing as children:
+
+```tsx
+<CounterBadge>{count > 99 ? '99+' : count}</CounterBadge>
+```
+
+Available `variant` values: `default` (destructive background) · `secondary` · `ghost`.
+
+## 7. Grouping badges
+
+Use `BadgeGroup` to wrap a set of badges with consistent spacing, and `BadgeGroupCount` for the trailing overflow chip:
+
+```tsx
+<BadgeGroup>
+  <Badge color="blue" tone="medium-light">Support</Badge>
+  <Badge color="green" tone="medium-light">Active</Badge>
+  <BadgeGroupCount>{overflow}</BadgeGroupCount>
+</BadgeGroup>
+```
+
+## 8. Before / After examples
+
+### 8a. Simple Tag → Badge (variant rename)
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+
+<Tag variant="primary">Active</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+
+<Badge color="green" tone="medium-light">Active</Badge>
+```
+
+> Tractor `primary` = green brand color → DS `color="green"` `tone="medium-light"`.
+
+### 8b. Dark variant
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+
+<Tag variant="darkBlue">Escalated</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+
+<Badge color="blue" tone="dark">Escalated</Badge>
+```
+
+### 8c. Hard-coded hex color
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+
+<Tag bg="#0761B5">Sales</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+
+<Badge legacyColor="#0761B5">Sales</Badge>
+```
+
+### 8d. CounterBadge with max cap
+
+**Before (Tractor):**
+```tsx
+import { CounterBadge } from '@aircall/tractor';
+
+<CounterBadge count={count} max={99} />
+```
+
+**After (DS):**
+```tsx
+import { CounterBadge } from '@aircall/ds';
+
+<CounterBadge>{count > 99 ? '99+' : count}</CounterBadge>
+```
+
+### 8e. Icon inside a Badge
+
+**Before (Tractor):**
+```tsx
+import { Tag } from '@aircall/tractor';
+import { CheckCircle } from '@aircall/react-icons';
+
+<Tag variant="green"><CheckCircle size={12} /> Verified</Tag>
+```
+
+**After (DS):**
+```tsx
+import { Badge } from '@aircall/ds';
+import { CheckCircle } from '@aircall/react-icons';
+
+<Badge color="green" tone="medium-light"><CheckCircle /> Verified</Badge>
+```
+
+> DS auto-sizes SVG children via `[&>svg]:size-3!` (default) or `[&>svg]:size-4!` (lg). Do not pass a `size` prop to the icon.
+
+## 9. Common mistakes
+
+### Mistake 1: Using `variant` instead of `color` + `tone`
+
+```tsx
+// Wrong — DS Badge has no `variant` prop; it is silently ignored
+<Badge variant="primary">Active</Badge>
+
+// Correct — map to the two-axis color + tone model
+<Badge color="green" tone="medium-light">Active</Badge>
+```
+
+**Mechanism:** DS Badge replaced Tractor's single `variant` string with two orthogonal props `color` and `tone`. Passing `variant` goes to the underlying `span` as an unknown HTML attribute and has no visual effect — the badge renders with the default charcoal/light appearance instead of the intended color.
+
+Source: `packages/ds/src/components/badge.tsx` — `badgeVariants` has `color` and `tone` keys, no `variant` key.
+
+---
+
+### Mistake 2: Mapping Tractor status `Badge` (dot) to DS `Badge`
+
+```tsx
+// Wrong — DS Badge is a label chip, not a status dot
+<Badge status="online" />
+
+// Correct — Tractor's status dot maps to AvatarBadge
+import { Avatar, AvatarBadge, AvatarImage } from '@aircall/ds';
+
+<Avatar>
+  <AvatarImage src={src} alt={name} />
+  <AvatarBadge />
+</Avatar>
+```
+
+**Mechanism:** Tractor had two components both named `Badge`: a label chip (`Tag`) and a small status dot (`Badge`). DS names them differently — `Badge` is the label chip and `AvatarBadge` is the status indicator that composes inside `Avatar`. Migrating the dot to DS `Badge` renders a text chip with no content instead of a dot.
+
+Source: `packages/ds/src/components/badge.tsx` — `Badge` is a label chip; `packages/ds/src/components/avatar.tsx` exports `AvatarBadge` for the status dot.
+
+---
+
+### Mistake 3: Relying on DS `CounterBadge` to cap overflow automatically
+
+```tsx
+// Wrong — DS CounterBadge has no `max` prop; it renders the raw number
+<CounterBadge max={99} count={count} />
+
+// Correct — cap the value yourself before passing as children
+<CounterBadge>{count > 99 ? '99+' : count}</CounterBadge>
+```
+
+**Mechanism:** Tractor's `CounterBadge` accepted a `max` prop and formatted "99+" internally. DS `CounterBadge` is a presentational span that renders whatever children it receives — the cap logic is the caller's responsibility. Passing `max` and `count` as props results in an empty badge with two unknown HTML attributes instead of the formatted string.
+
+Source: `packages/ds/src/components/counter-badge.tsx` — `CounterBadge.Props` extends `useRender.ComponentProps<'span'>` with only a `variant` prop; no `max` or `count` keys.
+
+---
+
+### Mistake 4: Using `outline` / `fill` mode to style a badge
+
+```tsx
+// Wrong — DS Badge has no `mode` prop
+<Badge color="blue" mode="outline">Beta</Badge>
+
+// Correct — reach for a lighter tone to approximate the outline look
+<Badge color="blue" tone="light">Beta</Badge>
+```
+
+**Mechanism:** Tractor's `Tag` supported a `mode` prop (`outline` / `fill`) that toggled between a bordered and a filled appearance. DS Badge has no `mode` prop — the visual weight is controlled entirely by `tone`. A lighter tone (`light` or `medium-light`) produces a softer background that approximates the old outline look.
+
+Source: `packages/ds/src/components/badge.tsx` — `badgeVariants` has `size`, `color`, and `tone` variants; no `mode` variant.

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