@wix/design-system-tokens

Wix Design System Tokens

This package contains:

• JSON files containing WDS token definitions.
• style-dictionary script to process these files and create required output.
• output generated with style-dictionary.

If you're looking to contribute, refer to Add Tokens Guide.

How it works

Source files which are used to generate style-dictionary output are stored in src/tokens directory in JSON format. These files are processed by style-dictionary, which transforms data into a specific structure & format and outputs files to root tokens directory.

To generate output, run

$ yarn generate

Since this package just exports static files, the build script is only used to prepare package for publishing by moving generated files to the root of the package to allow more elegant imports.

Build & Configuration

Build entry point is generate.ts file which controls the execution of input parsing & output generation. Main configuration for expected output is stored in build-config.ts file. Current solution is partly customized, we use custom Format and Transform to suit our needs.

You can find more details on Style Dictionary and its' configuration here.

Consumption

Tokens are available in 2 themes - default and Studio. Default theme resides at the root of the package, while Studio theme is under the studio directory. Each theme has files named foundation, semantic and component, these correspond directly to the tiers of the tokens. File named all contains the tokens from all of the tiers.

Custom Formats

Style Dictionary allows to create your own output format, it's called Formats. These are our custom formats:

css/properties-stylable

It outputs Stylable file with .st.css extension. This file contains:

• Variable declarations using partially correct @property rule syntax, which in this form is only valid for Stylable pre-processor.
• Variable definitions under .root class.

@property st-global(--wds-color-border-dark-primary);
...
.root {
  --wds-color-border-dark-primary: #868aa5;
  ...
}

Custom Transforms

Style Dictionary supports defining your own custom token value parsers, they're called Transforms. We have several custom transforms.

color/gradient

Only applies to tokens which have attribute "type": "gradient". Refer to transforms/color-gradient.ts to find object structure definition. Outputs linear-gradient function to be assigned to background property.

background: var(--wds-color-fill-gradient-light-bottom-to-top);

shadow/box

Only applies to tokens which have attribute "type": "shadow". Refer to transforms/shadow.ts to find object structure definition. Outputs shadow values to be assigned to box-shadow property.

box-shadow: var(--wds-shadow-focus-warning);

size/px-custom

Only applies to tokens which have attribute "type": "float". Adds px unit to token values.

Scoped styling - sass mixin tokens

@mixin tokens has been introduced to accomplish scoped styling within the same HTML document.

Usage

  @use "@wix/design-system-tokens/all.scss" as wds;
  // @use "@wix/design-system-tokens/studio/all.scss" as wds;
  // @use "@wix/design-system-tokens/wixel/all.scss" as wds;
  // @use "@wix/design-system-tokens/odeditor/all.scss" as wds;

  .scoped {
    @include wds.tokens;
  }