Design tokens for focus indicators: define the contract and verify every state

The useful unit of work isn't "make focus accessible." That scope is too broad to assign or verify. Name one focus-indicator contract, its governing source and version, its supported environments and consumers, and the surfaces where it must remain inspectable. Mark everything outside that boundary as unresolved or not applicable, with a reason.

For example, a bounded review might cover the primary button, inline link, text input, checkbox, and tabs in one web application. It could include the application's light and dark themes, ordinary and contrasting surfaces, currently supported browsers, and forced colors. It would not cover every operating system, browser, component, or assistive-technology combination unless someone actually tested them.

Focus color is often semantic because several controls need to share the same intent across themes. Geometry can also be reusable when a system standardizes outline width, offset, style, or a combined treatment. HPE's global focusIndicator is one example of reusable geometry living above individual components. A component contract should own a decision only when a named component genuinely needs behavior narrower than the shared rule.

Public design systems solve similar problems with different structures. Their names describe their own systems; they are not portable names that every project must copy.

A portable method begins above those system-specific choices: record the purpose, authority, mapping, consumers, evidence, and disposition. Your project can then adopt, translate, or reject a vendor's structure without treating the vendor's terminology as a web-wide convention.

The contract below is long on purpose. A field may be required, conditional, unresolved, or not applicable, but it should not disappear. Missing fields are where assumptions turn into local overrides.

focusIndicatorContract:
  contractId: required
  governingSource:
    name: required
    version: required
    authorityOwner: required
  semanticPurpose: required
  supportedEnvironments:
    browsersAndVersions: required
    platforms: required
    forcedColors: required | not_applicable_with_reason
  modes:
    lightMapping: required
    darkMapping: required
    additionalThemes: conditional
  geometry:
    sharedTreatment: required | unresolved
    componentOverrides: conditional
  selectorPolicy:
    focusRule: required
    focusVisibleRule: required
    unsupportedSelectorFallback: required
    keyboardExpectation: required
    pointerExpectation: required
    programmaticFocusExpectation: required
  forcedColorPolicy:
    affectedPropertyRisk: required
    systemColorFallback: required | unresolved
  namedConsumers: required
  protectedSurfaces: required
  approvedExceptions: required | none
  owners:
    tokens: required
    components: required
    css: required
    verification: required
  evidence:
    sourceDecision: required
    artifactIdentity: required
    projectMapping: required | unresolved
    runtimeObservations: required | open
  retestTriggers: required
  disposition: accept | revise | block

Protected surfaces should be concrete: a primary button on the default page background, an inline link inside a card, or tabs inside a contrasting navigation panel. "All surfaces" is not inspectable. Named consumers and representative surfaces keep verification finite without implying that untested consumers passed.

The public Ambient Sage page establishes a versioned upstream artifact: Ambient Sage v1, a semantic ring role, light and dark token sets, focus-ring direction, and implementation exports. It also describes vivid yellow as the saturated accent used for focus rings. Those facts belong in a project contract. They do not establish the project's alias name, selector policy, component adoption, forced-color branch, runtime result, or accessibility disposition.

The following chain is illustrative. Only the Ambient Sage v1 source role and export availability come from the frozen public kit evidence. Every downstream identifier is a proposed local mapping, so it remains unresolved until the project confirms it.

1. 1

   Pin the governing source

   Record Ambient Sage v1 and the public kit page as the authority for the upstream semantic ring role. Do not replace that versioned source with a screenshot or copied literal.

   Copy

   source: Ambient Sage v1
   role: ring
   status: established

2. 2

   Identify the emitted artifact

   Choose the export the project actually consumes and record its file identity or generated version. Identity Forge offers DESIGN.md, CSS, Tailwind, DTCG, shadcn, CLI, and MCP routes, but availability does not prove which one a project used.

   Copy

   artifact: unresolved
   expectedRole: ring
   status: open

3. 3

   Declare the project alias

   Map the incoming role to one local semantic property. The name below is an example, not an observed Ambient Sage export.

   Copy

   --app-focus-ring: var(--ring);

4. 4

   Apply selector policy

   Keep a visible :focus fallback, then refine it with :focus-visible where supported. Record expected behavior by focus path instead of assuming that the device type determines the match.

   Copy

   .control:focus {
     outline: var(--app-focus-width) solid var(--app-focus-ring);
     outline-offset: var(--app-focus-offset);
   }
   
   .control:focus:not(:focus-visible) {
     outline: none;
   }
   
   .control:focus-visible {
     outline: var(--app-focus-width) solid var(--app-focus-ring);
     outline-offset: var(--app-focus-offset);
   }

5. 5

   Bind the component contract

   For the primary Button, record whether it inherits the shared geometry or owns an approved override. Put clipping, border-radius interaction, and any variant-specific rule in the component contract instead of hiding them in a local selector.

   Copy

   consumerContract: Button.primary
   sharedGeometry: unresolved
   approvedOverride: none_recorded
   status: open

6. 6

   Inspect the named consumer

   Render the primary Button on one named surface under every in-scope condition. Record its computed styles and visible result. Until then, the trace ends with an open observation.

   Copy

   consumer: Button.primary
   surface: dashboard/default
   actualObservation: open
   disposition: block

This trace prevents a common false conclusion. Finding the ring role in an exported file proves that the artifact contains the role. It does not prove that the application loads the artifact, the local alias resolves, the selector matches, the component preserves the outline, or the rendered indicator remains distinguishable on its surface.

The :focus-visible pseudo-class matches a focused element when the user agent decides that a focus indicator should appear. Keyboard interaction commonly influences that decision, but "keyboard means match" and "pointer means no match" are not reliable universal rules. User preferences, element type, focus movement, browser behavior, and the way focus was assigned can all affect the result.

A practical fallback begins with :focus. Remove or replace that treatment only inside a selector using :focus-visible. If a browser does not support :focus-visible, it ignores the unsupported refinement and keeps the :focus rule. Test the exact rule ordering and supported-browser set; copying the pattern does not prove that the cascade works in your application.

Forced-colors mode changes the rendering environment. The browser may force colors on several properties, while altering or suppressing decorative effects. A focus treatment that depends on box-shadow alone is therefore risky: its visual separation may disappear even when the ordinary theme looks correct.

Use the forced-colors media feature to define a bounded fallback, then inspect it. System colors such as Highlight follow colors selected by the user agent or operating environment. They are a suitable candidate for a focus outline in this branch, but choosing one in CSS remains an expectation. It does not prove that every consumer renders correctly.

@media (forced-colors: active) {
  .control:focus-visible {
    box-shadow: none;
    outline: var(--app-focus-width) solid Highlight;
    outline-offset: var(--app-focus-offset);
  }
}

Record four facts for this branch: which authored effects may be lost, which system color is selected, which consumers were inspected, and what happened. A global media query may be insufficient if a composite control draws focus on an internal item while its container clips outlines. That requires a component-specific contract or an approved exception; it is not evidence that the token failed.

Prepare the matrix before testing so the expectations cannot drift to match a screenshot. Each row below is a test specification, not a completed benchmark. Replace "Open" with an environment-specific observation only after inspection.

A rendered mismatch sits at the end of a chain. Correct it at the first layer that differs from the approved contract, then retest every downstream layer affected by the correction.

1. 1

   Confirm source authority

   Check the governing source, version, approved semantic purpose, mode mappings, and reusable geometry. If authority is missing or disputed, stop and assign the decision. Do not let local CSS settle it by accident.

2. 2

   Inspect the emitted artifact

   Identify the exact export the project uses. Confirm that the expected role and values appear in that artifact. A correct source paired with a stale or incomplete export is an artifact problem.

3. 3

   Resolve the project mapping

   Follow the emitted role into the local alias and both mode branches. If the alias points elsewhere or an override applies at the wrong scope, the project mapping is the first divergence.

4. 4

   Check selector and environmental CSS

   Inspect rule order, specificity, the :focus fallback, :focus-visible matching, and the forced-colors branch. Record the browser and environment instead of generalizing from one result.

5. 5

   Check the component contract

   Confirm that the named component consumes the shared rule or has an approved narrow override. Inspect overflow, borders, shadows, internal focus targets, and state composition.

6. 6

   Record the consumer observation

   Record expected and actual results separately. Assign the correction owner at the first divergent layer, name the change that triggers a retest, and set the disposition to accept, revise, or block.

If the upstream role is correct, the artifact contains it, and the project alias resolves, changing the source color is unlikely to restore a missing ring. Check the selector, cascade, component overflow, or focus target. Conversely, trace a ring rendered with the wrong light or dark value through the local mapping and emitted artifact before adding a component override.

The acceptance record closes the loop. Keep source facts, proposed mappings, observations, exceptions, and decisions in separate fields so reviewers can see exactly what remains open.

focusIndicatorAcceptance:
  contractId: focus-web-v1
  sourceAuthority:
    source: Ambient Sage
    version: v1
    upstreamRingRole: established
  artifactIdentity:
    format: unresolved
    fileOrBuildId: unresolved
    observedRole: open
  projectMapping:
    alias: --app-focus-ring
    status: illustrative_unverified
  consumer:
    component: Button.primary
    surface: dashboard/default
  environment:
    browserAndVersion: unresolved
    theme: light
    focusPath: keyboard
    forcedColors: inactive
  expectedResult:
    selectorPolicy: use_focus_fallback_then_focus_visible_refinement
    visibleTreatment: required
    geometry: unresolved
  actualResult:
    selectorMatches: open
    computedStyles: open
    visualInspection: open
  exception:
    id: none_recorded
    owner: not_applicable
  correctionOwner: unresolved_until_first_divergence
  retestTrigger: any_change_to_source_artifact_mapping_css_or_button_contract
  disposition: block

Use accept only when every required field within the stated boundary has evidence and no blocking mismatch remains. Use revise when the contract or implementation needs a named correction that can be retested. Use block when required authority or evidence is missing, the first divergence has no owner, or an in-scope consumer fails its expectation. Optional evidence may be marked not applicable with a reason; required evidence may not.

• Global - HPE Design System: HPE documents a system-wide focusIndicator token that combines focus-related values within HPE's own global-token structure.
• Color Tokens - Carbon Design System: Carbon documents color and focus roles within Carbon's own token catalog and naming system.
• Design Tokens - NYS Design System: The NYS Design System separates primitive, semantic, and theme-token layers and includes a semantic focus color role.
• :focus-visible CSS pseudo-class - MDN Web Docs: MDN documents that :focus-visible matching depends on user-agent heuristics and provides a :focus-based fallback pattern.
• :focus CSS pseudo-class - MDN Web Docs: MDN documents :focus as matching an element that has received focus and warns against removing a visible outline without a replacement.
• forced-colors CSS media feature - MDN Web Docs: MDN documents the forced-colors media feature and the browser adjustments that can change or suppress authored visual properties.
• <system-color> CSS type - MDN Web Docs: MDN documents system colors for authored properties that need to follow user-selected colors, including forced-color conditions.
• Ambient Sage Design Kit: The public Ambient Sage v1 kit establishes a semantic ring role, light and dark token sets, focus-ring direction, and downloadable implementation artifacts.