Migrating custom implementations to Wix Design System linked tokens ยท May 2026
To get started, run this command in your terminal:
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
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.
.css/.scss/.st.css and style={{ in .tsx โ see AuditFind 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.
// TODO [ticket] and keep movingSwap hardcoded values for --wds-* CSS custom properties and replace inline style overrides on WDS components with the correct skin or size props.
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.
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.
Token tiers
| Tier | File | Use it for |
|---|---|---|
| Foundation | foundation.st.css | Raw palette values. |
| Semantic | semantic.st.css | Intent-driven aliases. Primary migration target. |
| Component | component.st.css | Component-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
| Type | On theme change |
|---|---|
--wds-* CSS var or Stylable variable | Updates automatically |
| Hardcoded hex, pixel value, font name | Never 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 -.
Commands
Also check:
.st.css files importing WDS variables without @wix/design-system-tokens โ using stale copies.Button .root { background: ... }) โ bypasses token layerAudit template
Use this audit template to track the issues. This template is completely optional, depending on your needs.
| Component / Surface | Property | Current value | Target WDS token | Owner | Status |
|---|---|---|---|---|---|
| PrimaryButton | background | #2F5DFF | --wds-color-fill-standard-primary | Dev | To do |
| CardTitle | color | #151414 | --wds-color-text-standard-primary | Dev | To do |
| Divider | border-color | #DEDEDE | --wds-color-border-dark-secondary | Dev | In progress |
| SectionHeading | font-family | "Arial" | --wds-font-family-heading | Design | Blocked |
All tokens from @wix/design-system-tokens. Values shown are light theme defaults.
Colour โ Fill (Background)
| Use case | Custom pattern | WDS 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 |
| Warning | Yellow tones | --wds-color-fill-warning-light |
| Success | Green tones | --wds-color-fill-success-light |
Colour โ Text & Icon
| Use case | Custom pattern | WDS 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 case | Custom pattern | WDS token |
|---|---|---|
| Standard | #767574 | --wds-color-border-dark-primary |
| Destructive | #DF3336 | --wds-color-border-destructive |
Typography
| Use case | Custom pattern | WDS 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 โ size | 32px | --wds-font-size-heading-1 |
| Heading 1 โ line height | 32px | --wds-font-line-height-heading-1 |
| Heading 1 โ letter spacing | -0.5px | --wds-font-letter-spacing-heading-1 |
| Heading 1 โ weight | 500 / Medium | --wds-font-weight-heading-1 |
Component skin Prop Mapping
| Component | Wrong | Correct |
|---|---|---|
| Button | style={{ background: "#2F5DFF" }} | skin="standard" |
| Button | style={{ background: "#DF3336" }} | skin="destructive" |
| Text | style={{ color: "#151414" }} | skin="standard" |
| Text | style={{ color: "#DF3336" }} | skin="error" |
CSS / Stylable
Stylable import:
WDS Component Props
Box / Custom Containers
For non-WDS containers:
If you can't explain in one sentence why a value can't be a WDS token, it should be a WDS token.
| Situation | Action | Note in code |
|---|---|---|
| Token exists | Migrate | โ |
| Intentional brand deviation (e.g. campaign) | Keep, scope tightly and mark in code | // intentional โ [reason] |
| Token almost fits | Raise gap request, try to find new value | // TODO: migrate when [token] โ [ticket] |
| Token doesn't exist yet | Ship with temp value, raise request. No design work needed unless it's genuinely unclear | // TEMP: replace with --wds-[name] โ [ticket] |
You can use this checklist to help you navigate the migration period clearly.
Visual QA
Accessibility
Code Review
style props where skin is correctstyle props on WDS components--wds-* usage vs. hardcoded values per component// TEMP in the meantime. Design exploration only when the right token is genuinely unclear| I need toโฆ | Go to |
|---|---|
| Follow the migration process | Migration Process |
| Find a colour token | Colour tokens |
| Find a typography token | Typography tokens |
Know which skin prop to use | skin prop mapping |
| Find custom values in my codebase | Audit |
| See before/after code examples | Code Patterns |
| Decide if a custom value is ok | When to Keep |
| Run a QA pass | Validation Checklist |
| Install WDS tokens | npm install @wix/design-system-tokens |
| Browse WDS components | Components |
| Get help | #ux_on_wds or #wix-design-system |
Anything unclear โ token mappings, edge cases, missing tokens:
Last updated: 30 July 2026