Token Naming Audit

Audit your design token names against naming conventions and flag inconsistencies, typos, and structural issues.

All Prompts

When to Use

  • After exporting tokens from Figma or Tokens Studio
  • Before publishing a new token set to code
  • When merging token contributions from multiple designers
  • During onboarding to check if new tokens follow team conventions

The Prompt

Audit these design token names against best practices and flag issues.

Check for:
1. **Naming convention** — Are all tokens using the same format? (kebab-case, camelCase, dot.notation, slash/notation). Flag any that break the pattern.
2. **Tier structure** — Do names follow a clear tier: primitive > semantic > component? Flag tokens that skip tiers (e.g., a component token referencing a raw hex).
3. **Predictability** — Could a developer guess the token name without looking it up? Flag cryptic or ambiguous names.
4. **Redundancy** — Are there duplicate or near-duplicate tokens? (e.g., color-bg-primary and color-background-primary)
5. **Completeness** — Are related states missing? (e.g., button-bg-hover exists but button-bg-pressed does not)

Format:
- Group issues by severity: Errors, Warnings, Suggestions
- For each issue, show the token name, what's wrong, and a suggested fix

Here are my token names:
[paste your token names here, one per line]

Example Output

## Errors (3)

1. `clr-bg-primary` — Inconsistent abbreviation. Other tokens use `color`, not `clr`.
   Fix: Rename to `color-bg-primary`

2. `button.background.Primary` — Mixed casing. All other tokens use lowercase.
   Fix: Rename to `button.background.primary`

3. `spacing-4px` — Includes unit in name. Token values should be unit-agnostic.
   Fix: Rename to `spacing-4`

## Warnings (2)

1. `color-bg-primary` and `color-background-primary` — Likely duplicates.
   Fix: Keep one, alias the other, then deprecate.

2. `button-bg-hover` exists but `button-bg-active` and `button-bg-disabled` are missing.
   Fix: Add the missing state tokens.

## Suggestions (1)

1. Consider grouping by component: `button-background-*` instead of `button-bg-*`
   to match the verbose style used elsewhere in this set.