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.

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