Quality and Accessibility

Token quality checks

Studio evaluates five categories every time you save. Each category flags a specific class of problem and tells you where to fix it.

• •Undescribed tokens — any token without a description. Fix: open the token in the editor and add one.
• •Stale deprecation references — a non-deprecated token whose alias points to a deprecated token. Fix: update the alias to point to the replacement token instead.
• •Unresolved aliases — an alias token pointing to a target that does not exist. This check runs on every save and again at publish time. An unresolved alias blocks publish until resolved. Fix: correct or remove the alias.
• •Naming violations — tokens that break your project's configured naming rules. This check runs automatically whenever naming rules are saved. Fix: rename the token or adjust the rule. To configure the naming rules that drive this check, see Token Enforcement Settings.
• •Format violations — token values that do not match a configured format constraint. This check runs on every token save. Fix: correct the value to match the expected format. To configure format constraints, see Token Enforcement Settings.

Accessibility score

The score runs from 0 to 100. It is calculated as: 100 minus (errors × 10, plus warnings × 3, plus infos × 1), clamped between 0 and 100.

Color thresholds in Studio: green at 80 or above, orange between 50 and 79, red below 50.

The score covers three check types:

• •Contrast (WCAG 1.4.3) — checks 10 foreground/background semantic color pairs. A pair that fails AA (4.5:1 for normal text, 3:1 for large text) is an error. A pair that passes AA but fails AAA is a warning.
• •Focus ring (WCAG 2.5.3) — checks the contrast of border.focus against surface.background and surface.card. Below 3:1 is an error. Below 4.5:1 is a warning.
• •Touch targets (WCAG 2.5.5) — checks that spacing-11 (eleven times your base unit) is at least 44px. Below 44px is an error. spacing-10 below 44px is a warning.

A check only fires when the relevant tokens are mapped. If border.focus is not mapped, the result is an info-level notice, not an error.

Component quality checklist

Every component in the atoms package is evaluated against a 21-item checklist. The checklist is machine-readable so automated checks can run in CI without any manual setup.

• •Code (8 checks) — file structure, section ordering, no hardcoded CSS values (stylelint), JSDoc on the public API (manual), event naming conventions (eslint), slot names (manual), logical CSS properties for RTL support (stylelint), and a reduced-motion media query (stylelint). A mix of automated and manual.
• •Accessibility (5 checks) — keyboard operability (manual), focus ring using design tokens (manual), ARIA roles (vitest), state announcements (manual), and axe-core passing (vitest). Mostly manual with two automated.
• •Tokens (4 checks) — all visual values sourced from CSS custom properties (stylelint), private fallback pattern (manual), CSS parts exposed (manual), and component tokens documented in @cssprop JSDoc (manual). Mostly manual.
• •Tests (6 checks) — all variants render (vitest), public props tested (vitest), events tested (vitest), keyboard navigation tested (vitest), slots tested (vitest), and axe passing (vitest). All automated.

Automated checks (eslint, stylelint, and vitest) run as part of the atoms package test and lint suite on each pull request.

What runs automatically

• •On every token save: format violations, naming violations, and unresolved alias detection.
• •At publish time: all five token quality checks run again. An unresolved alias blocks the publish until it is resolved.
• •Continuously in Studio: the accessibility score recalculates whenever color or spacing tokens change.
• •In CI (atoms package): all eslint, stylelint, and vitest checks from the component checklist run on each pull request.

Manual checks require human review. They are surfaced during the publish workflow and on the component reference page in the consumer docs portal.

Improving your score

Contrast errors give the fastest accessibility wins. Go to the Quality section in Studio and use the token navigation links on each issue card to jump directly to the offending semantic slot.

For undescribed tokens: use the bulk-describe workflow in the token table to add descriptions to multiple tokens at once instead of editing each one individually.

For stale deprecations: search the token table for tokens aliased to the deprecated path, then update each alias to point to the replacement. Removing a deprecated token before its consumers are updated creates unresolved aliases, which block publish.

For component checklist items: start with the automated checks. They run in CI and produce clear pass/fail output. Manual checks are reviewed during the publish workflow and shown on the component reference page in the consumer docs portal.

For the full list of token types and how aliases work, see Token Types. For how quality checks interact with the publish flow, see Publishing. For how quality scores appear on component reference pages, see Component Builder.