---
title: "Accessibility"
description: "The accessibility requirements Tanrei builds into tokens and component specs, and the checks that enforce them."
url: "https://tanrei.chnotchy.com/foundations/accessibility/"
last_updated: 2026-11-21T03:27:29.000Z
---

> This page is part of the Tanrei documentation. The index at [llms.txt](https://tanrei.chnotchy.com/llms.txt) lists every page; the specs of the default system's components are in one file, [llms-full.txt](https://tanrei.chnotchy.com/llms-full.txt).

# Accessibility

> The accessibility requirements Tanrei builds into tokens and component specs, and the checks that enforce them.

Accessibility in Tanrei is a set of constraints on the system itself. The token build refuses to produce a scheme that fails contrast, and a component spec is not valid without its role, keyboard table and target guarantee.

## Contrast

The token build measures every scheme, light and dark at standard, medium and high contrast, against these thresholds, and fails when a pair falls short:

| Content | Standard and medium contrast | High contrast |
| --- | --- | --- |
| Text, and icons drawn in a content color | 4.5:1 | 7:1 |
| A status’s mark on its own tonal container | 3:1 | 3:1 |
| Boundaries and graphics needed to identify or operate a control | 3:1 | 3:1 |
| The focus ring against adjacent surfaces | 3:1 | 3:1 |

Large text has no lower threshold. WCAG accepts less contrast for text of about 24px regular, or 19px bold, and up, but the build holds every text role at 4.5:1, and at 7:1 at high contrast: a color role does not know the size it will be set in.

Disabled elements and pure decoration are exempt, and so is the `outline-variant` hairline at standard contrast. That exemption is why a border which is the only sign of a control must use `outline`, not `outline-variant`.

### Enforced invariants

These hold for every theme at every contrast level, six permutations in all, and the build fails otherwise:

- each `(X, on-X)` role pair, and each text role (`on-surface`, `on-surface-variant`, `link`, an intent’s color) on every surface role, is at least 4.5:1, and at least 7:1 in the two high-contrast schemes;
- each status color is at least 3:1 against its own tonal container;
- `outline` is at least 3:1 against every surface role;
- in the default system at medium and high contrast, `outline-variant` is at least 3:1 and 4.5:1 against every surface role, and `outline` stays stronger;
- `focus-ring` is at least 3:1 against surfaces.

Project rules forbid loosening a threshold to make a check pass.

## Target size

The least sizes of what a person presses. minimum is the least height (and, for an icon-only control, width) anything pressable is drawn at; touch and pointer are the least areas a press is taken from, under a finger and under a fine pointer, never less than minimum. Where they are above it, a control that stands alone reaches them past what it draws, and a row that touches its neighbours is drawn that high.

| Token | Value | Preview |
| --- | --- | --- |
| `--tanrei-sys-target-minimum` | 36px |  |
| `--tanrei-sys-target-pointer` | 36px |  |
| `--tanrei-sys-target-spacing` | 8px |  |
| `--tanrei-sys-target-touch` | 36px |  |

Generated from `design/tokens/tanrei.light.tokens.json`, `tokens/sys/measure.tokens.json`

**Nothing a person presses is drawn smaller than the minimum.** `sys.target.minimum` is 36 in the default system: a button, an input box, a tab or a row is drawn at least that high whatever its size, and an icon-only button at least that wide, so a small button, which the size ladder draws at 32, is drawn 36 high. A mark drawn smaller than the target, such as a checkbox’s box or a small chip, keeps its size and extends its hit area to `sys.target.touch` for touch and `sys.target.pointer` for a fine pointer. Both equal the minimum in the default system; a system that sets them higher takes a press from that larger area. Every spec declares this guarantee. Where two of them stand side by side, each hit area stops at the middle of the gap between them, so that a press never goes to a neighbour: a component that lays out a row does this itself, and a product that places buttons side by side on its own sets the caps described on the [Button page](https://tanrei.chnotchy.com/components/button.md#buttons-you-place-side-by-side). [Size and density](https://tanrei.chnotchy.com/foundations/size-and-density.md) shows the heights, and how a product sets the minimum.

## Focus

Every interactive component shows the gap-then-ring focus indicator for keyboard and assistive-technology focus, immediately and without animation. Focus order follows reading order. Disabled components leave the focus order.

## Keyboard

Each component spec contains a table of keys and actions, shown on its documentation page under **Accessibility**. Platforms with hardware keyboard support implement the table exactly.

## Text scaling

Interfaces must remain usable with text at **200%**. Containers grow with their text, labels wrap before they truncate, and nothing relies on a fixed height to fit a line of text. Native implementations use each platform’s scalable text mechanism.

## Reduced motion

Motion is reduced when the person’s system setting asks for it, or when the product sets `data-tanrei-motion="reduce"` on the root element for a setting of its own. Spatial animation is then removed or replaced by a brief fade, and what shows work under way — a loading indicator, an indeterminate progress indicator, a busy button — stops turning or sliding and fades its opacity out and back once per cycle instead. See [Motion](https://tanrei.chnotchy.com/foundations/motion.md).

## Semantics

A spec names the component’s WAI-ARIA role and how its accessible name is formed. Each platform maps the role to its native equivalent: accessibility traits in SwiftUI, semantics properties in Compose and Flutter, `accessibilityRole` in React Native. On the web, Tanrei prefers native elements inside the shadow root, so that browsers and testing tools see real semantics.

## How it is tested

| Platform | Automated check |
| --- | --- |
| Web | axe-core in Playwright |
| SwiftUI | XCTest accessibility audit |
| Compose | Accessibility Test Framework checks |
| Flutter | `meetsGuideline` matchers |
| React Native | role and label assertions, plus native audits through the gallery app |

> [!NOTE]
> **Note**
>
> Automated checks catch a minority of real problems. They are a floor. Use a screen reader and a keyboard on anything you build with these components.
