[DRAFT RFC] Design Token Sourcemaps and Traceability

[GarthDB]

⚠️ DRAFT STATUS: This RFC is in early concept stage and open for feedback. It proposes a sourcemap system for tracing design tokens across implementations.

---

RFC: Design Token Sourcemaps and Traceability

Status: Draft - Concept Stage
Author: Garth Braithwaite
DACI: [To be assigned]
Related: Token Structure RFC, Token Lifecycle RFC

---

Executive Summary

This RFC proposes a sourcemap system for design tokens that creates bidirectional traceability between design data (spectrum-tokens), platform implementations (iOS, Android, Web), and design tools (Figma).

Problem: When tokens are transformed for platform use (e.g., Spectrum iOS), the connection to the original design data is lost. Engineers can't easily access lifecycle metadata, discover deprecations, or trace token origins. Design-to-code mapping is manual and error-prone.

Solution: Generate sourcemap-like files during token compilation that maintain references via UUIDs and semver, enabling:

• Tracing platform code back to spectrum-tokens source
• Accessing lifecycle metadata from implementations
• Mapping between spectrum-tokens ↔ Figma variables
• Automated deprecation warnings in platform builds

---

Background & Context

Current Pain Points

1. Lost Context: Generated platform code (Swift, Kotlin, CSS) has no reference to source token
2. Manual Mapping: Teams manually maintain mappings between Figma, design data, and implementations
3. Deprecation Blindness: Platform builds don't know if they're using deprecated tokens
4. Audit Difficulty: Can't easily answer "which tokens does iOS use?"
5. Breaking Change Risk: Platform implementations may break if token structure changes

---

Proposal

1. Token Sourcemap Specification

Inspired by JavaScript Source Maps v3, create a .tokens.map file format for design token compilation.

Sourcemap File Structure

{
  "version": 1,
  "sourceRoot": "https://github.com/adobe/spectrum-tokens",
  "sourceVersion": "3.2.0",
  "platform": "ios",
  "mappings": {
    "button-background-default": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "sourceFile": "tokens/semantic/action.json",
      "generatedFile": "Sources/SpectrumTokens/Action.swift",
      "generatedSymbol": "ButtonBackgroundDefault",
      "lifecycle": {
        "introduced": "2.0.0",
        "status": "active"
      },
      "figmaMapping": {
        "variableId": "figma-var-id-123",
        "variableName": "button/background/default"
      }
    }
  }
}

2. UUID-Based Token Identity

Every token in spectrum-tokens gets a stable UUID that persists across renames and refactors.

Benefits:

• ✅ Tokens can be renamed without breaking mappings
• ✅ Cross-reference tracking via stable identifier
• ✅ Historical tracking even after token removal
• ✅ Figma ↔ spectrum-tokens mapping via UUID

3. Platform Build Tool Integration

Swift Example (iOS):

// Build plugin reads .tokens.map and warns:
warning: Token 'button-background-primary' is deprecated (v3.0.0)
  Use 'action-background-default' instead
  Planned removal: v4.0.0

4. Figma ↔ Spectrum Tokens Mapping

Sourcemap enables bidirectional mapping between Figma variables and spectrum-tokens, even when naming differs.

Use Cases:

• Figma → Tokens: "Which token does this Figma variable represent?"
• Tokens → Figma: "Where is this token used in Figma?"
• Sync Status: "Are Figma variables in sync with latest tokens?"
• Deprecation Propagation: "Mark deprecated tokens in Figma with warnings"

5. Cross-Platform Token Usage Tracking

Example Query: "Where is button-background-default used?"

Token: button-background-default (UUID: 550e8400...)
Status: active (v2.0.0)

Platform Usage:
  iOS (v3.2.0): ButtonBackgroundDefault
  Android (v3.2.0): button_background_default  
  Web (v3.2.0): --spectrum-button-background-default

Figma Usage:
  Variable: "button/background/default"

---

Use Cases

Use Case 1: Platform Engineer Debugging

Look up generated code symbol → Find source token → Check GitHub history

Use Case 2: Migration Planning

Query deprecated tokens → Check platform usage → Prioritize migrations

Use Case 3: Figma Sync Validation

Compare Figma variables against sourcemap → Report mismatches → Automate sync

Use Case 4: Breaking Change Prevention

Compare old vs new sourcemaps → Detect removals/renames → Generate migration guide

---

Implementation Phases

Phase 1: Proof of Concept

• Define sourcemap format specification
• Implement UUID generation for tokens
• Build prototype sourcemap generator for one platform (iOS)

Phase 2: Single Platform Validation

• Pilot on iOS with sourcemap generation
• Build Swift build plugin for deprecation warnings

Phase 3: Multi-Platform Rollout

• Extend to Android, Web, Desktop

Phase 4: Figma Integration

• Build Figma ↔ spectrum-tokens mapping system
• Automated sync validation

---

Open Questions

Technical Questions

1. Should UUIDs be deterministic (v5) or random (v4 with registry)?
2. What sourcemap format: inline comments or separate files?
3. How to handle tokens that split/merge (UUID assignment)?
4. Should sourcemaps be included in production builds or debug only?

Integration Questions

5. Which platform should pilot sourcemap integration first?
6. How to integrate with existing platform build systems without disruption?
7. How to handle Figma variable renames (manual mapping update)?

---

References

External Standards

• JavaScript Source Maps v3 Specification
• Swift Package Manager Plugins

Related RFCs

• RFC 01: Token Deprecation and Consolidation (lifecycle metadata)
• RFC 02: Token Structure Changes (foundation/platform layers)
• RFC 03: Token Authoring Workflow (generation process)

---

Full RFC: View complete RFC with all technical details

[GarthDB]

🔗 Related Work: Token Schema Structure RFC

A new RFC has been published that provides 70% of the foundation needed for this sourcemap proposal:

RFC: Token Schema Structure and Validation System (PR #644)

Already Implemented (Foundation Complete)

✅ UUID Preservation - All tokens maintain stable UUIDs
✅ Reference Tracking - Semantic aliases track which tokens they reference
✅ Structured Format - Tokens have queryable structure for mappings
✅ Round-trip Verification - Perfect conversion between formats

What This RFC Adds (Next Steps)

🔨 Bidirectional Traceability - Track implementations back to tokens
🔨 Platform Integration - Connect CSS vars, Swift constants, etc.
🔨 Implementation Tracking - Which files use which tokens
🔨 Figma Mapping - Connect Figma variables to tokens

Example: What's Already Possible

// Find all tokens that reference blue-800
const references = tokens.filter(t => 
  t.name.structure.referencedToken === "blue-800"
);
// Returns: ["accent-color-100", "button-background-default", ...]### Recommendation

This RFC should be the next priority after schema RFC approval because:

1. Foundation is 70% complete
2. Provides immediate value ("where is this used?")
3. Enables platform teams with traceability
4. Technical specification (lower consensus complexity)