@wix/design-system-tokens
v1.245.0
Published
Design system tokens
Maintainers
Keywords
Readme
Wix Design System Tokens
This package contains:
- JSON files containing WDS token definitions.
style-dictionaryscript 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
$ pnpm generateSince 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.
Next to its CSS, each theme also has its foundation and semantic source files as Style Dictionary JSON (foundation.json, semantic.json), copied from src/tokens by build. Tools that generate custom themes read the token contract from there, so a custom theme always matches the installed tokens version.
Deprecated: the Stylable token files (
all.st.css,foundation.st.css,semantic.st.cssandcomponent.st.css, at the root and in every theme folder) will be removed in a future release. Read the tokens as CSS custom properties fromall.css, or fromall.scssfor scoped styling.
Custom Formats
Style Dictionary allows to create your own output format, it's called Formats. These are our custom formats:
css/properties-stylable
Deprecated, and will be removed together with the files it generates.
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
.rootclass.
@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 in 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;
}