Skip to main content

DTCG Token Format Conversion

  • Status: Proposed
  • Deciders: Abyss Team
  • Date: 2026-02-20

Context​

The Abyss design token system was originally implemented using a legacy token format with properties like value, type, and description. As the design tokens ecosystem has evolved, the Design Tokens Community Group (DTCG) has established a standardized format for design tokens that uses $-prefixed properties ($value, $type, $description) to distinguish token metadata from user-defined properties.

The legacy format had several limitations:

  1. Property naming conflicts: Using unprefixed properties like type could conflict with user-defined token properties
  2. Type redundancy: Each individual token contained a type property, even when all tokens in a group shared the same type
  3. Readability issues: Type declarations appeared at the end of token groups (due to JavaScript's property ordering for numeric keys), making it harder to quickly identify token types
  4. Ecosystem compatibility: Many modern design token tools and platforms expect the DTCG format

Our token files included 127 JSON files across core, semantic, and component token layers for both web and mobile platforms, totaling approximately 11,000+ individual token definitions.

Decision​

We have adopted the DTCG token format and created an automated conversion script to transform all legacy tokens to the new format. The conversion script implements the following transformations:

Core Transformations​

  1. Property Renaming:

    • value → $value
    • type → $type
    • description → $description

Implementation​

All 127 token files were converted using an automated conversion script that:

  • Recursively processes all .json files in the token directory
  • Preserves directory structure (mobile/, web/, and component subdirectories)
  • Excludes metadata files ($metadata.json and $themes.json)
  • Ensures consistent formatting and property ordering across all files

Build Script Compatibility​

The existing token build script (abyss-build-tokens) currently parses legacy format tokens (checking for value and type properties) and transforms them into the custom output format used by Abyss components. To support the transition to DTCG format, the build script will be updated to:

  1. Detect token format: Check for the presence of $value (DTCG) or value (legacy) properties
  2. Parse both formats: Handle both legacy and DTCG token structures during the parsing phase
  3. Maintain identical output: Generate the same flattened token structure regardless of input format

This format-agnostic approach ensures:

  • The build script continues to work with existing legacy tokens during development
  • New DTCG tokens are properly parsed and transformed
  • The output format for Abyss components remains unchanged
  • A smooth transition path without breaking existing workflows

Key considerations for DTCG parsing:

  • Hoisted types: In DTCG format, $type may be at the parent group level rather than on individual tokens. The parser must check parent context when a token lacks a $type property.
  • Format detection: Check for $value presence to determine if a token uses DTCG format
  • Backward compatibility: Continue supporting legacy format until all tokens are converted

Example detection logic:

const isLegacyFormat = Object.prototype.hasOwnProperty.call(token, 'value');
const isDTCGFormat = Object.prototype.hasOwnProperty.call(token, '$value');


const value = isDTCGFormat ? token.$value : token.value;
const type = isDTCGFormat ? token.$type : token.type;

Runtime Token Flattening Utilities​

The flattenTokens utility functions in both the web and mobile packages are used at runtime to process design tokens and convert them into the theme structure consumed by components. These utilities must also be updated to support both DTCG and legacy formats.

Affected files:

  • packages/abyss-web/src/tools/theme/flattenTokens/flattenTokens.ts
  • packages/abyss-mobile/src/tools/theme/flattenTokens/flattenTokens.ts

Required updates:

  1. Format detection: Check for both $value (DTCG) and value (legacy) properties
  2. Type inheritance: Support $type hoisting by inheriting types from parent groups when tokens don't have explicit types
  3. Metadata filtering: Skip $-prefixed properties during token iteration to avoid processing metadata as tokens
  4. Transform compatibility: Ensure all existing transforms (cast/number, cast/string, shadows/parse, typography/fontWeight, etc.) work with both formats

Key implementation details:

  • The parseTheme function receives a parentType parameter to track inherited types through the token hierarchy
  • Tokens check for $type at their own level first, then fall back to the inherited parentType
  • All existing functionality (reference value parsing, transform application, unit handling) remains unchanged
  • The output format for components stays identical regardless of input format

This ensures that components consuming tokens at runtime continue to work seamlessly whether they receive DTCG or legacy format tokens, maintaining backward compatibility during the transition period.

Validation in Figma and Token Studio​

To ensure the converted DTCG tokens work correctly with design tooling, comprehensive validation was performed using Figma and the Tokens Studio plugin. The validation confirmed that the DTCG format is fully compatible with the design workflow.

Validation tests performed:

  1. Tokens properly load in Token Studio from DTCG format

  2. Adding a new token

    • Created new tokens using Token Studio's interface
    • Verified new tokens are saved in DTCG format with proper $value and $type properties
    • Confirmed new tokens integrate seamlessly with existing token structure
    • Validated that type inheritance works for newly created tokens
    • Video demonstration

  3. Tokens export to Figma

    • Verified tokens sync correctly from Token Studio to Figma
    • Confirmed all token types (colors, spacing, typography, etc.) apply as expected
    • Video demonstration

Results: All validation tests passed successfully, confirming that the DTCG format conversion maintains full compatibility with the design workflow and tooling ecosystem.

Example Conversion​

Before (Legacy Format):

{
  "sizing": {
    "100": {
      "value": "16",
      "type": "sizing"
    },
    "250": {
      "value": "20",
      "type": "sizing"
    },
    "full": {
      "value": "100%",
      "type": "sizing"
    }
  }
}

After (DTCG Format):

{
  "sizing": {
    "$type": "sizing",
    "100": {
      "$value": "16"
    },
    "250": {
      "$value": "20"
    },
    "full": {
      "$value": "100%"
    }
  }
}

Alternatives Considered​

Manual Conversion​

Advantages:

  • Complete control over each conversion
  • Opportunity to review and refactor token structure

Disadvantages:

  • Extremely time-consuming (127 files, 11,000+ tokens)
  • High risk of human error and inconsistencies
  • Difficult to maintain consistency across all files

Using Existing Token Transform Tools​

Advantages:

  • Leverage existing solutions
  • Community-supported tools

Disadvantages:

  • Most tools don't handle type hoisting
  • Limited control over property ordering
  • May not preserve our specific token structure and metadata
  • Would still require custom scripting for our specific needs

Gradual Migration​

Advantages:

  • Lower immediate effort
  • Can test with subset of tokens

Disadvantages:

  • Maintaining two formats simultaneously is complex
  • Tooling must support both formats during transition
  • Delays benefits of standardization
  • Risk of incomplete migration

Consequences​

Positive​

  • Standards compliance: Tokens now follow the DTCG specification, improving compatibility with design token tools and platforms
  • Reduced redundancy: Type hoisting eliminates thousands of duplicate $type declarations across token files
  • Improved readability: $type appearing first in groups makes token structure immediately clear
  • Automation: The conversion script can be reused if we need to convert additional legacy token files or regenerate tokens
  • Consistency: All 127 token files follow identical formatting and structure
  • Future-proof: Aligns with industry standards and emerging design token tooling

Negative​

  • Breaking change: Any tools or processes that directly parse our token JSON files will need updates
  • Learning curve: Team members familiar with the legacy format need to adapt to $-prefixed properties
  • Custom serializer maintenance: The custom JSON serializer that ensures $type appears first requires maintenance if we upgrade Node.js or JSON handling libraries

Future Considerations​

  • Token validation: Implement automated validation to ensure all tokens conform to DTCG specification
  • Build-time transformation: Consider whether build tools should consume DTCG tokens directly or if we need transformation layers
  • Token documentation: Update all documentation and examples to reflect DTCG format
  • Tooling integration: Evaluate DTCG-compatible tools for token management, validation, and transformation (e.g., custom token script, Style Dictionary, Theo, Token Studio)
  • Version control: Consider how token format changes should be versioned and communicated to consumers

References​

Revision History​

  • 02/20/2026: Added PR for token conversion PR #5402
  • 02/24/2026: Removed section on type hoisting of internal token structure. Our structure will keep type in place and not hoist it to the parent group. This is to maintain consistency with our current token structure.
Table of Contents