/token-audit

name: token-audit
description: "Audit a design system's token definitions for naming violations, missing semantic tiers, and structural debt. This audits how tokens are defined and organised, NOT how they are consumed in code. Trigger when someone says: audit my tokens, token naming review, are my tokens consistent, token health check, review my token architecture, or anything involving token quality or structure. Do NOT trigger for checking whether code uses tokens correctly — use token-compliance for that."
references:
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/output-discipline.md

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.

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

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

• `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` — if enabled, auto-parse tokens via Style Dictionary v4 (see auto-pull below)
• `integrations.figma` — if enabled, pull Figma variables as an additional token source
• `recurring.*` — if this is a recurring run, load the previous report for trend comparison (see recurring workflow below)

If no config file exists, proceed with defaults and manual input as before.

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically before asking the user for manual input:

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

• 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
• If Style Dictionary v4 is installed, run `npx style-dictionary build --config [path] --dry-run` to validate references without writing output

**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`):

• Search the repository for hardcoded colour/spacing values using `gh api search/code` to quantify the scope of violations before the detailed audit
• Pull the token file directly from the default branch if no local file is provided

If an integration is configured but fails (e.g. auth error, rate limit), log the failure and fall back to manual input. Never block the audit because an integration is unavailable.

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, use `gh api search/code` as a secondary source. 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