Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Components

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 sayTechniqueWhat happens
aria-busy="true" and a visually hidden role="status" lineaccessibilityAnyone 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 seedpure layoutlayout(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 noisewobbleEach 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 offsetstroke dashingEach 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 twoshand-drawn animationThree 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 screenbudgetA shared IntersectionObserver pauses the wobble off screen, and it is cancelled the moment the content arrives.
the ink-in plays only on a real arrivalreal arrivalThe 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:

shapedraws
text (default)lines bars of text, the last one shorter
carda picture, a title and lines bars
listlines rows, each a circle and two bars
mediaone 16:9 picture

Attributes, properties and events

NameTypeWhat it does
busyboolean attribute, and the busy propertyWhile set, the content is hidden, the element is aria-busy, and the placeholder shows.
shapetext, card, list or mediaThe placeholder layout. Unknown values fall back to text.
linesnumber, 1 to 12 (default 3)Lines of text, or rows of a list.
labeltextWhat is loading, as a noun phrase in lower case: label="your guests" gives "Loading your guests", then "Your guests loaded".
seednumber or textChanges the bar widths. The same seed always gives the same placeholder.
registerquiet, warm or playfulOverrides the page's register for this element.
sg-loadedeventFires 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 read 1,0,0 on 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-keyframe step-end would 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
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe 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 relationshipsMeetspackages/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 colorNot applicableThe 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 applicableThe 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 textMeetsManual 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 ReflowMeetsManual 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 contrastNot applicableThe 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 spacingMeetsManual 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, hideMeetsManual 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 thresholdMeetsThe 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, valueMeetsaria-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 messagesMeetsAdded 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 in skeleton.core.js, so on a page in another language they are a passage in English: mark it with lang (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 busy only 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 hidden role="status" line saying what is loading. The drawing is aria-hidden.
  • The content is hidden with display: none while 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.

All 57 tables, and how the library tests

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.