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

Tumble

A headline that arrives. It wraps a real heading and leaves it alone: the text stays one string in the page, read once, selectable and translatable, while an aria-hidden copy of its letters, laid exactly over it, moves for about a second. Quiet is still. Warm slides the lines in from alternate sides and settles them.

quiet warm playful for heading, headline, hero, section-heading

Open the live demo npx @susegad/cli add tumble

Stands on: Core, Core: components, Engine, Tokens

The prompt

the prompt

A playful headline for a launch, an event page, a kids' site, a food maker's opening line.

<link rel="stylesheet" href="susegad/components/tumble/tumble.css">
<script type="module" src="susegad/components/tumble/tumble.js"></script>

<sg-tumble><h2>Life is short, eat good pasta</h2></sg-tumble>

The prompt

Make a headline that arrives, as a web component that wraps a real heading and never changes it. The text stays one string in the DOM: read once by a screen reader, selectable, translatable. The moving letters are an aria-hidden copy laid over the heading, built when the arrival starts: measure each letter with a Range after document.fonts.ready, place a span for each exactly where the browser put it with the heading's own font, colour, spacing and case, group them into the lines the browser laid out, hide the real text for as long as the copy moves, then remove the copy and show the real text again. Three registers. Quiet: nothing moves. Warm: the lines slide in alternately from the left and the right, a little past rest, and settle, each line after the one above, clipped to the heading's box so nothing widens the page. Playful: each letter drops from above with a little spin, touches down, bounces once and settles, staggered so the whole arrival never takes more than about two and a half seconds. Under reduced motion, the finished heading at once and no copy. It plays once, the first time it is seen (an IntersectionObserver of its own), or when the page calls play(), which returns a promise that resolves when the heading has settled; a manual attribute turns auto-play off. The heading must never be left invisible: not with JavaScript off, not before the script runs, not if measuring throws, not on a resize, not if the element leaves the page; leave a heading with a transparent fill alone. An optional hold attribute hides the heading until play(), and lets it go after eight seconds. It must work under style-src 'self' and script-src 'self': set positions through element.style, animate with Web Animations.

Words to code

When you sayTechniqueWhat happens
the text stays one stringoverlayThe copy is a sibling layer, aria-hidden, pointer-events none; the heading keeps its one text node.
exactly where the browser put themRange.getClientRects per letter, letters()Graphemes (so an accent or an emoji is one letter) each measured against the host, after the fonts are ready.
the lines the browser laid outgroupLinesLetters whose vertical middles are within half a letter's height share a line.
alternate sides, settlewarmPlan, warmFramesOdd lines from the right, even from the left, a small overshoot, each line 170 ms after the one above.
drop with a little spin, bounce onceplayfulPlan, dropFramesSeeded spin and height per letter; keyframes: above and turned, touch down, one small lift, rest.
never longer thanMAX_TOTAL_MSThe stagger shrinks with the letter count.
never invisiblerestore()Called in a finally, on resize, on disconnect and after a failsafe timer; hide happens only after the copy exists.
wait for web fontsdocument.fonts.readyAt most three seconds, then it measures what there is.
strict CSPCSSOM and WAAPINo style element and no style attribute in what it builds.

Accessibility

  • The heading is announced by its own text, once; the copy is aria-hidden.
  • Quiet and reduced motion: the finished heading, no copy.
  • Selecting the heading while it plays selects the real text.

<sg-tumble> is a headline that arrives. It wraps a real heading and leaves it alone: the text stays one string in the page, read once, selectable and translatable. The moving letters are an aria-hidden copy laid exactly over it, built when the arrival starts and gone when it ends.

Markup

<link rel="stylesheet" href="susegad/components/tumble/tumble.css">
<script type="module" src="susegad/components/tumble/tumble.js"></script>

<sg-tumble><h2>Life is short, eat good pasta</h2></sg-tumble>      <!-- plays once, the first time it is seen -->
<sg-tumble manual id="hero"><h1>Saffron Spoon</h1></sg-tumble>      <!-- waits: document.getElementById('hero').play() -->
<sg-tumble manual hold><h1>Saffron Spoon</h1></sg-tumble>           <!-- hidden until played; let go after 8 s -->

Use a real <h1> to <h6> (or role="heading"). Style the heading as you like: the copy takes each letter's font, colour, spacing and case from the heading itself.

Attributes, method, events

manualno auto-play; call play()
holdwith JavaScript running, hide the heading until it plays (so it does not flash before an arrival you will start later). A page that never plays it gets the heading back after 8 seconds. Never applies in quiet or under reduced motion.
seedseeds the spin of the letters (default: the heading's text)
registerquiet, warm, playful
play()plays the arrival; returns a promise that resolves when the heading has settled (at once when nothing moves)
sg-tumble-start, sg-tumble-doneevents, bubbling

data-state on the element is held, playing or done while there is something to say.

Registers

quietnothing moves
warmlines slide in, alternately from the left and the right, a little past rest, and settle; each line follows the one above
playfulletters drop from above with a little spin, bounce once and settle, one after another (the whole arrival never takes more than about 2.6 seconds, however long the heading)
reduced motionthe finished heading at once; no copy is ever made

How it stays honest

  • The text is never changed or split: the heading keeps its one text node. The copy is a sibling aria-hidden layer, outside the heading, with pointer-events: none, so selecting the heading while it plays selects the real text.
  • The heading is hidden only once the copy is built and the animations have started (and with hold, before that). Without JavaScript, before the module runs, if measuring throws, on a resize, if the element leaves the page, or after a timeout, it is shown again.
  • A heading with a transparent fill (gradient text) is left alone, because a copy of it would be invisible too. So is one with more than 160 letters.
  • It waits for document.fonts.ready (for at most 3 seconds) before measuring, so a web font that arrives late does not leave the copy in the wrong places. The letters are measured with a Range for each, so ligatures are drawn as separate letters during the arrival and snap back at the end.
  • Without tumble.css it still works: it makes the element a positioned block and hides the heading itself.

Content-Security-Policy

No <style> element and no style attribute in anything it builds in markup: positions and typography are set through the CSSOM, the arrival through Web Animations. It runs under style-src 'self'; script-src 'self'.

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
  • Meets with author's part 1
  • Not applicable 2
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe moving letters are an aria-hidden copy laid over the real heading: packages/components/tumble/tumble.check.mjs, "the moving copy is aria-hidden and outside the heading". The heading is text, so there is no image to describe.
1.3.1 Info and relationshipsMeetsThe author's real <h1> to <h6> is left alone and stays one text node with its own string while the letters move: tumble.check.mjs, "the heading is still one text node with its own string while the letters move" and "the heading is announced by its own text".
1.4.1 Use of colorNot applicableThe component carries no meaning in colour; it moves a heading that already says what it says in words.
1.4.3 Contrast (minimum)Meets with author's partThe heading keeps the colour the author gives it, and the copy takes each letter's colour from it, so contrast is whatever the heading's colour and ground give (token text roles pass 4.5:1 in packages/tokens/tokens.test.js). A heading with a transparent fill, such as gradient text, is left alone and never copied (tumble.check.mjs, "gradient text is left alone"). axe: tools/axe.mjs --url /packages/components/tumble/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07; color-contrast was left for review by hand and is covered by the ratios in this table.
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 real heading is what resizes; a resize during the arrival ends it cleanly and gives the heading back (tumble.check.mjs, "a resize mid-play ends it cleanly").
1.4.10 ReflowMeetsManual test, 2026-10-07: demo at 320 CSS px, three registers, page width 320. While the warm lines slide in, the copy sits outside the heading's box inside a clipped wrapper (overflow: clip) and the page does not scroll sideways; the copy is gone when the arrival ends (throwaway Playwright script).
1.4.11 Non-text contrastNot applicableThe component draws no control or graphic of its own; the letters are the heading's text.
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). No check in the repository asserts it yet.
2.2.2 Pause, stop, hideMeetsThe arrival plays once, the first time the heading is seen, and ends: warm slides the lines in and playful drops the letters in about 2.6 seconds at most however long the heading, under the 5 seconds the criterion allows (packages/components/tumble/tumble.test.js, "playful: one plan per letter, in reading order, never slower than the cap however long the heading"; tumble.check.mjs, "first view: it plays once; scrolling away and back does not play it again"). Quiet and reduced motion move nothing.
2.3.1 Three flashes or below thresholdMeetsNothing flashes or changes brightness: the letters travel, spin and bounce once (tumble.test.js, "the bounce is only one: after the touch-down the letter lifts once and never goes below rest") and the warm lines slide (tumble.test.js, "warm: the slide ends at rest, passes a little over, and starts out of sight").
2.3.3 Animation from interactionsMeetsAAA, informative. Under reduced motion the finished heading shows at once and no copy is made: tumble.check.mjs, the reduced-motion probe, and packages/components/tumble/tumble.docs.md.
4.1.2 Name, role, valueMeetsThe component adds no role, state or control; the author's heading is announced by its own text, once (tumble.check.mjs, "the heading is announced by its own text"), and nothing is in the tab order. axe: tools/axe.mjs --url /packages/components/tumble/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07; color-contrast was left for review by hand and is covered by the ratios in this table.

The page author owns:

  • The heading's text, in the language of the page, and its colour and ground: at least 4.5:1 for text (1.4.3), or 3:1 for large text.
  • A real heading element (<h1> to <h6> or role="heading") inside the element, and a sensible heading order for the page.
  • hold only where a script will play the heading; a held heading is hidden until it plays, and is given back after 8 seconds if nobody plays it.

How it behaves

  • The heading is announced by its own text, once; the copy is aria-hidden.
  • Reduced motion and quiet show the finished heading and make no copy. High-contrast mode hides the copy.
  • Nothing is in the tab order.
  • Known limit: it only moves text. Text with a background-clip gradient, or in a canvas, is not copied.

All 57 tables, and how the library tests