design-token-governance-review
Reviews design-token source of truth and build pipelines for hardcoded-value drift and resolved WCAG 1.4.3/1.4.11 contrast compliance across theme variants (light, dark, high-contrast), grounded in the W3C Design Tokens format and current WCAG success criteria.
Install
npx skills add https://github.com/VincentChuWaiChow/vanguard-frontier-agentic/tree/master/skills/frontend/design-token-governance-review
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install vincentchuwaichow-vanguard-frontier-agentic@llmmart
git clone https://github.com/VincentChuWaiChow/vanguard-frontier-agentic.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole vincentchuwaichow/vanguard-frontier-agentic collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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:
- Call
mcp__Context7__resolve-library-idfor the library in scope (Style Dictionary,Storybook) if not already resolved in this session. - Call
mcp__Context7__query-docswith a specific query before asserting version-specific behavior (transform config shape, DTCG$typeinheritance rules, a11y-addon detection coverage, etc.). - Verified library IDs for this skill's scope: Style Dictionary
/style-dictionary/style-dictionary(DTCG format,$value/$type,resolveReferences/getReferences,typeDtcgDelegatefor$typeinheritance); 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). - 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 claimdocumentation-basedrather thanverified. - 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$typegroup-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-a11ypass 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-reviewskill 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,
$typeinheritance, 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.
Files (vanguard-frontier-agentic)
-
references
-
contrast-compliance-review.md 8.1 KB
Loading… -
token-source-and-pipeline-review.md 8.2 KB
Loading…
-
-
metadata.json 1.1 KB
Loading… -
SKILL.md 5.5 KB
--- name: design-token-governance-review description: Reviews design-token source of truth and build pipelines for hardcoded-value drift and resolved WCAG 1.4.3/1.4.11 contrast compliance across theme variants (light, dark, high-contrast), grounded in the W3C Design Tokens format and current WCAG success criteria. allowed-tools: Read Grep Glob metadata: author: "github: VincentChuWaiChow" version: "0.1.0" updated: "2026-07-02" category: compliance --- # 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](references/token-source-and-pipeline-review.md) — 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](references/contrast-compliance-review.md) — 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.