/token-compliance

name: token-compliance
description: "Find hardcoded colour, spacing and type values and wrong-tier token references in consuming code. Trigger: find hardcoded values, any hex in the code, are we using tokens correctly, token compliance. Do NOT use for token definitions — token-audit; token file format — schema-validator."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*), Bash(grep:*), Bash(rg:*), Bash(git log:*), Bash(git blame:*)
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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `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` — the repo to check out and search (see below)
• `integrations.style_dictionary` — the parsed token tree, as the reference for what tokens exist and their correct tiers
• `gates.*` — when running as part of `component-to-release`, which violations block release

Auto-pull integrations

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

• Search a local checkout of `integrations.github.repo`, not GitHub's code search API (see the note's GitHub caution): code search drops `#`, so a colour search there returns nothing and reads as clean.
• Broad colour search before the manual checks:

  rg -n --glob '*.{css,scss,less,ts,tsx,js,jsx,vue}' --glob '!**/tokens/**' --glob '!**/{dist,node_modules}/**' \
    '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\('

Without ripgrep: `grep -rnE --include='*.css' --include='*.scss' --include='*.tsx' [etc.] --exclude-dir=tokens --exclude-dir=node_modules --exclude-dir=dist '<same pattern>' .` Adjust the globs to where tokens actually live. Expect some false positives (CSS ID selectors such as `#add` or `#faded`) and weed them out by hand.

• **Positive control:** run the same pattern over the token source files. It must find hits there before a zero anywhere else is reported as zero. If it finds nothing in the token source either, the pattern doesn't fit this codebase — say the result is unconfirmed.
• 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" (illustrative figures) is a useful framing for the report summary

**Style Dictionary (4 or 5)** (`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

Step 0: 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)`