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

Button

A native <button> or <a href>, unchanged, with the register's drawing laid over it: quiet is a hairline outline; warm is a hand-inked outline that boils gently on hover or focus; playful is a stamped chip that presses in and blooms an ink ring on release. Forced colours bring back the browser's own control.

quiet warm playful

Open the live demo npx @susegad/cli add button

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

The prompt

the prompt

The word or the way, plainly offered: a line to press, or a road to walk.

A native <button> or <a href> is the whole control. Warm draws its outline a little off true, the way a hand does; playful stamps it as a chip that presses in.

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

<sg-button><button type="submit" data-tone="accent">Send the request</button></sg-button>

The prompt

Make a button web component that wraps a real <button> or <a href>, so it takes the keyboard, submits and navigates with or without JavaScript. Style the native element directly for quiet: a hairline border, transparent background, the surface colour on hover, a visible focus ring, data-tone="accent" for a filled primary look. Give it three registers. Quiet: exactly that, and nothing more. Warm: draw a hand-inked outline behind the label as an aria-hidden SVG path, jittered from a seed so it looks drawn rather than plotted (walk the rounded-rect perimeter, nudge each corner and a few points along every edge by a small random offset, seeded so the same button always draws the same wobble); keep it invisible until the button is hovered or focused, then fade it in and let a small CSS keyframe animation "boil" it (a slow, tiny scale and translate loop) for as long as the pointer or focus stays, so nothing moves until someone's attention is there. Playful: a bold-bordered stamped chip that presses in on :active with a plain CSS transform, and on release blooms a soft ink ring from the point of contact using Web Animations, fading to nothing; skip the ring under reduced motion, where the press transform alone is the feedback. Read the button's size with ResizeObserver so the warm outline redraws at the button's true box, and place the ink ring at the pointer's position, not the button's centre.

Words to code

When you sayTechniqueWhat happens
a native <button> or <a href> is the whole controlnative firstThe keyboard, :disabled, form submission and navigation are the browser's; the component only decorates.
jittered from a seedseeded randomnessboilOutline(w, h, seed) uses rng('button-boil:' + seed), so two buttons with different labels (the default seed) never draw the same wobble, and the same button always draws the same one.
invisible until hovered or focused … boil ithonest, state-triggered motionThe outline's opacity and its CSS animation are both gated on :hover, :focus-within in button.css; nothing plays on page load, and the animation stops the moment attention leaves, because CSS unapplies it.
presses in on :activenative state, plain CSStransform: translateY(1px) scale(0.97) on :active, no JavaScript.
blooms a soft ink ring … using Web Animationsported techniqueinkSpread(motion), the fade-out ring, is the same shape as stamp.core.js's landing().spread: a small scaled-up ring that fades to opacity: 0.
skip the ring under reduced motionΩ honestyinkSpread('still') and inkSpread('state') return null; the skin then plays nothing, and the press transform (a real state, not decoration) still shows.
read the button's size with ResizeObserverresize correctnessAn SVG redrawn only at its true box avoids the Wave 4 lesson about a canvas cleared by resize; here the viewBox is recomputed, not a canvas context.

Accessibility

  • disabled (native) or aria-disabled="true" (a disabled-looking link) dims the button and turns off hover, boil and the ink ring.
  • Focus is always visible (--sg-focus), in every register.
  • The outline, the accent border and the text on the accent fill hold WCAG contrast in every palette and theme (tested).
  • Forced colours restore the browser's own button and link appearance; the drawings are hidden.

Credit

The ink-spread press is ported from the Wave 1 Stamp's landing, itself from an earlier booking calendar's drawStamp. Tier: a general technique, not a motif; no cultural credit is owed beyond the Stamp's own.

<sg-button> wraps one native <button> or <a href>. It takes the keyboard, submits a form, or follows a link with or without JavaScript. The register lays a drawing over it; the native element carries every behaviour.

Use

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

<sg-button><button type="submit" data-tone="accent">Send the request</button></sg-button>
<sg-button><a href="/rooms">See the rooms</a></sg-button>

data-tone="accent" on the native element gives the filled, primary look. Leave it off for the plain, secondary look. Both skin the same way.

Attributes and properties

ValuesDefault
seedany string, for the warm outline's wobble and the playful inkthe button's own text
registerquiet, warm, playfulinherited

Registers

LookMotion
quiet (and no JS)a hairline outline, crispnone beyond the native hover and focus states
warman ink outline drawn a little off true, behind the labelthe ink "boils" (a slow, small wobble) only while hovered or focused
playfula stamped chip, bold border, bold weightpresses in on :active; on release, an ink ring blooms from the point of contact and fades

Reduced motion: the boil never animates and the ink ring never plays; the press transform (:active) still gives feedback, because it marks a real state (held down), not decoration. Forced colours: the browser's own button and link look, drawings hidden.

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 1
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe warm outline and playful ink are aria-hidden drawings behind the label, hidden entirely in forced colours: packages/components/button/button.check.mjs: "<register>, forced colours: the browser's own look, ornament hidden". The label is the name.
1.3.1 Info and relationshipsMeetsThe native <button> or <a href> is the whole control. button.check.mjs: "no JS: the submit is announced as a button, by its own text" and "no JS: the link is announced as a link".
1.4.1 Use of colorMeetsThe label says what the button does. A disabled button is dimmed and its border turns dashed (packages/components/button/button.css, button:disabled), and the accent button is told from the others by its fill and its words, never by colour alone.
1.4.3 Contrast (minimum)Meetspackages/components/button/button.test.js: "contrast: <palette> <theme>: the hairline outline and the accent chip read" asserts 4.5:1 for text on the accent fill; plain labels are --sg-text, tested in packages/tokens/tokens.test.js. axe color-contrast is clean: tools/axe.mjs --url /packages/components/button/demo.html: 0 violation(s) across 6 run(s) (three registers, light and dark, desktop), 2026-10-07. A disabled button is exempt (it is inactive) and is dimmed to 55 percent opacity on purpose.
1.4.4 Resize textMeetsManual test, 2026-10-06: the demo with the root font size at 200 percent in three registers (1280 px wide), no sideways scroll and no clipped label (throwaway Playwright script). Size is in em in packages/components/button/button.css.
1.4.10 ReflowMeetsManual test at 320 CSS px, three registers, 2026-10-06: no sideways scroll and no clipped label (throwaway Playwright script). No check in the repository asserts it yet.
1.4.11 Non-text contrastMeetspackages/components/button/button.test.js: the hairline outline (--sg-rule-strong) and the accent border are 3:1 or more on --sg-surface and --sg-surface-raised in every palette, light and dark. The focus ring is tested 3:1 or more in packages/tokens/tokens.test.js.
1.4.12 Text spacingMeetsManual test, 2026-10-06: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph spacing 2em) injected on the demo in three registers, no clipped or overlapping text (throwaway Playwright script). No check in the repository asserts it yet.
2.1.1 KeyboardMeetsThe native element takes Enter and Space, a link takes Enter. packages/components/button/button.check.mjs: "no JS: the form really submitted", and tools/touch.check.mjs Tabs onto each button in every register.
2.1.2 No keyboard trapMeetsManual test: packages/components/button/button.js binds no key handler and sets no tabindex; the native control takes Tab and Shift+Tab as any button does.
2.4.3 Focus orderMeetsManual test: the native element is the only tab stop and keeps its place in the page's order; the drawing is aria-hidden and takes no focus (packages/components/button/button.js sets no tabindex).
2.4.7 Focus visibleMeetstools/touch.check.mjs Tabs onto the control in each register and requires a focus style; the rule is button:focus-visible in packages/components/button/button.css, and the test "the CSS keeps the native control whole" in packages/components/button/button.test.js asserts it.
2.4.11 Focus not obscured (minimum)Meets with author's partManual test: packages/components/button/button.css has no position: fixed or sticky. A sticky header or banner the page adds can cover a button that is scrolled to.
2.5.3 Label in nameMeetsThe accessible name is the visible label, because the component adds no aria-label (button.check.mjs: "still announced as a button" reads button "Book now" in each register).
2.5.8 Target size (minimum)Meetsmin-height: 2.75em (44 px at 16 px type) in packages/components/button/button.css. Manual test, 2026-10-06: no focusable control under 24 by 24 CSS px at 1280 px or at 390 px with touch, in all three registers on the demo, which holds short and long labels, a link and a disabled button (throwaway Playwright script).
4.1.2 Name, role, valueMeetsbutton.check.mjs: "still announced as a button" in each register and "no JS: the link is announced as a link"; disabled is the native attribute. axe: 0 violation(s), tools/axe.mjs --url /packages/components/button/demo.html, 2026-10-07.

The page author owns:

  • The label text, in the language of the page, saying what the button does, and lang on a label in another language (3.1.2).
  • A link used as a button (<a>) is a link: put role and key handling on it only if the page needs a button.
  • Sticky headers and banners that could cover a button when it takes focus (2.4.11).
  • The colours the page sets behind the button, if it overrides the tokens.

How it behaves

  • The native element is the whole control. disabled and aria-disabled="true" both dim it and stop the press feedback.
  • Focus uses --sg-focus, visible against every register.
  • Outline, accent border and accent-filled text hold 3:1 (border) or 4.5:1 (text on the accent fill) in every palette and theme (tested).

All 57 tables, and how the library tests

Budget

Behaviour 1.6 KB (button.js + button.core.js); skins quiet 0.1 KB, warm 1.1 KB, playful 0.8 KB.