Skip to content

Accessibility ​

Refine targets WCAG 2.2 AA compliance across the component library. ARIA roles and states are managed automatically. Keyboard navigation, focus management, and live-region announcements are built into each component.

What You're Responsible For ​

Most accessibility is handled for you. Two things require action on your side:

  • Icon-only buttons must have a label attribute: it becomes aria-label. Without it, screen readers have nothing to announce.
  • Decorative icons should have aria-hidden="true" so screen readers skip them. Meaningful standalone icons need an aria-label.
html
<!-- Icon-only button: label required -->
<ore-button icon-only label="Delete item" color="error">
  <ore-icon name="trash-2" size="18"></ore-icon>
</ore-button>

<!-- Decorative icon: hidden from screen readers -->
<ore-icon name="check" size="16" aria-hidden="true"></ore-icon>

<!-- Meaningful standalone icon -->
<ore-icon name="warning" size="16" aria-label="Warning"></ore-icon>

You can also connect an input to external help text using aria-describedby:

html
<ore-input label="Password" aria-describedby="pwd-hint" />
<p id="pwd-hint">Minimum 8 characters, one uppercase, one number.</p>

Testing Strategy ​

Refine uses a three-layer approach.

1: Unit tests (jsdom + Ore test helpers)

Every component has tests verifying correct role and aria-* attributes at render time, ARIA state changes on attribute mutation, keyboard event handling, focus management for overlays, and live-region announcements.

2: Axe-core automated audit (jsdom)

The axeCheck helper is available globally in all Refine unit tests:

ts
import { mount } from '@vielzeug/ore/testing';

it('has no axe violations', async () => {
  const fixture = await mount('ore-button', { attrs: { color: 'primary' } });
  const results = await axeCheck(fixture.element);
  expect(results.violations).toHaveLength(0);
});

The jsdom scan runs the full WCAG 2.2 AA tag set (wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa) plus best-practice. Rules that need a real layout engine (color-contrast, target-size) or document-level CSS (css-orientation-lock) are disabled there and covered by the browser scan instead.

3: Axe-core in a real browser (Playwright)

Every component also ships a co-located *.e2e.ts accessibility suite that runs axe in Chromium against a mounted component — all 44 component suites, so color-contrast, target-size (SC 2.5.8), and layout-dependent rules are verified with a real engine, including interaction states (open dialogs, expanded pickers, filled inputs). The shared axeCheck(page) helper in @vielzeug/refine/testing carries the same WCAG 2.2 AA tag set with page-level rules scoped out, so the rule configuration lives in exactly one place.

4: Manual checklist (per release)

Before each minor release:

Per-Component Coverage ​

Inputs ​

ComponentRoleKeyboardKey ARIA attrs
ore-buttonbutton (implicit)Enter / Spacearia-disabled, aria-busy
ore-inputtextbox (native)Standardaria-describedby, aria-invalid, aria-required
ore-textareatextbox (native)Standardaria-describedby, aria-invalid, aria-required
ore-selectcomboboxArrow / Enter / Escapearia-expanded, aria-activedescendant
ore-comboboxcomboboxArrow / Enter / Escapearia-expanded, aria-activedescendant
ore-checkboxcheckbox (native)Spacearia-checked, aria-required
ore-radioradio (native)Arrow keys (group nav)aria-checked
ore-switchswitchSpacearia-checked
ore-slidersliderArrow keysaria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext
ore-ratingsliderArrow keysaria-valuetext for the value
ore-color-pickerradiogroup + radioArrow keys, Home/Endaria-checked per swatch, roving tabindex, group aria-label from label
ore-countergroup + spinbuttonArrow keys, Home/End, Page Up/Downaria-valuenow, aria-valuemin, aria-valuemax, aria-live
ore-number-inputspinbuttonArrow keysaria-valuenow, aria-valuemin, aria-valuemax
ore-otp-inputgroup of text inputsArrow / Backspace / Tabaria-label per cell
ore-file-inputbutton-triggered nativeStandardaria-label

Feedback ​

ComponentRoleKeyboardKey ARIA attrs
ore-alertalert / statusDismiss buttonaria-live via region
ore-toastalert / statusDismiss buttonaria-live="polite" or "assertive"
ore-statestatus / alert (regions)Retry buttonHost aria-busy only; role="status" (loading/empty) or role="alert" (error) on the announced region, retry outside it
ore-progressprogressbarN/Aaria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext
ore-pull-to-refreshstatus (spinner)Pointer onlyrole="status" on the persistent spinner; provide a separate refresh button for keyboard
ore-skeletonNone (decorative)N/Aaria-hidden="true" on bones
ore-typing-indicatorstatus (on a visually-hidden label)N/Aaria-live="polite"; dots are aria-hidden="true"
ore-badgeNoneN/Aaria-label if meaningful
ore-chipbutton (interactive)Enteraria-pressed, aria-label

Content ​

ComponentRoleKeyboardKey ARIA attrs
ore-accordionbutton + regionEnter / Spacearia-expanded, aria-controls
ore-cardbutton (interactive)Enter / Spacearia-disabled, aria-busy
ore-card-pickerBrowsing region, card group, selection checkbox, reading dialog or regionArrow / Home / End browse; Space selects; Details moves focus into reading; Escape dismissesaria-label, aria-expanded, aria-controls, aria-haspopup, aria-modal, aria-hidden/inert, aria-checked
ore-statsarticleN/Aaria-disabled, aria-busy
ore-chat-messagearticle (on the bubble)N/Aaria-label describing sender; failed sends also announced via an assertive live region
ore-listlist or listbox (selectable)Arrow / Home / End / Enter / Space (selectable only)aria-disabled; needs aria-label/aria-labelledby in listbox mode
ore-list-itemlistitem or option (selectable)Enter / Space (activation); Tab reaches slotted actions-left/actions-right contentaria-selected, aria-disabled
ore-tabletable (native)Standardaria-label, aria-busy
ore-textheading (as="h1"–h6) or button (expandable)Enter / Space (expandable)role="heading" + aria-level; role="button" + aria-expanded when expandable
ore-avatarNoneN/Aalt or aria-label
ComponentRoleKeyboardKey ARIA attrs
ore-tabstablist + tab + tabpanelArrow keysaria-selected, aria-controls, aria-labelledby
ore-steppernavigation + listArrow / Home / End (when clickable)aria-current="step", aria-disabled
ore-paginationnavigationStandardaria-label, aria-current
ore-breadcrumbnavigationStandardaria-label, aria-current
ore-navigation-menunavigation + disclosureArrow / Enter / Escapearia-expanded, aria-controls, aria-haspopup

Overlay ​

ComponentRoleKeyboardKey ARIA attrsNotes
ore-command-palettedialog + combobox + listboxArrow / Enter / Escape, focus traparia-modal, aria-activedescendant, aria-expandedFocus restored on close; global shortcut via keymap
ore-dialogdialogEscape, focus traparia-modal, aria-labelledbyFocus restored on close
ore-drawerdialogEscape, focus traparia-modal, aria-labelledbyFocus restored on close
ore-popoverdialog / menuEscapearia-expanded, aria-haspopup
ore-menumenu + menuitemArrow / Enter / Escapearia-orientation
ore-tooltiptooltipEscapearia-describedby on trigger
ore-tourdialogEscape, ArrowLeft / ArrowRightaria-modal (dialog modes), aria-valuetext on progressPopover mode: focus on open, restored on close; dialog modes: native focus trap + background lock
ore-spotlightdecorativeN/Aaria-hidden on overlayNever captures pointer events

Layout ​

ComponentNotes
ore-sidebarNavigation landmark: provide aria-label for screen readers
ore-navbarNavigation landmark: provide aria-label for screen readers
ore-gridLayout only, no interactive semantics
ore-boxLayout only, no interactive semantics

Built-in Guarantees ​

  • Touch targets are 44×44 on every pointer. Interactive components set a 44px minimum target unconditionally, not only under a coarse pointer: a mouse user gets the same hit area as a touch user. Under a coarse pointer the whole component also promotes one size tier, so padding and icons grow with the target.
  • Native editors have an absolute mobile font floor. Under @media (pointer: coarse), the native text in ore-input, ore-textarea, ore-message-composer, ore-otp-input, and ore-command-palette uses at least 16 CSS pixels, including with a smaller root font, smaller text tokens, or size="sm". Larger configured fonts are preserved. Composites built on these editors inherit the same floor. This addresses iOS Safari's sub-16px focus-zoom threshold without disabling user zoom.
  • Hover decoration requires hover capability. Hover-only styles use @media (hover: hover) so touch taps do not leave a sticky hover appearance. Focus, selected, expanded, and active states remain available independently.
  • Truncated text is recoverable. Any label clipped by an ellipsis (ore-text, ore-list-item, ore-menu-item, ore-sidebar-item) mirrors its full text into a title while it is actually clipped, and drops it as soon as there is room. ore-text additionally supports expandable for a tap-to-reveal disclosure.
  • Focus rings share one primitive. Every keyboard focus indicator composes --focus-ring, so the increased-contrast path (prefers-contrast: more or html.contrast-more) thickens all rings at once by re-declaring one token.
  • Reduced motion and reduced transparency are honored. prefers-reduced-motion zeroes every duration token; an app can force either direction with setMotionMode('reduced' | 'full') (see Animation & Motion → Motion Mode). prefers-reduced-transparency swaps translucent frost fills for opaque ones.
  • Continuously moving content pauses by default. ore-marquee stops on hover and on keyboard focus (pause-on-hover defaults to true), giving pointer and keyboard users a pause for the repeating ticker (SC 2.2.2) on top of the reduced-motion stop.
  • Keyboard focus is never hidden behind sticky chrome. Sticky ore-table / ore-datagrid headers set scroll-padding-block-start, so a focused row scrolls into clear view below the pinned header rather than underneath it (SC 2.4.11).
  • Accessible names contain their visible labels. Controls are named from their own visible text wherever a name can be derived that way — a slider mirrors its default-slot label onto the host aria-label, a file drop zone and the query-bar filter button are labelled by their visible content — so a speech-recognition user can activate them by what they read (SC 2.5.3). No aria-label overrides a visible label.
  • Helper and tertiary text uses AA tokens. Form helper text, drop-zone hints, and out-of-month day numbers use the plain --color-contrast-500 ink (≥ 4.5:1 on canvas) rather than a lightened color-mix(), which dropped below the contrast floor (SC 1.4.3).
  • Input helpers carry autofill hints. ore-input forwards autocomplete, ore-otp-input sets one-time-code, and the search-style fields (ore-combobox, ore-query-bar, ore-command-palette) set autocomplete="off" with aria-autocomplete="list" so their listbox behaviour isn't fought by the browser's own autofill (SC 1.3.5).
  • Return-key labels reach the native editor. Text inputs, textareas, and message composers support a typed enterkeyhint, without changing their keyboard behavior.

Compliance Contract ​

Every published component must satisfy:

RequirementStandard
Keyboard navigabilityWCAG 2.2 AA §2.1
Visible focus indicatorWCAG 2.2 AA §2.4.7
Focus not obscured by sticky contentWCAG 2.2 §2.4.11
Pointer-gesture cancellation (no down-event actuation)WCAG 2.2 §2.5.2
Drag alternatives (single-pointer where draggable)WCAG 2.2 §2.5.7
Target size ≥ 24×24 (Refine exceeds at 44×44)WCAG 2.2 §2.5.8
Accessible name contains visible labelWCAG 2.2 §2.5.3
Motion pause (hover / keyboard)WCAG 2.2 §2.2.2
Colour contrast ≥ 4.5:1 (normal text)WCAG 2.2 AA §1.4.3
Colour contrast ≥ 3:1 (large text / UI components)WCAG 2.2 AA §1.4.11
Orientation-independent layoutWCAG 2.2 §1.3.4
Autofill for personal-data inputsWCAG 2.2 §1.3.5
Accessible name on every interactive controlWCAG 2.2 AA §4.1.2
Correct ARIA roles and states (valid, non-duplicate)WCAG 2.2 AA §4.1.2 / §4.1.4
Live region announcements for dynamic changesWCAG 2.2 AA §4.1.3
Forced-colors / Windows High ContrastWCAG §1.4.3 enhanced
Reduced-motion fallbackWCAG 2.1 §2.3.3

Known Gaps ​

AreaGapPlanned
Visual regressionNo snapshot CI yetPlaywright visual diff in vNext
NVDA + JAWS parityNot systematically testedManual audit before 2.0 stable
ore-select virtual listVirtual items need aria-setsize / aria-posinsetTracked