token-compliance

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:

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."
Violation age estimation. Use git log -S'<value>' -- <file> (the commit that introduced the value) or git blame -w -C to estimate when violations were introduced. Plain git blame and file modification dates point at the last reformat or file move, not the original author — check for bulk formatting commits before trusting a date. 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

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 (illustrative):
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)

Intentional override detection. Not every hardcoded value is a violation:
- Values with comments like /* override */ or /* intentional */: list them separately as "Marked intentional in code", with the comment, so the team can confirm.
- Values that match no token are still violations, logged once in the violation log with their severity like any other. In the Correct token column, write "none — nearest: <token>" and mark the row off-system in Notes: the value may be a one-off design requirement or a gap in the scale, and the team should decide which, not the tool.

Step 1: Define the scope and access

Ask for or confirm (skip questions already answered by auto-pull):

What is being assessed? (Full codebase, specific product area, specific component set)
Access to the implementation: codebase, Figma file, Storybook, or described properties
The token system in use: what tokens exist, what tiers are defined, and how tokens are consumed in code
The styling approach: CSS custom properties (var(--token)), SCSS variables ($token), Tailwind utility classes, CSS-in-JS theme objects, or a mix
Any known compliance hotspots the check should prioritise
Whether this is a baseline audit or a follow-up to a previous check
Codebase age and migration history: When were tokens introduced? Has there been a previous migration? Are there known legacy areas? (This determines whether the messy codebase protocol applies.)
Context the code can't show (used only by the severity adjustments below): which components sit on critical user paths, and which are scheduled for deprecation. Ask once; if there's no answer, apply no adjustment and say so under Scope. Never infer a critical path from a directory name.

If no code is in reach (no path, no local checkout, no pasted files), stop and ask for one; a compliance check on described code produces guesses. The design system's own component code counts as consuming code: when the target is the system repo, say so under Scope, because the token source files are excluded and the components are what's being checked.

Styling approach matters for how violations are detected:

CSS custom properties: Token references look like var(--color-action-primary). Hardcoded values are raw hex/rgb/px values outside of var().
SCSS variables: Token references look like $color-action-primary or map-get($tokens, 'action-primary'). Hardcoded values are raw literals not using $ variables.
Tailwind utility classes: Token references are utility classes that map to the design system's Tailwind config (e.g. bg-primary, text-color-content-default, gap-4). These are NOT hardcoded values — they are token references expressed as utility classes. Hardcoded values in Tailwind are arbitrary value brackets: h-[12px], bg-[#ff0000], p-[7px]. Flag arbitrary values as violations; do not flag standard utility classes that resolve to configured tokens.
CSS-in-JS (Emotion, styled-components): Token references look like theme.colors.action.primary or tokens.spacing[4]. Hardcoded values are raw literals in style objects.

Framework-specific detection notes:

If using Vue SFC: Token violations appear inside <style lang="scss" scoped> blocks. Look for raw px values where $token variables or var(--token) should be used. Vue's scoped styles may also contain token references via v-bind() for dynamic CSS — these are valid token usage if bound to a token-backed prop.
If using Twig/Fractal: Token violations appear as inline style="" attributes in templates (e.g. style="background-color: {{ item.color }}"), hardcoded hex values in SVG fill/stroke attributes, and raw pixel values in HTML dimension attributes. Twig components typically reference tokens via BEM utility classes — audit the SCSS that backs those classes, not just the template.
If using Emotion/styled-components: helper calls such as theme.spacing(4) are valid token usage — find the codebase's helpers first so they aren't flagged. Template-literal CSS (css\padding: 16px``) is where raw values hide from object-syntax searches; search inside the backticks too.
If using React Native: styles are unitless numbers (padding: 16, fontSize: 14) in StyleSheet.create or inline style. A numeric literal there is the hardcoded form; token references look like tokens.spacing.md or a theme hook.

Step 2: Run the compliance checks

Excluded from all checks: token source files, generated CSS (build output), SVG assets, and stories/test fixtures. Say in the Scope block which paths were excluded.

Base severity (before the context adjustments in Step 3; severity.* config keys override):

🔴 Critical — a hardcoded colour, or a wrong-tier colour reference, in a system that ships more than one theme: it won't switch
🟠 High — a hardcoded colour or wrong-tier reference in a single-theme system; hardcoded typography on a text role that has a token
🟡 Medium — hardcoded spacing where a scale token matches the value; the same role implemented with different tokens across sibling components
⚪ Low — fixed dimensions where intent is ambiguous (border widths, touch targets); off-system values awaiting a design decision

Every violation's Location is a file and line. A finding without one is not logged.

Exempt values, everywhere: transparent, currentColor, inherit, none, and CSS-wide keywords (initial, unset, revert). These are never violations.

Check 1: Hardcoded colour values

Find and flag all colour values that are not token references:

Hex values (e.g. #0066CC, #FFF)
RGB and RGBA values (e.g. rgb(0, 102, 204), rgba(0,0,0,0.5))
HSL values
Named colour values (e.g. red, white) — the exempt keywords above excepted

For each finding: file reference or context, the raw value found, and the token it should reference.

If the assessment is conducted against a design file rather than code: look for any colour styles applied as raw values rather than library styles.

Check 2: Hardcoded spacing values

Find and flag spacing values that are not token references:

Raw pixel values in padding, margin, gap, width, or height properties (e.g. padding: 16px, gap: 8px)
Rem values that correspond to spacing scale values (e.g. 1rem when there is a spacing token for 16px/1rem)

Note: not all pixel values are compliance violations. Border widths, minimum touch targets, and other fixed dimensions may be intentionally hardcoded. Where intent is ambiguous, log it as ⚪ Low and say why.

Check 3: Hardcoded typography values

Find and flag typography values that are not token references:

Raw font-size values (e.g. font-size: 14px)
Raw font-weight values (e.g. font-weight: 700)
Raw line-height values (e.g. line-height: 1.5)
Raw font-family values (e.g. font-family: 'Inter', sans-serif)
Raw letter-spacing values

Check 4: Wrong-tier token references

Find and flag component-level code that references primitive tokens directly rather than routing through semantic tokens:

Violation example: background-color: var(--color-blue-500) in a button implementation Should be: background-color: var(--color-action-primary) → var(--color-blue-500)

This is the subtlest compliance violation and the most architecturally damaging. It appears correct on the surface — the right colour is being used — but it breaks the semantic contract and means a semantic change (e.g. changing what "action primary" means) does not propagate to the component.

For each finding: the token being referenced, the semantic token that should be used instead, and the context.

A component token that is defined against a primitive in the token files (card.border: {color.gray.200}) is a definition problem, and token-audit's tier-leakage check owns it. Log a wrong-tier reference here only where it appears in consuming code (var(--color-gray-200) in a component stylesheet). If you notice the definition problem on the way, name it once under Scope as handed to token-audit; don't give it a TC- id.

Check 5: Inconsistent token application

Find and flag cases where the same visual property is implemented differently across components or contexts:

The same semantic role implemented with different tokens in different components (e.g. color.action.primary in some places, color.brand.500 in others, for the same role)
The same spacing context using different spacing tokens across similar components
Interactive states (hover, focus, active) implemented differently across components that should share the same token

These violations are often invisible in a per-component review but surface clearly when components are compared.

Step 3: Produce the violation report

Token compliance report

Open with a headline sentence that tells the reader the overall state and where to focus.

Date: [date] Scope: [what was assessed] Assessment method: [codebase / design file / Storybook / described properties]

Summary

Overall compliance picture. What is the most significant finding? Is the violation pattern concentrated or distributed?

Violation counts

Check	Violations found	🔴 Critical	🟠 High	🟡 Medium	⚪ Low
Hardcoded colour values
Hardcoded spacing values
Hardcoded typography values
Wrong-tier token references
Inconsistent token application
Total

Violation log

Group by check type. For each violation:

ID	Check	Severity	Location	Raw value / incorrect reference	Correct token	Notes
TC-01	Colour	🔴 Critical / 🟠 High / 🟡 Medium / ⚪ Low	[file path or context]	`#0066CC`	`var(--color-action-primary)`

Each value appears once. Off-system values (no matching token) stay in this table with their severity; put "none — nearest: <token>" in the Correct token column and "off-system" in Notes. Don't repeat them in a separate list.

Excluded as structural: one line listing the values left out and why — e.g. max-width: 960px (layout container), border: 1px solid (divider), test-wrapper padding. Don't log these as violations.

Context-aware violation severity

Not all violations carry equal weight. Adjust severity based on component importance. This is the feature that distinguishes a compliance check from a simple grep — without context-aware severity, every violation looks the same.

Elevated severity (upgrade one level):

Violations in components on critical user paths (checkout, authentication, primary navigation)
Violations in components with high fan-in (from .ai/index/ if codebase-index has run; otherwise skip this adjustment and say so)
Violations in components that are theming-sensitive (brand-facing surfaces, dark mode targets)
Violations in post-token-era code (introduced after the token system was established — these are active compliance failures, not inherited debt)

Standard severity:

Violations in general-purpose components with moderate usage
Violations in migration-era code (partially migrated — compliance improvement is in progress)

Reduced severity (downgrade one level):

Violations in internal/utility components not directly user-facing
Violations in components that are already scheduled for deprecation
Violations in legacy code areas with a known migration timeline
Violations in pre-token-era code (introduced before the token system existed — these are expected debt)
Layout utilities that use raw pixel values for structural concerns unrelated to design tokens (e.g., max-width: 1200px for a container, height: 1px for a divider) — not violations; list them on the "Excluded as structural" line

Apply the adjustment after the initial severity assignment. Note the adjustment and reason in the violation log — "Severity upgraded from Medium to High: component is on the checkout critical path."

Pattern analysis

Step back from individual violations and describe the pattern:

Are violations concentrated in specific files, components, or product areas?
Are there recurring raw values that appear frequently and clearly correspond to a specific token?
Is there a particular check type that dominates the violation count?

Pattern analysis turns a violation log into actionable intelligence. "Hardcoded spacing violations are concentrated in the legacy product area — likely pre-dates the token system" leads to a different response than "hardcoded spacing violations are evenly distributed and increasing — the token system is not being adopted."

Remediation priority

Immediate: Wrong-tier token references and any hardcoded values that would break under theming or brand change. These have architectural impact.

Planned: Consistent hardcoded values that correspond clearly to existing tokens. These can be resolved in a systematic pass.

Review: Ambiguous values (raw percentages, context-dependent px values, intentional overrides). These need human judgment before remediation.

Remediation approach

Recommend the most efficient approach for the volume and pattern of violations found:

If violations are high-volume and repetitive: a migration script or codemod is more efficient than manual correction
If violations are concentrated in a specific area: a focused refactoring sprint on that area
If violations are sparse and distributed: add to the team's ongoing code review criteria and address as work touches each area
If wrong-tier references are significant: a token architecture review may be warranted before remediation to ensure the semantic tier is complete enough to reference correctly
Whenever violations are post-token era, the standing fix is a lint rule so the count stops growing while the cleanup happens: for CSS, SCSS and CSS-in-JS strings, Stylelint's stylelint-declaration-strict-value on the token-backed properties with the token pattern as ignoreValues; for Tailwind, eslint-plugin-tailwindcss no-arbitrary-value; for React Native, a custom ESLint rule on numeric style literals. governance-encoder writes the config

Scope

Inspected: [directories and file types searched]
Not inspected: [excluded paths — token source, generated CSS, SVG assets, stories/fixtures — and anything out of reach]
How "none found" was checked: [for any check reporting zero, the positive control: the same pattern found hits in the token source]
Assumptions: [e.g. the token tree used as the reference is current]

If any of these values are deliberate (a one-off the design called for, or a legacy area you've accepted), tell me and I'll exclude them in future runs.

Token definitions are out of scope for this skill: for DTCG format and alias integrity use schema-validator; for tier structure and cross-system consistency use token-audit.

Quality checks

All five checks are covered
Wrong-tier references are checked separately from hardcoded values — they are a different category of violation
Pattern analysis section exists and describes the distribution of violations, not just the total
Remediation priority distinguishes between architectural violations and surface-level ones
The report is specific enough to act on: file references or context for each violation, not just "hardcoded values found"
Any zero count is backed by a positive control against the token source
Severity adjustments cite the fact they rest on (a stated critical path, an index fan-in count, a git era); none is inferred from a name
Exempt keywords and excluded paths are never logged as violations
The report ends with the Scope block and the invitation to flag deliberate values