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

Tabs

A row of headed sections, read one at a time. Without JavaScript it is a table of contents: every section shows and each link jumps to its heading.

quiet warm playful

Open the live demo npx @susegad/cli add tabs

Stands on: Core, Core: components, Tokens, Page transitions

The prompt

the prompt

A row of headed sections, read one at a time.

Without JavaScript it is a table of contents. With JavaScript it becomes the ARIA APG tabs pattern, and the selected tab is marked by a line that travels to it instead of jumping.

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

<sg-tabs>
  <nav aria-label="Room details">
    <ul>
      <li><a href="#overview">Overview</a></li>
      <li><a href="#amenities">Amenities</a></li>
    </ul>
  </nav>
  <section id="overview"><h2>Overview</h2>…</section>
  <section id="amenities"><h2>Amenities</h2>…</section>
</sg-tabs>
Attribute / memberWhat it does
labelThe tablist's accessible name, if the <ul> has no aria-label of its own.
select(index, { focus })Select a tab in code; focus (default false) also moves keyboard focus there.
activeIndexRead only: the selected tab's index.
sg-tab-change eventdetail: { index, tab }, fired after a selection (not on the first, silent one).

The prompt

Build a tabs web component that starts as a table of contents: a <nav> with a <ul> of links to headed <section>s, each with its own id, so the page reads and works with no JavaScript at all. When JavaScript runs, enhance it into the ARIA APG tabs pattern with automatic activation: give the <ul> role="tablist", each link role="tab" with roving tabindex (0 on the selected tab, -1 on the rest), and each linked section role="tabpanel", hidden unless selected. The arrow keys both move focus and select, wrapping at the ends; Home and End jump to the first and last tab. A click selects and focuses, except when it carries a modifier key or isn't the primary button, so the browser's own "open in a new tab" still works on every tab. Draw the selected tab with an ink line that travels along the tablist to sit under it, instead of jumping: a static hairline in quiet, an inked line eased into place in warm, the same line with a small bead riding its centre, on a springier ease, in playful. Wrap the panel swap in a same-document View Transition where the browser has one, naming only the panel that is changing (per <sg-tabs>, so two on one page never collide), so the content can cross-fade; fall back to an instant swap. Keep the underline itself outside that transition, so it keeps travelling under the cross-fade rather than jumping with it.

Words to code

When you sayTechniqueWhat happens
starts as a table of contentsnative firstThe <ul> of links to <section id>s is real navigation on its own. tabs.js only adds roles, tabindex and the hidden state; nothing about the markup requires it.
automatic activation … wrapping at the endsARIA APGtabs.core.js's moveIndex(current, key, count) is the whole keyboard model as one pure function, tested for every key and for wrapping in both directions; tabs.js only calls it and applies the result.
an ink line that travels … instead of jumpinglayout, transitiontabs.js's state() measures every tab's box relative to the tablist once per update; the warm and playful skins set that box's left and width as inline styles on one <span>, and tabs.css transitions those two properties, so the browser interpolates the travel, no animation loop.
a small bead riding its centregeometrybeadAt(box) in tabs.core.js is the box's midpoint; a second, smaller element rides it on its own, springier transition.
a same-document View Transition … naming only the panel that is changingnative firstdocument.startViewTransition() wraps the panel-hidden toggle; the newly active panel alone gets a per-instance view-transition-name set just before the swap and cleared on the one it replaces, so two <sg-tabs> never fight over one name.
keep the underline itself outside that transitionseparationThe underline lives in the light DOM as an ordinary positioned element with its own CSS transition; a View Transition only captures elements it names, and the underline is never named, so it keeps animating through the capture untouched.

Accessibility

  • role="tablist", role="tab" with aria-selected and roving tabindex, role="tabpanel" with aria-labelledby, exactly the ARIA APG pattern.
  • Nothing the underline shows is the only place that state appears: aria-selected and the hidden panel say the same thing in the accessibility tree.
  • The underline and the bead are aria-hidden.
  • Reduced motion collapses the underline's transition and the View Transition to near-zero through the shared duration tokens; nothing needs to check for it separately.

Credit

The travelling underline and the ink-with-a-bead treatment are original to Susegad UI's playful register; no plate is ported here (Wave 5's harvest touches Tabs only through the shared Teental stagger tokens, used elsewhere in the wave).

<sg-tabs> turns a table of contents into the ARIA APG tabs pattern.

Markup

<sg-tabs>
  <nav aria-label="Room details">
    <ul>
      <li><a href="#overview">Overview</a></li>
      <li><a href="#amenities">Amenities</a></li>
    </ul>
  </nav>
  <section id="overview"><h2>Overview</h2>…</section>
  <section id="amenities"><h2>Amenities</h2>…</section>
</sg-tabs>
  • The <nav><ul> list of links and the <section id>s it points to are the whole component without JavaScript: every section shows, and each link jumps to its heading. Give the <nav> (or the <ul> itself) an aria-label, or pass label on <sg-tabs>.
  • Each link's href must be a #fragment matching a section's id. Sections are looked up inside <sg-tabs> first, then in the whole document.
  • Give exactly one <ul> (or <ol>) inside <sg-tabs>; its direct <li><a> children become the tabs.

Behaviour

With JavaScript, tabs.js enhances the list into a tablist (role="tablist" / role="tab" / role="tabpanel") and hides every panel but the selected one. Activation is automatic: the arrow keys move focus and select together (Left/Right; wrapping at the ends), Home and End jump to the first and last tab. A plain click also selects; a click with a modifier key, or a middle/right click, is left alone so "open in a new tab" keeps working. The starting tab is the one matching location.hash, then the one marked aria-current, then the first.

Attributes and members

labelThe tablist's accessible name, when the markup gives it none of its own.
select(index, { focus = false })Select a tab from code. focus also moves keyboard focus there.
activeIndexRead only.
registerquiet, warm or playful, as usual.

Events

sg-tab-change: { index, tab }, fired after every selection except the silent first one.

The registers

  • Quiet: a static hairline under the selected tab (box-shadow, no JavaScript-drawn element).
  • Warm: the ink underline travels between tabs (tabs.css's transition: left, width, on the --sg-dur-calm / --sg-ease-ink tokens).
  • Playful: the same underline plus a small bead riding its centre, on the spring ease.

Panel swaps use a same-document View Transition where the browser supports one (Chromium today), so the outgoing and incoming panel content cross-fade; without it, or under reduced motion (the duration tokens collapse to near zero), the swap is instant. Two <sg-tabs> on one page never collide: each names only its own active panel, and only while it is mid-swap.

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 13
  • Meets with author's part 3
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe travelling underline and its bead are drawn with aria-hidden="true" (packages/components/tabs/skins/warm.js, skins/playful.js); the quiet look is a CSS hairline. Everything a tab says is its text.
1.3.1 Info and relationshipsMeetsThe tablist, each tab and each panel carry their roles, and each panel is labelled by its tab: packages/components/tabs/tabs.check.mjs, "<register> the tablist is announced with its tabs and their selected state" (tablist "Room details", tab "Overview" [selected]). Without JavaScript it is a table of contents of plain anchors over headed sections ("no JS: the element is never defined, every section shows, and the links are plain anchors").
1.4.1 Use of colorMeetsThe selected tab is set by aria-selected, bold weight and an underline, not colour alone: packages/components/tabs/tabs.css ([aria-selected="true"], the quiet hairline, the warm and playful underline); tabs.check.mjs asserts the selected state in the accessibility tree.
1.4.3 Contrast (minimum)MeetsTab text is --sg-text-soft and the selected tab --sg-text, both text roles: 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/tabs/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 at 1280 px, three registers, nothing wider than the screen (throwaway Playwright script). Sizes are in rem and tokens: packages/components/tabs/tabs.css.
1.4.10 ReflowMeets with author's partManual test, 2026-10-07: demo at 320 CSS px, three registers, page width 320 (the page does not scroll sideways). The row of four tabs, "Overview" to "Reviews", is 425 px wide, so the tablist scrolls sideways inside its own box (overflow-x: auto, packages/components/tabs/tabs.css) with every tab still reachable by keyboard or touch (throwaway Playwright script). Short labels, or fewer tabs, fit without scrolling; whether a scrolling tab row is acceptable for 1.4.10 is a judgement for the audit.
1.4.11 Non-text contrastMeetsThe underline and bead are --sg-accent-text, a text role at 4.5:1; the quiet hairline is --sg-text; the list rule is decorative; the focus ring is --sg-focus: packages/tokens/tokens.test.js ("AA: <palette> <theme>: focus ring and control borders are 3:1 or more on every surface").
1.4.12 Text spacingMeets with author's partManual 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: the page does not scroll sideways; the right edge of the tab row moves from 425 to 495 px and the row scrolls inside its own box (throwaway Playwright script). No check in the repository asserts it yet.
2.1.1 KeyboardMeetspackages/components/tabs/tabs.check.mjs: ArrowRight moves focus and selects together, End jumps to the last tab, ArrowRight wraps from the last to the first and ArrowLeft back, a click selects; Home and the arrow keys are unit-tested in packages/components/tabs/tabs.test.js.
2.1.2 No keyboard trapMeetsManual test: packages/components/tabs/tabs.js handles only the arrow keys, Home and End on a tab, with roving tabindex: Tab leaves the tablist for the selected panel and onward, and Shift+Tab comes back. The panels hold focus like any content.
2.4.3 Focus orderMeetsOne tab stop in the tablist (the selected tab), then the selected panel, which is tabindex="0", then the rest of the page; hidden panels are hidden and take none (packages/components/tabs/tabs.js, roving tabindex and aria-selected).
2.4.7 Focus visibleMeetspackages/components/tabs/tabs.css sets a :focus-visible outline in the token focus colour on each tab and on the panel; 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/tabs/tabs.css uses no position: fixed or sticky and no overlay, and the focus ring sits inside the tab (outline-offset is negative). A sticky header or banner the page adds can cover a panel's start when focus moves to it.
2.5.3 Label in nameMeetsThe accessible name of a tab is its visible text; the component adds no aria-label: tabs.check.mjs reads tab "Overview" and the others.
2.5.8 Target size (minimum)MeetsManual test, 2026-10-07: each tab is 106 by 39.4 px at 1280 px, in all three registers (throwaway Playwright script on the demo), from the padding in packages/components/tabs/tabs.css. No check in the repository asserts target size for the tabs yet.
4.1.2 Name, role, valueMeetsFull ARIA tabs semantics (aria-selected, roving tabindex, aria-labelledby on each panel): tabs.check.mjs, "the tablist is announced with its tabs and their selected state" and "the second tablist keeps its own selection independent of the first". axe: tools/axe.mjs --url /packages/components/tabs/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07.

The page author owns:

  • The label of the tablist (aria-label on the <nav>), the tab text and the panel headings, in the language of the page, and lang on any in another language (3.1.2). The element falls back to a name from the host when none is given.
  • Tab labels short enough to fit the narrowest width, or accepting that the row scrolls (1.4.10).
  • Sticky headers and banners that could cover a panel when focus moves to it (2.4.11).

How it behaves

  • Full ARIA APG tabs semantics: aria-selected, roving tabindex, aria-labelledby on each panel.
  • The underline and its bead are aria-hidden; the selected state is always also in aria-selected and the hidden panel.
  • Works with no JavaScript as a table of contents; degrades to native anchor navigation.

All 57 tables, and how the library tests

Lineage

No plate is ported for Tabs itself. It shares Wave 5's harvested Teental stagger (packages/tokens/tokens.js, talaDelay) where a page uses tabs inside a staggered list, but the tab strip and its underline are original to this register system.

Budget

See registry.json.