Token analysis

When importing a design system, preset AI can analyze how tokens are actually used in your codebase. This helps identify gaps and opportunities to improve your design system.

What is token analysis?

Token analysis compares your defined tokens (from config files) against actual usage (from component code). This reveals:

• Missing tokens: colors used in code but not defined in your design system
• Unused tokens: tokens defined but never used in code
• Component patterns: AI-detected groupings of similar component usage

Running analysis

After scanning your repository or zip file, you'll see the Analysis step:

1. Click Run Analysis to start
2. Wait for the analysis to complete (usually a few seconds)
3. Review the findings
4. Take action on any issues
5. Click Continue to proceed to import

You can also Skip analysis and import directly.

Missing tokens

Color values found in your component code that don't have a corresponding token in your design system.

Why this matters

When developers use raw values like #3b82f6 instead of tokens like primary, it creates:

• inconsistent colors across your app
• harder maintenance when colors need to change
• no single source of truth

What you'll see

Element	Description
Color swatch	Visual preview of the color
Value	The hex/rgb value found in code
Usage count	How many times it appears
Suggested name	AI-suggested token name

Actions

Action	Result
Add to import	Includes this token in your design system

Tip: Focus on colors with high usage counts first: these are the most impactful to tokenize.

Unused tokens

Tokens defined in your design system but never referenced in your component code.

Why this matters

Unused tokens can indicate:

• outdated tokens that should be removed
• tokens intended for future use
• tokens used in CSS that wasn't scanned

What you'll see

Element	Description
Token name	The defined token name
Defined in	Source file where token is defined

Actions

Action	Result
Remove	Excludes this token from import
Keep	Keeps the token in your design system

Tip: Don't remove tokens just because they're unused: they may be intentionally reserved or used in unscanned files.

Component patterns

AI analyzes your component usage to detect semantic patterns: groups of components that serve similar purposes.

Why this matters

Patterns help you:

• identify opportunities for presets
• ensure consistent styling for similar actions
• understand how your design system is actually used

What you'll see

Element	Description
Intent badge	The detected purpose (e.g., "Destructive Action")
Component count	Number of components in this pattern
Confidence	How certain the AI is (High / Medium / Low)
AI rationale	Explanation of why this pattern was detected
Common props	Shared properties across components
Suggested preset	Recommended preset name

Confidence levels

Level	Meaning
High	Strong signal from naming and usage patterns
Medium	Good indicators but some ambiguity
Low	Weak signal, manual review recommended

Actions

Creating presets from patterns is coming in a future release. For now, use patterns as guidance for manual preset creation.

Analysis summary

At the top of the analysis step, you'll see a summary card:

Indicator	Meaning
Green dot	No issues found
Amber dot	Review recommended
Blue dot (pulsing)	Analysis in progress
Red dot	Analysis failed

The summary shows counts for each category:

• + X missing: tokens to potentially add
• − X unused: tokens to potentially remove
• ✦ X patterns: component patterns detected

Preview step banner

After completing analysis, the preview step shows a summary banner if issues were found:

• When issues exist: amber banner with key metrics and "View Analysis" button
• When no issues: no banner, just a subtle "View analysis" link

You can dismiss the banner with the X button.

FAQ

What if analysis finds no issues?

Great. Your design system is well-aligned with your codebase. Proceed with import.

Can I skip analysis?

Yes. Click Skip to go directly to the preview step. You can always re-import later with analysis.

Why are some tokens marked as "missing" when I know they exist?

Analysis only checks files that were scanned. If tokens are used in files outside the scan scope (e.g., CSS-in-JS, external stylesheets), they won't be detected.

Should I add all missing tokens?

Not necessarily. Consider:

• Is this a one-off value or a recurring pattern?
• Should this use an existing token instead?
• Is this value intentionally not tokenized?

Should I remove all unused tokens?

Be cautious. Tokens may be:

• reserved for future use
• used in files that weren't scanned
• part of a complete color scale (you might want gray-100 through gray-900 even if only gray-500 is used)

How accurate is the AI pattern detection?

Pattern detection uses heuristics based on:

• token naming patterns (e.g., "red" suggests destructive)
• common prop combinations
• usage frequency

High-confidence patterns are usually accurate. Review medium and low confidence patterns manually.

Will analysis slow down my import?

Analysis typically takes 2-5 seconds. It runs after scanning completes and doesn't affect the scan itself.