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