Design tokens for status colors: define roles, map modes, and verify states

Start with the decision the token must carry. Your product may need success, information, warning, danger, emergency, pending, or another local concept. No vendor taxonomy can decide which of those belongs in your product. Carbon and the NYS Design System document different, system-specific structures. Their catalogs are useful examples, not a universal vocabulary.

For each proposed status, record its governing source and version, plain-language meaning, permitted uses, exclusions, supported modes, required channels, named consumers, protected surfaces, owner, and evidence state. Exclusions matter. A danger role may describe a destructive product outcome while remaining excluded from ordinary hover styling, focus indicators, and chart series.

Don't ask only whether a case uses color. Ask what decision would change it and which consumers should change with it. A case outside the status taxonomy does not automatically belong to a component. It may be another shared semantic role. The matrix is a routing method, not a mandatory naming scheme.

Carbon's observed catalog separates support colors from hover, active, selected, focus, and component responsibilities. The NYS guide documents shared semantic status and focus roles. Identity Forge's general semantic-color guide also separates state, form and focus, and reusable chart roles. Together, these references support keeping the concerns separate. The local product still decides ownership.

Don't create foreground, surface, border, and icon aliases for every status by default. Start with one named consumer and add only the channels its contract needs. The example below is limited to an account-settings save-confirmation banner. It is a planning matrix, not an executed implementation.

The surface and foreground are proposed as separate channels, but neither is mapped yet. A mapped claim requires the source identifier, project alias, and light and dark relationship to be recorded. The banner carries a product status. A dismiss button inside it carries interaction and focus states under another contract.

Ambient Sage v1 is useful as a source record because its public page exposes a real semantic system rather than a hypothetical palette. The page lists 28 semantic tokens in light and dark modes. For this status-specific scope, the relevant public upstream roles are success, warning, and destructive.

This fixture is deliberately unexecuted. It shows what the record needs without attributing placeholder values to Ambient Sage or claiming that anyone rendered, inspected, or tested a component.

Make the expected observation falsifiable. "Looks correct" can't reveal whether the failure belongs to the status policy, mode value, project alias, component contract, or a local override.

Write the record before you inspect the preferred render. Required means acceptance depends on the field. Conditional means the scoped consumer determines whether it applies. Unresolved marks a missing decision or observation. Not applicable needs a reason.

Accept only when all evidence required by the declared scope supports the expectation. Choose revise when the policy is sound but a correctable mapping, artifact, component contract, or record remains incomplete. Block when a required policy decision has no owner, a required observation is missing, or the result contradicts the approved contract.

When the consumer does not match the expectation, inspect the chain in ownership order. Stop at the first divergence instead of correcting whichever file is easiest to edit.

1. 1

   Check the source policy

   Confirm that the status meaning, permitted uses, exclusions, modes, channels, consumers, and owner are explicit and current.

2. 2

   Check the emitted artifact

   Confirm that the expected source version produced the required identifiers and mode values in the artifact the project received.

3. 3

   Check the project mapping

   Confirm that local aliases point to the intended emitted roles in each supported mode and that no stale value replaced them.

4. 4

   Check the component contract

   Confirm that the named component and variant consume the project mapping for every required channel and do not substitute a literal or unrelated role.

5. 5

   Check the approved exception

   Determine whether a documented exception intentionally changes this consumer. Verify its scope and owner before treating the difference as a defect.

6. 6

   Check the rendered consumer

   Inspect the named consumer under the recorded modes, content, and state. Record the observation without making claims about untested consumers.

Product status describes something the product needs to communicate, such as a completed operation or a condition requiring attention. Hover, active, selected, and disabled describe interaction or control state. Focus can be a shared semantic role. Input validation needs a local decision: does it reuse danger, use a form semantic role, or belong to a component contract? Chart colors may also be reusable semantic roles. Being close on screen doesn't give these cases shared meaning.

The general Identity Forge semantic-color guide covers the broader role system, including paired foreground roles, state colors, form and focus roles, and chart colors. This guide focuses on status policy, adoption, and evidence. Add a component-token layer only when a named component property has independent change authority and bounded consumers.

Choose the status role reused by the most important current consumers. Select one precise consumer, complete the acceptance record, map only its required channels, inspect both supported modes, and record the first divergence. Add another status name only after the first role has an owner, a traceable mapping, and an actual observation.

• Design Tokens Color Module 2025.10: The captured report describes the technical representation of color token values and opacity. It identifies itself as a preview draft that must not be implemented or cited as authoritative guidance.
• Color Tokens - Carbon Design System: Carbon documents system-specific core and component color tokens, including separate support, focus, hover, active, and selected responsibilities.
• Design Tokens - NYS Design System: The NYS Design System separates primitive, semantic, and theme layers and documents shared semantic roles for status and focus.
• Ambient Sage Design Kit: Ambient Sage v1 is a public free kit with 28 semantic tokens in light and dark modes, including success, warning, and destructive roles, plus implementation artifacts.
• Semantic color tokens explained: Identity Forge's general semantic-color guide documents role-based colors, paired foreground roles, light and dark values, and separate state, form, focus, and chart responsibilities.
• Component tokens vs semantic tokens: when to add a component layer: A component token is warranted when a named component property needs independent change authority and a bounded set of consumers.
• Design token handoff checklist: prove the path from source to consumer: A token handoff requires traceability from its governing source through the delivered artifact and project mapping to named consumers and observed results.