@aircall/blocks 0.5.1 → 0.7.0

package/skills/aircall-blocks/migrate-dashboard/loading/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: aircall-blocks/migrate-dashboard/loading
+description: >
+  Migrate @dashboard/library Loading, Loader, and Spinner to @aircall/ds
+  Spinner (animated spinner) and Skeleton (content placeholder). Load when a
+  file imports Loading, Loader, or Spinner from @dashboard/library.
+type: sub-skill
+library: aircall-blocks
+library_version: "0.5.1"
+requires:
+  - aircall-blocks/setup
+  - aircall-blocks/migrate-dashboard
+sources:
+  - "aircall/hydra:packages/ds/src/index.ts"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+## 1. Component mapping
+
+| `@dashboard/library` | `@aircall/ds` | Notes |
+| --- | --- | --- |
+| `Loading` | `Spinner` | Full-area centered spinner — replace the flex wrapper with a parent `div` using Tailwind layout classes |
+| `Loader` | `Spinner` | Inline spinning icon — direct 1-to-1 replacement |
+| `Spinner` | `Spinner` | Already a spinner — direct 1-to-1 replacement |
+
+**Content placeholders:** when `Loading` was used while async content loads (e.g. inside a card or list panel), prefer `Skeleton` over `Spinner` — it better communicates that content is incoming rather than a blocking operation.
+
+## 2. Verified DS exports (`packages/ds/src/index.ts`)
+
+```
+Spinner, spinnerVariants
+Skeleton
+```
+
+## 3. Prop mapping
+
+### `Loading` → `Spinner`
+
+| `@dashboard/library` prop | DS equivalent | Action |
+| --- | --- | --- |
+| `size` (number, e.g. `40`) | `size` (`"sm"` \| `"default"` \| `"lg"` \| `"xl"`) | Map to the nearest token (see table below) |
+| `color` (tractor color token, e.g. `"primary-500"`) | `className` | Use a Tailwind text-color class |
+| `data-test` | `data-test` | Pass through as-is |
+| Flex layout (`FlexProps`) | Tailwind parent | Wrap `Spinner` in a container `<div className="flex h-full w-full items-center justify-center">` |
+
+**Size mapping:**
+
+| Old `size` (px) | New `size` token |
+| --- | --- |
+| ≤ 12 | `"sm"` (12 px) |
+| 13–16 | `"default"` (16 px) |
+| 17–20 | `"lg"` (20 px) |
+| ≥ 21 | `"xl"` (24 px) |
+
+When `size` was not set, `Loading` defaulted to `40` and `Spinner` defaulted to `30` — both map to `"xl"`.
+
+### `Loader` → `Spinner`
+
+| `@dashboard/library` prop | DS equivalent | Action |
+| --- | --- | --- |
+| `size` (number) | `size` (token string) | Map using the table above |
+| `color` | `className` | Use a Tailwind text-color class |
+| `data-test` | `data-test` | Pass through as-is |
+
+### `Skeleton`
+
+`Skeleton` has no direct `@dashboard/library` predecessor — it is introduced as a
+replacement for `Loading` when used during content fetch. It accepts a plain `<div>`
+`className` for sizing and shape.
+
+## 4. Before / After examples
+
+### 4a. `Loading` (full-area centered spinner)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Loading } from '@dashboard/library';
+
+<Loading data-test="reports-loading" size={40} color="primary-500" />
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Spinner } from '@aircall/ds';
+
+<div
+  data-test="reports-loading"
+  className="flex h-full w-full items-center justify-center"
+>
+  <Spinner size="xl" className="text-primary" />
+</div>
+```
+
+Key changes:
+- The flex-center wrapper that `Loading` rendered internally must now be an explicit parent `<div>`.
+- Numeric `size` becomes a size token string.
+- Tractor color token (`"primary-500"`) becomes a Tailwind text-color class (`"text-primary"`).
+
+### 4b. `Loader` (inline spinner icon)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Loader } from '@dashboard/library';
+
+<Loader size={20} color="neutral-700" />
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Spinner } from '@aircall/ds';
+
+<Spinner size="lg" className="text-neutral-700" />
+```
+
+`Loader` was already a bare spinning icon with no layout wrapper — `Spinner` is the direct replacement.
+
+### 4c. `Spinner` (bare spinning icon)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Spinner } from '@dashboard/library';
+
+<Spinner size={30} />
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Spinner } from '@aircall/ds';
+
+<Spinner size="xl" />
+```
+
+The API is nearly identical; only the `size` type changes from a numeric pixel value to a string token.
+
+### 4d. `Loading` as a content placeholder (prefer `Skeleton`)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { Loading } from '@dashboard/library';
+
+function StatsCard({ isLoading, value }) {
+  return (
+    <div className="p-4">
+      {isLoading ? <Loading size={24} /> : <span>{value}</span>}
+    </div>
+  );
+}
+```
+
+**After (`@aircall/ds`):**
+```tsx
+import { Skeleton } from '@aircall/ds';
+
+function StatsCard({ isLoading, value }) {
+  return (
+    <div className="p-4">
+      {isLoading ? <Skeleton className="h-6 w-24" /> : <span>{value}</span>}
+    </div>
+  );
+}
+```
+
+Use `Skeleton` when the spinner was filling the space of specific content that will
+appear once data loads. `Skeleton` communicates the shape of the incoming content, which
+reduces layout shift and improves perceived performance compared to a generic spinner.
+
+## 5. Common Mistakes
+
+### Mistake 1 — Keeping the `Loading` flex wrapper implicit
+
+```tsx
+// WRONG — Spinner has no built-in flex-center layout; it renders as an inline SVG
+import { Spinner } from '@aircall/ds';
+
+<Spinner size="xl" className="h-full w-full" />
+
+// CORRECT — wrap in an explicit flex container to center in the available area
+import { Spinner } from '@aircall/ds';
+
+<div className="flex h-full w-full items-center justify-center">
+  <Spinner size="xl" />
+</div>
+```
+
+`Loading` rendered its own `<Flex … alignItems="center" justifyContent="center">` internally. DS `Spinner` is a bare SVG icon; the centering layout must be provided by the caller.
+
+Source: `packages/ds/src/components/spinner.tsx`
+
+---
+
+### Mistake 2 — Passing a numeric pixel value to `size`
+
+```tsx
+// WRONG — size accepts only the four named tokens; a number is a type error
+import { Spinner } from '@aircall/ds';
+
+<Spinner size={30} />
+
+// CORRECT — use the nearest token string
+import { Spinner } from '@aircall/ds';
+
+<Spinner size="xl" />
+```
+
+`Spinner.Props` extends `VariantProps<typeof spinnerVariants>` where `size` is
+`"sm" | "default" | "lg" | "xl" | null | undefined`. Passing a number does not satisfy
+the type and will error at compile time.
+
+Source: `packages/ds/src/components/spinner.tsx`
+
+---
+
+### Mistake 3 — Passing a Tractor color token to `className`
+
+```tsx
+// WRONG — Tractor color tokens are not valid Tailwind classes and produce no styling
+import { Spinner } from '@aircall/ds';
+
+<Spinner className="primary-500" />
+
+// CORRECT — use a Tailwind text-color utility class
+import { Spinner } from '@aircall/ds';
+
+<Spinner className="text-primary" />
+```
+
+`Spinner` renders a `Loader2Icon` SVG that inherits its color from the CSS `currentColor`
+(the `text-current` Tailwind class is baked in via `spinnerVariants`). To tint it, apply
+a `text-*` Tailwind class — a bare Tractor token string like `"primary-500"` is not a
+recognized utility and has no effect.
+
+Source: `packages/ds/src/components/spinner.tsx`
+
+---
+
+### Mistake 4 — Using `Spinner` for content-area placeholders instead of `Skeleton`
+
+```tsx
+// WRONG — a spinner implies an active blocking operation, not an inline content gap
+import { Spinner } from '@aircall/ds';
+
+function UserName({ isLoading, name }) {
+  return isLoading ? <Spinner size="sm" /> : <span>{name}</span>;
+}
+
+// CORRECT — use Skeleton to represent the shape of the incoming content
+import { Skeleton } from '@aircall/ds';
+
+function UserName({ isLoading, name }) {
+  return isLoading ? <Skeleton className="h-4 w-32" /> : <span>{name}</span>;
+}
+```
+
+`Skeleton` (an animated pulse `<div>`) is semantically and visually correct for
+inline content placeholders because it mirrors the dimensions of the element it replaces.
+`Spinner` is intended for full-area or button loading states where the action source is
+explicit.
+
+Source: `packages/ds/src/components/skeleton.tsx`

package/skills/aircall-blocks/migrate-dashboard/page-header/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: aircall-blocks/migrate-dashboard/page-header
+description: >
+  Migrate @dashboard/library PageHeader, PageHeaderLink, and GaramondTitleTypography
+  to @aircall/blocks DashboardPageHeader and its sub-components (DashboardPageHeaderTitle,
+  DashboardPageHeaderActions, DashboardPageHeaderAction, DashboardPageHeaderNav,
+  DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderTitleGroup,
+  DashboardPageHeaderSubtitle, DashboardPageHeaderDescription). Load when a file
+  imports PageHeader or PageHeaderLink from @dashboard/library.
+type: sub-skill
+library: aircall-blocks
+library_version: "0.5.1"
+requires:
+  - aircall-blocks/setup
+  - aircall-blocks/migrate-dashboard
+sources:
+  - "aircall/hydra:packages/blocks/src/index.ts"
+---
+
+This skill builds on aircall-blocks/migrate-dashboard.
+
+## 1. Component mapping
+
+| @dashboard/library | @aircall/blocks |
+| --- | --- |
+| `PageHeader` (root container) | `DashboardPageHeader` |
+| `PageHeader` `title` prop (small heading) | `DashboardPageHeaderTitle size="sm"` |
+| `PageHeader` `largeTitle` prop (large heading) | `DashboardPageHeaderTitle size="lg"` |
+| `PageHeader` `subtitle` prop | `DashboardPageHeaderDescription` inside `DashboardPageHeaderSubtitle` inside `DashboardPageHeaderTitleGroup` |
+| `PageHeader` `renderTitleRight` render prop | `DashboardPageHeaderActions` + `DashboardPageHeaderAction` |
+| `PageHeader` `renderExtra` render prop | Extra children appended directly inside `DashboardPageHeader` |
+| `PageHeader` `renderSubLeft` / `renderSubRight` render props | Children inside `DashboardPageHeaderSubtitle` |
+| `PageHeader` `gobackLinkRoute` + `gobackLinkText` props | `DashboardPageHeaderNav` + `DashboardPageHeaderNavBack` |
+| `PageHeaderLink` (standalone back-link component) | `DashboardPageHeaderNavBack` inside `DashboardPageHeaderNav` |
+| `PageHeader` `icon` prop (tractor `Icon` component) | `DashboardPageHeaderPrefix` (put icon/flag/avatar inside) |
+| `PageHeader` `avatarSrc` / `avatarInitials` / `renderAvatar` props | `DashboardPageHeaderPrefix` (put `Avatar` or equivalent inside) |
+| `PageHeader` `activeTabId` / `onTabChange` / `Tab.*` children | No direct equivalent — implement tabs separately below the header |
+| `GaramondTitleTypography` / `useGaramondFont` prop | Not reproduced — use `DashboardPageHeaderTitle size="lg"` (system font) |
+| `PageHeader` `titleProps` (BoxProps spread) | Remove — `DashboardPageHeaderTitleGroup` handles layout |
+
+`DashboardPageHeader` is a flat-children composition: sub-components self-place via CSS
+grid areas — declaration order determines render order within each area. You do **not** pass
+data via props on the root; every piece of content is a named sub-component child.
+
+## 2. Imports
+
+```tsx
+// All DashboardPageHeader parts from @aircall/blocks
+import {
+  DashboardPageHeader,
+  DashboardPageHeaderTitle,
+  DashboardPageHeaderTitleGroup,
+  DashboardPageHeaderSubtitle,
+  DashboardPageHeaderDescription,
+  DashboardPageHeaderActions,
+  DashboardPageHeaderAction,
+  DashboardPageHeaderNav,
+  DashboardPageHeaderNavBack,
+  DashboardPageHeaderPrefix,
+} from '@aircall/blocks';
+
+// DS primitives used alongside (Tooltip, DropdownMenu, etc.)
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@aircall/ds';
+```
+
+## 3. Before / After
+
+### 3a. Simple title-only header
+
+**Before (`@dashboard/library`):**
+```tsx
+import { PageHeader } from '@dashboard/library';
+
+function AnalyticsHeader() {
+  return <PageHeader largeTitle="Analytics" />;
+}
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import { DashboardPageHeader, DashboardPageHeaderTitle } from '@aircall/blocks';
+
+function AnalyticsHeader() {
+  return (
+    <DashboardPageHeader>
+      <DashboardPageHeaderTitle size="lg">Analytics</DashboardPageHeaderTitle>
+    </DashboardPageHeader>
+  );
+}
+```
+
+Key changes:
+- `largeTitle` string prop → `DashboardPageHeaderTitle size="lg"` child with the string as children.
+- `title` string prop → `DashboardPageHeaderTitle size="sm"` (level-2 pages that have a nav row).
+- No `data-test` prop — set `data-test` directly on `DashboardPageHeader` if needed.
+
+---
+
+### 3b. Title with actions (renderTitleRight)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { PageHeader } from '@dashboard/library';
+import { Button } from '@aircall/tractor';
+
+function CampaignsHeader() {
+  return (
+    <PageHeader
+      largeTitle="Campaigns"
+      renderTitleRight={() => (
+        <Button variant="primary" size="regular">Create campaign</Button>
+      )}
+    />
+  );
+}
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  DashboardPageHeader,
+  DashboardPageHeaderTitle,
+  DashboardPageHeaderActions,
+  DashboardPageHeaderAction,
+} from '@aircall/blocks';
+
+function CampaignsHeader() {
+  return (
+    <DashboardPageHeader>
+      <DashboardPageHeaderTitle size="lg">Campaigns</DashboardPageHeaderTitle>
+      <DashboardPageHeaderActions>
+        <DashboardPageHeaderAction variant="default">Create campaign</DashboardPageHeaderAction>
+      </DashboardPageHeaderActions>
+    </DashboardPageHeader>
+  );
+}
+```
+
+Key changes:
+- `renderTitleRight` render prop → `DashboardPageHeaderActions` child containing `DashboardPageHeaderAction` elements.
+- Tractor `Button variant="primary"` → `DashboardPageHeaderAction variant="default"` (size is fixed by the component).
+- Icon-only action buttons: `DashboardPageHeaderAction variant="outline" size="icon-lg"`.
+
+---
+
+### 3c. Back navigation (gobackLinkRoute / gobackLinkText)
+
+**Before (`@dashboard/library`):**
+```tsx
+import { PageHeader } from '@dashboard/library';
+
+function NumberDetailHeader() {
+  return (
+    <PageHeader
+      title="Number settings"
+      gobackLinkRoute="/numbers"
+      gobackLinkText="Back to numbers"
+      renderTitleRight={() => <button>Save</button>}
+    />
+  );
+}
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  DashboardPageHeader,
+  DashboardPageHeaderNav,
+  DashboardPageHeaderNavBack,
+  DashboardPageHeaderTitle,
+  DashboardPageHeaderActions,
+  DashboardPageHeaderAction,
+} from '@aircall/blocks';
+import { Link } from 'react-router-dom';
+
+function NumberDetailHeader() {
+  return (
+    <DashboardPageHeader>
+      <DashboardPageHeaderNav>
+        <DashboardPageHeaderNavBack render={<Link to="/numbers" />}>
+          Back to numbers
+        </DashboardPageHeaderNavBack>
+      </DashboardPageHeaderNav>
+      <DashboardPageHeaderTitle size="sm">Number settings</DashboardPageHeaderTitle>
+      <DashboardPageHeaderActions>
+        <DashboardPageHeaderAction variant="default">Save</DashboardPageHeaderAction>
+      </DashboardPageHeaderActions>
+    </DashboardPageHeader>
+  );
+}
+```
+
+Key changes:
+- `gobackLinkRoute` + `gobackLinkText` props → `DashboardPageHeaderNav` > `DashboardPageHeaderNavBack` with `render={<Link to="…" />}` (Base UI render prop — avoids a nested `<a><button>` violation).
+- When nav is present, use `size="sm"` on `DashboardPageHeaderTitle` (level-2 pattern).
+- The `PageHeaderLink` standalone export is replaced the same way.
+
+---
+
+### 3d. Header with prefix (icon / avatar) and subtitle
+
+**Before (`@dashboard/library`):**
+```tsx
+import { PageHeader } from '@dashboard/library';
+import { PhoneOutlined } from '@aircall/icons';
+
+function NumberHeader({ number, description }) {
+  return (
+    <PageHeader
+      largeTitle={number.name}
+      subtitle={description}
+      icon={PhoneOutlined}
+      renderSubRight={() => <span>{number.countryCode}</span>}
+    />
+  );
+}
+```
+
+**After (`@aircall/blocks`):**
+```tsx
+import {
+  DashboardPageHeader,
+  DashboardPageHeaderPrefix,
+  DashboardPageHeaderTitleGroup,
+  DashboardPageHeaderTitle,
+  DashboardPageHeaderSubtitle,
+  DashboardPageHeaderDescription,
+} from '@aircall/blocks';
+import { Phone } from '@aircall/react-icons';
+
+function NumberHeader({ number, description }) {
+  return (
+    <DashboardPageHeader>
+      <DashboardPageHeaderPrefix>
+        <Phone className="size-5 text-muted-foreground" />
+      </DashboardPageHeaderPrefix>
+      <DashboardPageHeaderTitleGroup>
+        <DashboardPageHeaderTitle size="lg">{number.name}</DashboardPageHeaderTitle>
+        <DashboardPageHeaderSubtitle>
+          <DashboardPageHeaderDescription>{description}</DashboardPageHeaderDescription>
+          <span className="text-sm text-muted-foreground">{number.countryCode}</span>
+        </DashboardPageHeaderSubtitle>
+      </DashboardPageHeaderTitleGroup>
+    </DashboardPageHeader>
+  );
+}
+```
+
+Key changes:
+- `icon` prop → `DashboardPageHeaderPrefix` containing the icon element; icons come from `@aircall/react-icons`, not `@aircall/icons`.
+- `subtitle` prop → `DashboardPageHeaderDescription` inside `DashboardPageHeaderSubtitle` inside `DashboardPageHeaderTitleGroup`.
+- `renderSubLeft` / `renderSubRight` → siblings of `DashboardPageHeaderDescription` inside `DashboardPageHeaderSubtitle`.
+- When `DashboardPageHeaderPrefix` is present, `DashboardPageHeaderTitleGroup` resets its left padding automatically (CSS group selector).
+- `avatarSrc` / `avatarInitials` / `renderAvatar` → render your avatar element inside `DashboardPageHeaderPrefix`.
+
+---
+
+### 3e. Tabs (activeTabId / onTabChange / Tab.Menu children)
+
+`PageHeader` accepted `Tab.Menu` / `Tab.Content` children and wired them into a
+`Tab.Container`. `DashboardPageHeader` has no built-in tab support.
+
+Pattern: render a DS `Tabs` compound below `DashboardPageHeader`, outside of it.
+
+```tsx
+// Before
+import { PageHeader, Tab } from '@dashboard/library';
+<PageHeader largeTitle="Reports" activeTabId="overview" onTabChange={setTab}>
+  <Tab.Menu tabId="overview">Overview</Tab.Menu>
+  <Tab.Menu tabId="calls">Calls</Tab.Menu>
+  <Tab.Content tabId="overview"><Overview /></Tab.Content>
+  <Tab.Content tabId="calls"><Calls /></Tab.Content>
+</PageHeader>
+
+// After — use DS Tabs below the header
+import { DashboardPageHeader, DashboardPageHeaderTitle } from '@aircall/blocks';
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aircall/ds';
+
+<DashboardPageHeader>
+  <DashboardPageHeaderTitle size="lg">Reports</DashboardPageHeaderTitle>
+</DashboardPageHeader>
+<Tabs value={tab} onValueChange={setTab}>
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="calls">Calls</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview"><Overview /></TabsContent>
+  <TabsContent value="calls"><Calls /></TabsContent>
+</Tabs>
+```
+
+---
+
+## 4. Common mistakes
+
+### Mistake 1 — Passing title/largeTitle as props instead of children
+
+```tsx
+// ❌ Wrong — PageHeader prop API; DashboardPageHeader ignores unknown props
+<DashboardPageHeader largeTitle="Analytics" title="Overview" />
+
+// ✅ Correct — title is a child component
+<DashboardPageHeader>
+  <DashboardPageHeaderTitle size="lg">Analytics</DashboardPageHeaderTitle>
+</DashboardPageHeader>
+```
+
+`DashboardPageHeader` extends `React.ComponentProps<'div'>` — it has no `title`, `largeTitle`, or `subtitle` props. Passing them results in unknown HTML attributes forwarded to the DOM and no visible heading rendered.
+
+Source: `packages/blocks/src/components/dashboard-page-header.tsx`
+
+### Mistake 2 — Using a Router Link directly instead of the `render` prop on DashboardPageHeaderNavBack
+
+```tsx
+// ❌ Wrong — nests <a> inside <button>, invalid HTML
+<DashboardPageHeaderNavBack>
+  <Link to="/numbers">Back to numbers</Link>
+</DashboardPageHeaderNavBack>
+
+// ✅ Correct — render prop replaces the <button> element with the Link
+<DashboardPageHeaderNavBack render={<Link to="/numbers" />}>
+  Back to numbers
+</DashboardPageHeaderNavBack>
+```
+
+`DashboardPageHeaderNavBack` renders a `Button` (which renders a `<button>`). Nesting a
+`<Link>` (`<a>`) inside a `<button>` is invalid HTML and breaks keyboard navigation.
+The `render` prop (Base UI pattern) polymorphically replaces the root element while
+keeping all button behavior.
+
+Source: `packages/blocks/src/components/dashboard-page-header.tsx`
+
+### Mistake 3 — Placing DashboardPageHeaderActions outside DashboardPageHeader
+
+```tsx
+// ❌ Wrong — outside the @container context; grid-area:actions has no effect
+<DashboardPageHeader>
+  <DashboardPageHeaderTitle size="lg">Analytics</DashboardPageHeaderTitle>
+</DashboardPageHeader>
+<DashboardPageHeaderActions>
+  <DashboardPageHeaderAction variant="default">Export</DashboardPageHeaderAction>
+</DashboardPageHeaderActions>
+
+// ✅ Correct — all sub-components are children of DashboardPageHeader
+<DashboardPageHeader>
+  <DashboardPageHeaderTitle size="lg">Analytics</DashboardPageHeaderTitle>
+  <DashboardPageHeaderActions>
+    <DashboardPageHeaderAction variant="default">Export</DashboardPageHeaderAction>
+  </DashboardPageHeaderActions>
+</DashboardPageHeader>
+```
+
+Sub-components use `[grid-area:actions]` Tailwind classes that only resolve inside the
+CSS grid established by `DashboardPageHeader`'s inner grid `div`. Rendered outside, they
+appear in normal document flow and lose their placement entirely.
+
+Source: `packages/blocks/src/components/dashboard-page-header.tsx`
+
+### Mistake 4 — Importing icons from @aircall/icons instead of @aircall/react-icons
+
+```tsx
+// ❌ Wrong — @aircall/icons is the old tractor-era icon package
+import { PhoneOutlined } from '@aircall/icons';
+
+// ✅ Correct — @aircall/react-icons is the current icon package
+import { Phone } from '@aircall/react-icons';
+```
+
+`DashboardPageHeader` and the DS components it composes (`Button`, etc.) are built for
+`@aircall/react-icons` (lucide-based). The `@aircall/icons` package ships SVG components
+with a different size/color API (`size` / `color` props vs `className`).
+
+Source: `packages/blocks/src/components/dashboard-page-header.tsx`
+
+### Mistake 5 — Using GaramondTitleTypography / useGaramondFont in the new stack
+
+```tsx
+// ❌ Wrong — GaramondTitleTypography and useGaramondFont are @dashboard/library internals
+import { GaramondTitleTypography } from '@dashboard/library';
+<GaramondTitleTypography>{title}</GaramondTitleTypography>
+
+// ❌ Wrong — no equivalent prop on DashboardPageHeaderTitle
+<DashboardPageHeaderTitle size="lg" useGaramondFont>Analytics</DashboardPageHeaderTitle>
+
+// ✅ Correct — use DashboardPageHeaderTitle with size="lg" (system font, trimmed baseline)
+<DashboardPageHeaderTitle size="lg">Analytics</DashboardPageHeaderTitle>
+```
+
+`GaramondTitleTypography` and `useGaramondFont` were `@dashboard/library`-only overrides
+for the ITC Garamond Narrow font. `DashboardPageHeaderTitle size="lg"` renders `text-3xl
+font-bold` in the system font stack with `leading-10`, matching the design spec without
+a custom typeface dependency.
+
+Source: `packages/blocks/src/components/dashboard-page-header.tsx`