Run a Token Naming Audit with AI

1. 01

   Scan

   Find every token name in your file

2. 02

   Flag

   Mark inconsistent casing, duplicates, raw values

3. 03

   Rename

   Map old names to new convention

4. 04

   Verify

   Confirm zero broken references

I once found a token file with primaryBlue, blue-primary, color.primary.blue, and colorBluePrimary all pointing to the same hex value. Four names. One color. Three confused engineers. The file had 240 tokens, and nobody could tell me which naming convention was “the right one” because there were at least five conventions mixed together.

Token naming audits are brutal to do by hand. You open a JSON file with 300 entries, squint at the names, try to spot patterns, lose your place, start over. A repo-aware AI tool can read the entire file in seconds and give you a categorized report of every inconsistency. This workflow takes 15 minutes.

---

---

Step 1: Run the Initial Scan

Navigate to your project and open your AI assistant. In Claude Code, that means:

cd ~/your-design-system
claude

Ask the assistant to analyze your token naming:

Read all token files in the tokens/ directory. Analyze every token name and report:

1. **Naming conventions found**: List each distinct pattern you detect (e.g., camelCase, kebab-case, dot.notation, slash/notation) with example token names for each.
2. **Inconsistencies**: Token names that don't follow the dominant convention. List them grouped by type of issue.
3. **Duplicate values**: Different token names that resolve to the same value.
4. **Naming depth**: Tokens with unusually shallow names (e.g., "blue") or unusually deep names (e.g., "color.background.primary.hover.active.disabled").
5. **Category coverage**: Which categories exist (color, spacing, typography, elevation, etc.) and how many tokens are in each.

Format the output as a markdown report.

Claude will produce something like this:

## Token Naming Audit Report

### Conventions Detected
- **dot.notation** (68% of tokens): color.background.primary, spacing.md
- **camelCase** (22% of tokens): primaryBlue, borderRadiusLg
- **kebab-case** (10% of tokens): font-size-sm, line-height-base

### Inconsistencies (47 tokens)
| Token Name | Expected | Issue |
|-----------|----------|-------|
| primaryBlue | color.primary.blue | camelCase in dot.notation file |
| font-size-sm | typography.fontSize.sm | kebab-case in dot.notation file |
| colorBG | color.background | Abbreviation |
| color.bg.primary | color.background.primary | Inconsistent abbreviation |

Why this step matters

You cannot fix what you cannot see. Most token files accumulate inconsistencies over months as different people add tokens using different conventions. The audit makes every inconsistency visible in one report, ranked by severity.

---

Step 2: Generate a Naming Convention

Now that you know what is broken, ask Claude to propose a fix:

Based on the audit results, propose a token naming convention for our design system. Requirements:

1. Use the dominant convention already in use (to minimize renaming)
2. Define a clear hierarchy: category.property.variant.state
3. Include rules for:
   - Color tokens (primitives vs. semantic vs. component)
   - Spacing tokens
   - Typography tokens (size, weight, line-height, font-family)
   - Border tokens (width, radius, color)
   - Shadow/elevation tokens
   - Motion/animation tokens
4. Show 3 examples for each category
5. List forbidden patterns (abbreviations, redundant prefixes, etc.)

Format this as a reference document I can share with my team.

Claude will generate a structured convention document:

## Token Naming Convention

### Structure
[category].[property].[variant].[state]

### Color Tokens
Primitives: color.palette.blue.500
Semantic:   color.background.primary
Component:  color.button.background.hover

### Rules
- Always use dot.notation
- No abbreviations (use "background" not "bg")
- No redundant prefixes (use "color.primary" not "color.color.primary")
- States are always the last segment: .hover, .active, .disabled, .focus
- Primitives use scale numbers: .100, .200, .300 through .900

Why this step matters

A naming convention is only useful if it builds on what you already have. Starting from scratch means renaming every token, which breaks every consumer. By analyzing your dominant convention first, Claude proposes rules that require the least amount of change.

---

Step 3: Generate a Rename Map

With the convention defined, ask Claude to create a concrete rename plan:

Generate a rename map for all inconsistent tokens. For each token that violates the naming convention, show:

1. Current name
2. Proposed name
3. File location
4. Risk level (high = used in many places, medium = used in a few places, low = used once or not referenced)

Format as a CSV-compatible table so I can import it into a spreadsheet.

Do NOT rename tokens that already follow the convention. Only include tokens that need to change.

The output will look like:

current_name,proposed_name,file,risk
primaryBlue,color.palette.blue.500,tokens/colors.json,high
font-size-sm,typography.fontSize.sm,tokens/typography.json,medium
colorBG,color.background.default,tokens/semantic.json,high
borderRadiusLg,border.radius.lg,tokens/borders.json,low

Copy this into a spreadsheet. Review each rename. Mark which ones you approve and which need discussion with the team.

Why this step matters

Renaming tokens is a breaking change. Every rename needs to be deliberate. The CSV format lets you review, filter, and prioritize. High-risk renames (tokens used across many files) need a migration plan. Low-risk renames can happen immediately.

---

Step 4: Apply the Fixes

For approved renames, ask Claude to make the changes:

Apply these token renames in the tokens/ directory:

- primaryBlue → color.palette.blue.500
- colorBG → color.background.default
- borderRadiusLg → border.radius.lg

For each rename:
1. Update the token name in the source JSON file
2. Update all references to this token in other token files (aliases)
3. List any files outside the tokens/ directory that reference the old name (so I can coordinate with engineers)

Do not modify files outside the tokens/ directory. Just list them.

After Claude applies the changes, run the audit again:

Run the same token naming audit from Step 1. Show me the updated report. How many inconsistencies remain?

Why this step matters

The second audit is your verification step. You should see the inconsistency count drop significantly. Any remaining issues are either tokens you deliberately skipped or new issues Claude found in the second pass. Repeat until the report is clean.

---

What You Get

After completing this workflow, you have:

• A complete audit of every naming inconsistency in your token files
• A documented naming convention based on your existing patterns
• A rename map you can review and approve before making changes
• Clean, consistent token names across your entire system
• A repeatable process you can run after every sprint to catch new inconsistencies

Common Pitfalls

• Renaming everything at once. Start with low-risk tokens (unused or referenced once). Build confidence before tackling high-risk renames that affect multiple consumers.
• Not communicating renames to engineers. Every token rename is a breaking change for code consumers. Share the rename map with engineering before applying changes. Better yet, coordinate a migration with deprecation warnings.
• Ignoring semantic meaning. A token called color.blue.500 is a primitive. A token called color.primary is semantic. Do not rename semantics to look like primitives or vice versa. The naming convention should reflect the token’s role in the system.

Exercise

Run the audit on your real token file today

20 min

1. Point your AI tool at your tokens and get the first report

   Navigate into your design system repo and start Claude Code. Paste the prompt above. Read the report end to end without trying to fix anything yet.

   • One dominant naming convention is named with its share of tokens
   • Every inconsistency is quoted by exact token name, not summarized
   • At least one duplicate-value pair shows up (almost every real file has these)
   • The “most broken” category is clearly called out so you know where to start

   Read every file inside tokens/. Analyze every token name and report:
   
   1. Naming conventions found (camelCase, kebab-case, dot notation, slash notation) with counts and examples.
   2. Inconsistencies: tokens that do not follow the dominant convention, grouped by type of issue.
   3. Duplicate values: different names that resolve to the same hex or px value.
   4. Unusual depth: names with one segment or more than four segments.
   5. Category coverage: how many tokens per category (color, spacing, typography, radius, elevation, motion).
   
   Format as a markdown report. Rank issues so I know where to start.

   Copy prompt

2. Approve a rename map and verify with a second audit

   Ask Claude to propose a rename map as CSV (current name, proposed name, file, risk level). Review the rows. Pick only the low-risk renames for now. Apply them. Then rerun the audit from step 1 and compare the inconsistency count before and after.

   • Inconsistency count drops meaningfully on the second audit
   • No high-risk token was renamed without a written migration plan
   • You can hand the remaining mid and high-risk renames to engineering as a scoped list, not a vague request