DocsBack to homepage

Start Here

  • Getting Started
  • Key Concepts

Design Tokens

  • Token Types
  • Token Modes
  • Token Enforcement
  • Deprecated Tokens
  • Quality and Accessibility

Components

  • Component Builder
  • Composition Rules

Publishing

  • Publishing
  • Docs Mode
  • Changelog Notifications
  • Notifications and Alerts

Integrations

CLI & Data

  • CLI Reference
  • CLI Configuration
  • Import Formats
  • Importing Tokens
  • Export Formats

Tooling

  • Studio AI Assistant
  • Figma Plugin
  • API Reference
  • Webhooks

Account & Billing

  • Audit Log
  • Security and Access
  • Account Security
  • Pricing and Payments

Documentation

Deprecated Tokens

Mark any primitive token as deprecated to guide consumers toward a replacement. The deprecation status, replacement pointer, and reason are published with your docs so every team that consumes the package knows exactly what to switch to.

Marking a token deprecated

Open a primitive token in Studio by clicking its row in the token table. In the drawer that opens on the right, scroll to the Deprecation section and toggle Mark as deprecated on.

Two fields appear below the toggle.

  • Replaced by (optional): a select menu listing all other primitives in the same design system. Pick the token consumers should use instead.
  • Reason (optional): a short explanation that appears in your published docs and in consumer change summaries.

The change is saved when you blur the reason field or select a replacement. No separate save button is needed.

Visual indicators in Studio

Deprecated tokens show an amber Deprecated badge next to their name in the token list. The name is also shown with a strikethrough and reduced opacity so the status is visible at a glance without opening the drawer.

What consumers see

When you publish, the deprecation status travels with the token. In the published docs portal, deprecated tokens display:

  • An amber warning box at the top of the token detail panel.
  • The replacement token name as a link, when a replacement was set.
  • The reason text, when one was provided.

Consumer change summaries generated at publish time also include deprecation notices so engineering teams see what to migrate before they upgrade the package.

Undoing a deprecation

Toggle Mark as deprecated off. The replacement and reason fields are cleared automatically and the token returns to normal status on the next publish.