Build a Token Parity Check Skill for Claude Code

A designer changes color.background.surface from #FAFAFA to #F7F6F3 in Figma. Three weeks later, an engineer notices the dashboard still looks slightly off. The token in code never got updated. Multiply that by 200 tokens, two themes, four product surfaces, and you have a parity problem that quietly compounds.

This guide gives you a Claude Code skill that compares two token sources side by side and tells you, in one report, exactly what drifted: missing tokens, extra tokens, and same-name-different-value mismatches. Type /check-token-parity and you have your answer in under a minute.

The SKILL.md

Copy this whole block into a new file.

---
name: check-token-parity
description: Compare design tokens between two sources (Figma export and code)
  and report drift. Use when the user mentions parity, drift, sync, mismatch,
  Figma vs code, or runs /check-token-parity. Outputs a markdown report with
  three sections: missing in code, missing in Figma, value mismatches.
---

# Token Parity Check

You are comparing two token sources and reporting drift. Be exact. Quote
both values when they mismatch. Never assume which side is correct.

## Step 1: Identify the two sources

Look for a config file at `.design-system/parity.json`:

```json
{
  "figma": "tokens/figma-export.json",
  "code":  "src/tokens/tokens.json"
}
```

If it does not exist, search for these defaults:

**Figma source** (in this order):
1. `tokens/figma-export.json`
2. `tokens/$themes.json` + `tokens/Modes/*.json` (Tokens Studio format)
3. `design-tokens/figma.json`
4. Any JSON file in `figma/` directory

**Code source** (in this order):
1. `src/tokens/tokens.json`
2. `src/styles/tokens.css` (CSS custom properties)
3. `src/design-tokens/index.{js,ts}` (exported objects)
4. `tailwind.config.{js,ts}` (theme.extend.colors etc.)

If you cannot find both, ask the user for the paths before proceeding.

## Step 2: Normalize both sources

Both sources must end up as a flat map: `{ token.name: value }`.

**Naming normalization:**
- Lowercase everything
- Convert separators to dots: `color/background/primary` and
  `color-background-primary` both become `color.background.primary`
- Strip leading `--` from CSS custom properties

**Value normalization:**
- Hex colors: lowercase, expand 3-char hex to 6-char (`#fff` to `#ffffff`)
- Strip whitespace from values
- For pixel values, normalize to a canonical unit (e.g. always `px`, not `1rem` vs `16px`)
- For aliased tokens (`{color.primitive.blue.500}`), resolve to the final value
  before comparing. Note the alias chain in the report.

## Step 3: Run the comparison

Build three sets:

1. **Missing in code:** Token exists in Figma source, no match in code.
2. **Missing in Figma:** Token exists in code, no match in Figma source.
3. **Value mismatches:** Same token name, different resolved values.

Also flag a fourth category for awareness:

4. **Naming pattern drift:** Tokens that look like they should match but use
   different naming patterns (e.g. Figma has `color.bg.primary`, code has
   `color.background.primary`). Suggest the canonical name.

## Step 4: Output the report

Write a single markdown report with this exact structure:

```markdown
# Token Parity Check

**Figma source:** `{path}` ({n} tokens)
**Code source:**  `{path}` ({n} tokens)
**Last updated (Figma):** {file mtime}
**Last updated (code):**  {file mtime}

## Summary

| Status            | Count |
|-------------------|-------|
| In sync           | {n}   |
| Missing in code   | {n}   |
| Missing in Figma  | {n}   |
| Value mismatch    | {n}   |
| Naming drift      | {n}   |

**Parity score:** {in-sync / total} %

## Missing in code

Tokens defined in Figma but not in your code source. Likely needs to be
added to the code pipeline.

| Token | Figma value | Notes |
|-------|-------------|-------|
| `color.background.surface.subtle` | `#f7f6f3` | New in latest Figma export |
| `spacing.gap.2xs` | `4px` | |

## Missing in Figma

Tokens defined in code but not in Figma. Either Figma is stale, or these
tokens are code-only (acceptable in some teams).

| Token | Code value | Notes |
|-------|------------|-------|
| `motion.duration.instant` | `0ms` | Possibly code-only |

## Value mismatches

Same token name, different value. These are the highest-priority fixes.
Pick a source of truth and update the other side.

| Token | Figma | Code | Suggested action |
|-------|-------|------|------------------|
| `color.background.surface` | `#f7f6f3` | `#fafafa` | Update code to match Figma |
| `radius.md` | `8px` | `6px` | Confirm intent, update one side |

## Naming drift

Likely the same token, named differently across sources.

| Figma name | Code name | Same value? | Suggested canonical |
|------------|-----------|-------------|---------------------|
| `color.bg.primary` | `color.background.primary` | yes | `color.background.primary` |
```

## Rules

- Never auto-pick a source of truth. If values mismatch, present both and
  let the user decide.
- Show the alias chain when relevant: `color.action.primary -> blue.500 (#3b82f6)`.
- If one source has 0 tokens, stop and tell the user the source path is
  probably wrong or empty.
- If parity score is above 95%, lead with "Mostly in sync" before the report.

## When to skip

- Files in `node_modules/`, `dist/`, `build/`, `.cache/`
- Tokens with names starting with `_` or `__` (private/internal)
- Anything explicitly marked `// parity:skip` at the file top

How to install this skill

Personal (your own use):

mkdir -p ~/.claude/skills/check-token-parity
nano ~/.claude/skills/check-token-parity/SKILL.md

Paste the block, save.

Team (shared via git):

mkdir -p .claude/skills/check-token-parity
nano .claude/skills/check-token-parity/SKILL.md
git add .claude/skills/check-token-parity
git commit -m "Add token parity check skill"

Optional: add a config file so the skill always knows where your sources are without you typing them every time:

mkdir -p .design-system
cat > .design-system/parity.json <<'EOF'
{
  "figma": "tokens/figma-export.json",
  "code":  "src/tokens/tokens.json"
}
EOF

Example invocations

/check-token-parity

Are my Figma tokens in sync with code?

Check for token drift between figma-export.json and src/tokens/

Run a parity check on the brand colors

You can scope the check to a subset by passing a path: /check-token-parity color.* will compare only color tokens.

What it actually does

1. Locates both sources. It reads .design-system/parity.json first. No config? It falls back to common file locations for Tokens Studio, Style Dictionary, raw JSON, CSS variables, and Tailwind configs. If it cannot find one side, it asks instead of guessing.
2. Normalizes names and values. This is the part that breaks most homemade scripts. The skill lowercases names, unifies separators, expands hex shorthand, resolves aliases, and converts units. Without normalization you get false drift on every comparison.
3. Builds three sets and a fourth flag. Missing in code, missing in Figma, value mismatch. Plus a naming-drift category for tokens that probably mean the same thing but have different names.
4. Outputs a structured report. Same format every time. Same column order. So your team can read it the same way every week.

The whole run takes 5 to 30 seconds depending on file size.

Customize for your team

Lock in your source of truth. If your team has decided “Figma always wins” or “code always wins”, update the rules section to make the suggested actions one-directional:

## Source of truth: Figma

For every value mismatch, the suggested action is always:
"Update code to match Figma value."

Add custom normalizers. If your team uses unusual units (e.g. rem everywhere, or named font sizes like medium mapped to 16px), document the conversion in Step 2.

Tag code-only tokens. Many teams have intentional code-only tokens (motion durations, breakpoints, z-index). Add a list:

## Code-only tokens (do not flag as missing in Figma)

- motion.*
- breakpoint.*
- z.*

Add a parity threshold. Append: “If parity score drops below 90%, output a warning at the top in bold.”

Wire it into CI. Once the report format is stable, you can write a simple GitHub Action that runs Claude Code with this skill on every PR and comments the result.

What you get

• A repeatable parity check that runs in under a minute
• A consistent report format you can paste into Slack, Linear, or a PR comment
• Three clear lists of fixes (missing, missing, mismatch) so you can split the work
• A parity score you can track over time

Run it weekly. Watch the score go up. Or down, if someone is shipping changes without sync.

Common pitfalls

False mismatches from unit drift. 1rem and 16px are the same value but the skill will flag them as different unless your normalizer catches it. Add an explicit conversion rule for your unit system.

Alias chains that loop. If a Figma alias points to a code-only token (or vice versa), the resolver will fail. Configure the skill to “resolve aliases up to 5 levels then warn” so it does not hang.

Empty Figma export. A common cause of “everything is missing in Figma” is a stale or empty export file. The skill should bail out early if either source has 0 tokens.

Different token sets on purpose. Brand A and Brand B in the same repo often use different token subsets. Run the skill scoped to one brand at a time, or add a brand filter to the config.

Report that buries the lead. If you have hundreds of mismatches, the report becomes a wall of text. Customize the skill to “show top 20 mismatches inline, attach the rest as a collapsible section.”

Exercise

Run your first parity check and read the drift

20 min

1. Install the skill and point it at your two sources

   Run mkdir -p ~/.claude/skills/check-token-parity and create SKILL.md from the block above. Then create .design-system/parity.json in your project that points to your Figma export and your code token file:

   {
     "figma": "tokens/figma-export.json",
     "code":  "src/tokens/tokens.json"
   }

   • ~/.claude/skills/check-token-parity/SKILL.md exists and has the exact frontmatter name: check-token-parity
   • .design-system/parity.json resolves to two files that both exist and both have more than zero tokens
   • cat on each path prints real JSON, not an empty stub

2. Run /check-token-parity and fix one mismatch

   In Claude Code, run /check-token-parity. Read the four sections of the report. Pick one value mismatch, decide which side is the source of truth, and fix the other side by hand. Rerun the skill. The mismatch should be gone.

   • The report opens with a parity score and counts per category, not prose
   • Every value mismatch row shows both values side by side, with no auto-picked winner
   • After your one fix, the second run shows the mismatch count drop and the parity score rise
   • You now know exactly how many drifts you are living with, which you did not know before