JSON Design Tokens Format

JSON design tokens format provides a structured way to store design decisions in a machine-readable and human-editable format. JSON has become the dominant format for token definitions due to its simplicity, broad tooling support, and compatibility with transformation pipelines. Understanding JSON token structure enables effective authoring and tooling integration.

What Is JSON Design Tokens Format

JSON design tokens format refers to the convention of storing design token definitions in JSON files with specific structural patterns. While JSON itself is a general data format, the design tokens community has developed conventions for how tokens should be organized within JSON structures.

These conventions specify how to name tokens, structure nested hierarchies, express values, and include metadata. Tools like Style Dictionary expect tokens in specific JSON formats, making adherence to conventions important for tooling compatibility.

How JSON Design Tokens Format Works

A basic JSON token file organizes tokens in nested objects where the path through the nesting forms the token name:

{
  "color": {
    "background": {
      "primary": {
        "value": "#ffffff"
      },
      "secondary": {
        "value": "#f5f5f5"
      }
    },
    "text": {
      "primary": {
        "value": "#171717"
      }
    }
  }
}

Each terminal object contains a value property holding the actual token value. The nested path (color.background.primary) becomes the token identifier.

Token references use curly brace syntax to create aliases:

{
  "color": {
    "primitive": {
      "blue": {
        "500": { "value": "#3B82F6" }
      }
    },
    "action": {
      "primary": { "value": "{color.primitive.blue.500}" }
    }
  }
}

The W3C Design Tokens Community Group has developed a standardized format specification that defines:

• Type annotations for tokens ("$type": "color")
• Description metadata ("$description": "Primary action color")
• Alias syntax using curly braces
• Composite token structures for complex values

Modern tooling increasingly supports this emerging standard, improving interoperability between different token tools.

Key Considerations

• Consistent formatting improves readability and reduces merge conflicts
• The value property is required for tokens; objects without it are groups
• Type annotations help validation and transformation
• References must point to existing tokens or builds fail
• File organization should match logical token groupings
• Comments are not native to JSON; descriptions use metadata properties
• Circular references must be avoided
• Large token sets benefit from multiple files rather than one monolithic file

Common Questions

How should token files be split?

Token files should be split based on logical groupings that match how teams think about tokens. A common approach creates separate files for each token category:

tokens/
  color/
    primitive.json
    semantic.json
  spacing.json
  typography.json
  elevation.json

Within files, grouping related tokens creates clear organization. All background colors in one section, all text colors in another. This structure aids navigation without creating excessive file proliferation.

Build tools typically support patterns that combine multiple input files. Style Dictionary accepts globs like tokens/**/*.json, processing all matching files into a combined token set.

Very large systems may benefit from further splitting, perhaps by subcategory or by brand/theme. The goal is files small enough to navigate comfortably while maintaining logical cohesion.

What metadata should tokens include?

Beyond the required value property, tokens benefit from additional metadata that aids understanding and processing.

Type annotations specify what kind of value the token contains:

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#3B82F6"
    }
  }
}

Types enable validation (ensuring color tokens contain valid color values) and inform transforms about how to process values.

Descriptions document token purpose:

{
  "spacing": {
    "page-margin": {
      "$value": "24px",
      "$description": "Horizontal margin for page-level content containers"
    }
  }
}

Descriptions appear in generated documentation and help consumers understand when to use each token.

Deprecation markers flag tokens scheduled for removal:

{
  "color": {
    "brand": {
      "$value": "#3B82F6",
      "$deprecated": "Use color.action.primary instead"
    }
  }
}

Custom metadata can support organization-specific needs like component associations, theme applicability, or ownership information.

How does JSON format compare to alternatives?

JSON is the most common format but not the only option. YAML offers more readable syntax for humans, especially for deeply nested structures. JavaScript/TypeScript files enable computed values and better IDE support. The W3C spec focuses on JSON with YAML as an alternative representation.

JSON advantages include universal tooling support, strict syntax that prevents ambiguity, and easy parsing in any programming language. Most token tools assume JSON input.

JSON disadvantages include lack of comments (requiring description metadata instead), verbose syntax for deep nesting, and limited expressiveness for complex values.

YAML provides a more compact representation and supports comments natively, but its significant whitespace can cause subtle errors. Some teams use YAML for authoring with automatic conversion to JSON for tooling.

The best choice depends on team preferences and tooling requirements. JSON remains the safest choice for broad compatibility.

Summary

JSON design tokens format provides a structured, machine-readable approach to storing design decisions. Nested object structures define token hierarchies, with the value property containing actual values and curly brace syntax enabling references. Metadata including types, descriptions, and deprecation markers enhances token definitions. Understanding JSON token conventions enables effective authoring and ensures compatibility with transformation tooling.