Accessibility.

What the runtime guarantees

Aktion is not certified against a conformance level, and this page does not claim one — WCAG conformance is a property of a finished page, and the library controls only part of it.

What it does do is ship accessible behaviour by default, and pin the measurable parts to tests in this repository:

The criteria the source and tests name as targets are 1.4.11 (non-text contrast, the 3:1 bar), 2.4.11 (focus appearance), and 2.4.3 (focus order — what FocusTrap’s restoreFocus exists for). They are design targets, not an audit result.

ARIA built into components

These behaviours come from the component itself, so a generated program gets them without asking. Everything here was read out of the component source, not inferred from the class names:

Keyboard map

Aktion adds no global shortcuts of its own. Everything below is either the browser’s native behaviour on a real element, or a documented component contract:

Which components implement arrow-key navigation

Grouped by the interaction pattern, so you can tell what a key will do before you press it:

Every widget in the first four rows uses a roving tab stop: the group is one Tab stop and the arrows move inside it, which is what keeps a 30-item menu from adding 30 stops to the page.

Screen readers & streaming

Because UI streams in token-by-token, content can change rapidly. To keep the experience calm for assistive tech:

• The morph reconciler patches the DOM in place rather than replacing it, so focus, selection, and a screen reader’s reading position survive re-renders.
• Status changes use polite/assertive live regions via Toast roles — reserve the assertive danger tone for errors that must interrupt.
• Prefer revealing a region once its content has settled (e.g. an Async/Lazy fallback) over announcing every intermediate token.
• Announce the outcome, not the progress: one LiveRegion that flips to “Saved” beats a region bound to a value that changes on every keystroke.

Theme contrast

The built-in themes are not eyeballed. Three contrast invariants are asserted for every one of them in tests/theme-focus-contrast.test.ts, so a retint that breaks one fails the build rather than shipping:

That third invariant is why light.colorPrimary is #4f46e5 (6.29:1 on white) and no longer the indigo-500 #6366f1, which measured 4.47:1 — fine as large text, short as the small text the library actually paints with it. colorPrimaryHover moved with it, to #4338ca.

One more split worth knowing: colorAccent has two jobs — a fill paired with colorAccentText, and link text. Themes whose accent already clears 4.5:1 as text inherit a derived colorLink; soft, mui, heroui and signal ship an explicit one because theirs do not — HeroUI's #006fee is 3.8:1 as text on its own dark card, so heroui-dark paints links in #66aaf9 instead while the button FILL stays HeroUI blue.

The three-way status colour split

A status hue cannot do three jobs at three different contrast bars, so each one is three tokens. This is the part of the theme system most likely to be missed when you write a custom palette:

#10b981 measures 2.54:1 on white, so around forty-five rules — Badge, Tag, Pill, Callout, the StatCard value, a danger MenuItem, field errors — take the *Text token instead of the fill.

Symmetrically, everywhere that used a literal #fff on a status fill now takes colorOn*: a completed Step tick, a Toast icon disc, a danger Button label, a count badge.

The rest of the rule set is short: body text at 4.5:1, large text and UI affordances at 3:1, and never meaning from colour alone — pair tone with an icon or a label, as the components already do.

One caveat on the invariants: they compare opaque hex values, so a theme whose surface or ink is an rgba(…) — Material's rgba(0,0,0,0.87) body text, for one — is skipped by the test and reviewed by hand. Themes has the full token reference.

Keeping custom components accessible

OnClick(
  Box([Text("Delete")], { padding: "sm" }),
  { onClick: () => remove() }
)

Button("Delete", {
  variant: "danger",
  icon: "trash",
  onClick: () => remove()
})

• Build from real interactive elements (button, a, input) rather than click-handler divs. The global focus-visible rule only nets real controls and widget roles — a bare div gets nothing.
• Give every control an accessible name (visible label, aria: { label: "…" }, or aria: { labelledby: "…" }).
• Use $id(prefix?) to generate unique ids for label/description associations instead of hard-coding them — hard-coded ids collide the moment the component renders twice, and axe() flags it as duplicate-id.
• Manage focus for anything that opens or closes: wrap it in FocusTrap while open rather than reimplementing the cycle.
• An icon-only control needs a label somewhere — either aria: { label } on the button or a VisuallyHidden child.

The universal role and aria channels

Every component accepts a small set of universal props on top of its own, and two of them are the escape valve for ARIA you cannot fix from the outside. Reach for them when a component’s default semantics are wrong for your context — not as a first resort.

The role allow-list is closed on purpose: an unrecognised role is ignored by assistive tech anyway, and a plausible-but-wrong one (button on a container, a landmark with no owned children) is worse than the defect it was meant to work around.

$app(Column([
  Column([
    Input("q", { placeholder: "Search invoices", aria: { label: "Search invoices" } }),
    Button("Search", { variant: "primary" })
  ], { gap: "sm", role: "search" }),                              // landmark on a plain container
  Row([
    IconButton("trash", { aria: { label: "Delete selected" } }),  // name an icon-only control
    IconButton("download", { aria: { label: "Export selected" } })
  ], { gap: "xs", role: "toolbar" }),                             // one group, not two loose buttons
  Box([Text("3 of 12 selected")], { role: "status" })             // announced whenever the text changes
], { gap: "md" }))

Roles that need matching owned children or ARIA state (gridcell, row, treeitem…) are deliberately absent, because a bare role override cannot supply them. Use the component that already builds the whole pattern instead.

none and presentation go the other way: they take a purely decorative wrapper out of the accessibility tree entirely.

Accessibility primitives

Four components cover the most common screen‑reader and focus‑management needs. They render the right ARIA and behaviour so you don’t hand‑roll it.

$status = "Nothing saved yet"
$app(Column([
  SkipLink("#main", { label: "Skip to content" }),
  Column([Text("Main content starts here.")], { id: "main" }),
  Button("Save", { variant: "primary", onClick: () => { $status = "Saved just now" } }),
  LiveRegion(`Status: ${$status}`, { politeness: "polite" }),   // announced, not shown
  VisuallyHidden(Text("Press Escape to close"))                 // shown to AT only
], { gap: "md" }))

Give the SkipLink target a real id through the universal id channel. If that id is missing at click time the link lands on the nearest content landmark (main, [role="main"], the render root, or the first h1) instead of sending the hash router to a bogus route.

$status = "Nothing saved yet"
$app(Column([
  SkipLink("#main", { label: "Skip to content" }),
  Button("Save", { variant: "primary", onClick: () => { $status = "Saved just now" } }),
  Column([Text($status)], { id: "main" }),
  LiveRegion(`Status: ${$status}`, { politeness: "polite" }),
  VisuallyHidden(Text("This sentence is read by screen readers but hidden visually."))
], { gap: "md" }))

FocusTrap — confine keyboard focus

Wrap any subtree in FocusTrap while it is open and Tab / Shift+Tab cycle within it instead of escaping to the page behind. It is the primitive for hand‑rolled dialogs, drawers, and command palettes.

Modal, Drawer, and Sheet already trap focus, so reach for it only when you build the overlay yourself.

Initial focus fires on the closed→open transition only, so typing inside a trapped form never yanks the caret back to the first field.

$open = false
function closePanel() { $open = false }
$app(Column([
  Button("Open panel", { variant: "primary", onClick: () => { $open = true } }),
  $open ? FocusTrap(
    Card([
      CardHeader("Edit profile", { subtitle: "Tab cycles inside. Escape closes." }),
      Input("name", { placeholder: "Name", aria: { label: "Name" } }),
      Input("email", { placeholder: "Email", aria: { label: "Email" } }),
      Row([
        Button("Cancel", { onClick: closePanel, data: { cancel: "true" } }),
        Button("Save", { variant: "primary", onClick: closePanel })
      ], { gap: "sm" })
    ]),
    { active: $open, onEscape: closePanel, autoFocus: "[data-cancel]" }
  ) : Text("Panel closed.", { tone: "muted" })
], { gap: "md" }))

autoFocus: "[data-cancel]" lands on Cancel rather than the first field — the right default for a dialog whose primary action is destructive. The selector is resolved inside the trap, so data: { cancel: "true" } on the button is all the wiring it needs.

RTL & logical layout

Set dir on the host <aktion-app> element to flip the whole tree for right‑to‑left languages. The runtime reflects it onto the render root, so direction and CSS logical properties mirror text, flex order, and logical spacing automatically.

<aktion-app dir="rtl"></aktion-app>
<!-- "rtl" | "ltr" | "auto" -->

Because spacing and layout primitives use logical properties, most programs need no changes — the same tree lays out correctly in both directions. The direction key inside $theme({…}) is advisory metadata only; the attribute is what flips layout.

Reduced motion & forced colors

Motion is suppressed automatically under prefers-reduced-motion: reduce. A global rule disables every animate preset and hover utility; twelve more scoped blocks stop or slow individual animations; and motion components (Reveal, Parallax, Confetti, Backdrop, TypingIndicator, Sheet…) guard themselves with matchMedia.

You can branch on the same flag from a program:

anim = $util.media.prefersReducedMotion ? "none" : "fade-up"
Card([Text("Respectful by default")], { animate: anim })

Looping indicators are slowed rather than frozen — a Spinner or Skeleton that stopped entirely would read as a hung page — while decorative animation (Confetti, blobs, pulsing dots) is switched off outright.

Two @media (forced-colors: active) blocks keep components legible in Windows High Contrast mode. Borders on buttons, cards, inputs, badges, tags, selects, textareas, tables, and modals switch to CanvasText, and focus rings switch to Highlight.

The second block reverts the gradient-title effect the soft theme uses to plain CanvasText, so those headings do not vanish.

Auditing with axe()

The testing utilities ship an axe(node) audit that needs no dependency. It returns an array of { rule, message, element } violations — empty means clean — so it drops straight into an assertion:

import { describe, it, expect } from "vitest"
import { render, axe, flush } from "aktion-runtime/test"

describe("dashboard a11y", () => {
  it("has no axe violations", async () => {
    const screen = render(program)
    await flush()                                        // let the first render commit
    const issues = axe(screen.shadowRoot)                // NOT screen.container — see below
    expect(issues).toEqual([])                           // failure prints rule + message + element
  })
})

within(node) from the same entry point scopes queries to one subtree, which pairs well with auditing a single Card or dialog rather than the whole app. See Testing for the surrounding harness and TypeScript for the A11yViolation type.

Pre-ship checklist

1. Every interactive element is reachable and operable by keyboard, and composite widgets are one tab stop with arrow keys inside.
2. Focus is visible everywhere and never trapped except intentionally — and every intentional trap has an Esc route out.
3. All controls have accessible names; icon-only controls carry aria: { label } or a VisuallyHidden child.
4. Status and error messages use the correct Toast tone or LiveRegion politeness — assertive only for interruptions.
5. Ids come from $id, not literals, so nothing collides.
6. A custom theme retints colorBorderControl, colorFocusRing, and every *Text / colorOn* partner — not just the base hues.
7. Meaning isn’t conveyed by colour alone.
8. axe(screen.shadowRoot) returns an empty array in CI.

Next