Token Audit

Token audit

A skill for auditing design token architecture across whichever tiers are in use — typically primitives and semantics, with component tokens where the system uses them. Produces a structured report with severity-rated findings and a prioritised remediation list.

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

This skill draws on the tiered token architecture model: primitives encode raw values, semantic tokens encode intent, and — where present — component tokens map intent to specific UI contexts. Not every system uses component tokens, and the absence of a component tier is not a finding. Most token debt accumulates when tiers blur — when component contexts reference primitives directly, when semantic names describe appearance rather than purpose, or when the primitive layer is treated as the only layer.

The audit is not about enforcing a particular naming convention. It's about identifying where the token structure is working against the teams using it.

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 finding severity ratings (e.g. hardcoded_color: critical instead of the default high)
• system.theming — if true, elevate hardcoded colour findings to the severity specified in config
• system.styling — pre-selects the format-specific guidance to apply
• integrations.style_dictionary — parse tokens via Style Dictionary 4 or 5 (see below)
• integrations.figma — Figma variables as an additional token source
• recurring.* — the previous report, for trend comparison (see recurring workflow below)

Auto-pull integrations

Style Dictionary 4 or 5, or Terrazzo (integrations.style_dictionary.enabled: true, or a config in the repo):

• Parse the config at integrations.style_dictionary.config_path
• Extract the full token tree with resolved references and tier structure
• Use this as the primary token source — skip the manual "provide your token files" question
• Run npx style-dictionary build --config [path] into a scratch output directory (or npx terrazzo build) to let the tool resolve every alias before you reason about the tree; its errors are findings with the tool named as the source

Figma variables (integrations.figma.enabled: true):

• Use the Figma MCP server to read variables from the file at integrations.figma.file_key
• Extract variable collections, modes, and resolved values
• Cross-reference Figma variables against code token files to detect mismatches (Figma says --color-primary is #0066CC but the code says #0064CC — that is a finding)

GitHub (integrations.github.enabled: true):

• Pull the token file directly from the default branch if no local file is provided

Step 0: Token discovery

Before asking the user for files, search the codebase for token-like patterns. This step lowers activation energy for teams where tokens exist but are not centralised — the user does not have to know where all their tokens live.

What to search for:

1. CSS custom properties — scan all .css files for :root blocks or -- prefixed properties. Include scoped variants (.dark, [data-theme="..."], .theme-*).
2. SCSS/Sass variables — scan all .scss and .sass files for $-prefixed names. Follow @import and @use chains to find partial files (_colors.scss, _variables.scss, _tokens.scss).
3. JSON/YAML token files — scan for files matching common token naming patterns: tokens.json, tokens.yaml, *.tokens.json, design-tokens/**, src/tokens/**, tokens/**. Also look for DTCG-formatted files containing $type or $value keys.
4. Style Dictionary configs — scan for style-dictionary.config.json, config.json in a style-dictionary/ directory, or .style-dictionary.json.
5. TypeScript/JavaScript token objects — scan .ts and .js files for exports matching common patterns: export const tokens, export const theme, export default { color, as const typed objects with token-like key hierarchies.
6. Tailwind configurations — scan for tailwind.config.js, tailwind.config.ts, or tailwind.config.mjs and extract the theme and extend blocks.
7. Figma Tokens / Tokens Studio — scan for tokens.json in a .tokens or tokens directory, or files exported from Tokens Studio.

How to search:

Use file system access (glob patterns, file reads) to scan the project. If GitHub integration is configured and there's no local clone, use gh api search/code only to locate candidate files, then read them. If Figma integration is configured, pull Figma variables as an additional token source.

Prioritise by specificity: a dedicated tokens/ directory is more reliable than scattered CSS files. A Style Dictionary config is more reliable than raw JSON. But collect everything — fragmented token sources are themselves a finding.

Discovery output:

Produce a brief inventory before continuing:

Token sources found:
- src/tokens/colors.json (94 tokens, JSON, likely primitives)
- src/tokens/semantic.json (67 tokens, JSON, likely semantic tier)
- src/styles/variables.scss (43 variables, SCSS)
- tailwind.config.ts (theme block with 28 custom values)
Total: ~232 token-like declarations across 4 sources

If discovery finds nothing, proceed to Step 1 and ask the user for manual input. If discovery finds scattered sources across multiple formats, flag this as a finding: "Tokens exist in [N] different formats across [M] files. This fragmentation is structural debt — consider centralising to a single source of truth."

Present the discovered sources to the user and ask: "I found these token sources. Should I audit all of them, or focus on specific files?" This gives the user control without requiring them to have assembled the inventory manually.

Step 0b: Orphan detection checkpoint

Before running the full audit, do one pass to identify token usage. This is the only orphan pass — Step 3c reuses its results.

1. Declared tokens — count every token found in Step 0 (or provided manually in Step 1).
2. Referenced tokens — search for references to each declared token, both from other tokens and from components in this repo. For CSS custom properties, search for var(--token-name). For SCSS variables, search for $variable-name outside their declaration files. For JSON/DTCG tokens, search for alias references ({token.path}). For TypeScript objects, search for import and access patterns (tokens.color.primary, theme.spacing.md).
3. Positive control — before trusting the result, pick one token you know is used and confirm each search pattern finds it. If a pattern finds nothing for a known-used token, the pattern doesn't fit this codebase; fix it or report orphans for that format as unconfirmed.
4. Orphan candidates — tokens not referenced by another token or by any component in the scanned repo.

In a design system repo, most tokens are consumed by product repos that weren't scanned. An orphan here means "no in-repo consumer", not "unused". Report orphans as unconfirmed for external consumers unless the user has given you access to the consuming repos or usage data.

Produce a checkpoint summary (figures illustrative):

Orphan detection:
- 232 tokens declared
- 189 tokens referenced in-repo (at least once)
- 43 orphan candidates (no reference from another token or an in-repo component)
  Top candidates: --color-legacy-teal, --spacing-xl-deprecated, $font-heading-alt (3 more)
  Positive control: --color-action-primary found in 14 files by the same patterns
  Not checked: consuming product repos

This tells the user the scale of the question before the full audit begins. Confirmed orphans are maintenance burden without value — they clutter autocomplete, confuse new team members, and inflate the token count. Include orphan candidates as findings in the main audit (category: Coverage, severity: Low unless count exceeds 20% of total, then Medium), and say which consumers were checked.

If the orphan count is high (>30% of total tokens), flag this prominently: "Over a third of declared tokens are unreferenced. Before auditing token quality, consider whether a cleanup pass would simplify the architecture."

Step 1: Gather the token source

If Step 0 discovered token sources, use them as the primary input — skip the manual question unless the user wants to override. If Step 0 found nothing (or was skipped because no codebase access was available), ask for the token source. Acceptable inputs:

• A JSON, YAML, or DTCG-formatted token file
• A Figma file or Tokens Studio export
• A pasted list of token names and values
• A Style Dictionary configuration
• A CSS file with custom properties (e.g. :root { --color-primary: #5e4890; } or theme variants scoped to .dark { }, [data-theme="dark"], or similar selectors)
• An SCSS/Sass file with variables (e.g. $color-primary: #5e4890;)
• A TypeScript or JavaScript token object (e.g. export const tokens = { color: { ... } })
• A Tailwind CSS configuration file (tailwind.config.js or tailwind.config.ts) with a theme or extend block defining custom tokens

Format-specific guidance:

For CSS custom properties: treat each -- prefixed property as a token. Infer tier from naming patterns — properties like --color-blue-500 are likely primitives, --color-action-primary are semantic, --button-background-default are component-tier. Where properties are scoped to selectors (:root, .dark, [data-theme="dark"]), treat each scope as a theme variant. References between CSS custom properties using var(--other-token) indicate tier relationships — map these the same way as JSON token references.

For SCSS variables: treat each $ prefixed variable as a token. SCSS variables that reference other variables (e.g. $color-primary: $blue-500) indicate tier relationships. If variables are split across partials (_colors.scss, _spacing.scss), the file organisation may signal tier structure.

For TypeScript/JavaScript objects: treat the exported object's key hierarchy as the token structure. Nested objects map to tiers the same way JSON tokens do. For Emotion or styled-components themes, the theme object is the token source. Common patterns include: flat exports (export const backgroundColor = { scene: '#FFF', primary: '#206EF6' }), as const typed objects (const tokens = { ... } as const), aggregated barrel exports (export const tokens = { breakpoint, fontSize, spacing }), and theme-to-CSS-variable mapping functions (mapThemeToVars()). Helper functions like theme.spacing(4) or theme.colors.primary that resolve to token values are valid token references.

For Tailwind configurations: the theme block defines primitives, extend adds semantic overrides. Tailwind utility classes that reference custom tokens (e.g. bg-primary, text-color-content-default) are token references, not hardcoded values. Arbitrary values in square brackets (e.g. h-[12px], bg-[#ff0000]) are the actual hardcoded violations.

If the person pastes raw token names without values, proceed with a naming and structure audit only. Note in the output that value analysis was not possible.

Step 2: Map the tier structure

Identify which tiers are present:

Primitive tier — raw values, no semantic meaning. Examples: color.blue.500, spacing.4, font-size.base

Semantic tier — intent-driven references. Examples: color.action.primary, spacing.component.gap, text.body.size

Component tier — scoped to a specific component context. Examples: button.background.default, card.padding.inner

Flag a missing primitive or semantic tier. A system with only primitives has no semantic contract. A system with only semantic tokens has no single source of truth for raw values. Both are structural problems worth naming. A missing component tier is not a finding — see the token-architecture note.

Step 3: Run the audit checks

For each check, produce a PASS, WARN, or FAIL rating with specific examples. Every finding carries evidence: the token path and the file and line where it is defined (tokens/component.tokens.json:9, src/styles/tokens.css:17).

Severity rubric (the severity.* config keys override these defaults):

• 🔴 Critical — a token file that isn't the source of truth it claims to be (generated output has drifted from it); tier leakage or a raw value at the semantic or component tier in a system that ships more than one theme, because the theme switch silently misses it
• 🟠 High — tier leakage or a raw value at the semantic or component tier in a single-theme system; an upward reference (semantic → component); a semantic token that names an appearance (color.semantic.blue)
• 🟡 Medium — convention inconsistency within a tier; a missing interaction state for a role the components already use; duplicate raw values with no documented distinction; orphan candidates above the 20% threshold
• ⚪ Low — ambiguity flags, platform suffixes, orphan candidates below the threshold, DTCG migration signals

Naming checks

Descriptive vs prescriptive naming Semantic tokens should describe purpose, not appearance.

• FAIL example: color.semantic.blue — describes colour, not intent
• PASS example: color.action.primary — describes role

Tier leakage Component tokens should reference semantic tokens, not primitives.

• FAIL example: button.background.default: {color.blue.500} — skips the semantic tier
• PASS example: button.background.default: {color.action.primary} — correct reference chain

Ambiguity flags Token names that could mean multiple things or require context to interpret (the token-architecture note has the full rule and its exceptions):

• Examples to flag: normal, alt, variant, misc, other, and default or base when they are the entire role (color.default)
• Not flagged: default/base as a state or level segment beside a role (color.action.default, color.surface.base), and t-shirt or numeric scale steps (spacing.sm, radius.lg)
• Each flagged token should include a suggested rename

Convention consistency (this skill owns token naming; naming-audit covers components and patterns) Within each tier, identify the dominant casing, separator and segment order, and flag the tokens that break from it: color.blue-500 beside color.blue.500, hover/active beside hover/pressed, button.background-hover beside button.background.hover. Report the dominant convention in the findings so the team can confirm it's the intended one.

Platform suffix abuse Token names that encode platform specifics in the name rather than in the transformation layer:

• Examples: color.primary.ios, spacing.mobile.gap — these belong in transforms, not names

Value checks (if values are available)

Hardcoded values at semantic or component tier Any semantic or component token with a raw value rather than a reference is structural debt.

• Flag each occurrence with: token name, raw value found, and suggested reference target

Duplicate raw values without token aliases Identical raw values appearing at the primitive tier under different names without explanation.

• Flag potential duplicates and ask whether the distinction is intentional

Out-of-tier references Any token referencing a token from a higher-specificity tier.

• Example: a semantic token referencing a component token — this inverts the dependency direction