# Skeleton

> Loading placeholder that mirrors the layout of incoming content.

- Status: stable
- Group: feedback
- Page: https://www.digitaltableteur.com/design-system/components/skeleton
- Contract: https://www.digitaltableteur.com/contracts/v1/Skeleton.contract.json

## When to use

Skeleton holds the shape of content that is still loading so the layout never jumps: pick the variant that mirrors what will appear (text with a lines count, avatar, card, or free-form rect/circle sized via width/height) and compose several to sketch the incoming view. Each skeleton renders a polite role=status span whose visually hidden text is its label (by default the translated busyIndicator.loading string); pass decorative on all but one skeleton of a composed view, or on all of them when the surrounding component already announces loading. The shimmer is decorative and turns off under prefers-reduced-motion. Family rule: Skeleton for layouts, Spinner for sub-second unknown waits, Progress for measurable work.

## When not to use

- Do not use Skeleton for measurable work (uploads, multi-step jobs); that is Progress territory.
- Do not leave skeletons on screen after content fails to load; resolve to an error state instead.
- Do not use Skeleton for measurable work like uploads; Progress communicates completion, Skeleton only promises layout.

## Look-alikes

- EmptyState: Do not use EmptyState for errors or loading; AlertBanner owns failures and Skeleton owns loading.
- Progress: Do not use Skeleton for measurable work (uploads, multi-step jobs); that is Progress territory.
- Spinner: Do not scatter one spinner per element while a view loads; use a Skeleton layout or one region-level spinner.

## Props

| Prop | Type | Default | Description | Required |
| --- | --- | --- | --- | --- |
| `variant` | `"text" \| "circle" \| "rect" \| "avatar" \| "card"` | `text` | Shape variant. Defaults to `text`. | No |
| `width` | `number \| string` | none | Width (px or %) | No |
| `height` | `number \| string` | none | Height (px) | No |
| `lines` | `number` | `3` | Number of lines for text variant. Defaults to `3`. | No |
| `className` | `string` | `""` | Optional className. | No |
| `label` | `string` | none | Visually hidden text that names what is loading, read inside the status region. Defaults to the translated busyIndicator.loading string ("Loading"). Ignored when decorative. | No |
| `decorative` | `boolean` | `false` | Hide this skeleton from assistive tech (aria-hidden, no status region). Use it on every skeleton but one when several sketch one view, or when the surrounding component already announces loading. Defaults to `false`. | No |
| `animate` | `boolean` | `true` | Animate shimmer (disabled with prefers-reduced-motion). Defaults to `true`. | No |

## Variants

- Available variants: `text`, `circle`, `rect`, `avatar`, `card` (default `text`).

## Invalid combinations

The contract records no invalid combinations.

## Keyboard

The contract records no keyboard interaction.

## Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

| Level | Rule | How it is checked |
| --- | --- | --- |
| MUST | ARIA: Each non-decorative instance is a role=status span with aria-live=polite, named by aria-label, whose content is the same label as visually hidden text (default: the translated busyIndicator.loading string), so the label is live-region content and is readable in browse mode; whether a region inserted together with its text is announced depends on the screen reader. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: Decorative renders aria-hidden="true" with no role, live region or text; when several skeletons sketch one view, keep one labelled and mark the rest decorative so the view is one status, not many. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: Shimmer suppressed under prefers-reduced-motion. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | Required stories produce no axe violations at the configured severity. | Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8. |
| MUST | The accessibility tree (role, name, state) matches the committed snapshot for every required story. | Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2. |
| MUST | The component remains legible and operable under a real browser forced-colors: active pass. | Automated by `npm run test:stories:hc`. |
| MUST | A human completed an end-to-end accessibility review of this component. | Manual review, last on 2026-11-04. |
| SHOULD | Mirror the real layout; same widths, heights, and rhythm as the content that will replace it; so the swap is seamless. | Not stated in the contract. |
| SHOULD | Name what is loading in the label prop ("Loading article", not "Loading content") for assistive tech. | Not stated in the contract. |
| SHOULD | Compose variants (avatar + text lines inside a card) to sketch whole modules; see the ComposedPage example. | Not stated in the contract. |
| SHOULD | Give one composed region one labelled status and wrap the skeletons inside it in an aria-hidden container; Skeleton has no decorative prop, so every bare instance is its own live region. | Not stated in the contract. |
| SHOULD NOT | Do not keep skeletons on screen when loading fails; resolve to an error state; a forever-shimmer reads as a hang. | Not stated in the contract. |

## Install and import

- Install: `npm install @digitaltableteur/react` (version 0.9.1, restricted access on npm).
- Import: `import { Skeleton } from "@digitaltableteur/react";`
- Entry point: `@digitaltableteur/react/feedback` exports it too.
- Styles: import `@digitaltableteur/react/style.css` once at the app boundary.
- Also available as the custom element `<dt-skeleton>`; see the custom elements manifest.

## Links

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/Skeleton.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/skeleton.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.