Token Category Organization

Token category organization determines how tokens are grouped and classified within a design system. Effective categorization makes tokens discoverable, establishes clear ownership boundaries, and creates intuitive mental models for both designers and developers. As token systems grow, thoughtful organization prevents the chaos that undermines token utility.

What Is Token Category Organization

Token category organization refers to the taxonomic structure used to classify tokens into meaningful groups. Categories establish top-level divisions (color, spacing, typography) while subcategories provide finer distinctions (background colors, text colors, border colors).

Organization serves multiple purposes: helping users find relevant tokens, defining scope for documentation and governance, and creating logical boundaries for file structure and build processes. The same organizational scheme typically flows through all of these contexts.

How Token Category Organization Works

Most token systems organize tokens into hierarchical categories reflecting the fundamental attributes tokens represent.

Primary categories typically include:

• Color: All color values including primitives and semantic assignments
• Spacing: Padding, margin, gap, and layout measurements
• Typography: Font families, sizes, weights, line heights, and composite text styles
• Elevation: Shadows and z-index values
• Border: Border widths, styles, and radii
• Motion: Duration, timing functions, and animation properties
• Sizing: Component dimensions and fixed measurements

Within each primary category, subcategories add specificity. Color subcategories might include:

color/
  primitive/     # Raw palette values
  background/    # Surface and container backgrounds
  text/          # Typography colors
  border/        # Stroke and divider colors
  icon/          # Icon fill colors
  interactive/   # States like hover, focus, active
  status/        # Error, warning, success, info

This hierarchical structure creates predictable paths for locating tokens. Finding the error text color means navigating to color → text → error or color → status → error, depending on the organizational philosophy.

Key Considerations

• Categories should reflect how teams think about design attributes
• Consistency in categorization aids discoverability
• Overlapping categories create confusion about where tokens belong
• Empty categories suggest over-specification
• Categories too broad become unwieldy as tokens accumulate
• Migration between categories is disruptive and should be minimized
• Documentation navigation should mirror category structure
• Build processes can leverage categories for selective output generation

Common Questions

How should overlapping concepts be handled?

Some tokens resist clean categorization because they relate to multiple categories. Interactive colors apply to both color and component behavior. Border radius affects both borders and component shape. These overlaps require deliberate organizational decisions.

One approach assigns tokens to their primary attribute type. Border radius goes under border because it is fundamentally a border property, even though it affects overall shape. Interactive colors go under color because they are color values, even though they relate to interaction.

Another approach creates semantic categories that transcend attribute types. An “interactive” category might include colors, shadows, and transitions that all relate to interaction states.

A pragmatic approach places the token where users most expect to find it. If developers consistently look for border radius under “shape” rather than “border,” the organization should match that expectation.

Whatever approach is chosen, consistency matters more than perfection. Apply the same principles across all edge cases.

Should component-level tokens have their own categories?

Component-specific tokens (button colors, card shadows) can exist within attribute categories or in separate component categories.

Attribute-first organization places component tokens within their attribute category:

color/
  background/
    button/
      primary.json
      secondary.json
    card/
      default.json

Component-first organization creates a component category:

component/
  button/
    color.json
    spacing.json
  card/
    color.json
    shadow.json

Attribute-first keeps similar values together, making it easier to maintain consistency across components. Component-first keeps everything about a component together, making component-focused work more convenient.

Many systems use attribute-first for semantic tokens and add component-first organization only when component-specific tokens diverge significantly from semantic patterns. This hybrid approach maintains attribute consistency while accommodating component needs.

How should categories scale as systems grow?

Growing systems add tokens that may strain original categories. Scaling approaches include deepening categories, adding new categories, and periodic reorganization.

Deepening adds subcategories within existing categories. When color/background becomes unwieldy, subdivide into color/background/surface, color/background/container, color/background/overlay.

Adding new categories is appropriate when genuinely new attribute types emerge. Adding a “motion” category when previously animations used hardcoded values makes sense. Avoid adding categories for small token counts that fit existing structures.

Periodic reorganization reassesses the entire structure as systems mature. Major versions provide opportunities to reorganize without constant disruption. Reorganization should follow clear principles and provide migration support for consumers.

Growth should not mean unbounded expansion. Regular auditing identifies tokens that can be consolidated, deprecated, or eliminated. Category organization should simplify access, not just accommodate everything.

Summary

Token category organization creates the taxonomy that makes tokens findable and manageable. Hierarchical categories based on design attributes provide intuitive structures, while subcategories add necessary specificity. Handling overlapping concepts consistently, making deliberate choices about component-level organization, and planning for growth keeps categorization effective as systems evolve.