[DRAFT RFC] Token Deprecation and Consolidation

[GarthDB]

[UPDATED] RFC: Token Lifecycle Metadata Framework

Status: Draft - Updated Based on Feedback
Author: Garth Braithwaite
Related: DNA-1458, SDS-15500, RFC #714, RFC #715, RFC #646

---

⚠️ DRAFT STATUS: This RFC is in draft form and open for feedback. It focuses on establishing a token lifecycle metadata framework and governance process. Specific token deprecations will be identified through separate initiatives (SDS-15500, SDS-15227, SDS-15229) after this framework is in place.

Recent Updates (Oct 29, 2025): Updated based on @NateBaldwinDesign's feedback to clarify scope, dependencies, and timeline. This RFC is about the infrastructure (lifecycle metadata), not about specific token deprecations.

Update (March 2026): Connected to the distributed Design Data Specification (RFC #714, RFC #715) and structured tokens / cascade (RFC #646).

---

Executive Summary

This RFC proposes a systematic token lifecycle metadata framework for the Spectrum design data system, providing the infrastructure needed to safely evolve the token system over time.

Problem: No formal lifecycle tracking or deprecation process exists, making it difficult to safely evolve the token system without breaking implementations or surprising consumers.

Solution: Establish a token lifecycle metadata schema (inspired by Swift's @available attribute) and governance-driven deprecation process that ensures backwards compatibility and clear communication. This foundational infrastructure will enable future token refinement initiatives (such as SDS-15500) to proceed safely while maintaining backwards compatibility.

---

This RFC's Specific Goal

Establish a token lifecycle metadata framework that enables the safe evolution of the token system, ensuring that consumers:

• Receive clear advance notice of deprecations
• Have time to migrate (enforced by governance process)
• Can track token history and status programmatically
• Experience zero unexpected breaking changes

---

Related Work

• SDS-15500: "Semantic token refinement and taxonomy formalization" - Epic (In Progress) - Led by Spectrum Foundations. This RFC provides the infrastructure to support this work.
• SDS-15227: "Layout token optimization (Batch 1)" - Epic tracking layout token consolidation
• SDS-15229: "Propose semantic spacing tokens" (Nate Baldwin) - Story (In Review)
• DNA-1458: "Layout token deprecation plan" - This RFC addresses this ticket
• DNA-1485: Schema improvements (In Progress) - Required for implementation
• RFC #714 — Spectrum Design Data Specification — Umbrella for the spec family
• RFC #715 — Distributed Design Data Architecture — Foundation vs platform repos, semver releases, upgrade automation
• RFC #646 — Token Schema Structure and Validation — Structured token format; lifecycle fields attach to each token record
• RFC coordination outline — Living cross-reference for editors

---

Proposal: Token Lifecycle Metadata Schema

Inspired by: Swift's @available, SassDoc's @deprecated

Every token will include lifecycle metadata:

{
  "token-name": {
    "value": "...",
    "lifecycle": {
      "introduced": "2.0.0",           // Semver when token was added
      "lastModified": "2.1.0",          // Last semver where value/metadata changed
      "status": "active",               // active | deprecated | removed
      "deprecated": null,               // Semver when marked deprecated
      "plannedRemoval": null,           // Target semver for removal
      "renamed": null,                  // New token name (if renamed)
      "message": null                   // Deprecation/migration message
    }
  }
}

Example: Deprecated Token

{
  "button-background-primary": {
    "value": "{action-background-default}",
    "lifecycle": {
      "introduced": "1.0.0",
      "lastModified": "3.0.0",
      "status": "deprecated",
      "deprecated": "3.0.0",
      "plannedRemoval": "4.0.0",
      "renamed": "action-background-default",
      "message": "Use semantic token 'action-background-default' instead. This token will be removed in 4.0.0."
    }
  }
}

---

Governance-Driven Deprecation Process

Mandatory: At least 2 monthly governance meetings must occur between deprecation announcement and token removal.

Example Timeline:

• Meeting 1: Propose deprecation → Get approval
• Meeting 2: Review migration progress, address concerns
• Meeting 3+: Final review before removal

---

Implementation Phases

Phase 1: Schema and Infrastructure

• Implement lifecycle metadata schema (DNA-1485)
  • Add lifecycle fields to Design Data JSON schema
  • Create validation rules and enforcement
  • Build tooling for automated lifecycle checks
  • Add CI/CD checks for lifecycle metadata compliance
• Begin backfilling lifecycle metadata for existing tokens

Deliverable: Token schema supports lifecycle metadata with full validation. All existing tokens have baseline lifecycle data.

---

Future Work: Using the Framework for Token Evolution

Once the lifecycle metadata framework is in place (this RFC), it will enable safe token evolution across multiple initiatives:

Semantic Token Refinement (SDS-15500)

• Led by Spectrum Foundations
• Determines taxonomy and semantic token structure
• Identifies specific tokens to deprecate/rename/consolidate
• Will use lifecycle metadata to communicate changes safely
• Timeline: In Progress (separate from this RFC)

Layout Token Work (SDS-15227, SDS-15229)

• Nate Baldwin's semantic spacing token proposal (SDS-15229, In Review)
• Layout token consolidation and optimization (SDS-15227)
• First major use case for lifecycle metadata in practice

Note: The lifecycle metadata framework (this RFC) is not dependent on these token refinement initiatives. It's an architectural enhancement that enables them to proceed safely.

---

Lifecycle metadata in a distributed architecture

The Design Data Specification assumes foundation packages publish tokens and metadata, while platform repos pin a foundation version and may add overrides/extensions (RFC #715).

• Deprecation flow: Foundation marks tokens deprecated with plannedRemoval / renamed / messages (this RFC). Platform teams consume releases on their own cadence; validators can warn or fail on deprecated usage depending on policy.
• Upgrade automation: A foundation upgrade bot can open PRs that bump the pinned version and apply mechanical renames when renamed is set — still subject to human review.
• Cascade-specific tokens: A platform-only override or dimension-specific token carries its own lifecycle record when it is not a 1:1 rename of a foundation token; when it shadows a foundation token, tooling should surface both foundation lifecycle and platform change history (exact merge rules TBD in implementation).

---

Dependencies

This RFC Requires:

• 🟡 Schema improvements (DNA-1485) - In Progress

This RFC Does NOT Require:

• ❌ Completion of semantic token refinement work (SDS-15500)
• ❌ Completion of layout token consolidation (SDS-15227, SDS-15229)
• ❌ Specific token deprecation decisions

This RFC Enables (Unblocks):

• ✅ SDS-15500: Semantic token refinement can proceed with safe deprecation process
• ✅ SDS-15227, SDS-15229: Layout token work can use lifecycle metadata
• ✅ RFC #714 / #715 — Distributed design data and semver releases use lifecycle metadata for safe upgrades
• ✅ Phase 2 repository evolution work — Safe migration paths established

---

Tooling and Automation

Build-Time Warnings

Example (CSS build warning):

Warning: Token 'button-background-primary' is deprecated as of v3.0.0
  Reason: Use semantic token 'action-background-default' instead.
  Planned removal: v4.0.0
  Migration guide: https://spectrum.adobe.com/tokens/migration/...

Example (Swift compilation warning):

@available(*, deprecated, message: "Use 'action-background-default' instead. Removal planned in 4.0.0")
static let buttonBackgroundPrimary = ...

Developer Experience

• Figma plugin shows deprecation warnings
• Token browser displays lifecycle status prominently
• IDE extensions provide deprecation warnings

---

Success Metrics

Process Metrics

• Lifecycle Metadata Coverage: 100% of tokens
• Governance Compliance: 100% of deprecations go through 2+ governance meetings
• Timeline Adherence: 90%+ of deprecations follow planned timeline
• Communication Effectiveness: 95%+ of platform teams aware before implementation

---

References

Jira Tickets

• SDS-15500: "Semantic token refinement and taxonomy formalization" - Epic (In Progress)
• SDS-15227: "Layout token optimization (Batch 1)" - Epic (In Progress)
• SDS-15229: "Propose semantic spacing tokens" - Story (In Review)
• DNA-1458: "Layout token deprecation plan" - This RFC addresses this ticket
• DNA-1485: Schema improvements (In Progress) - Required for implementation

External Inspiration

• Swift's @available Attribute
• SassDoc's @deprecated Annotation

---

📄 Full RFC: Available in internal docs with complete details on proposal, risks, alternatives, and implementation details.

[NateBaldwinDesign]

This is great @GarthDB ! I have some comments:

The problem/solution is mismatched

Problem: Users report difficulty finding the right tokens, managing complexity, and dealing with inconsistent naming. No formal lifecycle tracking or deprecation process exists.

Solution: Establish a token lifecycle metadata schema (inspired by Swift's @available attribute) and governance-driven deprecation process that ensures backwards compatibility and clear communication.

The problem defined here includes the overarching challenges we've identified, but this is not a solution to all of them. The way this is written strongly suggests that the token lifecycle metadata is the solution to this problem.

I would recommend reducing the problem definition here to the specific problem the lifecycle metadata solves: "No formal lifecycle tracking or deprecation process exists"

This is made more unclear by the Strategic Goal section, which only includes the higher level problem statement, and nothing about the lifecycle.

Alternatively rephrasing the solution to clarify or include "...to ensure the enhancements to our token system required to solve the larger problem can be clearly communicated, tracked, and managed by our team and consumers" so it's clear this doesn't solve the problems of discoverability, managing complexity, or naming issues.

Context item questions

Two items in your context origin section have me confused

August 2025: Core token set determination completed (layout tokens foundation)
We did not determine what the core token set would be, aside from an action item to determine what would be "foundational" based on the semantic token work. I'm curious what you mean by this is completed, and what is documented.

September 2025: Token name taxonomy RFC approved
This is also confusing, as the Semantic token refinement and taxonomy formalization initiative / (led by Spectrum Foundations SDS-15500) is the work that would determine the taxonomy and terms used in token names.

Could you clarify what this is referring to with links to provide context?

Related work

Could we add SDS-15500 to this list?

Proposal

I really like this proposal 👏. The level of granularity in the lifecycle data is a much more sophisticated solution than simple deprecated status. I think this would be tremendously helpful in managing design data especially across multiple versions (as consumers will never all be on the same version at a time). It's a great way to preemptively provide deprecation information for consumers alongside the data, rather than requiring them to find that information elsewhere.

Timeline

This looks like a timeline for the entirety of the semantic token work, rather than a timeline for this specific proposal (adding metadata to tokens / schema). This positions the proposal as being dependent upon asynchronous work, which it should not be if it's merely about adding this new metadata into the token system.

Is this RFC proposal about adding metadata, or is it about the entirety of the refinement initiative (adding semantic tokens, deprecating old ones)? My impression is that the proposal you're making is an architectural enhancement that will support the refinement work, but it is not dependent upon it to be implemented.

If this work is dependent upon the other work, I have other details as the January time frame is only for Layout tokens; not for other token types. Also that work is tracked under SDS-15500.

Related links redundancy

It's a bit unclear what the difference is between the "Related work" section and "Related links" at the bottom.

[GarthDB]

Thanks so much for this detailed feedback @NateBaldwinDesign! These are excellent points that really clarify the scope and dependencies. Let me address each:

1. Problem/Solution Mismatch ✅

You're absolutely right - the broader discoverability and complexity issues are what SDS-15500 addresses, and this RFC provides the infrastructure to support that work safely.

Updated to:

Problem: No formal lifecycle tracking or deprecation process exists, making it difficult to safely evolve the token system without breaking implementations or surprising consumers.

Solution: Establish lifecycle metadata schema and governance process that ensures backwards compatibility and clear communication. This foundational infrastructure will enable future token refinement initiatives (such as SDS-15500) to proceed safely.

I also added a "This RFC's Specific Goal" section to make the scope crystal clear.

2. Context Questions ✅

Good catches on both:

"Core token set determination completed" - You're right, this wasn't completed. I've rephrased this to:

August 2025 Onsite: Identified need to determine "foundational" token set (to be addressed by semantic token refinement work)

"Token name taxonomy RFC approved" - Updated to reference SDS-15500 as the actual taxonomy work:

October 2025: Semantic token refinement and taxonomy formalization initiative (SDS-15500) underway, led by Spectrum Foundations

3. Related Work - SDS-15500 ✅

Absolutely! Added SDS-15500 to Related Work with the Paper doc link:

SDS-15500: "Semantic token refinement and taxonomy formalization" - Epic (In Progress) - Led by Spectrum Foundations, determines the taxonomy and terms used in token names. This RFC provides the infrastructure to support this work.

4. Proposal ✅

Glad you like the lifecycle metadata approach! The goal is exactly what you said - managing tokens across multiple versions safely. The Swift @available pattern has worked really well in the iOS ecosystem for this exact problem.

5. Timeline - Critical Clarification ✅

This was the most important feedback. You're absolutely right - this RFC is about the architectural enhancement (lifecycle metadata), NOT about the entirety of the refinement work.

I've completely restructured the Timeline section:

This RFC: Lifecycle Metadata Framework (Nov-Dec 2025)

• Nov 7 Governance Meeting: Present RFC for approval
• Post-Approval: Implement lifecycle metadata schema (DNA-1485)
  • Add lifecycle fields to JSON schema
  • Create validation rules
  • Build tooling for automated checks
  • CI/CD enforcement
• Nov-Dec 2025: Backfill lifecycle metadata for existing tokens

Deliverable: Token schema supports lifecycle metadata with full validation

Future Work: Using the Framework (Q1-Q2 2026+)

Clearly separated section showing how SDS-15500 and your layout token work (SDS-15227, SDS-15229) will use this framework once it's ready.

Added explicit note:

The lifecycle metadata framework (this RFC) is not dependent on these token refinement initiatives. It's an architectural enhancement that enables them to proceed safely.

I also updated the Dependencies section to make this crystal clear:

### This RFC Does NOT Require:
- ❌ Completion of semantic token refinement work (SDS-15500)
- ❌ Completion of layout token consolidation (SDS-15227, SDS-15229)
- ❌ Specific token deprecation decisions

### This RFC Enables (Unblocks):
- ✅ SDS-15500: Semantic token refinement can proceed with safe deprecation process
- ✅ SDS-15227, SDS-15229: Layout token work can use lifecycle metadata

Also noted your point about the January timeframe being for layout tokens only (tracked under SDS-15500).

6. Related Links Redundancy ✅

Reorganized to reduce duplication. "Related Work" (near top) stays focused and concise, "References" (at bottom) includes the Paper doc link and all Jira tickets with clear annotations.

---

Updated RFC

I've updated the full RFC with all these changes. I'll post the updated version as a new comment below. The scope is now much clearer:

This RFC delivers: Lifecycle metadata infrastructure (Nov-Dec 2025)
Future work: Specific token deprecations using that infrastructure (SDS-15500, SDS-15227, etc.)

Thanks again for the thorough review - this really helps clarify the architecture vs. implementation distinction! 🙏

[GarthDB]

Update (March 2026): Added lifecycle in a distributed architecture and cross-links to #714, #715, #646.

[GarthDB]

Resolution: Token Lifecycle Model

PR #793 implements the lifecycle model discussed in this RFC. Closes #736.

What was adopted

Field	Type	Description
deprecated	string (version)	Spec version when deprecated (e.g. "3.2.0") — was boolean
deprecated_comment	string	Human-readable explanation — unchanged
replaced_by	UUID or UUID[]	Machine-actionable replacement pointer — replaces renamed
plannedRemoval	string (version)	Target removal version (optional)
introduced	string (version)	When token was first added (optional)

What was intentionally skipped

• status — derivable from presence of deprecated (no field = active, has field = deprecated, not in dataset = removed)
• lastModified — redundant with git history
• lifecycle wrapper object — fields are top-level on the token, not nested
• Graduated severity levels (WARNING/ERROR/HIDDEN) — implicit from version progression

Design rationale

Inspired by Swift @available (version-tagged + renamed), Kotlin @Deprecated (required message + ReplaceWith), and OpenAPI 3.3 proposed deprecation (deprecatedAt + sunset + successor).

Key difference from this RFC: replaced_by uses UUID instead of token name, making it unambiguous in cascade format. Legacy output generates renamed from replaced_by via UUID resolution.

Normative documents

• spec/token-format.md — field definitions and normative rules
• spec/evolution.md — deprecation lifecycle, migration windows, change classification
• Validation rules SPEC-010 through SPEC-013 enforce lifecycle field constraints

[GarthDB]

Update (April 2026): This RFC's lifecycle model is implemented and normative.

The lifecycle fields adopted via PR #793 (deprecated, deprecated_comment, replaced_by, plannedRemoval, introduced) are documented in spec/token-format.md and the evolution policy is in spec/evolution.md. The Rust SDK validates lifecycle metadata as part of the standard validation pipeline.

This RFC remains open as the design rationale reference for the implemented model.