Design Token File Structure

Design token file structure defines how token definitions are physically organized within a codebase. The chosen structure affects discoverability, maintainability, and the ease of extending the system over time. A well-designed file structure makes token management intuitive, while a poorly considered structure creates friction that slows development and invites inconsistency.

What Is Design Token File Structure

Design token file structure encompasses the directories, files, and naming patterns used to store token definitions. This includes decisions about directory depth, file granularity, naming conventions, and the separation between source tokens and generated outputs.

Token files typically use JSON, YAML, or JavaScript formats, though the specific format matters less than the organizational principles applied. The structure should support the tools in the build pipeline, particularly transformation tools like Style Dictionary that process token files to generate platform-specific outputs.

How Design Token File Structure Works

A typical token file structure begins with a root tokens directory that contains subdirectories for each major token category. Within each category, files group related tokens at a logical level of granularity.

tokens/
  color/
    primitive.json
    background.json
    text.json
    border.json
  spacing/
    primitive.json
    padding.json
    margin.json
    gap.json
  typography/
    font-family.json
    font-size.json
    line-height.json
    font-weight.json
  elevation/
    shadow.json
  motion/
    duration.json
    easing.json

This structure creates predictable locations for different token types. Developers searching for background color tokens know to look in tokens/color/background.json. The separation of primitive tokens from semantic tokens within each category maintains the abstraction hierarchy.

Theme variations often introduce parallel structures or dedicated theme directories. A common pattern places base tokens at the root and theme-specific overrides in nested directories:

tokens/
  color/
    background.json
  themes/
    dark/
      color/
        background.json
    brand-b/
      color/
        background.json

Build configurations specify how these files combine, typically using the base tokens as defaults that theme tokens override. This approach minimizes duplication while maintaining clear separation.

Key Considerations

• File paths should translate directly into token name prefixes for predictability
• Source files should remain separate from generated output files
• Build configurations should live alongside token definitions
• Platform-specific transformations belong in build configuration, not source tokens
• Version control should track source tokens while ignoring generated outputs
• File naming should follow consistent casing conventions throughout
• Index files can simplify imports but add maintenance overhead
• The structure should accommodate future growth without reorganization

Common Questions

How many tokens should be in one file?

A single file should contain tokens that logically belong together and are likely to be modified together. This typically means grouping by subcategory, resulting in files with ten to fifty tokens each.

Files that are too granular create filesystem clutter and make it difficult to see relationships between related tokens. Files that are too large become unwieldy to navigate and create merge conflicts when multiple team members edit simultaneously.

The right granularity depends on the system’s complexity. A small design system might have one file per category (all colors in color.json). A large enterprise system might have dozens of files per category to support multiple brands and themes. The goal is to optimize for how teams actually work with tokens.

Should primitive and semantic tokens be in separate directories?

Separating primitive and semantic tokens into distinct directories clarifies the token hierarchy and supports different access patterns. Primitive tokens represent raw values that rarely need direct reference in application code. Semantic tokens represent the intentional design decisions that developers should use.

A common structure places primitives in their own hierarchy:

tokens/
  primitives/
    color.json
    spacing.json
  semantic/
    color/
      background.json
      text.json
    spacing/
      layout.json

This separation makes it clear which tokens form the foundation and which represent the consumption layer. It also supports tooling that might expose only semantic tokens to application developers while keeping primitives available to design system maintainers.

How should generated files be organized?

Generated files, the output of token transformation processes, should live in a dedicated build or dist directory that version control ignores. This prevents confusion between source and output and ensures that generated files always reflect the current source state.

A typical output structure mirrors the target platforms:

dist/
  css/
    tokens.css
    themes/
      dark.css
  js/
    tokens.js
    tokens.d.ts
  ios/
    Tokens.swift
  android/
    tokens.xml

Build processes should clear and regenerate this directory completely rather than updating files in place. Complete regeneration prevents stale outputs from persisting when source tokens are deleted or renamed.

Summary

Design token file structure provides the physical foundation for token management. Effective structures organize tokens by category and subcategory, separate primitives from semantic tokens, and maintain clear boundaries between source definitions and generated outputs. A thoughtfully designed structure supports team workflows, scales with system growth, and integrates smoothly with build tooling.