Theming

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:

Copy

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:

Copy

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:

Copy

Combined styles and tokens

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

Copy

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

Copy
  • 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:

Copy

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:

Copy

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:

Copy

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:

Copy

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:

Copy

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:

Copy

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.

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 or the #ux_on_wds 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 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:

Copy

Then, define the override in your stylesheet:

Copy

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.

Last updated: 15 October 2026

Did this help?