Design Token Inventory

A design token inventory provides a complete accounting of all tokens in a system, serving as the foundation for management, governance, and planning decisions. Without inventory visibility, teams cannot confidently answer basic questions about what tokens exist, how they are used, and where they need attention.

What Is a Design Token Inventory

A design token inventory is a comprehensive catalog of all tokens including their names, values, types, relationships, and metadata. The inventory serves as a single source of truth for understanding the token landscape, distinct from the tokens themselves which are scattered across files and potentially multiple repositories.

Inventory enables analysis, planning, and reporting that would be difficult with raw token files alone.

How Design Token Inventory Works

Inventory content:

## Token Inventory Summary

Total tokens: 342

By category:
- Color: 128 (37%)
- Spacing: 45 (13%)
- Typography: 52 (15%)
- Shadow: 18 (5%)
- Border: 24 (7%)
- Motion: 15 (4%)
- Z-index: 12 (4%)
- Other: 48 (14%)

By tier:
- Primitive: 98 (29%)
- Semantic: 189 (55%)
- Component: 55 (16%)

Status:
- Active: 312 (91%)
- Deprecated: 30 (9%)

Detailed inventory record:

{
  "name": "color.action.primary",
  "value": "{color.primitive.blue.500}",
  "resolvedValue": "#3B82F6",
  "type": "color",
  "tier": "semantic",
  "status": "active",
  "description": "Primary action color for buttons and links",
  "references": ["color.primitive.blue.500"],
  "referencedBy": ["button.background.default", "link.text.default"],
  "usageCount": 156,
  "addedVersion": "1.2.0",
  "lastModified": "2024-01-15"
}

Inventory generation:

function generateInventory(tokens) {
  return tokens.map(token => ({
    name: token.name,
    value: token.value,
    resolvedValue: resolveValue(token),
    type: token.type,
    tier: determineTier(token),
    status: token.deprecated ? 'deprecated' : 'active',
    references: extractReferences(token.value),
    referencedBy: findReferencingTokens(token.name, tokens),
    usageCount: countUsages(token.name)
  }));
}

Key Considerations

• Inventory should update automatically with token changes
• Historical inventory enables trend analysis
• Inventory powers documentation and tooling
• Regular review identifies inventory issues
• Inventory visibility supports governance
• Export formats enable external analysis
• Inventory scope should be clearly defined
• Completeness is essential for inventory value

Common Questions

How should inventory be maintained?

Inventory maintenance ensures accuracy as tokens evolve.

Automated generation:

# CI job to update inventory
- name: Generate inventory
  run: npm run generate-inventory

- name: Commit inventory
  run: |
    git add inventory.json
    git commit -m "Update token inventory"

Manual verification:

Monthly inventory check:
- [ ] Run automated generation
- [ ] Verify counts match expectations
- [ ] Check for orphaned tokens
- [ ] Review deprecated token status
- [ ] Update metadata accuracy

Version tracking:

{
  "inventoryVersion": "2024-01-15",
  "tokenVersion": "2.3.0",
  "generatedAt": "2024-01-15T12:00:00Z",
  "tokens": [...]
}

What analysis does inventory enable?

Inventory enables various analyses for decision-making.

Growth analysis:

Token growth over time:
- Q1 2023: 245 tokens
- Q2 2023: 278 tokens (+13%)
- Q3 2023: 312 tokens (+12%)
- Q4 2023: 342 tokens (+10%)

Growth by category:
- Color: +15 tokens
- Spacing: +5 tokens
- Typography: +8 tokens

Health analysis:

Token health metrics:
- Deprecated tokens: 30 (9%)
- Unused tokens: 12 (4%)
- Missing descriptions: 45 (13%)
- Orphaned references: 0

Usage analysis:

Usage distribution:
- High usage (>50): 45 tokens
- Medium usage (10-50): 123 tokens
- Low usage (1-10): 156 tokens
- Zero usage: 18 tokens

How should inventory be presented?

Presentation formats serve different audiences and purposes.

Dashboard view:

Token Inventory Dashboard

+------------------+------------------+
|  Total: 342      |  Active: 312     |
|  Categories: 8   |  Deprecated: 30  |
+------------------+------------------+

[Category Chart]    [Tier Distribution]

Recent changes:
- +3 tokens (Jan 15)
- -2 deprecated (Jan 10)

Searchable catalog:

<input type="search" placeholder="Search tokens..." />
<filters>
  <select>Category</select>
  <select>Tier</select>
  <select>Status</select>
</filters>
<table>
  <tr><th>Name</th><th>Value</th><th>Usage</th></tr>
  <!-- Token rows -->
</table>

Export formats:

// JSON for tooling
inventory.toJSON();

// CSV for spreadsheet analysis
inventory.toCSV();

// Markdown for documentation
inventory.toMarkdown();

Summary

Design token inventory provides comprehensive visibility into the token system through complete token accounting with metadata, relationships, and usage information. Automated generation ensures accuracy as tokens change. Inventory enables growth, health, and usage analyses that inform governance decisions. Presentation through dashboards, searchable catalogs, and export formats serves different audiences and purposes.