Design token deprecation strategy: replace, migrate, and remove without breaking consumers

Deprecation means a token should move toward retirement. It doesn't mean the token is unused, every consumer has a replacement, or deletion is safe. A token can remain deprecated for several releases while its references, exports, components, and applications move away from it.

Treat lifecycle states as project policy. Don't assume that a metadata field, naming convention, or design-token format enforces the same behavior. The frozen DTCG document in the evidence set is a preview that explicitly says not to implement or cite it as authoritative. This guide therefore doesn't depend on a proposed $deprecated property.

Start at the authoritative token definition, then follow every place its name or resolved value can travel. Token references form a graph, so searching for the old identifier is necessary but insufficient. A direct reference may feed another semantic token, which may become a CSS custom property, a Tailwind theme value, a registry payload, and finally a component style.

1. 1

   Locate the authoritative definition

   Record the exact source file or system, token path, type, mode values, version, and owner. If two artifacts both appear authoritative, resolve that ownership conflict before migration.

2. 2

   Trace direct and transitive references

   Find tokens that reference the old token directly, then follow their dependants. Record resolved references separately from textual matches so a renamed intermediate token doesn't hide the chain.

3. 3

   List supported modes and themes

   Record every mode in which the token resolves, such as light and dark. The replacement may be equivalent in one mode and wrong in another.

4. 4

   Enumerate governed outputs

   List the CSS, Tailwind, DTCG, shadcn registry, platform, or other generated artifacts your project actually produces. For each output, record the expected old and new identifiers.

5. 5

   Name component and application consumers

   Choose concrete components, templates, routes, and applications. Include representative states such as hover, focus, disabled, error, and data-heavy variants when they consume the token differently.

6. 6

   Find local overrides and copied values

   Search for local variables, hardcoded resolved values, detached component styles, theme overrides, and stale generated files. A copied value won't appear in an identifier search, so inspect high-risk surfaces as well.

The result should read as a chain: source token, referenced tokens, mode resolutions, generated identifiers, shared components, application consumers, and exceptions. Record any gap between layers. Don't fill it with an assumption.

A rename sounds like a one-to-one operation, but the old token may have accumulated several meanings. For example, a broadly named color.action token might control button fills, links, focus rings, and selected navigation. Replacing every use with color.action.primary would preserve the old coupling under a cleaner name.

A fifth option is no replacement. Use it when the capability or visual decision is being removed instead of renamed. The migration then removes the consuming behavior or moves it to a non-token mechanism that has been explicitly approved. Don't invent a replacement merely to make the record look complete.

Keep the decision and its evidence together. Splitting the source change, consumer list, exception log, and approval across separate tickets makes it hard to tell whether the migration is complete. The following record is tool-neutral. Add project-specific fields only when they have a named consumer.

deprecationId: token-color-action-to-primary
status: deprecated
source:
  owner: design-systems
  artifact: tokens/source.json
  version: "illustrative-version"
deprecatedToken:
  path: color.action
  type: color
  reason: "Illustrative rename to clarify semantic role"
replacement:
  topology: one-to-one
  mappings:
    - from: color.action
      to: color.action.primary
  unresolved: []
affectedModes:
  - light
  - dark
references:
  direct: []
  transitive: []
generatedOutputs:
  - artifact: tokens.css
    oldIdentifier: --color-action
    expectedNewIdentifier: --color-action-primary
  - artifact: tailwind-theme.json
    oldIdentifier: color-action
    expectedNewIdentifier: color-action-primary
consumers:
  components:
    - name: PrimaryButton
      owner: ui-platform
      states: [default, hover, focus, disabled]
  applications:
    - name: account-settings
      owner: product-team
      surfaces: [profile-save]
localOverrides: []
compatibilityMechanism:
  kind: none-verified
  note: "Do not assume alias support"
observations: []
unchangedSurfaces:
  - secondary-actions
exceptions: []
deadline: "project-owned date"
disposition: migrate
approver: null
decisionEvidence: []

The record separates facts from intentions. expectedNewIdentifier states what regeneration should produce, but it isn't evidence that the artifact was regenerated. consumers names what must move, but it doesn't show that the application loaded the new version. Put observed results in observations. Attach the relevant build, diff, test, screenshot, or release reference under decisionEvidence, following your project's evidence system.

The following fixture demonstrates the sequence without claiming that Identity Forge or any delivery tool manages deprecation, discovers consumers, provides aliases, or performs migration. The token names, values, files, and results are illustrative.

{
  "color": {
    "action": {
      "$type": "color",
      "$value": "#5B5CE2"
    },
    "button": {
      "primary": {
        "$type": "color",
        "$value": "{color.action}"
      }
    }
  }
}

{
  "color": {
    "action": {
      "primary": {
        "$type": "color",
        "$value": "#5B5CE2"
      }
    },
    "button": {
      "primary": {
        "$type": "color",
        "$value": "{color.action.primary}"
      }
    }
  }
}

Equal color values can reduce immediate visual change, but they don't close the migration. The old identifier may remain in generated CSS, a cached registry item, an application theme, or a local override. A text search may find no old identifier even though a copied #5B5CE2 remains in a component. The record must cover both identifier flow and representative rendered behavior.

1. 1

   Approve the semantic decision

   Confirm why the old token is changing, who owns the decision, and whether the mapping is one-to-one, split, consolidation, contextual, or no replacement. Block new adoption using only controls your project has verified.

2. 2

   Update the authoritative source and references

   Add or change the replacement in the source of truth. Resolve direct and chained references there before treating generated files as current.

3. 3

   Regenerate every governed output

   Run the normal generators for each output in scope. Compare the result with the record: expected new identifiers must appear, and old identifiers must remain or disappear exactly as the migration stage requires.

4. 4

   Migrate named component consumers

   Update shared components before broad application surfaces where possible. Check the recorded variants and interaction states for each component instead of approving only its default state.

5. 5

   Migrate named application consumers

   Confirm that each application uses the intended artifact version. Inspect representative routes and realistic content instead of relying solely on a source-code match.

6. 6

   Check every supported mode

   Exercise light, dark, and any other supported mode listed in the record. Compare semantic behavior, not only whether both modes render without an error.

7. 7

   Inspect unchanged surfaces

   Choose surfaces that shouldn't change and verify that they didn't drift. This catches replacement maps or generators whose reach is broader than expected.

8. 8

   Close or assign exceptions

   Every unresolved consumer, override, stale artifact, or unavailable observation needs an owner and a next decision. An exception without an owner blocks removal.

Keep the old token during this sequence unless your project's verified compatibility mechanism makes a different order safe. Removing it early turns missing inventory into breakage. Keeping it forever leaves two apparent choices and invites new use. The lifecycle therefore needs both a new-use block and a removal gate.

This order prevents wasted work: patching an application when the source mapping is wrong, or changing the source repeatedly when one application is loading a stale artifact. Route the failure to the earliest layer whose observation differs from the record.

Removal should be a recorded decision, not the absence of objections. Complete the evidence matrix immediately before deleting the old token. Migration evidence can go stale when consumers or generated artifacts change.

• Keep: the old token still has a valid, supported meaning. Remove the deprecation state or narrow the proposal.
• Migrate: the replacement is valid, but named work or observations remain. Keep the old token and continue the recorded migration.
• Remove: every gate passes, governed outputs and consumers no longer require the old token, and an accountable owner authorizes deletion.
• Block: a dependency, mapping, mode, artifact, consumer, owner, exception, or evidence field is unresolved. Don't delete the token.

Choose one token currently proposed for retirement and complete the migration record before editing it. If any dependency, replacement, consumer, owner, mode, artifact, exception, or evidence field remains unresolved, set the disposition to block and keep the old token in place.

• Deprecating in design systems: When it's time to say goodbye: The guide treats deprecation as a sequenced dependency, replacement, communication, risk, migration, and deletion problem, including references from tokens, templates, and complex components.
• Design Tokens: The Foundation of Your UI Arch: The article describes token references as a dependency graph and treats tokens as governed interfaces delivered to downstream consumers.
• Design Tokens in Webstudio: A Practical Implementation Guide: The guide covers layered token architecture, maintenance, exports, custom code, and integrations, showing why a source change can affect several downstream layers.
• Design Tokens Format Module 2025.10: The captured document identifies itself as a preview draft and explicitly says not to implement it or cite it as authoritative.
• Token Values with References - Tokens Studio for Figma: The documentation explains reference behavior inside Tokens Studio and provides an example of product-specific deprecation behavior that should not be generalized to every token tool.