Accessibility
What the system guarantees, how it’s verified, and what’s still up to you. Anything that isn’t verified is stated here as a limit.
The approach
Accessibility isn’t a layer added at the end. It comes out of the same engine that emits the CSS. Contrast is calculated, not eyeballed. Visible focus doesn’t depend on someone remembering to style it. RTL mirroring doesn’t depend on migrating classes. When a guarantee can move into the engine or into a test, it does—whatever is left to discipline breaks.
The flip side is that the system is honest about its limit. A design system can guarantee its components, not your application. The bottom half of this page is about that.
What the system guarantees
| What it guarantees | How it’s verified |
|---|---|
| No axe violations on each component page, at rest, in light and dark mode | axe runs on every page, in light and dark mode, without opening menus, dialogs, or lists |
| AA text contrast against its intended background | the engine computes each theme’s color/contrast pair in OKLCH, and an automated test checks it |
| Focus always visible; on buttons and controls, only from the keyboard | component CSS uses :focus-visible, never plain :focus. In text fields, the browser also applies it on click |
| Less moves if you asked for reduced motion | prefers-reduced-motion: reduce turns transitions off and stills the skeleton, the indeterminate bar, and the Badge halo, emitted globally |
| The whole UI mirrors in RTL | the CSS uses logical properties (start and end) for spacing and alignment. Physical ones (left and right) remain only in positions set by coordinates or named by side (floating elements, toasts, the command palette, the Avatar presence indicator), and for floating elements the JS computes the coordinates already mirrored |
| Focus trapped and restored in overlays | Modal and AlertDialog use the native <dialog>, tested with real interaction in Chromium, Firefox, and WebKit |
The stated target is WCAG 2.2 level AA. Each component publishes its own statement—the WAI-ARIA APG pattern it implements, the keys it adds, and the ARIA it provides—in the Accessibility section of its page. Today there are 56 components with a statement, 21 of them built on an APG pattern, with 207 ARIA claims and 62 keyboard shortcuts of their own across 24 components.
The limits
No component has been through a real screen reader yet
There’s no formal ACR/VPAT yet either. The per-component statement is exactly the input one is written from, but until it’s signed, don’t treat it as one.
Nor was it tested on a real iPhone or iPad: desktop WebKit (Playwright) doesn’t replace Safari on iOS with VoiceOver.
How it’s tested
Four layers, from cheapest to most expensive. None of them replaces the next one:
- axe on every render. An automated check of every component. It finds a lot, but not everything.
- Real interaction in 3 browsers. Focus, keyboard, and stacked overlays in Chromium, Firefox, and WebKit, with real clicks rather than synthetic events.
- Hard combinations. Nested overlays, virtualized lists in small containers, 375 px screens in every mode. That’s where the problems a single-component demo hides show up.
- Screen readers, by hand. This is the layer that hasn’t been done for any component yet (see above).
What’s up to you
The components bring the behavior; you bring the content, and that’s where accessibility gets lost in practice. The minimum:
- Label your fields. A
placeholderisn’t a label—it disappears as you type. Use a real<label for>, and tie the hint and the error to it witharia-describedby. The Field comes with that structure built in. - Icon-only buttons need a name. With no visible text, give it an
aria-label. - Declare the language in
<html lang>. It decides how the screen reader pronounces things. - Don’t skip heading levels. The system gives you the
type scales on their own precisely so that size never forces you into the wrong level.
type-heading-24on an<h3>is perfectly valid. - If you theme, check the contrast. The engine guarantees it for the seeds you give it, but a color forced by hand outside the system doesn’t go through that calculation.
<!-- Wrong: the placeholder disappears as you type -->
<div class="ts input size-md variant-default" data-ts-input>
<input class="ts input-field" type="email" placeholder="Email" />
</div>
<!-- Right: a real label, tied to the control, with its hint -->
<label for="correo" class="ts input-label">Email</label>
<div class="ts input size-md variant-default" data-ts-input>
<input id="correo" class="ts input-field" type="email" aria-describedby="correo-ayuda" />
</div>
<div id="correo-ayuda" class="ts input-hint variant-default">
<span>The confirmation is sent to this address</span>
</div>
<!-- Icon-only button: without aria-label it has no name -->
<button class="ts button size-md variant-ghost" aria-label="Close">
<svg class="ts icon size-16" aria-hidden="true"><use href="taisho/taisho.icons.svg#ts-x"></use></svg>
</button>Report a problem
An accessibility failure is treated as a functional bug, not as an enhancement. If you find one, here’s what helps: which component, with which screen reader and browser, what you expected to hear, and what you heard. If it contradicts a claim published in the component’s Accessibility section, say so—that claim is the first thing to fix.