/token-compliance

name: token-compliance
description: "Check a codebase or implementation for token compliance — finding hardcoded values, wrong-tier token references, and inconsistent token application in consuming code. This checks how tokens are used in code, NOT how the tokens themselves are defined or structured. Trigger when someone says: are we using tokens correctly, find hardcoded values, token compliance check, find raw values, token misuse, are there any hex values in the code, checking token usage, or anything about whether tokens are being used consistently and correctly. Do NOT trigger for auditing the token definitions themselves — use token-audit for that."
references:
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/output-discipline.md

Token compliance

A skill for identifying token compliance violations in a codebase or implementation: hardcoded raw values where tokens should be used, wrong-tier token references, and inconsistent token application. Produces a violation report with file references and remediation guidance.

Context

Token compliance problems compound quietly. A single hardcoded hex value does not break anything. Two hundred of them, distributed across a codebase by dozens of contributors over two years, mean that a brand refresh or a dark mode implementation becomes a manual find-and-replace operation through thousands of files rather than a token update.

The compliance check exists to catch violations before they accumulate, and to understand the pattern of violations when they already have. The pattern matters: if hardcoded values are concentrated in one product area or one team's contribution, the response is different than if they are evenly distributed.

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `severity.*` — overrides for violation severity. Especially: `hardcoded_color`, `wrong_tier_reference`, `tier_leakage`
• `system.theming` — if true, elevate hardcoded colour violations to the configured severity (typically `critical`)
• `system.styling` — pre-selects the detection approach
• `integrations.github` — if enabled, auto-search for violations across the repo (see below)
• `integrations.style_dictionary` — if enabled, use the parsed token tree as the reference for what tokens exist and their correct tiers
• `gates.*` — if running as part of `component-to-release`, these determine which violations block release

Auto-pull integrations

**GitHub** (`integrations.github.enabled: true`):

• Before running the manual compliance checks, do a broad search of `integrations.github.repo` for hardcoded values:
• `gh api search/code -q "repo:[repo] language:css #[0-9a-fA-F]{6}"` — hex colours in CSS
• `gh api search/code -q "repo:[repo] language:scss #[0-9a-fA-F]{6}"` — hex colours in SCSS
• Search for `px` values in styling files as a spacing compliance signal
• Use the results to quantify scope before the detailed audit — "approximately 340 hardcoded hex values across 47 files" is a useful framing for the report summary

**Style Dictionary v4** (`integrations.style_dictionary.enabled: true`):

• Parse the token tree to build a complete map of available tokens per tier
• Use this as the authoritative "what token should this reference?" lookup when flagging violations
• If a hardcoded value exactly matches a known token's resolved value, include the token name in the remediation guidance automatically

**Figma MCP** (`integrations.figma.enabled: true`):

• Pull Figma variable definitions as a cross-reference — if a colour is defined as a Figma variable but hardcoded in code, that is a compliance violation with a known correct token

If an integration fails, log it and proceed with manual input.

Step 0b: Messy codebase protocol

Token compliance has the most value on messy codebases — the ones with years of accumulated hardcoded values, inconsistent styling approaches, and multiple token migration attempts. For these codebases, apply the extended detection protocol:

**Indicators of a messy codebase:**

• Multiple styling approaches in the same project (CSS custom properties AND SCSS variables AND inline styles)
• Token files exist but significant portions of the codebase pre-date them
• Multiple naming conventions visible in style files (camelCase, kebab-case, BEM — mixed)
• Legacy colour palettes coexisting with current tokens
• Inline `style=` attributes in component templates

**Extended detection for messy codebases:**

1. **Legacy value mapping.** Before flagging violations, build a map of legacy values to current tokens. Many hardcoded values in legacy code were correct at the time they were written — they pre-date the token system. Map `#0066CC` to `var(--color-action-primary)` so remediation guidance is specific, not just "use a token."

2. **Violation age estimation.** Use git blame or file modification dates to estimate when violations were introduced. Group violations by era:

• **Pre-token era** (before the token system existed) — these are expected debt, not compliance failures
• **Migration era** (during token adoption) — partially migrated files where some values use tokens and others do not
• **Post-token era** (after tokens were established) — these are genuine compliance failures and should be higher severity

3. **Hotspot detection.** Identify the 5–10 files with the most violations. These are the high-value remediation targets — fixing them reduces the violation count disproportionately. Present as:

   Compliance hotspots:
   1. src/legacy/checkout/styles.scss — 47 hardcoded values (pre-token era)
   2. src/components/Card/Card.styles.ts — 23 hardcoded values (migration era)
   3. src/pages/Dashboard/index.tsx — 19 inline styles (post-token era — PRIORITY)

4. **Intentional override detection.** Not every hardcoded value is a violation. Look for patterns that indicate intentional overrides:

• Comments