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

Sound switch

The one control that turns Susegad's sound switch on or off, site-wide, over a native checkbox with role=switch. Checking it is the user's own gesture, so switch.js can resume the audio context right there and play the switch's own confirmation.

quiet warm playful

Open the live demo npx @susegad/cli add sound-switch

Stands on: Core, Core: components, Sound, Tokens

The prompt

the prompt

The one control that turns a page's sound on or off, and the user's own gesture for doing it.

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

<sg-sound-switch>
  <label><input type="checkbox" role="switch"> Sound</label>
  <small class="sg-sound-switch-note">Turning sound on needs JavaScript.</small>
</sg-sound-switch>

The prompt

Make a sound switch web component over a native <input type="checkbox" role="switch">: the checkbox is the whole control, it reads and writes one shared on/off setting stored in localStorage, and checking it is the only thing on the page allowed to make the first sound, because that click is the user's own gesture. Without JavaScript the checkbox still exists and is still announced as a switch, but nothing it does has an effect, since there is no sound without JavaScript; say so in a small note next to it, and hide that note once the element is running. Give it three registers. Quiet: the plain switch, no drawing. Warm: draw a small speaker beside the track, with a line struck through it when the switch is off and two arcs of sound in its place when it is on, faded between the two on a CSS transition under 200ms. Playful: the same speaker, but while the switch is on and the element is on screen, breathe the two arcs gently from seeded noise, so two switches on the same page never pulse in step, and hold them still under reduced motion, in quiet motion, or off screen. Keep every switch on the page in sync with the shared setting, so checking one checks them all.

Words to code

When you sayTechniqueWhat happens
the checkbox is the whole controlnative firststatic native = 'input[type="checkbox"]'; role="switch" is added if missing. The component adds role and a drawing only; the checkbox carries the keyboard, focus and screen-reader behaviour on its own.
reads and writes one shared on/off setting stored in localStorageshared statesoundOn()/setSoundOn() (packages/sound/switch.js) own localStorage['sg-sound'], wrapped in try/catch. The element only calls them; it holds no state of its own.
checking it is the only thing … allowed to make the first soundconsentsetSoundOn() runs inside the checkbox's own change handler, itself a user gesture, which is exactly when switch.js is allowed to resume the shared AudioContext. Turning it on also calls play('confirm') right there, so the tap and the first sound are the same gesture.
nothing it does has an effect … say so in a small notefallbacksound-switch.css shows a <small class="sg-sound-switch-note"> by default and hides it only once the element sets data-ready, which only happens with JavaScript running.
a line struck through … two arcs of soundredundancySPEAKER in sound-switch.core.js holds the body, two arc paths and a slash as plain SVG path data. [data-on] on the drawing shows the arcs and hides the slash, or the reverse; the state is a shape, never colour alone.
breathe the two arcs gently from seeded noise … never pulse in stepnoisepulse(t, seed) reads Perlin noise seeded by the element (its seed attribute or id), so no two switches share a phase. waveAnimation(motion, on, seed) samples it into Web Animations keyframes, or returns null to hold still.
keep every switch on the page in syncshared stateEvery instance calls onSoundChange(on => …) and writes the checkbox back only when it disagrees, so one page can hold as many switches as it likes without an event loop.

Accessibility

  • role="switch" on the native checkbox; the label you write is what is read.
  • The drawing is aria-hidden="true"; nothing about the switch's state is said only by a shape or a colour.
  • Forced-colours mode brings back the system's own control and hides the drawing.
  • The no-JS note keeps the page honest: it never implies sound works where it cannot.

<sg-sound-switch> is the one control that turns Susegad's sound switch on or off, site-wide. It wraps a native <input type="checkbox" role="switch">; the checkbox is the whole control.

Use

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

<sg-sound-switch>
  <label><input type="checkbox" role="switch"> Sound</label>
  <small class="sg-sound-switch-note">Turning sound on needs JavaScript.</small>
</sg-sound-switch>

Put one anywhere a page offers the setting: a header, a settings panel, the first scene that would use sound. More than one on a page stay in sync with each other, because they all read and write the same switch (packages/sound/switch.js).

What it does

  • On connect, the checkbox is set to soundOn(). Checking or unchecking it calls setSoundOn() from inside the browser's own change event, so that click or key press is the user gesture switch.js needs to resume the shared AudioContext: turning sound on and hearing the first sound can be the same tap. Turning it on also plays confirm, the switch's own first sound.
  • Every <sg-sound-switch> on the page listens for sg-sound-change and follows: check one, and the rest (and anything else reading soundOn()) update without a page reload.
  • Without JavaScript the checkbox is still there, still announced as a switch, and still takes Space, but nothing it does has an effect, because there is no sound without JavaScript. A <small class="sg-sound-switch-note"> beside it says so in words; this element hides that note once it is running.

Attributes

AttributeValuesDefault
registerquiet, warm, playfulinherited
seedany string (playful only: which arc breath this switch plays)the element's id, or a fixed default

Registers

LookMotion
quietthe native switch, hairline, no drawingnone
warma small speaker beside the track; a struck-through line when off, two arcs when onthe switch fades between the two on a CSS transition, under 200ms
playfulthe same speaker; the two arcs also breathe gently while it is ona slow Web Animation, seeded so two switches never pulse in step; paused off screen and under reduced motion

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 15
  • Meets with author's part 3
  • Not applicable 2
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe speaker drawing is aria-hidden and the <label> is the name: packages/components/sound-switch/sound-switch.check.mjs, "<register> still announced as a switch" reads switch "Sound" after each change.
1.3.1 Info and relationshipsMeetsA native <input type="checkbox" role="switch"> inside its <label>. sound-switch.check.mjs, "no JS: it is announced as a switch, by its label" and, with JavaScript, "still announced as a switch" in each register.
1.3.5 Identify input purposeNot applicableA sound switch holds no personal data.
1.4.1 Use of colorMeetsState is never colour alone: the thumb sits on one side or the other, and the warm and playful speaker shows its arcs when on and a slash when off ("The state lives in a shape, never only a colour", packages/components/sound-switch/sound-switch.css). sound-switch.check.mjs: "<register> clicking turns it on, and the drawing follows" and "clicking again turns it off, and the drawing follows".
1.4.3 Contrast (minimum)MeetsThe label is page text in --sg-text, and the "needs JavaScript" note --sg-text-faint, a text role: packages/tokens/tokens.test.js ("AA: <palette> <theme>: every text role on every surface is 4.5:1 or more"). axe: tools/axe.mjs --url /packages/components/sound-switch/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07.
1.4.4 Resize textMeetsManual test, 2026-10-07: demo with the root font size at 200 percent in a 320 px wide window (stricter than 200 percent alone), three registers, page width 320, nothing clipped (throwaway Playwright script). The switch is sized in em: packages/components/sound-switch/sound-switch.css.
1.4.10 ReflowMeetsManual test, 2026-10-07: demo at 320 CSS px, three registers, page width 320, no sideways scroll (throwaway Playwright script). The label column is minmax(0, 1fr) in sound-switch.css, so a long label wraps. No check in the repository asserts it yet.
1.4.11 Non-text contrastMeetsManual test, 2026-10-07: computed with resolveRoles from packages/tokens/tokens.js for every palette in light and dark (throwaway script). The accent track on the surface, sunk and raised grounds is 3.92:1 at the lowest (Susegad light, on the sunk ground); the off thumb, --sg-text-soft on the sunk ground, 4.93:1; the --sg-rule-strong track edge 3.11:1; --sg-on-accent thumb on the accent 4.69:1. The focus ring and control borders are also tested 3:1 or more in packages/tokens/tokens.test.js. The warm and playful drawing uses --sg-text, --sg-text-soft and text roles.
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.1.1 KeyboardMeetsManual test, 2026-10-07 (throwaway Playwright script on the demo): in each register one Tab reaches the switch, Space turns it on, and Space again turns it off. The control is a native checkbox and packages/components/sound-switch/sound-switch.js adds only a change listener. packages/components/sound-switch/sound-switch.check.mjs turns it on and off by click in each register.
2.1.2 No keyboard trapMeetsManual test: packages/components/sound-switch/sound-switch.js binds only a change listener and sets no tabindex; the native checkbox takes Tab and Shift+Tab as any checkbox does.
2.4.3 Focus orderMeetsThe native input is the only tab stop and keeps its place in the page's order; the drawing is aria-hidden with pointer-events: none and takes no focus (packages/components/sound-switch/sound-switch.css).
2.4.7 Focus visibleMeetssound-switch.css sets a :focus-visible outline in the token focus colour on the input; tools/touch.check.mjs Tabs onto the first focusable control in the component, in the quiet register, and requires an outline, ring or style change.
2.4.11 Focus not obscured (minimum)Meets with author's partManual test: packages/components/sound-switch/sound-switch.css uses no position: fixed or sticky and no overlay. A sticky header or banner the page adds can cover the switch when it takes focus.
2.5.3 Label in nameMeetsThe accessible name is the visible label text: sound-switch.check.mjs reads switch "Sound" in each register, with JavaScript off and on.
2.5.8 Target size (minimum)Meets with author's partManual test, 2026-10-07: the click target is the whole <label>, 28.8 px tall in quiet and warm (31.5 px for the Devanagari and Kannada labels) and 102 px or more wide. The drawn switch alone is 41 by 23 px in quiet and 47 by 25 px in warm and playful (throwaway Playwright script, 1280 px). The input must stay inside the <label>. No check in the repository asserts target size for the switch yet.
3.2.2 On inputMeetspackages/components/sound-switch/sound-switch.js stores the setting, plays its own confirming cue and updates other switches on the page; it moves no focus and navigates nowhere. sound-switch.check.mjs: "a second switch on the page follows the same setting".
3.3.1 Error identificationNot applicableA switch has no invalid state: it is on or off.
3.3.2 Labels or instructionsMeets with author's partThe native <label> is the name and the "needs JavaScript" note tells a reader without scripts that nothing here will sound (sound-switch.check.mjs, "no JS: the "needs JavaScript" note shows"). The label wording and the note are the author's.
4.1.2 Name, role, valueMeetssound-switch.check.mjs: announced as switch "Sound" in each register, with JavaScript off and on; the checked state is the native one and is remembered ("the setting is remembered"). In forced colours the native control returns ("forced colours: the system's own control, drawing hidden"). axe: tools/axe.mjs --url /packages/components/sound-switch/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07.

The page author owns:

  • The label text, in the language of the page, inside the <label> that wraps the input; lang on a label in another language (3.1.2).
  • The note's wording, if the page changes it.
  • Sticky headers and banners that could cover the switch when it takes focus (2.4.11).
  • Where sound is offered at all: the switch only turns the library's cues on, and content sound (a recording, a voice) needs its own press.

How it behaves

  • The checkbox carries role="switch"; a screen reader says "switch, Sound, on" or "off", from the <label> text you write.
  • The speaker drawing is aria-hidden; the state is never carried by the drawing alone, only by the checkbox itself.
  • Forced-colours mode returns the system's own checkbox in the system's own colours; the drawing is hidden.
  • The "needs JavaScript" note means the no-JS page never implies sound is available when it is not.

All 57 tables, and how the library tests

Budget

FileBytes
sound-switch.js + sound-switch.core.js (behaviour)within 12 KB
skins/quiet.jswell under 8 KB
skins/warm.jswell under 8 KB
skins/playful.jswell under 8 KB

Nothing runs per frame except a playful switch's single Web Animation, while it is on and on screen.