# Wix Design System Tokens

This package contains:

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

If you're looking to contribute, refer to [Add Tokens Guide](./docs/ADD_TOKENS_GUIDE.md).

## 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](https://amzn.github.io/style-dictionary/).

## 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](https://stylable.io/) file with `.st.css` extension. This file contains:

1. Variable declarations using partially correct [@property rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) syntax, which in this form is only valid for Stylable pre-processor.
2. 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](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/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](https://developer.mozilla.org/en-US/docs/Web/CSS/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
```sass
  @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;
  }
```