[DRAFT RFC] Token Structure Changes for Multi-Platform Support

[GarthDB]

⚠️ DRAFT STATUS: This RFC is in draft form and open for feedback from all platform teams.

---

RFC: Token Structure Changes for Multi-Platform Support

Status: Draft in Progress
Author: Garth Braithwaite
DACI: [To be assigned]
Related: DNA-[ticket], Onsite Day 2 "Multi-Platform Strategy" discussion

---

Executive Summary

This RFC proposes structural changes to how design tokens are organized, authored, and consumed to better support multiple platforms (web, iOS, Android, native desktop) while maintaining a coherent foundational system.

Problem: Current token structure doesn't adequately support platform-specific needs, customization, or the "system of systems" architecture defined at the onsite.

Solution: Implement a hierarchical token architecture with clear trunk (foundation) and branch (platform) layers, supporting inheritance, extension, and platform-specific overrides.

---

Background & Context

Origin

• August 2025 Onsite - Day 1: "Data System Model Overview" presentation (system of systems)
• August 2025 Onsite - Day 2: Multi-platform strategy discussion
• Current State: Single-layer token system struggling to accommodate platform diversity

Your Presentation (Day 1)

Key architecture concepts presented:

• System of systems: Foundation → Platform → Product
• Four main platforms: Web, iOS, Android, Native Desktop
• Principles:
  • Easy to reason about
  • Partner collaboration
  • Supports both strict contracts and flexible data
  • Governance and iteration

Current Challenges

1. Platform Autonomy: Teams want independence but lack framework
2. Customization: No structured way to extend or override tokens
3. Inheritance: Can't track token relationships across layers
4. Multi-dimensional Data: Modes (light/dark, contrast, etc.) not well supported
5. Governance: Unclear boundaries between foundation and platform responsibilities

---

Proposal

Hierarchical Token Architecture

Foundation (Trunk)
├── Primitives (colors, sizing, spacing)
├── Semantic Tokens (reusable across platforms)
└── Core Component Tokens (minimal set)
    │
    ├── Platform: Web
    │   ├── Web Extensions
    │   ├── Web Overrides
    │   └── Products (Express, Horizon, etc.)
    │
    ├── Platform: iOS
    │   ├── iOS Extensions
    │   ├── iOS Overrides
    │   └── Products (Mobile apps)
    │
    ├── Platform: Android
    │   └── [Similar structure]
    │
    └── Platform: Native Desktop
        └── [Similar structure]

Token Layers Defined

Foundation Layer ("The Trunk")

Purpose: Shared foundation supporting all platforms

Contains:

• Layout primitives (spacing-100, sizing-200)
• Semantic color tokens (background-default, text-primary)
• Core typography scales
• Essential component tokens with universal applicability

Governance: Data System team with platform team input

Platform Layer ("The Branches")

Purpose: Platform-specific interpretations and extensions

Contains:

• Platform extensions (new tokens specific to platform needs)
• Platform overrides (modified values for foundation tokens)
• Platform-specific component tokens
• Theme customizations

Governance: Platform teams own their extensions

---

Inheritance & Override Model

Example:

// Foundation defines:
{
  "button-background-default": {
    "value": "{accent-color}",
    "tier": "foundation"
  }
}

// iOS platform can override:
{
  "button-background-default": {
    "value": "{accent-color-tinted}",
    "tier": "platform",
    "platform": "ios",
    "extends": "foundation.button-background-default",
    "reason": "iOS applies tint for native feel"
  }
}

---

Platform Compatibility Requirements

Web Platform Requirements

• CSS output format maintained
• Design Tokens format support
• High contrast mode tokens included
• React/Web Components compatibility
• Migration path for existing implementations

iOS Platform Requirements

• Semantic token naming preserved
• SwiftUI variable generation
• Native appearance system support
• Tinting system compatibility
• Independent release cadence

Android Platform Requirements

• Material Design token mapping
• Resource file generation
• Theme system integration
• Jetpack Compose compatibility

Native Desktop Requirements

• Drover compatibility (legacy apps)
• QT format support (3D/AI apps)
• UXP support (browser in desktop)
• Performance optimization for older systems

---

Review & Feedback Needed

Platform Team Input Needed:

• Web Platform (React, Web Components): Technical review
• iOS Platform: Requirements validation
• Android Platform: Material Design compatibility review
• Native Desktop (Drover, QT, UXP): Format requirements

---

References

• August 2025 Onsite: Day 1 "Data System Model Overview" (Garth's presentation)
• August 2025 Onsite: Day 2 "Multi-Platform Strategy" discussion
• August 2025 Onsite: Day 2 "Defining Multi-Platform" session notes
• Nate's "Authoring Complex Design Data" presentation
• Platform team feedback from governance meetings

---

Full RFC: View complete RFC with all technical details

[NateBaldwinDesign]

I have a few questions about this solution

Hierarchical architecture

From my perspective, the diagram above implies the platform extensions, overrides, and product theming can only be applied to the Core Component Tokens leaf. Is that correct? If so, how would platform teams extend or override semantic or primitive tokens? I can see rationale for overriding or adding semantics, but there could potentially be primitive-level cases such as with a web platform using rem for some values, px for others (potentially creating a secondary set of rem-based primitives for their own platform). How could this architecture support those cases?

Inheritance & Override Model

The "tier" property
Is it required that an override specify "platform" as their tier in order for it to be overridden?

When common industry tiers are primitive, semantic, and component, (hierarchical tiers associated with specificity of token's applicable use cases), why are we adding "platform" to this model? It seems mis-matched as it's not a tier of tokens that adds specificity to the applicable use cases (eg "button-background-default" as the use case remains persistent). It would only qualify as another tier if somehow the name/classification itself was platform-based, such as "ios-button-background-default" (but this approach may not be best practice). For example

Primitive     →  Semantic          →  Component                               → Platform 
`blue-500` → `accent-color` → `button-background-default` → `ios-button-background-default`

This also has me curious how the "product" overrides use case would fit. Would products have a separate "tier" option as well, and how does that fit the existing model for token tiers?

I wonder if a different property / term would be more appropriate for signifying extensions and overrides, for example:

{
  "token-name": {
    "extensionType": "extension" | "override" 
  }
}

The "extends" type
Is this a necessary property, considering the token is named the same? Or is the intention here to support cases where tokens are also renamed as part of the extension?

// iOS platform override example:
{
  "button-background-default": {
    // Already clearly expresses that it's overriding foundation.button-background-default
  }
}

// Or does the model suggest this is possible for renaming?
{
  "my-new-token-name": {
    "extends": "foundation.button-background-default"
  }
}

General questions

• Which of these props will be required vs optional?
• How will this model work with decentralized ownership? (ie, where do overrides exist and how do those interact with this model?)
• I'm curious where the platform requirements are coming from and where to find more detail on some of these items?

[GarthDB]

🔗 Related Work: Token Schema Structure RFC

A new RFC has been published that provides foundational infrastructure for this multi-platform proposal:

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

How It Relates

The structured token format provides:

• ✅ Structured representation that can express platform extensions/overrides
• ✅ Schema validation for enforcing conventions across platforms
• ✅ Semantic complexity metric for platform-specific token selection
• ✅ Reference tracking to understand token inheritance chains

This provides the foundation your multi-platform RFC can build on to define platform-specific extensions and inheritance models.

Current State

• All 2,338 tokens now structured (100% coverage)
• Production-ready schemas and tooling
• Flexible format supporting platform layer architecture