Toolbox

Focus ring token and usage rules

Define one focus ring as tokens and prove it on every surface: 24 rules, a contrast and area checker, a CSS lint and a pixel test.

What it is

Field Guide 10: 24 rules for one focus ring that stays visible on every surface, in light and dark and in forced colors mode. The kit adds DTCG 2025.10 focus tokens on top of Field Guide 03's layers, the ring as CSS (two-tone, inset variant, brand-surface swap, forced colors), a checker for WCAG 1.4.11 and 2.4.13 across seven contexts in both themes (56 of 56 pass; six common ring designs fail 96 checks), a CSS lint and a Playwright script that measures the rendered ring in pixels.

When to use

When someone has removed the browser focus ring, when a dark mode or brand surface makes the ring disappear, or before making WCAG 2.4.13 Focus Appearance a system target.

How to use

Open the PDF or the interactive HTML and map the four WCAG criteria to the kit checks
Add color.border.focus-inner and stroke.focus-inset to your semantic tokens
Replace every focus style with styles/focus-ring.css and run the lint on your compiled CSS
List your surfaces in focus-contexts.json and run node scripts/check-focus-ring.mjs
Point tests/focus-ring.spec.mjs at your key routes and run it in normal and forced colors mode

Before you start

Prerequisites and when to skip this.

Prerequisites

Semantic colour tokens with a light and a dark value (Field Guide 03 describes the layers)
Node 22 for the checker and lint; Playwright and Chromium for the pixel test

When NOT to use this

A product that ships only the browser's default ring and never restyles focus or its surroundings
As proof of WCAG conformance on its own: it covers focus appearance, not the rest of a page

Consider instead

You need to check the whole keyboard experience, not only the ring: Start with the Keyboard-only QA checklist and come back for the ring

Downloads

Guide (PDF)Full kit (ZIP): PDF, HTML, Markdown, tokens, CSS, checker, lint, Playwright test

Error message templateKeyboard-only QA checklistAccessibility as a speed multiplier

The share link includes source tracking so LinkedIn traffic stays measurable in analytics.

Share on LinkedIn