Token Migration Guidelines


Migrating custom implementations to Wix Design System linked tokens ยท May 2026


Migration Process

To get started, run this command in your terminal:

Copy

This installs the migration skill, which handles converting your tokens to WDS theming.

For full details on what the skill does, see the source and documentation on GitHub. This guide is here when you need to understand a specific step or handle something the automation flags as unclear.

For any questions, feel free to reach out to #ux_on_wds and #wix-design-system


1. Identify custom values

Search your codebase for hardcoded values that should be tokens: hex colours, pixel font sizes, font-family strings, and inline style props on WDS components.


2. Map to WDS tokens

Find the correct WDS semantic token for each custom value using the token tables. Most cases resolve directly in code - no design input needed. If the right token isn't obvious, ask in #ux_on_wds or #wix-design-system before inventing a value.


3. Replace custom values

Swap hardcoded values for --wds-* CSS custom properties and replace inline style overrides on WDS components with the correct skin or size props.


4. Test across all themes

Verify the migrated component updates correctly across all applicable themes. Check all interactive states (hover, focus, disabled, selected) and feedback states (error, warning, success) - not just the default.


5. Review

You may want to review with your teams' UX, especially if there were deviations from previous design. Reviewers check: no new hardcoded values, no style props where skin is correct, all exceptions commented.

  • If using spreadsheet mark rows as Done
  • Anything that can't be migrated now โ†’ backlog ticket + code comment

Core Concepts

Token tiers

TierFileUse it for
Foundationfoundation.st.cssRaw palette values.
Semanticsemantic.st.cssIntent-driven aliases. Primary migration target.
Componentcomponent.st.cssComponent-scoped values. Only for building/forking WDS components.

When a component is properly linked to tokens it inherits all themes automatically.

Linked vs. custom values

TypeOn theme change
--wds-* CSS var or Stylable variableUpdates automatically
Hardcoded hex, pixel value, font nameNever updates
skin prop override via style={{ }}May work in one theme, breaks in others

Figma โ†’ CSS variable naming

Prepend --wds-, lowercase, replace / and spaces with -.

Copy

Audit

Commands

Copy

Also check:

  • .st.css files importing WDS variables without @wix/design-system-tokens โ€” using stale copies
  • Component-level CSS that styles WDS internals (e.g. .Button .root { background: ... }) โ€” bypasses token layer

Audit template

Use this audit template to track the issues. This template is completely optional, depending on your needs.

Component / SurfacePropertyCurrent valueTarget WDS tokenOwnerStatus
PrimaryButtonbackground#2F5DFF--wds-color-fill-standard-primaryDevTo do
CardTitlecolor#151414--wds-color-text-standard-primaryDevTo do
Dividerborder-color#DEDEDE--wds-color-border-dark-secondaryDevIn progress
SectionHeadingfont-family"Arial"--wds-font-family-headingDesignBlocked

Token Mapping Reference

All tokens from @wix/design-system-tokens. Values shown are light theme defaults.

Colour โ€” Fill (Background)

Use caseCustom patternWDS token
Primary action#2F5DFF--wds-color-fill-standard-primary
Dark secondary#DEDEDE--wds-color-fill-dark-secondary
Dark secondary โ€” hover#E8E7E7--wds-color-fill-dark-secondary-hover
WarningYellow tones--wds-color-fill-warning-light
SuccessGreen tones--wds-color-fill-success-light

Colour โ€” Text & Icon

Use caseCustom patternWDS token
Primary text#151414--wds-color-text-standard-primary
Interactive / link#2F5DFF--wds-color-text-primary
Destructive / error#DF3336--wds-color-text-destructive

Colour โ€” Border

Use caseCustom patternWDS token
Standard#767574--wds-color-border-dark-primary
Destructive#DF3336--wds-color-border-destructive

Typography

Use caseCustom patternWDS token
Heading font family"Wix Madefor Display" / "Arial"--wds-font-family-heading
Body font family"Wix Madefor Text" / "Arial"--wds-font-family-body
Heading 1 โ€” size32px--wds-font-size-heading-1
Heading 1 โ€” line height32px--wds-font-line-height-heading-1
Heading 1 โ€” letter spacing-0.5px--wds-font-letter-spacing-heading-1
Heading 1 โ€” weight500 / Medium--wds-font-weight-heading-1

Component skin Prop Mapping

ComponentWrongCorrect
Buttonstyle={{ background: "#2F5DFF" }}skin="standard"
Buttonstyle={{ background: "#DF3336" }}skin="destructive"
Textstyle={{ color: "#151414" }}skin="standard"
Textstyle={{ color: "#DF3336" }}skin="error"

Code Migration Patterns

CSS / Stylable

Copy
Copy

Stylable import:

Copy

WDS Component Props

Copy

Box / Custom Containers

Copy

For non-WDS containers:

Copy

When to Keep a Custom Value

If you can't explain in one sentence why a value can't be a WDS token, it should be a WDS token.

SituationActionNote in code
Token existsMigrateโ€”
Intentional brand deviation (e.g. campaign)Keep, scope tightly and mark in code// intentional โ€” [reason]
Token almost fitsRaise gap request, try to find new value// TODO: migrate when [token] โ€” [ticket]
Token doesn't exist yetShip with temp value, raise request. No design work needed unless it's genuinely unclear// TEMP: replace with --wds-[name] โ€” [ticket]

Validation Checklist

You can use this checklist to help you navigate the migration period clearly.

Visual QA

  • Component updates correctly across all applicable themes
  • All interactive states pass: hover, pressed, focus, disabled, selected
  • All feedback states pass: error, warning, success, neutral
  • Grep confirms no hardcoded values remain

Accessibility

  • Contrast check passes (especially non-standard surface/text combos)
  • Focus rings visible across themes

Code Review

  • PR references resolved audit rows
  • Screenshots cover all applicable themes
  • Remaining custom values have justification comments
  • No new hardcoded hex, pixel font sizes, or font families
  • No WDS component style props where skin is correct

Ongoing Governance

  • Stylelint โ€” flag hardcoded hex values; exceptions need a comment
  • ESLint โ€” warn on style props on WDS components
  • CI token report โ€” track --wds-* usage vs. hardcoded values per component
  • Token gaps โ€” confirm gap โ†’ check open requests โ†’ raise request (use case, name, tier) โ†’ ship a // TEMP in the meantime. Design exploration only when the right token is genuinely unclear
  • PR template โ€” add "no hardcoded values / use skin props" as a standing checklist item

Quick Reference

I need toโ€ฆGo to
Follow the migration processMigration Process
Find a colour tokenColour tokens
Find a typography tokenTypography tokens
Know which skin prop to useskin prop mapping
Find custom values in my codebaseAudit
See before/after code examplesCode Patterns
Decide if a custom value is okWhen to Keep
Run a QA passValidation Checklist
Install WDS tokensnpm install @wix/design-system-tokens
Browse WDS componentsComponents
Get help#ux_on_wds or #wix-design-system

Support

Anything unclear โ€” token mappings, edge cases, missing tokens:

  • #ux_on_wds โ€” design system questions, token gaps, design guidance
  • #wix-design-system โ€” general WDS questions and implementation help





Last updated: 30 July 2026

Did this help?