Design token governance review

Design Token Governance Review

Purpose

A token system only delivers its promise (consistent, themeable, accessible UI) if it is actually the single source of truth. This skill catches the two most common failure modes: hardcoded values that duplicate an existing token (silent drift) and token pairings that resolve to an inaccessible contrast ratio in some theme variant that nobody re-checked after the token value changed.

When to use

Use this skill when the user asks to:

• review a design-token source file or build/transform pipeline (Style Dictionary, Tokens Studio, W3C DTCG format),
• audit whether hardcoded colors/spacing values have crept back into components,
• verify WCAG 1.4.3 (text contrast) or 1.4.11 (non-text/UI-component contrast) compliance for token pairings,
• review a proposed rebrand, dark-mode, or high-contrast-mode token change for contrast regressions.

Context7 Documentation Protocol

Before making any claim about token-file format, $value/$type semantics, reference resolution, transform behavior, or Storybook a11y tooling, ground the claim in current library docs:

1. Call mcp__Context7__resolve-library-id for the library in scope (Style Dictionary, Storybook) if not already resolved in this session.
2. Call mcp__Context7__query-docs with a specific query before asserting version-specific behavior (transform config shape, DTCG $type inheritance rules, a11y-addon detection coverage, etc.).
3. Verified library IDs for this skill's scope: Style Dictionary /style-dictionary/style-dictionary (DTCG format, $value/$type, resolveReferences/getReferences, typeDtcgDelegate for $type inheritance); Storybook /storybookjs/storybook (@storybook/addon-a11y, built on axe-core, documented as catching up to ~57% of WCAG issues automatically — never represent an addon-a11y pass as full conformance).
4. If Context7 has no coverage for a claim, fall back to the W3C Design Tokens Community Group spec (https://tr.designtokens.org/format/) or WCAG 2.1 normative text, and mark the claim documentation-based rather than verified.
5. Never invent a transform name, CLI flag, or token property that was not confirmed via Context7 or the W3C spec.

Lean operating rules

• Always compute the resolved contrast ratio from the actual token values in scope; a token's semantic name (--color-text-secondary) does not guarantee its computed contrast is compliant.
• Check every theme variant (light, dark, high-contrast) independently; a token pairing compliant in light mode can fail in dark mode with no code-level warning.
• Distinguish a documented, intentional design-system escape hatch (a one-off spacing value explicitly allowed by governance docs) from undocumented drift; only the latter is a finding.
• Apply WCAG 1.4.3 (4.5:1 normal text / 3:1 large text) to text-on-background token pairings and WCAG 1.4.11 (3:1) to UI-component and graphical-object contrast (borders, focus indicators, icons) — these are different success criteria with different thresholds; do not conflate them.
• In DTCG-format token files, resolve {group.token} references and $type group-level inheritance before evaluating a value — a token's effective type/value can come from an ancestor group, not the token's own object.
• Require that generated token build output (CSS custom properties, JS token modules) be committed with a reviewable diff against source tokens, not silently regenerated; a build-only change with no source-token diff is itself a governance finding.
• Treat a Storybook @storybook/addon-a11y pass as partial automated evidence only (axe-core-class coverage, not full conformance); it does not substitute for manually verifying contrast math on token pairings the user is asking about.
• Load the visual-regression-storybook-review skill instead of this one when the question is about pixel-diff baseline approval rather than token source/contrast math.
• This is a static-review skill: read and analyze token source files, build configs, and resolved output; do not run builds, mutate token files, or execute pipeline commands.

References

Load these only when needed:

• Token source and pipeline review — use when reviewing DTCG/Style Dictionary token structure, reference resolution, $type inheritance, transform/build config, or hunting for hardcoded-value drift against an existing token set.
• Contrast compliance review — use when computing or verifying resolved contrast ratios for token pairings against WCAG 1.4.3/1.4.11 across theme variants.

Response minimum

Return, at minimum:

• inventory of hardcoded-value findings with file/line and the matching existing token,
• computed contrast ratio per token pairing reviewed, per theme variant, with WCAG pass/fail against the correct success criterion (1.4.3 vs 1.4.11),
• evidence level (computed from provided token values vs inferred, and Context7-grounded vs documentation-based),
• recommended governance mechanism (lint rule/CI check) to prevent recurrence,
• security caveat if the token pipeline pulls from an external API.