Accessibility | Surflane

Principles

Meet WCAG 2.2 AA on every screen. Components handle their own behavior, and the product owns names, structure, and messages.
Keep native semantics. Links navigate, buttons act, and headings outline the page, so assistive technology reads them right.
Keep the reader's input. After an error, keep every value and say what went wrong and how to fix it.
Announce each result once. Give a change one status message, and leave the result on the page.
Test the whole task. Finish it by keyboard, at 320px wide and 400% zoom, and with a screen reader.

Shared and product responsibilities

Shared components handle interaction, focus, and styling. The product owns the rest.

What to build and check in each area
Area	Build	Check
Structure	main, nav, headings, DOM order	Title, h1, and skip link after a route change
Keyboard	Native buttons, links, and form controls	The task with Tab, arrows, Enter, Space, and Escape
Forms	Labels, descriptions, errors, required state	Values kept, cause and fix stated
Feedback	status or alert, by severity	One announcement, result kept on the page
Perception	Shared color, focus, size, and motion tokens	Themes, zoom, text spacing, 320px width, forced colors

Keyboard and focus

Tab order follows DOM order, so write the DOM in reading order. Don't add positive tabIndex values or clickable divs. Use a button or a link instead.

On touch and narrow screens, controls are --surf-control-target-size (44px) tall. A control that keeps a smaller look, such as a table row's checkbox or a tree's disclosure button, reaches that size around it. A compact density, for dense monitoring screens, keeps them at their size instead, never under WCAG 2.2 AA's 24px. Never remove or cover the focus ring.

Dialogs keep focus inside, close on Escape, and return focus to their trigger. Don't build a focus trap of your own. When an action removes its trigger, move focus to the next meaningful element.

Errors and recovery

Submit the example empty or with spaces, then try a name conflict. It validates locally and sends nothing.

Mark a required field in its label and with required. State the cause and the fix in words, not by color alone. Move focus to a field only after the reader acts, as the conflict does.

<Field.Root name='name'>
  <Field.Label>Environment name (required)</Field.Label>
  <Field.Control required />
  <Field.Description>Use a unique environment name.</Field.Description>
  <Field.Error />
</Field.Root>

// Keep this live region mounted before updating its text.
<p role='status' aria-atomic='true'>
  {result}
</p>

Announcements

Announce a change that doesn't move focus, such as saved settings or new results, in a role=status region. Mount the region before its text changes.
Use role=alert only for an error that needs action now.
Say it once. Don't repeat one message in the field, a toast, and a status region.
Keep the result and its recovery path on the page. Don't rely on a toast alone.
When a status or a name has no place on screen, such as the name of a column of checkboxes, put it in VisuallyHidden: it keeps its place in the reading order and takes no space. Don't hide it with display: none, which removes it for everyone.

Testing

Finish the task by keyboard alone: start, edit, cancel, and recover from an error.
Check at 320px wide, at 200% and 400% zoom, and with wider text spacing.
Switch between light, dark, forced colors, and reduced motion.
Check names, order, and states with VoiceOver or NVDA. Automated checks such as axe don't replace this.

Mark only what you tested as done. These checks aren't an accessibility certification.

WAI — Form notifications / WCAG — Focus order / W3C — Keyboard control