@aircall/ds 0.13.0 → 0.15.0

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

@@ -0,0 +1,421 @@
+---
+name: aircall-ds/migrate-tractor/styling
+description: >
+  Convert Tractor layout and style primitives to @aircall/ds Tailwind classes and
+  tokens. Load when a file uses Typography, Flex, Box, Grid, Spacer, or the getColor
+  / getSpace / getRadii / defaultTheme helpers from @aircall/tractor. Covers the
+  highest-volume Tractor usages (these are not components with recipes — they map to
+  utility classes).
+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/02-design-tokens.md"
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/03-spacing.md"
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/07-typography.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Typography
+
+Tractor's `Typography` component is replaced by native HTML elements with Tailwind classes. No import needed.
+
+### Variant → Tailwind mapping
+
+#### Legacy variants
+
+| Tractor `variant=` | Tailwind classes |
+| --- | --- |
+| `displayXL` | `text-5xl font-bold` |
+| `displayXL2` | `text-5xl font-light` |
+| `displayL` | `text-4xl font-bold` |
+| `displayL2` | `text-4xl font-light` |
+| `displayM` | `text-3xl font-bold` |
+| `displayM2` | `text-3xl font-light` |
+| `displayS` | `text-xl font-bold` |
+| `displayS2` | `text-xl font-light` |
+| `heading` | `text-lg font-bold` |
+| `heading2` | `text-lg font-light` |
+| `subheading` | `text-base font-semibold` |
+| `subheading2` | `text-base font-normal` |
+| `body` | `text-sm font-medium` |
+| `body2` | `text-sm font-normal` |
+| `caption` | `text-xs font-medium` |
+| `caption2` | `text-xs font-normal` |
+| `overline` | `text-tiny font-medium` |
+| `overline2` | `text-tiny font-normal` |
+
+#### New variants
+
+| Tractor `variant=` | Tailwind classes |
+| --- | --- |
+| `supportingRegularXS` | `text-tiny font-normal` |
+| `supportingMediumXS` | `text-tiny font-medium` |
+| `supportingSemiboldXS` | `text-tiny font-semibold` |
+| `supportingRegularS` | `text-xs font-normal` |
+| `supportingMediumS` | `text-xs font-medium` |
+| `supportingSemiboldS` | `text-xs font-semibold` |
+| `bodyRegularS` | `text-sm font-normal` |
+| `bodyMediumS` | `text-sm font-medium` |
+| `bodySemiboldS` | `text-sm font-semibold` |
+| `bodyRegularM` | `text-base font-normal` |
+| `bodyMediumM` | `text-base font-medium` |
+| `bodySemiboldM` | `text-base font-semibold` |
+| `headingLightXS` | `text-lg font-light` |
+| `headingMediumXS` | `text-lg font-medium` |
+| `headingBoldXS` | `text-lg font-bold` |
+| `headingLightS` | `text-xl font-light` |
+| `headingMediumS` | `text-xl font-medium` |
+| `headingBoldS` | `text-xl font-bold` |
+| `headingLightM` | `text-3xl font-light` |
+| `headingMediumM` | `text-3xl font-medium` |
+| `headingBoldM` | `text-3xl font-bold` |
+| `headingLightL` | `text-[2.625rem] font-light` |
+| `headingMediumL` | `text-[2.625rem] font-medium` |
+| `headingBoldL` | `text-[2.625rem] font-bold` |
+| `headingLightXL` | `text-5xl font-light` |
+| `headingMediumXL` | `text-5xl font-medium` |
+| `headingBoldXL` | `text-5xl font-bold` |
+
+### Typography color prop mapping
+
+| Tractor `color=` | Tailwind class |
+| --- | --- |
+| `text.base` | `text-foreground` |
+| `text.secondary` | `text-muted-foreground` |
+| `text.disabled` | `text-muted-foreground/50` |
+| `text.inverted` | `text-primary-foreground` |
+| `primary.500` | `text-primary` |
+| `critical.500` / `critical.800` | `text-destructive` |
+| `informative.500` | `text-info` |
+| `success.500` / `success.800` | `text-success` |
+| `warning.500` / `warning.800` | `text-warning` |
+| `secondary.light` | `text-muted-foreground` |
+
+### Typography examples
+
+```tsx
+// Before
+import { Typography } from '@aircall/tractor';
+<Typography variant="heading">Page Title</Typography>
+<Typography variant="body" mt={2} mb={4} color="text.secondary">Text</Typography>
+<Typography ellipsis>Long text</Typography>
+<Typography ellipsis={2}>Multi-line clamp</Typography>
+<Typography wordBreak="break-word">Text</Typography>
+
+// After — no import needed
+<h1 className="text-lg font-bold">Page Title</h1>
+<p className="text-sm font-medium mt-2 mb-4 text-muted-foreground">Text</p>
+<p className="truncate">Long text</p>
+<p className="line-clamp-2">Multi-line clamp</p>
+<p className="break-words">Text</p>
+```
+
+**Do NOT add `leading-*` classes.** Tailwind's `text-*` size classes already include appropriate line-heights. Adding `leading-6` alongside `text-base` is redundant and overrides the built-in value.
+
+### Semantic HTML elements
+
+| Use case | Element |
+| --- | --- |
+| Page title | `<h1>` |
+| Section title | `<h2>` |
+| Subsection | `<h3>`, `<h4>` |
+| Paragraph | `<p>` |
+| Inline text | `<span>` |
+| Link | `<a className="text-sm font-medium text-primary hover:underline">` |
+
+---
+
+## 2. Layout — Flex, Box, Grid, Spacer
+
+Tractor's `Flex`, `Box`, `Grid`, and `Spacer` become plain `<div>` elements (or semantic HTML) with Tailwind classes. No import needed.
+
+### Flex
+
+```tsx
+// Before
+<Flex gap={2} alignItems="center" justifyContent="space-between" p={3}>
+  {children}
+</Flex>
+
+// After
+<div className="flex gap-2 items-center justify-between p-3">
+  {children}
+</div>
+```
+
+| Tractor prop | Tailwind class |
+| --- | --- |
+| `flexDirection="column"` | `flex-col` |
+| `alignItems="center"` | `items-center` |
+| `justifyContent="space-between"` | `justify-between` |
+| `flexWrap="wrap"` | `flex-wrap` |
+| `flex={1}` | `flex-1` |
+| `gap={N}` | `gap-{tw}` (see spacing table) |
+
+### Box
+
+`Box` is a generic layout primitive — replace with `<div>` and move all system props to Tailwind classes.
+
+```tsx
+// Before
+<Box p={4} bg="primary.500" borderRadius="sm" />
+
+// After
+<div className="p-4 bg-primary rounded-md" />
+```
+
+### Grid
+
+```tsx
+// Before
+<Grid gridTemplateColumns="1fr 1fr" gap={3} />
+
+// After
+<div className="grid grid-cols-2 gap-3" />
+```
+
+### Spacer
+
+`Spacer` adds whitespace between siblings. Replace with `gap-*` on the parent flex/grid container, or `space-x-*` / `space-y-*` as a fallback.
+
+```tsx
+// Before
+<Flex>
+  <A />
+  <Spacer space="s" />  {/* 16px */}
+  <B />
+</Flex>
+
+// After — prefer gap on the parent
+<div className="flex gap-4">
+  <A />
+  <B />
+</div>
+```
+
+---
+
+## 3. Spacing scale
+
+**Convert by pixel equivalence** — Tractor and Tailwind scales differ. Never assume the key number maps to the same Tailwind key.
+
+| Tractor key | px | Tailwind |
+| --- | --- | --- |
+| `0` | 0 | `0` |
+| `0.5` | 2px | `0.5` |
+| `1` | 4px | `1` |
+| `2` | 8px | `2` |
+| `3` | 12px | `3` |
+| `4` | 16px | `4` |
+| `5` | 24px | `6` |
+| `6` | 32px | `8` |
+| `7` | 40px | `10` |
+| `8` | 64px | `16` |
+| `9` | 80px | `20` |
+
+### Named spacing
+
+| Tractor name | px | Tailwind |
+| --- | --- | --- |
+| `xxxs` | 4px | `1` |
+| `xxs` | 8px | `2` |
+| `xs` | 12px | `3` |
+| `s` | 16px | `4` |
+| `m` | 24px | `6` |
+| `l` | 32px | `8` |
+| `xl` | 40px | `10` |
+| `xxl` | 64px | `16` |
+| `xxxl` | 80px | `20` |
+
+### Spacing prop mapping
+
+| Tractor prop | Tailwind prefix |
+| --- | --- |
+| `m` | `m-` |
+| `mx` | `mx-` |
+| `my` | `my-` |
+| `mt` | `mt-` |
+| `mr` | `mr-` |
+| `mb` | `mb-` |
+| `ml` | `ml-` |
+| `p` | `p-` |
+| `px` | `px-` |
+| `py` | `py-` |
+| `pt` | `pt-` |
+| `pr` | `pr-` |
+| `pb` | `pb-` |
+| `pl` | `pl-` |
+
+Pixel literal values become Tailwind arbitrary values: `mt="16px"` → `mt-[16px]`.
+
+Responsive objects become breakpoint prefixes: `m={{ _: 2, md: 4 }}` → `m-2 md:m-4`.
+
+---
+
+## 4. Design tokens — colors, radius, helpers
+
+### Replacing `getColor` / `getSpace` / `getRadii` / `defaultTheme.*`
+
+These runtime helpers do not exist in DS. They lived inside `styled()` blocks, which are removed entirely. Map each consumed value to its Tailwind equivalent:
+
+```tsx
+// Before
+const Styled = styled.div`
+  color: ${getColor('primary.500')};
+  padding: ${getSpace('m')};
+  border-radius: ${getRadii('sm')};
+`;
+
+// After
+<div className="text-primary p-6 rounded-md" />
+```
+
+For values that genuinely must be dynamic (computed at runtime), use the CSS variable directly:
+
+```tsx
+style={{ color: 'var(--primary)' }}
+```
+
+### Semantic color tokens (text)
+
+| Tractor token | Tailwind class |
+| --- | --- |
+| `text-base` | `text-foreground` |
+| `text-secondary` | `text-muted-foreground` |
+| `text-placeholder` | `text-muted-foreground` |
+| `text-disabled` | `text-muted-foreground` |
+| `text-highlight` | `text-accent-foreground` |
+| `text-critical` | `text-destructive` |
+| `text-success` | `text-success` |
+| `text-warning` | `text-warning` |
+| `text-info` | `text-info` |
+
+### Semantic color tokens (surfaces)
+
+| Tractor token | Tailwind class |
+| --- | --- |
+| `surface-background` | `bg-page-background` |
+| `surface-default` | `bg-background` |
+| `surface-overlay` | `bg-overlay` |
+| `surface-info` | `bg-info-background` |
+| `surface-success` | `bg-success-background` |
+| `surface-warning` | `bg-warning-background` |
+| `surface-critical` | `bg-destructive-background` |
+| `surface-disabled` | `bg-muted` |
+
+### Icon color tokens
+
+Icon color tokens share the text semantic layer — apply `text-*` to the icon's container or rely on `currentColor` fill.
+
+| Tractor token | Tailwind class |
+| --- | --- |
+| `icon-base` | `text-foreground` |
+| `icon-default` | `text-muted-foreground` |
+| `icon-highlight` | `text-accent-foreground` |
+| `icon-primary` | `text-primary` |
+| `icon-disabled` | `text-muted-foreground` |
+| `icon-critical` | `text-destructive` |
+| `icon-success` | `text-success` |
+| `icon-warning` | `text-warning` |
+| `icon-info` | `text-info` |
+
+### Border radius
+
+| Tractor token | Tailwind class | Notes |
+| --- | --- | --- |
+| `none` | `rounded-none` | Exact |
+| `xs` | `rounded-sm` | Closest (2px off) |
+| `sm` | `rounded-md` | Exact |
+| `md` | `rounded-xl` | Closest (2px off) |
+| `default` | `rounded-2xl` | Exact |
+| `lg` | `rounded-3xl` | Exact |
+| `full` | `rounded-full` | Exact |
+
+`xs` and `md` have no exact DS equivalent — flag for visual QA.
+
+### Palette tokens and raw colors — designer sign-off required
+
+If you encounter a **palette token** (e.g. `primary.500`, `critical.700`, `neutral-200`) or a **raw hex/rgb color** in the codebase, **do not map it yourself**. Flag it for designer review. The tables above cover only Tractor _semantic_ tokens (no trailing number), which can be migrated directly.
+
+---
+
+## 5. Dark mode
+
+DS supports `light`, `dark`, and `system` themes via `ThemeProvider`. Always use **semantic tokens** so colors swap automatically:
+
+```tsx
+// ✅ Adapts automatically
+<div className="bg-card text-card-foreground border border-border" />
+
+// ❌ Locked to light mode
+<div className="bg-white text-black border border-gray-200" />
+```
+
+For dark-mode-only overrides use the `dark:` variant: `dark:border-input`.
+
+---
+
+## 6. Common mistakes
+
+### Mistake 1 — Copying the Tractor spacing key as the Tailwind key
+
+```tsx
+// ❌ Wrong — Tractor 5 = 24px, but Tailwind 5 = 20px
+<Box gap={5} />  →  <div className="gap-5" />
+
+// ✅ Correct — convert by px: 24px = Tailwind 6
+<div className="gap-6" />
+```
+
+Tractor's scale diverges from Tailwind's at key `5` (24px vs 20px). Always resolve the pixel value first, then find the Tailwind equivalent.
+
+**Source:** `packages/ds/src/styles/globals.css`
+
+### Mistake 2 — Translating token names directly to matching class names
+
+```tsx
+// ❌ Wrong — Tractor `getRadii('sm')` = 8px, Tailwind `rounded-sm` = 6px
+getRadii('sm')  →  rounded-sm
+
+// ✅ Correct — resolve to px first: 8px = rounded-md
+getRadii('sm')  →  rounded-md
+```
+
+Token names that look identical (`sm`, `xs`, `lg`) resolve to different pixel values in Tractor vs DS. Read the resolved pixel value, then pick the Tailwind class that matches.
+
+**Source:** `packages/ds/src/styles/globals.css`
+
+### Mistake 3 — Adding `leading-*` when migrating Typography
+
+```tsx
+// ❌ Wrong — Tailwind text-base already includes the correct line-height
+<h2 className="text-base leading-6 font-semibold">Title</h2>
+
+// ✅ Correct — text size class sets line-height; font weight only
+<h2 className="text-base font-semibold">Title</h2>
+```
+
+Tailwind's `text-*` utility classes bundle a default `line-height`. Adding `leading-*` overrides the built-in value and is almost always wrong during migration.
+
+**Source:** `packages/ds/src/styles/globals.css`
+
+### Mistake 4 — Mapping palette tokens without designer sign-off
+
+```tsx
+// ❌ Wrong — palette tokens cannot be mechanically mapped
+getColor('primary.500')  →  bg-primary  // may be wrong design intent
+
+// ✅ Correct for semantic tokens only
+getColor('text-base')  →  text-foreground
+
+// For palette tokens (primary.500, critical.700, neutral-200), flag for designer review.
+```
+
+Palette tokens (those with a trailing number) carry design intent that cannot be determined mechanically. Only semantic tokens (no trailing number) have a direct mapping.
+
+**Source:** `packages/ds/src/styles/globals.css`

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

@@ -0,0 +1,250 @@
+---
+name: aircall-ds/migrate-tractor/tabs
+description: >
+  Migrate Tractor Tab, TabList, Tab.Item, TabPanel, and TabToggle (segmented
+  control) to the @aircall/ds Tabs compound (Tabs, TabsList, TabsTrigger,
+  TabsContent). Load when a file imports Tab, TabList, TabPanel, or TabToggle
+  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/tabs.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 tabs-specific steps below.
+
+## 1. Component mapping
+
+| Tractor | @aircall/ds |
+| --- | --- |
+| `TabList` | `TabsList` |
+| `Tab.Item` (individual tab trigger) | `TabsTrigger` |
+| `TabPanel` | `TabsContent` |
+| `Tab` (state owner) | `Tabs` |
+| `TabToggle` (segmented control) | `ToggleGroup` — **not** Tabs (separate migration) |
+
+Active state in Tractor was tracked by a numeric index. DS tracks it with a string `value` that links each `TabsTrigger` to its matching `TabsContent`.
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Tabs, TabsList, TabsTrigger, TabsContent
+ToggleGroup, ToggleGroupItem
+```
+
+## 3. Imports
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aircall/ds';
+```
+
+For the segmented-control pattern (`TabToggle`):
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from '@aircall/ds';
+```
+
+## 4. Before / After
+
+### 4a. Uncontrolled tabs (default open)
+
+**Before (Tractor):**
+```tsx
+import { Tab, TabList, TabPanel } from '@aircall/tractor';
+
+<Tab defaultIndex={0}>
+  <TabList>
+    <Tab.Item>Overview</Tab.Item>
+    <Tab.Item>Activity</Tab.Item>
+  </TabList>
+  <TabPanel>Overview panel.</TabPanel>
+  <TabPanel>Activity panel.</TabPanel>
+</Tab>
+```
+
+**After (DS):**
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aircall/ds';
+
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">Overview panel.</TabsContent>
+  <TabsContent value="activity">Activity panel.</TabsContent>
+</Tabs>
+```
+
+Key changes:
+- `defaultIndex={0}` (numeric) → `defaultValue="overview"` (string)
+- `Tab.Item` → `TabsTrigger` with a `value` prop
+- `TabPanel` → `TabsContent` with a matching `value` prop
+- There is no `size` prop and no `TabsList` `variant` — drop any Tractor equivalents
+
+### 4b. Controlled tabs
+
+**Before (Tractor):**
+```tsx
+import { Tab, TabList, TabPanel } from '@aircall/tractor';
+
+<Tab selectedIndex={activeTab} onChange={setActiveTab}>
+  <TabList>
+    <Tab.Item>Overview</Tab.Item>
+    <Tab.Item>Activity</Tab.Item>
+  </TabList>
+  <TabPanel>Overview panel.</TabPanel>
+  <TabPanel>Activity panel.</TabPanel>
+</Tab>
+```
+
+**After (DS):**
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aircall/ds';
+
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">Overview panel.</TabsContent>
+  <TabsContent value="activity">Activity panel.</TabsContent>
+</Tabs>
+```
+
+Key changes:
+- `selectedIndex` (number) → `value` (string)
+- `onChange` → `onValueChange`
+- State must be converted from a numeric index to a string key
+
+### 4c. Vertical orientation
+
+**Before (Tractor):**
+```tsx
+import { Tab, TabList, TabPanel } from '@aircall/tractor';
+
+<Tab orientation="vertical" defaultIndex={0}>
+  <TabList>
+    <Tab.Item>Settings</Tab.Item>
+    <Tab.Item>Billing</Tab.Item>
+  </TabList>
+  <TabPanel>Settings panel.</TabPanel>
+  <TabPanel>Billing panel.</TabPanel>
+</Tab>
+```
+
+**After (DS):**
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aircall/ds';
+
+<Tabs orientation="vertical" defaultValue="settings">
+  <TabsList>
+    <TabsTrigger value="settings">Settings</TabsTrigger>
+    <TabsTrigger value="billing">Billing</TabsTrigger>
+  </TabsList>
+  <TabsContent value="settings">Settings panel.</TabsContent>
+  <TabsContent value="billing">Billing panel.</TabsContent>
+</Tabs>
+```
+
+When conditionally styling by orientation in `className`, use `data-[orientation=horizontal]:` / `data-[orientation=vertical]:` — DS emits a `data-orientation` attribute, so a bare `data-horizontal:` selector won't match.
+
+---
+
+## 5. Common mistakes
+
+### Mistake 1 — Using numeric index state instead of string value
+
+```tsx
+// ❌ Wrong — value must be a string; passing a number silently prevents matching
+const [tab, setTab] = useState(0);
+<Tabs value={tab} onValueChange={setTab}>
+  <TabsTrigger value={0}>Overview</TabsTrigger>
+  <TabsContent value={0}>Overview panel.</TabsContent>
+</Tabs>
+
+// ✅ Correct — derive a string key; value must match between TabsTrigger and TabsContent
+const [tab, setTab] = useState('overview');
+<Tabs value={tab} onValueChange={setTab}>
+  <TabsTrigger value="overview">Overview</TabsTrigger>
+  <TabsContent value="overview">Overview panel.</TabsContent>
+</Tabs>
+```
+
+DS matches the active tab by strict string equality between `Tabs value`/`defaultValue`, `TabsTrigger value`, and `TabsContent value`. A numeric `0` never equals the string `"0"` — the active panel will not render.
+
+Source: `packages/ds/src/components/tabs.tsx`
+
+### Mistake 2 — Matching tabs by position instead of value
+
+```tsx
+// ❌ Wrong — panel order is irrelevant without value matching
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="activity">Overview panel.</TabsContent>
+  <TabsContent value="overview">Activity panel.</TabsContent>
+</Tabs>
+
+// ✅ Correct — value on TabsTrigger must match value on TabsContent
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">Overview panel.</TabsContent>
+  <TabsContent value="activity">Activity panel.</TabsContent>
+</Tabs>
+```
+
+Tractor matched panels by their position index, so DOM order determined which panel showed. DS matches by string value — the order of `TabsContent` elements in the DOM is irrelevant; mismatched `value` strings silently show the wrong panel.
+
+Source: `packages/ds/src/components/tabs.tsx`
+
+### Mistake 3 — Applying a `size` or `variant` prop
+
+```tsx
+// ❌ Wrong — DS Tabs has no size or variant prop; they are silently ignored
+<Tabs size="large" defaultValue="overview">…</Tabs>
+<TabsList variant="pills">…</TabsList>
+
+// ✅ Correct — DS renders exactly one style; drop size and variant entirely
+<Tabs defaultValue="overview">…</Tabs>
+<TabsList>…</TabsList>
+```
+
+DS Tabs has exactly one visual style. There is no `size` prop on `Tabs` and no `variant` prop on `TabsList`. Tractor's `size`/`variant` props do not map to anything — remove them without replacement.
+
+Source: `packages/ds/src/components/tabs.tsx`
+
+### Mistake 4 — Migrating `TabToggle` to `Tabs` instead of `ToggleGroup`
+
+```tsx
+// ❌ Wrong — TabToggle is a segmented control, not a tab panel pattern
+import { Tabs, TabsList, TabsTrigger } from '@aircall/ds';
+
+<Tabs defaultValue="month">
+  <TabsList>
+    <TabsTrigger value="week">Week</TabsTrigger>
+    <TabsTrigger value="month">Month</TabsTrigger>
+  </TabsList>
+</Tabs>
+
+// ✅ Correct — use ToggleGroup for segmented controls with no content panels
+import { ToggleGroup, ToggleGroupItem } from '@aircall/ds';
+
+<ToggleGroup type="single" defaultValue="month">
+  <ToggleGroupItem value="week">Week</ToggleGroupItem>
+  <ToggleGroupItem value="month">Month</ToggleGroupItem>
+</ToggleGroup>
+```
+
+`TabToggle` in Tractor is a segmented button control — it switches a value with no associated content panels. `Tabs` always expects paired `TabsContent` panels; using it for a segmented control couples content rendering to the selector unnecessarily. `ToggleGroup` is the direct DS equivalent.
+
+Source: `packages/ds/src/components/tabs.tsx`