Accessibility
Semetrika targets WCAG 2.2 AA for every component it ships. The classless-first principle is the largest single contributor: semantic HTML carries accessibility metadata that ad-hoc <div> markup does not. Beyond that, every component follows a small set of accessibility patterns that you inherit automatically by using the bundle.
What you get for free
Drop in the bundle, write semantic HTML, and the following are already correct:
- Semantic roles.
<button>is a button to assistive tech.<nav>is a navigation landmark.<article>is an article. The browser communicates this to screen readers and keyboard users without any ARIA decoration. - Keyboard navigation. Every interactive element is reachable with Tab. Buttons activate on Enter and Space. Links activate on Enter. Form controls follow native browser behavior.
- Visible focus rings. Every interactive element shows a focus ring via
:focus-visible- visible only when navigating with the keyboard, not when clicking with a mouse. The ring uses Semetrika's--focus-ring-*semantic tokens, so brand overrides keep it on-brand. - Color contrast. Body text meets a 4.5:1 contrast ratio against its background. Large text and bold text meet 3:1. The contrast holds in both light and dark schemes; the dark-scheme tokens were chosen to maintain the ratio, not just to look dark.
- Reduced motion. When the user has
prefers-reduced-motion: reduceenabled at the OS level, Semetrika zeroes--option-animationsautomatically. Components that opt into the Motion capability stop animating. You do not need to handle this yourself. - No autoplay. Carousels and videos do not auto-play without explicit consumer opt-in and a visible pause control.
Native HTML first, ARIA second
Semetrika prefers native HTML over ARIA wherever possible. The reasoning is simple: native elements come with correct semantics, keyboard behavior, focus management, and operating-system integration. ARIA only describes semantics - it does not provide behavior, so a <div role="button"> still has to re-implement everything a <button> already does.
| Use this | Not this |
|---|---|
<button> | <div role="button" tabindex="0"> |
<details> | <div aria-expanded="false"> |
<dialog> | <div role="dialog"> |
<nav> | <div role="navigation"> |
<main> | <div role="main"> |
<input type="checkbox"> | <div role="checkbox"> |
When ARIA is needed - because the semantics genuinely are not in HTML, or because the component layers behavior on top of a primitive that does not capture all the state - Semetrika uses ARIA both for assistive tech AND as a CSS selector hook. [aria-expanded="true"], [aria-busy="true"], [aria-selected="true"] all drive both the screen-reader announcement and the visual state, so the two cannot drift out of sync.
Keyboard patterns
Every interactive component is operable via the keyboard. The patterns below are followed consistently across the library:
| Pattern | Components | Keys |
|---|---|---|
| Tab navigation | All interactive elements | Tab moves forward. Shift+Tab moves backward. |
| Button activation | button, mirror .btn | Enter and Space activate. |
| Link activation | <a>, mirror .btn styled as link | Enter activates. Space does not (matches browser default). |
| Disclosure | accordion, dropdown, collapsible | Enter or Space toggles. Escape closes (where applicable). |
| Modal | modal, drawer | Tab focus is trapped inside the dialog. Escape dismisses. |
| Listbox / select | select, dropdown menu | Arrow keys move through items. Enter selects. Escape closes. |
| Radio group | radio, chip selection group | Arrow keys move between radios within the group. Tab leaves the group entirely. |
| Tabs | tabs | Arrow keys move between tabs. Tab moves to tab panel. |
| Carousel | carousel | Tab through controls. Arrow keys advance slides when the strip has focus. |
If a component you are placing breaks one of these patterns, file an issue.
Focus management
Focus management is one of the most error-prone aspects of accessibility. Semetrika handles it for you in the components that need it:
- Modal / drawer. When opened, focus moves to the dialog. When closed, focus returns to the element that opened it. Tab is trapped inside while open.
- Dropdown menu. When opened, focus moves to the first item. When closed, focus returns to the toggle.
- Skip link. A
.skiplink at the top of the page jumps focus past the header to the main content. Visible only when focused. - Live regions. Components that update content asynchronously (collection results, search results, announcement) declare
aria-liveso screen readers announce the change.
Color contrast guarantees
Semetrika's semantic color tokens (--text-color-neutral, --background-color-neutral, the per-component tokens) are paired in light and dark schemes such that the resulting contrast meets WCAG 2.2 AA. The guarantee is on the default tokens Semetrika ships; it does not survive arbitrary consumer overrides.
If you override a token, check the contrast with whatever tool you prefer (axe DevTools, Lighthouse, Color Contrast Analyser, WebAIM Contrast Checker). The token-override pattern is documented on Tokens.
There is no special "high-contrast" mode beyond what the OS already provides (Windows High Contrast Mode and macOS Increase Contrast both work on Semetrika). See Color schemes for why Semetrika ships exactly two schemes and how a consumer-level high-contrast theme could be layered on top.
Reduced motion
Semetrika wires --option-animations to prefers-reduced-motion: reduce automatically:
@media (prefers-reduced-motion: reduce) {
:root {
--option-animations: 0;
}
}
The token is a multiplier consumed via calc() in every animated component. When the user prefers reduced motion, the multiplier becomes zero and animations collapse to zero-duration transitions. You can override this at the consumer level - either to force animations off (--option-animations: 0) regardless of the OS setting, or to scale them (--option-animations: 0.5 for half-speed). See Tokens.
Components that animate by default opt into the Motion capability and accept .animated / .still value classes to override the global option per instance.
Form accessibility
Form controls are the area of most accessibility risk in any framework, so Semetrika is opinionated:
- Labels are siblings, not wrappers.
<label for="id">…</label><input id="id" />rather than<label><input /> text</label>. This makes the label-control association explicit, lets split-field enhancements re-position the label without DOM surgery, and matches the explicit-labeling convention used by major design systems. - Required fields are visually annotated. A small visual marker (asterisk in the default theme) is added to the label of required fields. The marker is decorative; the actual required state comes from the
requiredHTML attribute, which is what assistive tech reads. - Error states use ARIA. Form controls with errors carry
aria-invalid="true"and anaria-describedbypointer to the error message. The message itself is in a live region so screen readers announce it as it appears. - Fieldset groups related controls. Sets of radios, checkboxes, and address-entry forms wrap their inputs in
<fieldset>with a<legend>for screen-reader grouping. - Helper and error text are linked. Helper text and error text are linked to their input via
aria-describedby, so they are announced together when the input gets focus.
Component-level guarantees
A non-exhaustive list of accessibility features baked into specific components:
| Component | Accessibility features |
|---|---|
accordion | Uses <details>/<summary> natively. Mirror class form uses aria-expanded and Enter / Space toggle. Optional exclusive group behavior. |
announcement | role="status" live region. Dismissable via close button with focusable target. |
back-to-top | Works as a plain anchor link without JS. With JS, adds smooth scroll and visibility toggling. |
breadcrumb | <nav aria-label="Breadcrumb"> landmark. Current page marked aria-current="page". |
button | Native <button>. Mirror .btn carries role="button" and Enter / Space handlers when applied to non-button elements. |
carousel | Works without JS as a scroll-snap strip. Auto-play (when opted in) has a visible pause control and pauses on focus / hover. |
collection | Results count is aria-live="polite". Items region carries aria-busy="true" while loading. |
dropdown | Native popover API for top-layer rendering and light dismiss. Arrow key navigation. aria-expanded sync. |
modal / drawer | Native <dialog> element. Focus trap, Escape dismiss, focus return on close. Backdrop click optional. |
skip | First focusable element on the page, hidden until focused. Jumps focus to the #main landmark. |
tabs | Tab list with arrow-key navigation. Tab panel relationship via aria-controls and aria-labelledby. |
tooltip | Triggered via data-tooltip. Wired with aria-describedby so screen readers announce on focus / hover. |
The Storybook page for each component carries its full ARIA contract under the "Accessibility" tab.
Testing your site
Semetrika gives you the baseline. The rest depends on how you compose components into pages:
- Run an automated check. axe DevTools, Lighthouse, or Pa11y catch the bulk of straightforward violations (missing alt text, contrast on overridden tokens, missing landmarks).
- Tab through the page. If you can complete every task with only the keyboard, you have likely covered keyboard accessibility.
- Test with a screen reader. VoiceOver on macOS / iOS, NVDA on Windows, TalkBack on Android. Hearing how a screen reader announces your page is the single highest-signal test for assistive-tech compatibility.
- Toggle reduced motion in your OS settings and reload the page. Animations should collapse.
- Try the dark scheme if you ship one. Contrast should hold; nothing should disappear.
If you find a component in Semetrika that does not meet WCAG 2.2 AA in its default configuration, open an issue - accessibility bugs are treated as defects, not enhancements.