dtcg-format

DTCG Format

When to use this skill

Use this skill when you need to:

• Export design tokens in the Design Tokens Community Group (DTCG) standard format
• Create token files compatible with DTCG-supporting tools
• Include Figma variable metadata in token exports
• Convert hierarchical token names to nested JSON objects
• Generate token files with proper $type, $value, and $extensions structure

DTCG format overview

The Design Tokens Community Group format is a standard for representing design tokens in JSON. It uses special properties prefixed with $ to define token metadata.

Core properties

• $type: The token's data type (color, dimension, string, etc.)
• $value: The token's actual value
• $extensions: Additional metadata for tool-specific information

Figma extensions

The format includes Figma-specific extensions for variable integration:

• com.figma.variableId: Unique identifier for the variable
• com.figma.scopes: Array of applicable scopes
• com.figma.modeName: Mode name for the token

Token structure

Basic token structure

{
  "button": {
    "primary": {
      "background-color": {
        "$type": "color",
        "$value": "#0066CC",
        "$extensions": {
          "com.figma.variableId": "VariableID:123:456",
          "com.figma.scopes": ["FRAME_FILL", "SHAPE_FILL"]
        }
      }
    }
  }
}

Hierarchical organization

Token names with slashes are converted to nested objects:

button/primary/hover/background-color
  ↓
{
  "button": {
    "primary": {
      "hover": {
        "background-color": { ... }
      }
    }
  }
}

DTCG data types

Color tokens

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [0.0, 0.4, 0.8],
        "alpha": 1.0,
        "hex": "#0066CC"
      },
      "$extensions": {
        "com.figma.variableId": "VariableID:123:456",
        "com.figma.scopes": ["FRAME_FILL", "SHAPE_FILL"]
      }
    }
  }
}

Dimension tokens

{
  "spacing": {
    "md": {
      "$type": "dimension",
      "$value": "16px",
      "$extensions": {
        "com.figma.variableId": "VariableID:123:457",
        "com.figma.scopes": ["GAP"]
      }
    }
  }
}

String tokens

{
  "typography": {
    "family": {
      "primary": {
        "$type": "fontFamily",
        "$value": "Inter",
        "$extensions": {
          "com.figma.variableId": "VariableID:123:458",
          "com.figma.scopes": ["FONT_FAMILY"]
        }
      }
    }
  }
}

Number tokens

{
  "typography": {
    "weight": {
      "bold": {
        "$type": "fontWeight",
        "$value": 600,
        "$extensions": {
          "com.figma.variableId": "VariableID:123:459",
          "com.figma.scopes": ["FONT_WEIGHT"]
        }
      }
    }
  }
}

Type mapping

CSS property to DTCG type mapping

const typeMapping = {
  // Colors
  'background-color': 'color',
  'text-color': 'color',
  'border-color': 'color',
  'shadow-color': 'color',
  
  // Dimensions
  'width': 'dimension',
  'height': 'dimension', 
  'border-radius': 'dimension',
  'padding': 'dimension',
  'margin': 'dimension',
  'gap': 'dimension',
  'border-width': 'dimension',
  
  // Typography
  'font-family': 'fontFamily',
  'font-size': 'fontSize',
  'font-weight': 'fontWeight',
  'line-height': 'lineHeight',
  'letter-spacing': 'letterSpacing',
  
  // Numbers
  'opacity': 'number',
  
  // Strings
  'font-style': 'string',
  'text-align': 'string'
};

Figma type to DTCG type mapping

const figmaTypeToDTCG = {
  'COLOR': 'color',
  'FLOAT': 'number', // or 'dimension' for sizing
  'STRING': 'string',
  'BOOLEAN': 'boolean'
};

Generating DTCG format

Basic usage

const tokens = [
  { 
    name: 'button/primary/background-color', 
    type: 'COLOR', 
    scopes: ['FRAME_FILL'] 
  },
  { 
    name: 'spacing/md', 
    type: 'FLOAT', 
    scopes: ['GAP'] 
  }
];

const dtcgJson = generateDTCGFormat(tokens);

Generated output

{
  "button": {
    "primary": {
      "background-color": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [1, 1, 1],
          "alpha": 1,
          "hex": "#FFFFFF"
        },
        "$extensions": {
          "com.figma.variableId": "VariableID:39:123",
          "com.figma.scopes": ["FRAME_FILL"]
        }
      }
    }
  },
  "spacing": {
    "md": {
      "$type": "number", 
      "$value": 1,
      "$extensions": {
        "com.figma.variableId": "VariableID:39:124",
        "com.figma.scopes": ["GAP"]
      }
    }
  },
  "$extensions": {
    "com.figma.modeName": "Default"
  }
}

Default values by type

Color values

{
  "colorSpace": "srgb",
  "components": [1, 1, 1],  // White RGB normalized
  "alpha": 1,
  "hex": "#FFFFFF"
}

Dimension values

Numeric values default to 1 with appropriate units inferred from context.

String values

Default to the string "string" as placeholder.

Number values

Default to 1 for numeric tokens.

Extension properties

Figma variable ID

Automatically generated in Figma format:

"com.figma.variableId": "VariableID:39:123"

Figma scopes

Based on CSS property mapping:

"com.figma.scopes": ["FRAME_FILL", "SHAPE_FILL"]

Mode information

Collection-level mode metadata:

"$extensions": {
  "com.figma.modeName": "Default"
}

Tool integration

Figma integration

DTCG files with Figma extensions can be imported directly into Figma as variable collections, preserving:

• Variable types
• Scope assignments
• Hierarchical naming
• Mode organization

Token tools compatibility

The format works with DTCG-compatible tools including:

• Style Dictionary
• Theo
• Design Tokens CLI
• Token Studio for Figma

Best practices

1. Consistent naming: Use clear, hierarchical token names
2. Appropriate types: Match DTCG types to token usage
3. Meaningful scopes: Set Figma scopes that match intended usage
4. Organized structure: Group related tokens in logical hierarchies
5. Default values: Provide reasonable placeholder values for all tokens
6. Tool compatibility: Test exports with your target tools
7. Documentation: Include metadata explaining token purposes and relationships

Examples

See scripts/generateDTCG.js for the complete implementation of DTCG format generation with Figma extensions.