> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Token Migration Guidelines

## Article: Token Migration Guidelines

## Article Link: https://dev.wix.com/docs/wix-design-system/contributing/token-migration-guidelines.md

## Article Content:

<!-- heading -->

# Token Migration Guidelines

<!-- end heading -->

<br />


**Migrating custom implementations to Wix Design System linked tokens** · May 2026

---

## Migration Process

To get started, run this command in your terminal:

```bash
npx @wix/aicm skills add migrate-to-wds-theming -g
```
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](invalid-url). 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.

- Grep for hex values in `.css`/`.scss`/`.st.css` and `style={{` in `.tsx` — see [Audit](#/page/contributing/tokensmigration?s=audit)
- If you choose to log each finding, here's an [audit spreadsheet template](#/page/contributing/tokensmigration?s=audit)

---

### 2. Map to WDS tokens

Find the correct WDS semantic token for each custom value using the [token tables](#/page/contributing/tokensmigration?s=token-mapping-reference). 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](#/page/contributing/tokensmigration?s=support) before inventing a value.

- Colours → [Colour tokens](#/page/contributing/tokensmigration?s=token-mapping-reference)
- Typography → [Typography tokens](#/page/contributing/tokensmigration?s=token-mapping-reference)
- WDS component colours → [skin prop mapping](#/page/contributing/tokensmigration?s=token-mapping-reference)
- No match? Add a `// TODO [ticket]` and keep moving

---

### 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.

- CSS/Stylable: see [Code Migration Patterns](#/page/contributing/tokensmigration?s=code-migration-patterns)
- WDS components: see [skin prop mapping](#/page/contributing/tokensmigration?s=token-mapping-reference)
- Intentional exceptions must have a justification comment - see [When to Keep](#/page/contributing/tokensmigration?s=when-to-keep-a-custom-value)

---

### 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.

- Use the [validation checklist](#/page/contributing/tokensmigration?s=validation-checklist)
- Include screenshots across themes in your PR

---

### 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**

| 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 `-`.

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```
Color/Fill/Standard/standard-primary  →  --wds-color-fill-standard-primary
Font/Heading/font-family-heading      →  --wds-font-family-heading
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

---

## Audit

**Commands**

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```bash
# Hex colours in style files
grep -rn "#[0-9A-Fa-f]\{3,6\}" src/ --include="*.css" --include="*.scss" --include="*.st.css"

# Colours in TSX style objects
grep -rn "color:\s*['\"](\#\|rgb)" src/ --include="*.tsx"

# Inline style overrides (highest risk)
grep -rn "style={{" src/ --include="*.tsx"

# Hardcoded skin props
grep -rn 'skin="' src/ --include="*.tsx"
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

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 / 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 |

## Token Mapping Reference

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"` |


## Code Migration Patterns

**CSS / Stylable**

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```css
/* ❌ BEFORE */
color: #151414;
color: #2F5DFF;
color: #DF3336;
background: #2F5DFF;
background: #EAEFFF;
border-color: #DEDEDE;
font-family: "Wix Madefor Display";
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```css
/* ✅ AFTER */
color: var(--wds-color-text-standard-primary);
color: var(--wds-color-text-primary);
color: var(--wds-color-text-destructive);
background: var(--wds-color-fill-standard-primary);
background: var(--wds-color-fill-standard-tertiary-hover);
border-color: var(--wds-color-border-dark-secondary);
font-family: var(--wds-font-family-heading);
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

Stylable import:

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```css
:import {
  -st-from: "@wix/design-system-tokens/semantic.st.css";
  -st-named: --wds-color-fill-standard-primary,
             --wds-color-text-standard-primary;
}
.root { background: var(--wds-color-fill-standard-primary); }
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

**WDS Component Props**

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```tsx
// ❌ BEFORE
<Button style={{ background: "#2F5DFF" }}>Save</Button>
<Badge style={{ background: "#F4B8B9" }}>Error</Badge>
<Text style={{ color: "#DF3336" }}>Invalid email</Text>

// ✅ AFTER
<Button skin="standard">Save</Button>
<Badge skin="danger">Error</Badge>
<Text skin="error">Invalid email</Text>
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

**Box / Custom Containers**

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```tsx
// ❌ BEFORE
<Box style={{ background: "#F7F8FA", borderColor: "#DEDEDE" }}>

// ✅ AFTER
<Box backgroundColor="A-10" border="1px solid" borderColor="D-10">
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

For non-WDS containers:

<!-- grid layout -->

<!-- grid layout item -->

<!-- grid layout content -->

```css
.container {
  background: var(--wds-color-fill-standard-tertiary);
  border: 1px solid var(--wds-color-border-dark-secondary);
}
```

<!-- end grid layout -->

<!-- end grid layout item -->

<!-- end grid layout content -->

---

## 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.

| 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]` |


## 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 process | [Migration Process](#/page/contributing/tokensmigration?s=migration-process) |
| Find a colour token | [Colour tokens](#/page/contributing/tokensmigration?s=token-mapping-reference) |
| Find a typography token | [Typography tokens](#/page/contributing/tokensmigration?s=token-mapping-reference) |
| Know which `skin` prop to use | [skin prop mapping](#/page/contributing/tokensmigration?s=token-mapping-reference) |
| Find custom values in my codebase | [Audit](#/page/contributing/tokensmigration?s=audit) |
| See before/after code examples | [Code Patterns](#/page/contributing/tokensmigration?s=code-migration-patterns) |
| Decide if a custom value is ok | [When to Keep](#/page/contributing/tokensmigration?s=when-to-keep-a-custom-value) |
| Run a QA pass | [Validation Checklist](#/page/contributing/tokensmigration?s=validation-checklist) |
| Install WDS tokens | `npm install @wix/design-system-tokens` |
| Browse WDS components | [Components](#/component/button) |
| Get help | [#ux_on_wds or #wix-design-system](#/page/contributing/tokensmigration?s=support) |

---

## 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

<br>
<br>
<br>
<br>
<br>