---
title: "Skeleton"
description: "Stands where content will be while it loads — quiet placeholders in the shape of what is coming, lines of text, a block, a circle — and keeps the box the content will take, so that nothing moves when it arrives."
url: "https://tanrei.chnotchy.com/components/skeleton/"
last_updated: 2026-10-23T21:17:12.000Z
---

# Skeleton

> Stands where content will be while it loads — quiet placeholders in the shape of what is coming, lines of text, a block, a circle — and keeps the box the content will take, so that nothing moves when it arrives.

## Overview

A view often arrives before its content. A skeleton holds the shape of what is coming in the place where it will be: lines of text, a block for a picture or a control, a circle for a person’s picture. When the content arrives it takes the boxes that were held for it, and nothing a person was looking at, or about to press, moves.

It is a region and its placeholders. The region is said once to assistive technology — “Loading projects”, busy — and the placeholders say nothing by themselves. It waits a moment before it shows, so that a short wait shows a blank place of the right size instead of shapes that flash.

On the web it is `<tanrei-skeleton>` around your own elements with `class="tanrei-skeleton-placeholder"`. The other platforms have not implemented it yet.

### A skeleton, a loading indicator, a progress indicator, an empty state

Four components answer “there is nothing here yet”. Which one is decided by what is known about the wait and about what comes.

| The situation | Use | Why |
| --- | --- | --- |
| Content of a known shape will fill a region of a view, and the wait is long enough to see. | Skeleton | It holds the layout, so nothing moves on arrival, and it shows where things will be. |
| A short wait of unknown length whose result has no shape to hold, or is small: in a button, a row, a field, a status line. An action under way, such as saving or sending. | [Loading indicator](https://tanrei.chnotchy.com/components/loading-indicator/) | A mark is enough. Shapes for one row or one icon are noise. |
| A task whose progress can be measured, or that takes many seconds. | [Progress indicator](https://tanrei.chnotchy.com/components/progress-indicator/) | A skeleton says nothing about how far, and after a few seconds a person needs to know. |
| Nothing will come: the list is empty, the search found nothing. | [Empty state](https://tanrei.chnotchy.com/components/empty-state/) | A skeleton promises content. |
| Loading failed. | A [callout](https://tanrei.chnotchy.com/components/callout/) with the error status, in the place. | A skeleton that never ends is a lie. |
| The content is already there, and only its script, its picture or its font is late. | None of the four. The component holds its own box. | A skeleton does not know another component’s size. That component does. |

### Usage

Put the skeleton where the content will be when the wait starts, and replace it with the content when the wait ends. Give it a `label` that says what is loading. A placeholder is an empty element of your own with the class: a `<span>` anywhere, or a `<div>` where it is the child of a block, such as another `<div>`. Inside a heading or a paragraph it is a `<span>`.

**Web**

```html
<link rel="stylesheet" href="@tanrei/web/skeleton.css" />

<!-- Placeholders that are the skeleton's own children are stacked, with a gap. -->
<tanrei-skeleton label="Loading the project">
  <span class="tanrei-skeleton-placeholder" data-shape="block" style="block-size: 160px"></span>
  <span class="tanrei-skeleton-placeholder" style="inline-size: 12.5rem"></span>
  <span class="tanrei-skeleton-placeholder" data-lines="3"></span>
</tanrei-skeleton>

<!-- Anything more is your own layout, with the placeholders in it — where the content will be. -->
<tanrei-skeleton label="Loading the author's details">
  <div class="byline">
    <span class="tanrei-skeleton-placeholder" data-shape="circle" style="block-size: 40px"></span>
    <div>
      <h3><span class="tanrei-skeleton-placeholder" style="inline-size: 10rem"></span></h3>
      <p><span class="tanrei-skeleton-placeholder" data-lines="2"></span></p>
    </div>
  </div>
</tanrei-skeleton>

<!-- Part of the first presentation of a page, written by the server: shown at once, and right before any script. -->
<tanrei-skeleton show-delay="0" role="progressbar" aria-busy="true" aria-label="Loading the dashboard">
  …
</tanrei-skeleton>
<noscript>The dashboard needs JavaScript.</noscript>

<script type="module">
  import '@tanrei/web/components/skeleton';
</script>
```

**React**

```tsx
import { Skeleton } from '@tanrei/react';
import '@tanrei/web/skeleton.css';

{project ? (
  <ProjectCard project={project} />
) : (
  <Skeleton label="Loading the project">
    <span className="tanrei-skeleton-placeholder" data-shape="block" style={{ blockSize: 160 }} />
    <span className="tanrei-skeleton-placeholder" style={{ inlineSize: '12.5rem' }} />
    <span className="tanrei-skeleton-placeholder" data-lines={3} />
  </Skeleton>
)}
```

On the web the stylesheet is the whole component before any script runs: the shapes, the wait before it shows, the pulse, stillness under reduced motion and the outlines of forced colors. The element adds what a stylesheet cannot: the role and the name for assistive technology, keeping what the skeleton holds out of the focus order, and pausing while it cannot be seen.

## Specs

- Category: Communication
- Level: base
- Listing: default
- Page: https://tanrei.chnotchy.com/components/skeleton/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/skeleton.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | — |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the element `<tanrei-skeleton>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/skeleton`).
- React: `Skeleton` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-skeleton` | lagging |
| SwiftUI | `TanreiSkeleton` | planned |
| Jetpack Compose | `TanreiSkeleton` | planned |
| Flutter | `TanreiSkeleton` | planned |
| React Native | `Skeleton` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `decorative` (prop) | `decorative` | `isDecorative` | `decorative` | `decorative` | `decorative` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `container`: The region that stands in the content's place: a block as wide as the place it stands in and as tall as what it holds, with no fill, no edge, no padding and no elevation. It is what assistive technology is told about, once, and it carries no state: a skeleton takes no input.
- `placeholder`: A quiet filled shape in the place of one piece of the content: one or more lines of text, a block (a picture, a card, a control) or a circle (a person's picture, a round mark). It has the size the content will have and says nothing by itself.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `""` | `label` | What is loading, in the product's language ("Loading projects"): the name assistive technology is given for the whole skeleton, once. Never drawn. Left empty, it reads the product's words; Tanrei ships none of its own. Not read while decorative is true. |
| `decorative` | `boolean` | `false` | `decorative` | Whether something else already says this wait: a loading indicator beside it, a status text, a region the product itself exposes as busy and names. True keeps the whole skeleton from assistive technology, so that one wait is said once; it changes nothing that is drawn. |
| `showDelay` | `number` | — | `show-delay` | How long, in milliseconds, this skeleton waits from the moment it is inserted before it is drawn and exposed to assistive technology; 0 shows it as it is inserted. Null takes comp.skeleton.motion.show-delay, the system's answer for every skeleton. Set it to 0 where the skeleton is part of the first presentation of a page or a view, which has nothing else to show; leave it where content is fetched in a view that is already there. |

### Item: `placeholder`

One shape in the place of one piece of the content: lines of text, a block or a circle.

Names: Web `span`, SwiftUI `TanreiSkeletonPlaceholder`, Jetpack Compose `TanreiSkeletonPlaceholder`, Flutter `TanreiSkeletonPlaceholder`, React Native `SkeletonPlaceholder`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` | `enum`: `text`, `block`, `circle` | `"text"` | What the placeholder stands for. Text is one or more lines of the text style in effect where it stands. Block is a box: a picture, a card, a control, a row. Circle is a round box: a person's picture, a round mark. |
| `lines` | `number` | `1` | For text: how many lines the text will take, a whole number of 1 or more. The placeholder is exactly that many line boxes high. Not read for a block or a circle. |
| `inlineSize` | `number` | — | The placeholder's size along the line, in points. Null leaves it to the layout: the whole inline size of its place for text and for a block, the side of the square for a circle. A size the product's own layout gives the placeholder (a share of a row, a track of a grid) is used as it is and needs no prop. |
| `blockSize` | `number` | — | The placeholder's size across the line, in points: the height of a block, and the side of a circle. Null is one line of the text style in effect, or the size the product's own layout gives. Not read for text, whose height is its lines. |

### States

`enabled`

### Accessibility

- Role: `progressbar`
- Labeling: label is the accessible name of the whole skeleton: what is loading. Once shown, the skeleton is one element — a progressbar with no value, in the platform's busy (indeterminate) state — and its placeholders are hidden; during its show delay, and while decorative is true, it is not exposed at all. It is exposed exactly as a loading indicator is, because it says the same thing: something is loading here.
- Minimum target size: yes

- Not interactive: the skeleton takes no input and is never focusable (SKL-16, SKL-19), so there is no target of its own to size and minimumTarget holds trivially.
- One wait, said once. Every placeholder of a region belongs to one skeleton with one label; a skeleton inside another is silent (SKL-17). Where the same wait is already said — a loading indicator in a status row, a status text, a region the product itself marks busy and names — set decorative, or the wait is read twice.
- The skeleton does not announce that it appeared, and does not announce that the content arrived (SKL-16): it is removed with its busy state. Where arrival should be heard (results in answer to a search, a list that was asked for), the product says so through its own live region or the status text of the component that asked; a view that simply opens with its content needs no announcement.
- A wait shorter than the show delay shows and exposes nothing (SKL-7): no shapes that flash for a sighted person, and no progressbar that appears and vanishes for a screen-reader user.
- Nothing a person should read or use goes inside a skeleton: what it holds is kept from input and from assistive technology (SKL-19). A heading that is already known, a button that already works, stand outside it.
- The fill is decoration, held to no contrast ratio: comp.skeleton.placeholder.color is a low-emphasis fill, and in the default system it has the tone of the highest container step, so a placeholder on a surface of that tone is hard to see. The wait is never said by the fill alone: the label says it to assistive technology, and forced colors draw every placeholder as an outline (SKL-20).
- Motion: a pulse dims the fill by half and returns in 2 seconds in the default system, far below the three-per-second flash threshold; nothing moves and nothing brightens. Reduced motion stops it entirely (SKL-13): a large region that pulses is more than a small mark that does, and the shapes already say that the place is waiting.
- A skeleton that never ends tells a lie. The product replaces it with the content, with an empty state where nothing came, or with a callout of the error status where loading failed, and sets its own limit on the wait; a task that takes many seconds, or whose progress can be measured, is a progress indicator's.
- Text size, text spacing and reflow: SKL-21. A text placeholder follows the text style it stands in, so it grows with the reader's text size; a size given in points does not.

### Behaviour

Requirements in EARS form, each with its stable id.

- **SKL-1** THE skeleton SHALL lay itself out as a block that takes the whole inline size of the place it stands in and is as tall as what it holds: it SHALL lay out the placeholders that stand directly in it in one column, in the order given, each at its own size and at the start edge, comp.skeleton.container.gap apart, and SHALL leave placeholders that stand inside a layout of the product's own (a row, a grid, a card's own structure) to that layout, changing neither their place nor their size. THE skeleton SHALL draw no fill, no edge and no elevation, SHALL bring no padding and no outer space of its own, SHALL set no height of its own and SHALL NOT scroll or clip.
- **SKL-2** THE skeleton SHALL draw each placeholder as one box, or for text one box a line, filled with comp.skeleton.placeholder.color, with the corners of its shape (comp.skeleton.placeholder.shape.text for each line of text, comp.skeleton.placeholder.shape.block for a block, comp.skeleton.placeholder.shape.circle for a circle), never larger than half the box's smaller side, and with no edge, no elevation, no shadow and nothing inside it. THE skeleton SHALL draw nothing else: no glyph, no mark, no text, and never its label.
- **SKL-3** WHILE a placeholder's shape is text THE skeleton SHALL size it by the text style in effect where it stands — the style text placed there would be drawn in, and sys.typescale.body where the platform has no such style and the product gave none: the placeholder SHALL be exactly as tall as lines line boxes of that style, and in each line box THE skeleton SHALL draw one bar as tall as the style's font size, centred in the line box. Each bar SHALL be as long as the placeholder's inline size (inlineSize, else the whole inline size of its place), except that WHILE lines is 2 or more the last bar SHALL be comp.skeleton.placeholder.last-line-inline-size of that size, from the start edge. The placeholder SHALL NOT read blockSize.
- **SKL-4** WHILE a placeholder's shape is block THE skeleton SHALL draw one box whose inline size is inlineSize, else the size the product's layout gives it, else the whole inline size of its place, and whose block size is blockSize, else the size the product's layout gives it (a stretched cell, a ratio the product set), else one line box of the text style in effect where it stands (SKL-3). The block SHALL NOT read lines.
- **SKL-5** WHILE a placeholder's shape is circle THE skeleton SHALL draw one square box whose side is blockSize, else inlineSize, else the size the product's layout gives it, else one line box of the text style in effect where it stands (SKL-3), and SHALL draw it round. WHERE the place is narrower than the side THE skeleton SHALL make the square as large as the place allows and keep it square: a circle is never drawn as an oval. The circle SHALL NOT read lines.
- **SKL-6** THE skeleton SHALL keep the box of every placeholder, and so its own, unchanged from the moment it is inserted to the moment it is removed — while it waits to be shown (SKL-7), while it is shown and while it stirs (SKL-12) — and SHALL NOT guess what is coming: it draws the placeholders the product gave, in the sizes the product gave, and nothing of the content. That the content takes the box its placeholders held is the product's to arrange, by placing each placeholder where its content will be and as that content will be placed.
- **SKL-7** WHEN the skeleton is inserted into a view THE skeleton SHALL wait for its show delay (SKL-9) before it is shown, and WHILE it waits SHALL draw nothing, SHALL run no animation, SHALL be absent from the accessibility tree (no role, no name, no busy state), and SHALL still take the box it takes when shown (SKL-1 to SKL-5), so that nothing around it moves when it appears; a show delay of 0 SHALL show it as it is inserted.
- **SKL-8** WHEN its show delay ends THE skeleton SHALL be shown: it SHALL draw its placeholders at once, at their resting opacity and without an entrance of their own, expose itself as SKL-15 says without announcing itself (SKL-16), and start the animation of SKL-12 at the beginning of a pulse.
- **SKL-9** THE skeleton SHALL take its show delay from showDelay, a number of milliseconds used as given (the motion dial does not scale it). WHILE showDelay is null THE skeleton SHALL use comp.skeleton.motion.show-delay in its place; IF showDelay is negative or not a finite number THE skeleton SHALL use the token likewise and in debug builds report the value it ignored.
- **SKL-10** THE skeleton SHALL treat its show delay as a waiting time, not motion: WHERE motion is reduced it SHALL keep it, on every platform, including one whose reduced-motion setting removes every animation; and it SHALL keep counting it while the skeleton cannot be seen (scrolled out of view, in a hidden view), because the delay measures the wait, not what is seen.
- **SKL-11** WHEN the skeleton is removed before its show delay ends THE skeleton SHALL have drawn, exposed and announced nothing, and WHEN it is removed while shown it SHALL disappear at once, without a motion of its own: how the content enters is the content's. WHEN it is inserted again THE skeleton SHALL wait its whole show delay again; hiding it without removing it (a hidden ancestor, scrolling) SHALL neither restart nor pause the delay (SKL-10). WHEN showDelay changes while the delay is running THE skeleton SHALL finish the running delay as it started and use the new value from its next insertion.
- **SKL-12** WHILE the skeleton is shown THE skeleton SHALL stir as comp.skeleton.motion.animation names, without end. pulse SHALL ease the opacity of every placeholder's fill from its resting value to comp.skeleton.placeholder.dim-opacity of it over comp.skeleton.motion.dim-duration with comp.skeleton.motion.dim-easing and back over the same time on the same curve, every placeholder of the skeleton in step with the others. wave SHALL put each point of each placeholder through the same fall and return, each point later than the skeleton's start edge by a share of one whole pulse equal to its distance from that edge over the skeleton's inline size, so that one dimmer band travels from the start edge to the end edge through all the placeholders as through one surface. none SHALL leave the placeholders still at their resting opacity. In every manner THE skeleton SHALL change the fill's opacity only: no box moves, grows or changes shape, and nothing brighter than the resting fill is drawn.
- **SKL-13** WHERE reduced motion is requested THE skeleton SHALL NOT stir, whatever comp.skeleton.motion.animation names: it SHALL draw its placeholders still, at their resting opacity. The shapes, the label and the busy state still say that the place is waiting, and the show delay is kept (SKL-10).
- **SKL-14** WHILE the skeleton is not visible (scrolled out of view, in a hidden view, or in an app in the background) THE skeleton SHALL NOT run its animation, and SHALL resume it when it becomes visible.
- **SKL-15** WHILE the skeleton is shown and decorative is false THE skeleton SHALL expose itself to assistive technology as one element: the progressbar role with label as its name, no current value, and the platform's busy or indeterminate state. THE skeleton SHALL expose nothing of what it holds: no placeholder, no count of placeholders or of lines, and nothing of a layout the product placed in it.
- **SKL-16** THE skeleton SHALL NOT be focusable and SHALL NOT be a stop in the focus order, SHALL NOT announce itself when it is shown, when it changes or when it is removed, and SHALL NOT move keyboard or screen-reader focus. Saying that the content has arrived, where the product wants it said, is the product's, as it is beside a loading indicator.
- **SKL-17** WHILE decorative is true THE skeleton SHALL keep itself and everything it holds from assistive technology — no role, no name, no busy state — and SHALL draw, wait and stir as it otherwise would. A skeleton that stands inside another skeleton SHALL behave as decorative whatever its prop says: one wait is said once.
- **SKL-18** THE skeleton SHALL take its name from label, and WHILE label is empty from the product's words (the key loadingLabel); it has no words of its own in any language. WHILE both are empty and decorative is false THE skeleton SHALL still be drawn and still be exposed as SKL-15 says, without a name, and in debug builds report once that a skeleton has no label, naming the prop.
- **SKL-19** THE skeleton SHALL NOT take pointer, touch or keyboard input and SHALL NOT change anything it draws under a pointer, a press or focus: it has no hovered, focused, pressed, selected or disabled state and draws no state layer and no focus indicator. Whatever the product places in it besides placeholders SHALL be drawn as given, SHALL take no input and no focus, and SHALL NOT be exposed to assistive technology: a skeleton holds the shape of content, never content.
- **SKL-20** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE skeleton SHALL draw each placeholder, and each line of a text placeholder, as the outline of its shape, sys.border.hairline wide and inside its box, in the platform's text color, with no fill, and SHALL NOT stir: a fill is not drawn in that mode, and a placeholder that vanished would leave a blank place that says nothing.
- **SKL-21** WHILE the text size is enlarged THE skeleton SHALL grow its text placeholders with the text style they stand in, and every placeholder whose size is a line box with them, so that the skeleton still holds the box the enlarged content will take; it SHALL keep a size given as inlineSize or blockSize as given, SHALL never draw a placeholder wider than its place, SHALL keep its gap, and SHALL need no horizontal scrolling at a width of 320 points with text at 200 %.
- **SKL-22** WHERE the layout direction is right-to-left THE skeleton SHALL place its placeholders at the right edge, begin the shortened last bar of a text placeholder (SKL-3) and every placeholder narrower than its place at the right, and run a wave from the right edge to the left; a block and a circle are otherwise drawn as they are in a left-to-right layout.
- **SKL-23** THE skeleton SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the skeleton is shown THE skeleton SHALL draw itself for the new direction at once, without a motion of its own, keeping its place in its animation.
- **SKL-24** WHEN label, decorative or a placeholder's shape, lines, inlineSize or blockSize changes, or a placeholder is added or removed, while the skeleton waits or is shown THE skeleton SHALL draw and expose the new value at once, without a motion, without an announcement, and without restarting its show delay or its animation. THE skeleton SHALL neither show nor hide itself and SHALL NOT know when the content arrives: the product puts the skeleton in the content's place when the wait starts and takes it away when the wait ends, whatever the wait ends in.
- **SKL-25** WHEN a placeholder's shape names a value this spec does not have THE skeleton SHALL draw it as text; IF its lines is less than 1 or not a finite number THE skeleton SHALL use 1, and SHALL use the whole number below a lines that is not whole; IF its inlineSize or blockSize is negative or not a finite number THE skeleton SHALL treat it as null; WHEN comp.skeleton.motion.animation names a manner the skeleton does not know THE skeleton SHALL pulse. In each case it SHALL report the value it ignored in debug builds.
- **SKL-26** IF the skeleton holds no placeholder THE skeleton SHALL draw nothing, take no space and expose nothing, and in debug builds report that a skeleton holds no placeholder: a busy region with no shape in it is a blank place, and a wait whose shape is not known is a loading indicator's.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.skeleton.…` → `--tanrei-comp-skeleton-…`).

#### `tanrei.comp.skeleton`

| Token | Type | Value |
| --- | --- | --- |
| `comp.skeleton.container.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.skeleton.placeholder.color` | `color` | `{tanrei.sys.color.surface-variant}` |
| `comp.skeleton.placeholder.shape.text` | `dimension` | `{tanrei.sys.shape.corner.extra-small}` |
| `comp.skeleton.placeholder.shape.block` | `dimension` | `{tanrei.sys.shape.corner.medium}` |
| `comp.skeleton.placeholder.shape.circle` | `dimension` | `{tanrei.sys.shape.corner.full}` |
| `comp.skeleton.placeholder.last-line-inline-size` | `number` | `0.6` |
| `comp.skeleton.placeholder.dim-opacity` | `number` | `0.5` |
| `comp.skeleton.motion.animation` | `number` | `0` |
| `comp.skeleton.motion.dim-duration` | `duration` | `{tanrei.sys.motion.duration.extra-long4}` |
| `comp.skeleton.motion.dim-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.standard}` |
| `comp.skeleton.motion.show-delay` | `duration` | `{tanrei.sys.motion.role.show-delay}` |

## Guidelines

### It holds the box

The point of a skeleton is that nothing moves. Its box, and the box of every placeholder, is the same from the moment it is inserted to the moment it is removed: while it waits to show, when it appears, while it stirs.

The skeleton guesses nothing. It draws the placeholders you gave, in the sizes you gave. That the content takes the box its placeholders held is yours to arrange: put each placeholder where its content will be, placed as that content will be placed.

- A text placeholder goes inside the heading, the paragraph or the cell the text will be in. It takes that text style, and is exactly as tall as that many lines of it, also when a reader enlarges the text.
- Say how many lines the text will take with `data-lines`. You will be right as often as your content is regular. A skeleton that is one line short moves the page by one line, which is still less than a blank place moves it.
- Give a block the size of the picture or the control: a number, a ratio, or the size your layout gives it. A circle takes one number, its side.

### Shapes

| `data-shape` | Stands for | Its size |
| --- | --- | --- |
| `text` (default) | One or more lines of text. | `data-lines` line boxes of the text style it stands in. Each line is a bar as tall as the font size. The last of several lines is shorter, as a paragraph seldom ends at the edge. `inline-size` sets the bars’ length. |
| `block` | A picture, a card, a control, a row. | `inline-size` and `block-size`, or the size your layout gives it: a stretched cell, an `aspect-ratio`. With no size it is its place wide and one line high. |
| `circle` | A person’s picture, a round mark. | One side: `block-size`, or `inline-size`. With no size it is one line high. |

Placeholders that are the skeleton’s own children are stacked one under another, with a gap of 8. Anything else — a circle beside two lines, a grid of cards — is your own layout inside the skeleton. There is no ready-made card or list skeleton: your screens are yours, and only you know them.

In a row of your own, a text placeholder or a block needs a width from that row, as the content will: `flex: 1`, a track of a grid, or an `inline-size`.

### One wait, one sign

Put every placeholder of a region in one skeleton, with one `label`. A skeleton inside another skeleton is silent.

Where something else already says the same wait — a loading indicator in a status line, a status text, a region you mark busy and name yourself — set `decorative`. The skeleton is then drawn the same and kept from assistive technology, so that the wait is not read twice.

### It waits before it shows

From the moment it is inserted, a skeleton waits 300 ms before it is drawn and exposed, with its box already held. A wait that ends sooner shows a blank place that was the right size all along.

- Insert the skeleton when the wait starts and remove it when the content arrives. The delay counts from the insertion. Hiding the skeleton does not restart it.
- Set `show-delay="0"` where the skeleton is part of the first presentation of a page or a view, which has nothing else to show.
- The delay is a wait, not motion: reduced motion keeps it.

### It always ends in something

Replace the skeleton with the content, with an [empty state](https://tanrei.chnotchy.com/components/empty-state/) where nothing came, or with a [callout](https://tanrei.chnotchy.com/components/callout/) of the error status where loading failed. It never times out by itself: when to give up is yours to know.

The skeleton does not announce that the content arrived. Where arrival should be heard — results in answer to a search, a list that was asked for — say so through your own live region or the status text of the component that asked. A view that simply opens with its content needs no announcement.

### Motion

By default the placeholders pulse: the fill dims to half and returns, all of them together, two seconds a pulse. Only the opacity changes. Nothing moves, and nothing is drawn brighter than the resting fill.

A design system may choose another manner for all its skeletons with the token `comp.skeleton.motion.animation`: `pulse`, `wave` (the same dimming, travelling through the whole skeleton from its start edge to its end edge as one band) or `none`. There is no setting for one instance.

Under reduced motion the placeholders are still. The shapes, the label and the busy state already say that the place is waiting. While the skeleton cannot be seen its animation does not run.

### On the web, before the script

A skeleton is what a page shows before its script has run, so `@tanrei/web/skeleton.css` draws it whole without the element. A few things need the element, and are different until it is defined or where script never runs:

- The role and the name. A page that must be right before its script runs writes `role="progressbar"`, `aria-busy="true"` and `aria-label` on the element itself, and the element leaves what it finds.
- A `show-delay` other than `0`. The stylesheet waits the design system’s delay.
- More than 24 lines in one text placeholder.
- The `wave` manner, which is drawn as a pulse.
- A skeleton inside a view that is not displayed starts its wait when the view is shown.

Where script never runs, a skeleton never ends unless the server replaces it. Content that arrives only by script needs a `<noscript>` beside its skeleton.

### Do

- Give placeholders the shape and the size of what is coming.
- Put text placeholders inside the element the text will be in.
- Use one skeleton, with one label, for one wait.
- Replace it when the wait ends, whatever the wait ends in.

### Don’t

- Don’t put anything a person should read or use inside a skeleton. What it holds takes no input and is hidden from assistive technology. A heading that is already known, a button that already works, stand outside it.
- Don’t use it for a short wait in a control or a row, or for an action under way. That is a loading indicator.
- Don’t cover content that is already there with it.
- Don’t draw grey boxes by hand.

## Accessibility

### What the component handles

- Once shown, the skeleton is one element to assistive technology: a progressbar with no value, busy, named by `label`. It is exposed as a loading indicator is, because it says the same thing.
- Its placeholders, their number and their lines are not exposed, and neither is a layout you place in it.
- While it waits to show it is not exposed at all. A wait shorter than the delay shows no progressbar that appears and vanishes.
- With `decorative`, or inside another skeleton, it is kept from assistive technology.
- It is not focusable and not a stop in the focus order, and nothing inside it is. It does not announce itself and never moves focus.
- Under reduced motion it is still. The delay is kept.
- In forced colors each placeholder, and each line of text, is drawn as the outline of its shape in the text color. A fill is not drawn in that mode, and a placeholder that vanished would leave a blank place.
- With enlarged text a text placeholder grows with its text style, so the skeleton still holds the box the enlarged content takes. A size given as a number stays. Nothing is wider than its place; at a width of 320 with text at 200% nothing scrolls sideways.
- In a right-to-left layout the placeholders stand at the right, the short last line begins at the right, and a wave runs from right to left.
- An unknown shape, a number of lines or a size that cannot be used, a skeleton with no placeholder and a skeleton with no label are reported in debug builds.

### What you need to do

- Give a `label` in the language of the page that says what is loading (“Loading projects”), or give the word once for every skeleton with `setWords({ loadingLabel: … })`. The component supplies no words.
- Set `decorative` where something else already says the wait.
- Say that the content arrived where that is news.
- Never let a skeleton stand forever. Replace it with the content, an empty state or an error.
- The fill is decoration and is held to no contrast ratio. On a surface of the highest container tone it is hard to see. Do not rely on it alone to say that a place is waiting. Where it stands on one, point `comp.skeleton.placeholder.color` at a stronger role in a layer.
