Semantic token handoff contract

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

Hand a palette to an implementer so pages preserve color roles. Teaching tokens are ink=#18181B for body text and action=#2563EB for primary buttons/focus indication. Missing name, value or purpose makes the recipient guess.

Mechanism

Specify semantic name, machine-usable value, functional role and relevant states together. Identify one maintained owner in the existing token system and reference roles from components. A small project need not adopt three layers solely for this method. Inspect computed styles and real states for manually copied-value drift.

Bad example

Use dark text and a nice blue for these pages. Let each component choose similar values and independently guess button and focus colors.

Good example

Implement the teaching contract: ink=#18181B for body text; action=#2563EB for primary buttons and focus. Maintain them in existing semantic variables; components reference roles instead of hand-copying values. List names, values, purposes and states, then inspect actual button/focus rendering and contrast. Do not infer another value from 'nice blue' or treat token names as usability checks.

Why the change matters

Names express intent, values remove guesswork and roles identify where consistency belongs. Shared references preserve that contract and distinguish purposeful variants from unexplained drift.

Observable expectation

An illustrative mapping is body→ink→#18181B and button/focus→action→#2563EB. Trace computed styles to variables and inspect hover/focus plus text backgrounds.

An undocumented similar blue or values without roles indicate an incomplete handoff. Exact matching still requires contrast and readability checks.

Limits

The colors are teaching choices, not a universal palette. Theme mappings may change primitives and explicit variants may serve other roles. Source aesthetic bans are not required by this method; consistent names do not establish WCAG compliance.