> 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: Theming

## Article: Theming

## Article Link: https://dev.wix.com/docs/wix-design-system/introduction/theming.md

## Article Content:

<!-- heading -->

# Theming

<!-- end heading -->

<mcpbadge></mcpbadge>

## Introduction

To ensure consistent styling, the Wix Design System uses design tokens. These are named values like colors, font sizes, and spacing units that standardize design across products and platforms. This article explains how to apply styles using tokens, load specific token sets, and customize values with overrides.

## Importing Styles

Depending on your setup, you may need to import CSS files from the Wix Design System. These files provide either the base styles for components (like structure and layout) or the design tokens that define the theme (as CSS variables).

> If you're importing `.css` files in JavaScript (for example, `import './styles.css'`), make sure your build tool (like Webpack, Vite, or Parcel) supports CSS imports.

### Base component styles

To load the base component styles required by all components:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import '@wix/design-system/styles.css';
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

This file contains the core, minified CSS rules for all components. It uses version-scoped class names to prevent styling conflicts between different versions of the Wix Design System. These class names follow a pattern like `wds_<major>_<minor>_<patch>_ComponentName__localClassName`, where the numbers represent the specific Wix Design System version used (for example, `wds_1_172_1_Button__root`).

### Design tokens

To load only the theme-specific design tokens:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import '@wix/design-system/themes/<theme>.global.css';
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

Replace `<theme>` with `default`, `studio`, `odeditor`, `odeditor-dark` or `studio2-light`. The `wixel` theme is also published, but it's deprecated and frozen, so don't pick it for new work. These tokens define colors, fonts, and other style properties at the `:root` level. For example:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```css
:root {
  --wds-accordion-background-fill-light: #ffffff;
  --wds-accordion-background-fill-light-hover: #ffffff;
  --wds-accordion-caret-fill: #131720;
  /* ... many other design tokens */
}
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

### Combined styles and tokens

To import both the base component styles and a specific theme's design tokens in a single file:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import '@wix/design-system/styles-<theme>.global.css';
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

## Using Parastorage CDN

Parastorage CDN is a content delivery network (CDN) used by Wix to serve static assets like JavaScript files, CSS, fonts, images, and other web resources.

Instead of importing CSS in JavaScript, you can load Wix Design System styles directly from the Parastorage CDN using a `<link>` tag in your HTML `<head>`:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```bash
https://static.parastorage.com/unpkg/@wix/design-system@<version>/dist/statics/<file>
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

- Replace `<version>` with the version of `@wix/design-system` you use, for example 1.323.0.
- Replace `<file>` with the name of the CSS file, for example `styles.css` or `themes/studio.global.css`.

To load the base styles:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```html
<link
  rel="stylesheet"
  href="https://static.parastorage.com/unpkg/@wix/design-system@<version>/dist/statics/styles.css"
/>
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

> An exact version number must be included in the CDN URL. Omitting the version doesn't resolve to the latest release.

If your project includes the `@wix/design-system` package, you can get the correctly versioned CDN URLs directly. Import the specific URL strings you need from `@wix/design-system/dist/esm/CDN_URLS.js`:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import {
  STYLES_CSS_CDN_URL, // For styles.css
  THEME_DEFAULT_CSS_CDN_URL, // For themes/default.global.css
  THEME_STUDIO_CSS_CDN_URL, // For themes/studio.global.css
  THEME_WIXEL_CSS_CDN_URL, // For themes/wixel.global.css
  THEME_ODEDITOR_CSS_CDN_URL, // For themes/odeditor.global.css
  THEME_ODEDITOR_DARK_CSS_CDN_URL, // For themes/odeditor-dark.global.css
  THEME_STUDIO2_LIGHT_CSS_CDN_URL, // For themes/studio2-light.global.css
} from '@wix/design-system/dist/esm/CDN_URLS.js';
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

## Handling platform-injected styles

Some platforms automatically include Wix Design System CSS (design tokens and base styles) via `<link>` tags in the `<head>` from Parastorage CDN. Check this using your browser's developer tools by searching the DOM for "design-system".

There are primarily two situations affecting your imports:

1. If the platform injects only design tokens (for example, `themes/<theme>.global.css`), you must manually import the base styles: `styles.css`.
2. If the platform injects all required styles (either via both `themes/<theme>.global.css` and `styles.css`, or through a single file like `styles-<theme>.global.css`) no manual CSS import is needed.

The examples below use `import` statements for simplicity. Remember, loading styles via CDN links (explained before) also works.

### New Branding Colors

The New Branding Colors theme is designed for the Business Manager apps and uses CSS variables (prefixed with `--wsr-*`) instead of design tokens. To apply this theme and load the required `MadeFor` font, wrap your application in the `WixDesignSystemProvider`. You must also import `styles.css`, as these styles aren't automatically included in the Business Manager environment (not externalized). See the example below:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import { Button, WixDesignSystemProvider } from '@wix/design-system';
import '@wix/design-system/styles.css';

function App() {
  return (
    <WixDesignSystemProvider>
      <Button>Hello World</Button>
    </WixDesignSystemProvider>
  );
}
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

> If you are using Wix Design System version prior to `1.162.0`, you must explicitly enable the New Branding Colors. Add the `features={{ newColorsBranding: true }}` prop to the `WixDesignSystemProvider`. Otherwise, components fall back to the deprecated Old Branding Colors.

### Default (Classic)

In the Classic Editor environment, the platform automatically loads the required design tokens. You only need to manually import the base component styles:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import '@wix/design-system/styles.css';
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

### Studio

In the Studio Editor environment, the platform automatically loads both the required design tokens and the base component styles. Therefore, you don't need to manually import any Wix Design System CSS files.

### Panels

For `Yoshi OOI` panels and `Wix CLI` site widgets, the necessary design tokens are loaded automatically. Therefore, you only need to import the global base styles:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
import '@wix/design-system/styles.css';
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

## Debugging

You can verify which theme is applied by inspecting a component's styles using your browser's developer tools. For example, the `Button` component has the `background-color` property. When you inspect the element, you should see a definition using CSS variables like:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```css
background-color: var(
  --wds-color-fill-standard-primary,
  var(--wsr-color-B10, #3899ec)
);
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

The actual background color applied depends on which CSS variable is currently defined:

- If you are using design tokens (Default, Studio, Wixel, Odeditor themes), the value resolves from `--wds-color-fill-standard-primary`.
- If you are using the New Branding Colors theme (via WixDesignSystemProvider), the value resolves from `--wsr-color-B10`.
- If neither theme's variables are loaded correctly, the style falls back to the hardcoded value (for example, `#3899ec`).

## Customizing component styles

There are two reliable ways to customize how a component looks, so that products stay visually consistent.

### 1. Using component props (recommended)

Many components expose dedicated props, such as `skin`, that control specific visual aspects like colors, padding or borders. This is the **safest method**, because it keeps you inside the design variations the component is built for.

If the available props don't cover your styling needs, request new options through the [product review form](https://forms.monday.com/forms/dca799707c90a6f3181e8bd6bc49bbf2) or the [#ux_on_wds](https://wix.slack.com/archives/CR7P4A1UP) Slack channel. The UX team reviews these suggestions.

### 2. Overriding design tokens

When component props don't cover your case, override the underlying design token values. Design tokens are a public API, so their default values can be changed from outside the library. For large or complex token changes, **coordinate with the design team first** in the [#ux_on_wds](https://wix.slack.com/archives/CR7P4A1UP) Slack channel.

There is no central list mapping tokens to components yet. To find the tokens a component uses, inspect its rendered elements in your browser developer tools and look for CSS custom properties prefixed with `--wds-`.

> Tokenization is an ongoing effort, so some components and styles aren't controlled by tokens yet.

To apply an override, define the token's new value inside a custom CSS class. For example, to change the primary button's standard fill color to green, first apply a custom class to the Button component:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```jsx
<Button className="green-button">Button</Button>
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

Then, define the override in your stylesheet:

<!-- grid layout -->
<!-- grid layout item -->
<!-- grid layout content -->

```css
.green-button {
  --wds-color-fill-standard-primary: green;
}
```

<!-- end grid layout content -->
<!-- end grid layout item -->
<!-- end grid layout -->

While many components expose a `className prop`, it should only be used as shown above, to provide a hook for applying token overrides via CSS custom properties. Avoid using `className` to directly target and modify the component's internal DOM structure or CSS rules. Such direct manipulations are brittle because the component's internal implementation details change between library versions, potentially breaking your custom styles silently during updates.