[DRAFT RFC] Distributed Design Data Architecture

[GarthDB]

[DRAFT RFC] Distributed Design Data Architecture

Status: Draft — feedback requested from platform teams.
Parent umbrella: RFC #714 — Spectrum Design Data Specification indexes the full spec family; this RFC is the detailed design for distributed repos, manifests, distribution, validation, and cascade across layers.
Supersedes: RFC #624 — Token Structure Changes for Multi-Platform Support (historical; see closing note there).

---

1. Scope

This RFC specifies how platform-owned repositories consume foundation design data from spectrum-design-data: versioned dependencies, platform manifests (include/exclude, overrides, extensions), resolution and validation, and shared tooling (management app, Figma variable generation, upgrade automation, reports).

Out of scope here (owned by sibling RFCs):

• Structured token naming and schema enums — RFC #646 (includes cascade resolution model and multi-dimensional modes).
• Glossary / registry — RFC #661 and @adobe/design-system-registry.
• Lifecycle metadata and governance — RFC #623.
• Day-to-day authoring process — RFC #625 (aligned with PR-based, distributed authoring).

---

2. Problem statement

Spectrum design data today lives primarily in one repository. To scale to Web Components, React Spectrum, iOS, Android, and products, we need:

• Platform ownership — Each implementation versions and ships its own design data.
• Shared foundation — One spec (schemas, registry, validation rules) and base token values so we do not fork the spec.
• Controlled variation — Subsets, type-safe overrides, and extensions without breaking contracts.
• Tooling — Authoring that writes PRs, CI validation, Figma variables from resolved data, and automated upgrade PRs.

---

3. High-level architecture

Foundation publishes spec + base tokens; platform repos declare a pinned foundation version and a manifest; tooling operates on resolved platform data.

flowchart LR
  subgraph foundation ["Foundation (spectrum-design-data)"]
    direction TB
    spec["Spec + Schemas + Registry"]
    baseTokens[Base Token Values]
  end

  subgraph platforms ["Platform Repos"]
    direction TB
    swc[Web Components]
    rsp[React Spectrum]
    ios[iOS]
    android[Android]
  end

  subgraph tooling [Shared Tooling]
    direction TB
    mgmt[Management App]
    figma[Figma Variable Generator]
    bot[Upgrade Bot]
    report["Report / Diff Generator"]
  end

  spec --> baseTokens
  foundation -->|"versioned dependency + manifest"| platforms
  mgmt -->|"PRs as authenticated user"| platforms
  platforms -->|"resolved token sets"| figma
  foundation -->|"new release"| bot
  bot -->|"automated upgrade PRs"| platforms
  platforms --> report
  baseTokens --> report

Loading

Inside a platform repo:

flowchart TB
  foundationDep["Foundation Dependency (pinned version)"]

  subgraph manifest [Platform Manifest]
    include["include (query)"]
    exclude["exclude (query)"]
    overrides["overrides (type-safe)"]
    extensions["extensions (new tokens, registry terms, schemas)"]
  end

  foundationDep --> manifest
  manifest --> resolved[Resolved Platform Token Set]
  resolved --> outputs["Outputs: CSS vars, Swift, Kotlin, Figma vars, etc."]

  validation["GitHub Actions Validation"] --> manifest
  foundationDep --> validation

Loading

---

4. Cascade across layers

Resolution combines layer priority with semantic specificity (see RFC #646 for the token-level model):

• Layers: Foundation < Platform < Product (when product-level data exists).
• Within a layer: The most specific token wins (non-default structured properties in the name; defaults do not increase specificity).
• Platform / product overrides must remain type-safe (same token type as the foundation token they override).
• Cross-dimensional ambiguity: When overrides exist in more than one dimension (e.g. color scheme and contrast), explicit combination tokens are required; validators enforce completeness (see [DRAFT RFC] Token Schema Structure and Validation System #646).

Foundation publishes dimension declarations (available modes, default mode, coverage rules). Platforms inherit them; platform-only extensions must still validate against the spec.

---

5. Platform manifest

Each platform repo includes a manifest (name TBD, e.g. spectrum-foundation.json) declaring:

Field	Purpose
foundationVersion	Pinned foundation version (e.g. GitHub release tag / semver).
include	Optional query selecting foundation tokens/terms to include; default: all.
exclude	Optional query selecting exclusions.
overrides	Map of token identifiers to replacement values only; type must match foundation.
extensions	New tokens, registry terms, or schema extensions allowed by the spec.

Query language for include / exclude is TBD (align with JSONPath, JMESPath, or a small DSL — see open questions in #714).

---

6. Override and extension rules

• Type safety — Overrides change values, not types. CI rejects type-changing overrides.
• Extensions — New tokens or terms must conform to foundation naming and schema rules unless explicitly scoped as platform-private experimental (policy TBD).
• No rigid tier coupling — Manifests combine include/exclude, overrides, and extensions as needed; “foundation vs platform” is a layer, not a single extension kind.

---

7. Distribution

• Primary: GitHub releases from spectrum-design-data (spec artifacts, schemas, registry JSON, base tokens).
• Secondary: npm, Swift Package Manager, Rust crates, etc., mirroring the same semver where applicable.

---

8. Validation

• Where: CI in each platform repo (and optionally reference validation in foundation).
• What: Schema conformance; naming rules; type-safe overrides; valid foundation version; deprecated token usage (severity configurable); cascade / dimension coverage per [DRAFT RFC] Token Schema Structure and Validation System #646.
• Performance: Validators should support incremental checks (e.g. on save / watch) — coverage rules are naturally per token family.

---

9. Tooling ecosystem

Tool	Role
Design Data Management App	Authors curate data; writes pull requests to platform repos as the authenticated user (#625).
Figma Variable Generator	Input: resolved platform token set; output: Figma collections / modes.
Foundation Upgrade Bot	On new foundation releases, opens PRs to bump foundationVersion and apply mechanical migrations (e.g. renames from lifecycle metadata — #623).
Report / Diff Generator	Shows diff vs foundation: included subset, overrides, extensions.

---

10. Migration from monolithic structure

• Mechanical path: Today’s color-set and scale-set tokens split into individual cascade tokens with dimension properties in the structured name ([DRAFT RFC] Token Schema Structure and Validation System #646). Counts: on the order of hundreds per set type in current packages/tokens/src/.
• Consumers: Existing keyed JSON and dist outputs can continue during a transition; spec defines target authoring format and validation.
• system-set: No current data dependence; schema cleanup is a separate housekeeping task.

---

11. Deprecation and versioning

• Foundation follows semver; breaking removals require major bumps.
• Deprecation-first renames and removals align with RFC #623.
• Platforms choose when to adopt new foundation versions; the upgrade bot reduces drift.

---

12. Relationship to other RFCs

RFC	Relationship
#714	Umbrella index for the Design Data Specification.
#624	Superseded by this RFC for multi-platform / distributed structure.
#646	Token structure, dimensions, cascade specificity, validation details.
#661	Registry / glossary; terminology for dimensions and enums.
#623	Lifecycle metadata across foundation and consumers.
#625	Authoring workflow; management app and PR model.
#626	Future: sourcemaps / traceability on top of resolved + UUIDs.
#627	Tangential: DTCG export; should reflect resolved cascade when built.

---

13. Open questions

• Exact query schema for include / exclude.
• Product-level overrides within one platform repo without combinatorial explosion.
• Deprecation window before token removal (e.g. one major version).
• Policy for platform-private experimental tokens vs. spec-required publication.

---

14. Request for feedback

We want input from platform teams on manifest fields, CI severity defaults, upgrade automation, and any blockers for adopting pinned foundation versions in real repos.

Please comment on this discussion with constraints, use cases, or suggested refinements.

[GarthDB]

Note: Coordinating outline for all RFCs: docs/rfc-coordination.md. #624 was closed in favor of this RFC + #714.

[GarthDB]

Update (April 2026): Alignment with taxonomy and formatting work.

Manifest — extensions.formatting: The manifest schema now includes a typed extensions.formatting section (PR #807) with fields for:

• conceptOrder — ordered list of semantic field names for serialization
• casing — kebab-case, camelCase, PascalCase, SCREAMING_SNAKE_CASE
• delimiter — character(s) separating concepts
• abbreviations — term-to-short-form mappings

This aligns with the three-layer naming decomposition in #806: formatting (concept order, casing, delimiters, abbreviations) is a platform-malleable concern, while taxonomy and vocabulary are shared.

Cascade — semantic vs. dimension fields: The name object now distinguishes semantic fields (identity, structure, intent — advisory validation) from dimension fields (cascade axes — strict validation). Only dimension fields participate in specificity and cascade resolution. See spec/taxonomy.md and spec/token-format.md.

Resolved open questions:

• Query schema for include/exclude: Filter notation defined in spec/query.md and implemented in the CLI query subcommand.