> 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: Tokens and Theming basics

## Article: Tokens and Theming Basics

## Article Link: https://dev.wix.com/docs/wix-design-system/foundations/tokens-and-theming-basics.md

## Article Content:

<!-- heading -->

# Tokens and Theming Basics

<!-- end heading -->

## 1. Introduction

Design tokens and theming play a key role in bridging the gap between design and code. This guide explains how tokens and theming work, why you should use tokens, and how they are structured in the Wix Design System.

![The same interface rendered in several Wix themes](https://wixmp-833713b177cebf373f611808.wixmp.com/images/52a1bc74cdd5db1413c8e3c94b09678f.png)

### 1.1 Who should use this guide?

This guide serves as a general introduction to tokens and tokenization. It is intended for both designers and developers looking to understand how tokens work in the Wix Design System.

### 1.2 What are tokens and themes?

**Tokens** store design-related values and can be applied consistently across different themes. They provide a consistent structure while allowing values to change per theme.

**Themes** are collections of visual attributes assigned to the tokens to create a specific aesthetic.

Design tokens are reusable CSS variables that store design decisions such as colors, typography, spacing, and shadows. Instead of manually setting these values in designs or code, tokens act as a single source of truth. This ensures consistency across products and platforms through a theme. 

![A raw design value replaced by a token shared between design and code](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e3cce083729d0dd19b8169096dd63364.png)
### 1.3 Why use tokens?

**Consistency**: Tokens enforce uniformity across UI components, reducing visual discrepancies.

**Scalability and easier maintenance**: Updating a token propagates changes across the system without requiring manual adjustments to multiple components.

![One border token reused across several components](https://wixmp-833713b177cebf373f611808.wixmp.com/images/43513dd5a3a02a8c2d0d2b95a361e67e.png)

**Efficiency**: Tokens allow developers to start implementation early, even when a product's theme is still being refined by designers. This speeds up development without compromising design accuracy, as the components used remain the same.

**Brand consistency**: Creating new products, maintaining uniformity, and managing a brand is becoming more accessible, faster, and cheaper with a transparent visual hierarchy system. This allows each Wix Editor or dashboard to have a distinct UI while preserving a unified UX and behavior. 

![One token structure carrying several brand identities](https://wixmp-833713b177cebf373f611808.wixmp.com/images/1f93e1e3eba2ca315f7c2d7e9e180462.png)

### 1.4 What can be controlled with tokens?

* Colors
* Spaces
* Border width  
* Corner radius   
* Shadows   
* Text - size, weight, line height  ([see guide on Typography](#/component/typography))

Tokens control visual aspects like color, spacing, and typography, but not structural properties. For example, a component's default behavior, such as a prefix being enabled, can't be toggled using tokens and must be adjusted via the component's properties.

## 2. Tokens structure

The Wix Design System is built on three levels of tokens: **foundation tokens**, **semantic tokens**, and **component-level** tokens. 

These levels are interrelated. **Foundation tokens** define raw design values, such as colors, spacing, and typography, which serve as the base of the system. **Semantic tokens** reference these foundation values and apply them contextually across the product to express design intent.

**Component-level tokens** are used more selectively. They reference semantic tokens but are introduced only when a very specific part of a component needs to be styled differently. An example is the chevron icon in a dropdown. In such cases, instead of creating a semantic token for a single-use scenario, a component-level token is created to handle the exception without polluting the broader semantic layer.

![The three token levels: foundation, semantic and component](https://wixmp-833713b177cebf373f611808.wixmp.com/images/7597fba507ac0f13182f0e3cc3323f82.png)

### 2.1 Foundation Tokens

These tokens use raw values (for example, colors, spacing, typography) that serve as the core building blocks of the design system theme. For example, the main blue color used in the Wix dashboard is **#116DFF,** so it would be defined as **color-blue-100** foundation token.

These are the **base values**, that define your color pallet, spacing grid, font type etc. They serve as the **single source of truth** for the system.

We use a formula to define the naming conventions for foundation tokens: `category -> sub-category -> scale` 

Numeric scaling keeps clarity and consistency (100-900 for colors and 0-64 for spacing).<br>

![Foundation tokens holding raw color, spacing and typography values](https://wixmp-833713b177cebf373f611808.wixmp.com/images/0bfd1e9726475e80b8ce10f61e989e08.png)

### 2.2 Semantic Tokens

These are contextual tokens that describe the intended use, not a raw value. They reference foundation tokens and apply them contextually. For example, the **color-blue-100** value is the primary color for the Wix Business Manager theme. Therefore, the semantic token **fill-standard-primary** references **color-blue-100**. 

![Semantic tokens named for their intended use rather than their value](https://wixmp-833713b177cebf373f611808.wixmp.com/images/70477c1f3c7cb623b7609b2e868d7d75.png)

Semantic tokens make it easier to **adapt to future changes** in branding, accessibility, and design trends **without refactoring the entire codebase**.

For example:

* If a company rebrands and its primary color changes from blue to green, update the definition of the `standard-primary` token. Without tokens, you would search for and replace every hardcoded `#116DFF`.
  
![One semantic token resolving to a different value in each theme](https://wixmp-833713b177cebf373f611808.wixmp.com/images/13a3f9f6cd431d120f7fd1b4f8e171e5.png)

* If accessibility guidelines change, you could adjust `color-destructive-primary` to meet new contrast requirements without touching every error state in the UI.

### 2.2.1 Semantic tokens naming convention: 

The naming convention for semantic tokens: `category -> sub-category -> skin -> priority -> state`

![Examples of the semantic token naming convention](https://wixmp-833713b177cebf373f611808.wixmp.com/images/a2d7283c99d90705fbc542cb71958b35.png)

Naming convention deepdive:

![The category and sub-category segments of a semantic token name](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f8e49f69ccf4d7237cdf22fdca2c7a32.png)

![The state segment of a semantic token name](https://wixmp-833713b177cebf373f611808.wixmp.com/images/d0d9c596c36dff70a2174d9e82981a82.png)

By separating **design intent (semantic tokens)** from **design values (foundation tokens)**, we created a **more maintainable, future-proof system** that evolves without breaking consistency across components.

![A table of semantic tokens and the design intent each one carries](https://wixmp-833713b177cebf373f611808.wixmp.com/images/ae8af8d1a9d5d6613e664994ebdf1e40.png)

### 2.3 Component level tokens

These tokens are specific to components. Component tokens should **reference semantic tokens,** which map to foundation tokens.

* Use component tokens when components have **unique design needs** that can't be solved purely through semantic tokens.  

* We need to keep them **documented and limited** to where they add value.

For example:

* The dropdown chevron should stay blue in the "Default" theme, but should switch to black in the "Studio" theme. As there is no semantic token that would carry such a meaning with blue and black colors under the hood, a component level token `dropdown-icon-fill` was added.

Naming convention: the name should include a component name and the part of the component it affects, for example, vertical padding, label or border. If it is applicable to a certain skin or property, that should also be included in a token name. For example: `button-padding-horizontal-medium`.

![How component tokens resolve through semantic tokens to foundation tokens](https://wixmp-833713b177cebf373f611808.wixmp.com/images/3a29a9551ca9a0f70e755f1570da1b11.png)

Component level tokens can be problematic:<br> 

* **Overuse / duplication:** If every component has unique tokens for colors, spacing, etc., it becomes **hard to maintain** and defeats the purpose of a centralized system. If a required change is repetitive, it is better to request a semantic token change instead.  
* **Inconsistency:** Too many component tokens can cause **drift** from semantic tokens, breaking consistency across the UI.  
* **Harder to theme:** If component tokens don't map to semantic tokens, you'll need to update the theme of each component, instead of making the update in one place.  

## 3. Theming System

### 3.1 What is a Theme?

A theme defines a set of visual styles applied to a product, environment, or brand variant. In the Wix Design System, themes allow the same component structure to be used across different experiences while maintaining distinct visual identities.

Use cases for theming, current and potential:<br>

* **Product variants:** There are different themes for the Wix Dashboard, Wix Studio and other Editors while using the same component library.  
* **Branding customization:** Allows partners or businesses to apply their brand identity without changing component behavior.  
* **Dark Mode / accessibility:** Supports high-contrast or dark/light themes through token modifications.  
* **Localization adaptation:** Adjusts for different cultural color meanings or typographic preferences.

![One component structure shown under several themes](https://wixmp-833713b177cebf373f611808.wixmp.com/images/83563ba8703c26e4998c67476d1bc318.png)

### 3.2 How themes are structured

Themes in Wix are structured the same way both in code and Figma to ensure consistency across design and development. The naming is also consistent between code and design. 

Both the code repo and Figma are tokenized using three levels of tokens:

* **Foundation tokens:** Remain unchanged across themes (for example, raw colors and spacing values).  
* **Semantic tokens:** Can be modified per theme to reflect brand or contextual differences (for example, "Corner radius" in Dashboard vs. Editor).  
* **Component-level tokens:** Should be used sparingly for specific component adjustments.


### 3.3 Theme Switching

Theme switching allows real-time adaptation of UI elements based on user preferences or product contexts.

Implementation in Wix Products:

* Current themes provided by the Wix Design System are defined globally and can be applied dynamically.  
* When a theme switch occurs, **token values update**, while components remain unchanged.  
* Example: Switching from the **Dashboard** theme to the **Wix Studio** theme updates colors, spacing and typography, but keeps the UI components structurally identical.

![A panel switching themes, with token values updating and components unchanged](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b338a809b6c770fb3dad3f6216111431.gif)

### 3.4 Custom Themes

Design system consumers can create their own theme if they have a **business reason** or are building for a **new environment**. However, adjustments to existing themes shouldn't be made in ways that deviate from the design system guidelines.

* If a theme already exists for an environment (for example, Dashboard), **modifications should align with the established design language and need to be approved by the Wix Design System team**.

* Custom themes should be created only when necessary and should follow the token hierarchy and theming principles outlined in this guide.

<!-- dodont group -->
<!-- dodont -->
<!-- dodont image -->
![Do: align with the Wix Design System team before creating a new theme or token overrides](https://wixmp-833713b177cebf373f611808.wixmp.com/images/a0783d88de50d5568b13b2fd52a607ca.png)


<!-- end dodont image -->
<!-- dodont content -->


#### Do

Align with the Wix Design System team before creating a new theme or token overrides.<!-- end dodont content -->
<!-- end dodont -->
<!-- dodont -->
<!-- dodont image -->
![Don't: create custom UI in existing environments with a distinct style guide](https://wixmp-833713b177cebf373f611808.wixmp.com/images/61f72452ab024dbf6ef7631bda1c6ae9.png)

<!-- end dodont image -->
<!-- dodont content -->


#### Don't

Create custom UI in existing environments with a distinct style guide. <!-- end dodont content -->
<!-- end dodont -->
<!-- end dodont group -->

### 3.5 Guidelines for theme-safe design

To ensure flexibility and maintainability, follow these guidelines:

* **Avoid hardcoded colors:** Always use tokens instead of direct HEX/RGB values in the code and Figma.  
* **Use semantic tokens for UI elements:** This ensures colors adapt correctly across themes.  
* **Minimize component-level token overrides:** Keep theme changes at the semantic level whenever possible.  
* **Test across themes:** Validate designs in multiple themes to catch inconsistencies.

##  4. Tokens in Figma

### 4.1 How to check tokens in Figma?

All Wix Design System components in Figma use tokens. When you inspect a component, the inputs show their values in small white squares. All values like padding, fills, and text will have tokens already applied, so you don't need to apply them yourself. 

![The Figma inspector showing tokens already applied to a component](https://wixmp-833713b177cebf373f611808.wixmp.com/images/78a2fd0261ca8f3ebf732761696adf7a.png)

Keep in mind that switching between tokens in Figma isn't available in the code. Verify how components look and what properties or skins they support in the Storybook documentation. 

If there is a need to create a new theme or make changes to an existing theme, reach out for more guidance.

### 4.3 How to switch between themes

The Wix Design System is the default theme in the main Figma library. All of the components are already styled in this theme, but carry other themes under the hood. Different themes can be applied to a whole page, an artboard or a single component. When you have any components that are tokenised in your page, a "color pallet" icon will appear, that allows you to "apply variable mode" and switch between themes. All three levels (foundation, semantic, component) of tokens need to be selected to apply the theme correctly.  

![Applying a variable mode in Figma to switch a page between themes](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f9ed473b5380647687184451cf57e379.png)

## 5. Tokens in code

For a more detailed guide on how to apply tokens in the code refer to this [theming guide](#/page/introduction/theming).

For any further questions, reach out to us through [#wix-design-system.](https://wix.slack.com/archives/C39FTGUBZ)