Skeleton
A placeholder for a region whose content is on its way. The region is aria-busy and says what is loading, then announces the arrival once. Quiet is flat sunk blocks; warm is a pencil sketch whose outlines ink in when the content arrives; playful adds colour washes and a wobble on twos while waiting.
quiet warm playful
Open the live demo
npx @susegad/cli add skeleton
Stands on: Core, Core: components, Engine, Tokens
The prompt
the prompt
A pencil sketch of the page, inked when the real thing arrives.
A placeholder for a region whose content is on its way. While it waits, the region is aria-busy and a hidden line says what is loading. When the content arrives it shows at once, the arrival is announced, and in warm and playful the pencil outlines ink in before giving way.
<link rel="stylesheet" href="susegad/components/skeleton/skeleton.css">
<script type="module" src="susegad/components/skeleton/skeleton.js"></script>
<sg-skeleton busy shape="card" lines="2" label="the room details"></sg-skeleton>
<script>
const room = await fetch('/api/room').then(r => r.json());
skeleton.innerHTML = renderRoom(room); // the content goes inside
skeleton.busy = false; // and only then does the skeleton step aside
</script>
The prompt
Build a loading placeholder as a light-DOM custom element, <sg-skeleton busy shape="text|card|list|media" lines="3" label="…">, that wraps the region whose content is coming. While busy is set, hide the content, set aria-busy="true" on the element, and keep a visually hidden role="status" line that says "Loading" and the label; when busy is removed, show the content at once and change that line to "The room details loaded". Lay the placeholder out from the shape and a seed, in pixels for the element's width: bars for lines of text with the last one shorter, a picture block for media, a circle and two bars for each row of a list. Give it three registers. Quiet: flat blocks a shade deeper than the surface, with no shimmer and nothing moving; the content replaces them with a fade under 200 milliseconds. Warm: the same blocks drawn in SVG as two wandering pencil passes, the shape resampled and nudged by smooth noise, with light diagonal shading where a picture goes; nothing moves while waiting, and when the content arrives each outline is traced in ink with a dash offset, then the drawing crossfades to the content. Playful: soft colour washes in mango, sea, paddy and kokum, a doodled sun and two hills in the picture, and a wobble on twos while waiting: three drawings of the outlines swapped twelve times a second with step easing, run only while the region is busy and on screen; the ink is the accent colour. Show only what is true: nothing suggests an amount, the ink-in plays only on a real arrival, and with reduced motion the content simply appears. Without JavaScript, show one flat sunk block.
Words to code
| When you say | Technique | What happens |
|---|---|---|
aria-busy="true" and a visually hidden role="status" line | accessibility | Anyone reading the region hears "Loading the room details" instead of stale content. When busy goes, the same line says "The room details loaded" once, and the element fires sg-loaded. |
| lay the placeholder out from the shape and a seed | pure layout | layout(shape, { lines, width, seed }) returns plain blocks and runs in Node. The same seed gives the same widths every time, so a list does not shuffle on each render. |
| two wandering pencil passes, nudged by smooth noise | wobble | Each block's outline is resampled every 4 pixels and pushed along its normal by Perlin noise. A second pass with a different seed sits slightly off the first, as pencil lines do. |
| traced in ink with a dash offset | stroke dashing | Each ink path's dash array is its own measured length, and the Web Animations API moves the dash offset from that length to zero, one outline after another. |
| a wobble on twos | hand-drawn animation | Three versions of the outlines are drawn once. Each is shown for one twelfth of a second in turn with step-end easing, so the lines boil the way animation drawn on twos does. |
| run only while the region is busy and on screen | budget | A shared IntersectionObserver pauses the wobble off screen, and it is cancelled the moment the content arrives. |
| the ink-in plays only on a real arrival | real arrival | The arrival is driven by busy going away, never by a timer. Under reduced motion the phase goes straight to done. |
<sg-skeleton> stands in for a region while its content is loading, and steps aside the moment the content is there.
Usage
<link rel="stylesheet" href="susegad/components/skeleton/skeleton.css">
<script type="module" src="susegad/components/skeleton/skeleton.js"></script>
<sg-skeleton busy shape="list" lines="3" label="your guests">
<!-- the real list goes here when it arrives -->
</sg-skeleton>
Put the content inside the element, then remove busy (or set el.busy = false). If the content is already there when the page renders, leave busy off and nothing is drawn.
Pick the shape that looks most like what is coming, so the page does not jump when it arrives:
| shape | draws |
|---|---|
text (default) | lines bars of text, the last one shorter |
card | a picture, a title and lines bars |
list | lines rows, each a circle and two bars |
media | one 16:9 picture |
Attributes, properties and events
| Name | Type | What it does |
|---|---|---|
busy | boolean attribute, and the busy property | While set, the content is hidden, the element is aria-busy, and the placeholder shows. |
shape | text, card, list or media | The placeholder layout. Unknown values fall back to text. |
lines | number, 1 to 12 (default 3) | Lines of text, or rows of a list. |
label | text | What is loading, as a noun phrase in lower case: label="your guests" gives "Loading your guests", then "Your guests loaded". |
seed | number or text | Changes the bar widths. The same seed always gives the same placeholder. |
register | quiet, warm or playful | Overrides the page's register for this element. |
sg-loaded | event | Fires once when busy goes away, with detail: { label }. |
Registers
- Quiet: flat blocks a shade deeper than the surface. Nothing moves while waiting; the content fades in within 150 ms.
- Warm: the placeholder drawn in pencil, with light shading where a picture goes. Nothing moves while waiting. When the content arrives, each outline is traced in ink (about a third of a second), then the drawing gives way to the content.
- Playful: soft colour washes and a doodled picture in the accent ink. It is meant to boil on twos while waiting (three drawings swapped twelve times a second); as built it does not: the swap is set with
easing: 'step-end'on the whole animation, which holds the first drawing for the whole cycle, so the playful skeleton is still while waiting (manual test, 2026-10-07: opacity of the three drawings read1,0,0on every one of 20 samples 40 ms apart). The only motion is the ink-in on arrival. Known bug, for the skeleton's owner: per-keyframestep-endwould make it boil. - Reduced motion: the placeholder is still, and the content appears at once when it arrives.
Accessibility
How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.
- Meets 9
- Not applicable 3
| Criterion | Status | How it was checked |
|---|---|---|
| 1.1.1 Non-text content | Meets | The drawing is set aria-hidden="true" (packages/components/skeleton/skins/draw.js), and what is loading is said in words by a visually hidden status line. Manual test, 2026-10-07 (throwaway Playwright script on the playful demo): the drawing's aria-hidden is true and the status reads "Loading the room details". packages/components/skeleton/skeleton.test.js: "strings say what is loading and when it has arrived". |
| 1.3.1 Info and relationships | Meets | packages/components/skeleton/skeleton.css hides the content with display: none while busy, so nobody reads stale or half-rendered content, and when it arrives it joins the accessibility tree at once. Manual test, 2026-10-07: busy, the card's content has display: none, aria-busy="true" is set and the status is role="status"; after the content arrives aria-busy is false, the content is display: block and the status reads "The room details loaded" (throwaway Playwright script). |
| 1.4.1 Use of color | Not applicable | The placeholder carries no meaning in colour: what is loading is said in words, and the shapes only suggest where the content will go. |
| 1.4.3 Contrast (minimum) | Not applicable | The skeleton shows no text: it is a drawing and a visually hidden status line. The content that arrives is the author's, in the page's text colours. |
| 1.4.4 Resize text | Meets | Manual test, 2026-10-07: demo with the root font size at 200 percent at 1280 px, three registers, nothing wider than the screen (throwaway Playwright script). The placeholder is drawn to the width of its box and redrawn on resize (packages/components/skeleton/skins/draw.js). |
| 1.4.10 Reflow | Meets | Manual test, 2026-10-07: demo at 320 CSS px, three registers, page width 320, no sideways scroll (throwaway Playwright script). |
| 1.4.11 Non-text contrast | Not applicable | The placeholder blocks and outlines are not graphics required to understand the content, and not a control or a state of one: 1.4.11 covers those. What is loading is said in words in a role="status" line ("Loading your guests", then "Your guests loaded") built in packages/components/skeleton/skeleton.core.js and tested in packages/components/skeleton/skeleton.test.js; the line is visually hidden, so it is read by assistive technology, not seen. For the record, the blocks are faint by design: 1.07:1 to 1.19:1 against --sg-surface and 1.19:1 to 1.53:1 against --sg-surface-raised (manual test, 2026-10-07, resolveRoles from packages/tokens/tokens.js, every palette, light and dark). A page that uses the skeleton as the only sign of loading for sighted readers, with no words of its own, owns that. |
| 1.4.12 Text spacing | Meets | Manual test, 2026-10-07: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph 2em) injected on the demo, three registers, page width 320 with no sideways scroll (throwaway Playwright script). The skeleton has no text of its own. No check in the repository asserts it yet. |
| 2.2.2 Pause, stop, hide | Meets | Manual test, 2026-10-07 (throwaway Playwright script, playful demo, three animations running, 20 samples 40 ms apart while busy): the opacity of the three drawings read 1,0,0 every time, so nothing visibly moves while waiting in any register, and this is what the code does, not what the docs describe as the intended wobble (see Registers). The only motion is the ink-in on arrival, about a third of a second, triggered by the content arriving and never by a timer (packages/components/skeleton/skins/playful.js). Reduced motion shows the still. If the wobble is fixed to run, this row must be re-judged: it would loop for as long as the page is busy. |
| 2.3.1 Three flashes or below threshold | Meets | The same manual test: no frame changes while busy. The arrival fades in over 140 to 220 ms and the ink-in traces outlines once (packages/components/skeleton/skeleton.css, sg-skeleton-in). Nothing flashes. If the playful wobble is repaired to swap three drawings at 12 a second, as the docs describe, run this row again. |
| 4.1.2 Name, role, value | Meets | aria-busy carries the state and a role="status" line carries the name of what is loading (the manual test above); nothing in the skeleton takes focus. axe: tools/axe.mjs --url /packages/components/skeleton/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07. |
| 4.1.3 Status messages | Meets | Added because the component is a status. The line says "Loading ..." while busy and "... loaded" once on arrival, in a role="status" region that exists before the message (packages/components/skeleton/skeleton.js; skeleton.test.js, "strings say what is loading and when it has arrived"). Manual test, 2026-10-07: read after the arrival, "The room details loaded". |
The page author owns:
- Saying in visible words that something is loading, if the skeleton is the only sign of it for sighted readers (1.4.11).
- The
label, so the status says what is loading ("your bookings"), in the language of the page; the built-in words ("Loading ...", "... loaded") are fixed English inskeleton.core.js, so on a page in another language they are a passage in English: mark it withlang(3.1.2) or ask for them to be made replaceable. - The content that replaces the skeleton, its contrast and its headings (1.4.3, 1.3.1).
- Rendering
busyonly when a script will clear it, and not leaving it on after a failed load (a skeleton that never resolves says "Loading" for ever).
How it behaves
- While busy, the element has
aria-busy="true"and holds a visually hiddenrole="status"line saying what is loading. The drawing isaria-hidden. - The content is hidden with
display: nonewhile busy, so nobody reads stale or half-rendered content. - When the content arrives it joins the accessibility tree at once, even while the warm ink-in is still playing, and "… loaded" is announced once.
- Nothing in the skeleton takes focus.
What moves, and why
A skeleton does not know how far along the work is, so nothing in it suggests an amount. Playful's wobble, which is meant to say only that something is still coming and to stop when the region is off screen, does not currently show (see Registers). The ink-in is triggered by the content arriving, never by a timer.