[DRAFT RFC] DTCG Format as Additional Release Output

[GarthDB]

[DRAFT RFC] DTCG Format as Additional Release Output

Summary

Add Design Tokens Community Group (DTCG) 2025.10 format as an additional output format in the dist/ directory during the release process, alongside the existing Spectrum token format.

Motivation

Problem Statement

• Industry Standards: DTCG spec (2025.10) is the first W3C Community Group standard for design tokens
• Tool Interoperability: Growing ecosystem of tools support DTCG format (Style Dictionary, Tokens Studio, etc.)
• Future-Proofing: Being standards-compliant positions Spectrum tokens for broader adoption
• Non-Breaking: Publishing as additional format maintains backward compatibility

Current State

Spectrum tokens currently use a custom format:

• value property (not $value)
• $schema property pointing to Adobe schemas (not $type)
• Custom properties: uuid, private, component, etc.
• Published to dist/json/variables.json

Opportunity

The new Resolver Module (2025.10) addresses multi-context token management (themes, platforms, scales) - highly relevant to our multi-platform needs (iOS, Android, Web, Qt, Drover).

Detailed Design

Output Structure

Publish DTCG format to new dist/dtcg/ directory:

packages/tokens/
├── dist/
│   ├── json/
│   │   └── variables.json      (current format - unchanged)
│   └── dtcg/
│       ├── tokens.json          (all tokens merged)
│       ├── color-palette.json   (by category)
│       ├── typography.json
│       ├── layout.json
│       └── resolver.json        (resolver document)

Token Transformation

Current Format:

{
  "white": {
    "$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/color.json",
    "value": "rgb(255, 255, 255)",
    "uuid": "9b799da8-2130-417e-b7ee-5e1154a89837",
    "private": true
  }
}

DTCG Format:

{
  "white": {
    "$type": "color",
    "$value": "rgb(255, 255, 255)",
    "$extensions": {
      "com.adobe.spectrum": {
        "uuid": "9b799da8-2130-417e-b7ee-5e1154a89837",
        "private": true
      }
    }
  }
}

Transformation Rules

1. Value Property: value → $value
2. Type Property: Extract type from $schema URL → $type
   • color.json → "color"
   • dimension.json → "dimension"
   • font-family.json → "fontFamily"
3. Extensions: Move Adobe properties to $extensions.com.adobe.spectrum:
   • uuid, private, component, deprecated, deprecated_comment
4. Aliases: Transform references: {token-name} → {token-name} (same syntax, different property)

Resolver Document

Create resolver.json demonstrating theme structure (light/dark):

{
  "version": "2025-11-01",
  "name": "Spectrum Design Tokens",
  "description": "Adobe Spectrum Design System tokens",
  "sets": {
    "foundation": {
      "description": "Base tokens (color, typography, layout)",
      "sources": [
        { "$ref": "color-palette.json" },
        { "$ref": "typography.json" },
        { "$ref": "layout.json" }
      ]
    },
    "semantic": {
      "sources": [{ "$ref": "semantic-color-palette.json" }]
    },
    "components": {
      "sources": [
        { "$ref": "color-component.json" },
        { "$ref": "layout-component.json" }
      ]
    }
  },
  "modifiers": {
    "theme": {
      "description": "Color theme variations",
      "contexts": {
        "light": [{ "$ref": "color-aliases.json" }]
      },
      "default": "light"
    }
  },
  "resolutionOrder": [
    { "$ref": "#/sets/foundation" },
    { "$ref": "#/sets/semantic" },
    { "$ref": "#/sets/components" },
    { "$ref": "#/modifiers/theme" }
  ]
}

Package Exports

Update packages/tokens/package.json:

{
  "exports": {
    ".": "./index.js",
    "./json": "./dist/json/variables.json",
    "./dtcg": "./dist/dtcg/tokens.json",
    "./dtcg/*": "./dist/dtcg/*.json",
    "./dtcg/resolver": "./dist/dtcg/resolver.json"
  }
}

Implementation Approach

Create new tool: tools/dtcg-transformer/

• Transform source files to DTCG format
• Generate resolver document
• Validate against DTCG specification
• Integrate into build pipeline
• Publish alongside existing format

Benefits

1. No Breaking Changes: Existing consumers unaffected
2. Standards Compliance: Align with W3C Community Group spec
3. Tool Ecosystem: Enable use of DTCG-compatible tools
4. Future Resolver Benefits: Foundation for managing multi-platform/theme variations
5. Data Preservation: All Adobe metadata preserved in extensions
6. Incremental Adoption: Teams can adopt when ready

Drawbacks

1. Additional Build Output: More files to generate and maintain
2. Validation Tooling Immaturity: DTCG validation tools still emerging (no official JSON Schema yet)
3. Documentation Overhead: Need to document both formats
4. Resolver Complexity: Resolver module adds conceptual complexity
5. Limited Immediate Value: Few consumers currently request DTCG format

Alternatives Considered

1. Replace Current Format with DTCG

Rejected: Breaking change affecting all 6+ implementation teams

2. Wait for DTCG Tooling to Mature

Rejected: Publishing as additional format allows us to be ready when ecosystem matures

3. Transform Only on Request

Rejected: Better to provide consistent, tested output than require consumers to transform

4. Internal Format Only

Rejected: Limited value if not published

Adoption Strategy

Phase 1: Implementation

• Create transformer tool
• Add to build pipeline
• Publish DTCG format alongside existing format
• Update documentation

Phase 2: Validation

• Monitor DTCG spec for JSON Schema release
• Integrate official validation when available
• Refine based on ecosystem feedback

Phase 3: Evolution

• Expand resolver document as theme/platform variations mature
• Potentially add dark theme context
• Consider platform-specific resolvers

Migration Path for Consumers

Existing consumers: No changes required

New consumers: Choose format based on needs:

• @adobe/spectrum-tokens/json - Current format (stable, documented)
• @adobe/spectrum-tokens/dtcg - DTCG format (standards-based, emerging)

Validation

• Create basic JSON schemas for DTCG types
• Validate token structure matches DTCG spec
• Verify alias resolution works correctly
• Test that all source tokens transform successfully
• Confirm UUID mappings preserved

Open Questions

1. Should we include all 8 source files or start with a subset?

   • Proposal: All 8 files for completeness

2. Should resolver demonstrate theme variations or just structure?

   • Proposal: Basic light theme demonstration, document future expansion

3. Should we wait for official DTCG JSON Schema?

   • Proposal: Create internal validation, update when official schema available

4. Package size impact?

   • Need to measure: How much does DTCG format add to published package size?

5. Consumer demand?

   • Are implementation teams or external consumers requesting DTCG format?

Success Criteria

• DTCG format published successfully in releases
• All existing token data preserved (especially UUIDs)
• No regression in current format
• Validation passes for all transformed tokens
• Documentation clear and comprehensive
• At least one implementation team successfully consumes DTCG format

References

• DTCG Specification 2025.10
• Resolver Module
• Format Module
• Design Token Validator