Token Troubleshooting Guide

A token troubleshooting guide helps developers diagnose and resolve common token issues. When tokens do not work as expected, troubleshooting skills enable quick resolution without escalating to support. Documenting solutions to frequent problems reduces repeated questions and improves developer experience.

What Is a Token Troubleshooting Guide

A token troubleshooting guide is a problem-oriented reference that helps users identify issues and find solutions. Unlike feature documentation that explains how things work, troubleshooting documentation addresses what to do when things go wrong.

Effective troubleshooting guides organize problems by symptoms and provide step-by-step resolution paths.

How Token Troubleshooting Works

Symptom-based organization:

## Token Not Applying

**Symptom:** Token reference in code, but styles do not appear

**Diagnostic Steps:**
1. Open browser DevTools
2. Inspect the element
3. Check Computed tab for the property
4. Check if custom property is defined

**Common Causes:**

Cause: Token name misspelled
```css
/* Wrong */
color: var(--color-primry);

/* Correct */
color: var(--color-primary);

Solution: Check spelling against token catalog

Cause: Token file not loaded

• Check network tab for CSS file
• Verify import statement Solution: Ensure token CSS is imported

Cause: Specificity override

• Check if other rules override Solution: Inspect cascade to find competing rules

**Error message guide:**

```markdown
## Build Errors

### "Reference not found: {color.brand}"

**Cause:** Token references a non-existent token

**Solution:**
1. Check if referenced token exists in catalog
2. Verify spelling matches exactly (case-sensitive)
3. Check if token was deprecated/removed

### "Circular reference detected"

**Cause:** Token A references Token B which references Token A

**Solution:**
1. Trace the reference chain
2. Break the cycle by using a direct value
3. Reorganize token structure

Key Considerations

• Organize by symptoms users experience
• Include exact error messages for searchability
• Provide step-by-step diagnostic instructions
• Explain both cause and solution
• Update as new issues emerge
• Link to relevant documentation
• Include when to escalate
• Use actual code examples

Common Questions

What are the most common token issues?

Documenting frequent issues reduces repeated support questions.

Token value not appearing:

### Token Shows Wrong Value or No Value

Symptoms:
- Element has unexpected color/spacing
- Computed value shows fallback or nothing

Diagnostic:
1. DevTools → Inspect element → Computed
2. Search for the CSS property
3. Note the actual computed value

Solutions by finding:

If value is "initial" or empty:
- Token CSS not loaded
- Token name incorrect

If value matches fallback:
- Token not defined
- Scope issue (check parent selectors)

If value is different than expected:
- Wrong token referenced
- Theme override applied
- Specificity conflict

Build failures:

### Build Fails with Token Errors

Symptoms:
- npm run build fails
- Error mentions tokens

Common errors:

"Cannot resolve reference"
→ Referenced token does not exist
→ Check token path spelling

"Invalid value for type 'color'"
→ Non-color value in color token
→ Check value format

"Duplicate token name"
→ Same name defined twice
→ Search for duplicates

How should diagnostic steps be structured?

Diagnostic steps should progress from simple to complex.

Structured diagnosis:

## Token Not Working Checklist

### Level 1: Quick Checks (30 seconds)
- [ ] Token name spelled correctly?
- [ ] CSS file imported?
- [ ] Syntax correct? (`var(--token-name)`)

### Level 2: DevTools Investigation (2 minutes)
- [ ] Element inspection shows property?
- [ ] Computed value matches expected?
- [ ] Any rules overriding?

### Level 3: Build Verification (5 minutes)
- [ ] Token exists in source files?
- [ ] Build completes without errors?
- [ ] Output file contains token?

### Level 4: Environment Check (10 minutes)
- [ ] Correct package version installed?
- [ ] No caching issues?
- [ ] Same issue in clean environment?

### Still stuck?
- Post in #design-system-help with:
  - Token name
  - Expected vs actual behavior
  - Steps already tried

How should escalation paths be defined?

Escalation helps when self-service troubleshooting fails.

Escalation criteria:

## When to Escalate

Self-troubleshoot when:
- Issue matches documented symptoms
- Solution steps are available
- Problem is isolated to your code

Escalate when:
- Issue not in troubleshooting guide
- Suggested solutions do not work
- Problem appears in token system itself
- Multiple people experiencing same issue

## How to Escalate

1. Post in #design-system-help:
   - Brief description
   - Steps to reproduce
   - What you've tried
   - Screenshots/code snippets

2. For urgent issues:
   - Tag @design-system-oncall
   - Include impact description

3. For bugs in tokens:
   - File issue in tokens repository
   - Include reproduction case

Summary

Token troubleshooting guides help users diagnose and resolve common issues through symptom-based organization and step-by-step diagnostic instructions. Common issues include token values not appearing, build failures, and reference errors. Diagnostic steps progress from quick checks through deeper investigation. Clear escalation paths indicate when and how to seek additional help when self-service troubleshooting is insufficient.