# Strategies' Design System Tokens

 <a href='https://www.npmjs.com/package/@strategies/tokens'>
  <img src="https://img.shields.io/npm/v/@strategies/tokens?style=flat-square" alt="token pkg version" />
 </a>

[![Jest testing on Tokens pkg](https://github.com/sasakiassociates/design-system/actions/workflows/test-tokens.yml/badge.svg)](https://github.com/sasakiassociates/design-system/actions/workflows/test-tokens.yml)

[![Publish to Chromatic](https://github.com/sasakiassociates/design-system/actions/workflows/chromatic.yml/badge.svg)](https://github.com/sasakiassociates/design-system/actions/workflows/chromatic.yml) <a href="https://www.chromatic.com/reviews?appId=6568e2d97288bec78eb6e3cc"><img src="../../public/link.png" alt="chromatic link" width="15" height="15" /></a>

## Installation

```sh
pnpm add @strategies/tokens
```

## <img src="../../public/token.png" alt="token" width="21" /> How to update tokens ?

### Update the tokens in JSON files

- The tokens are stored in **JSON** files located in the `src` folder.
- We use our own code in `utils` to generate SCSS variable files from these JSON files.
- One of the advantages of storing tokens in JSON format is that they can be easily integrated into the `token` function. So that, tokens can be used in js/jsx/ts/tsx files

### Mixins

- The mixins are stored in the `mixins` folder.
  - The mixins are written in SCSS format.
  - The `-base.scss` files are the base mixins that are used in the other mixins.
  - The `.scss` files are the mixins that are used in the components.
  - The `-use-cases.scss` files are the use cases of the mixins, which contain implemented classes. They are ONLY for testing purposes.
- The mixins are NOT generated from the JSON files.

#### Token with reference/alias

- If the token is a reference/alias token, plz make sure the format of its `value` is like this. For example, we wanna set token `color-test` to be `palette-primary-test`.

```json
{
  "color": {
    "test": {
      "value": "palette.$primary-test",
      "isReference": true
    }
  }
}
```

1. `value` is the reference to another token
2. `isReference` is the flag to indicate that this token is a reference token
3. **Important!** Make sure the first divider, aka. the divider between the `palette` and `primary-test` is **`.$`**. This is meant for successfully converting the `json` files to `scss` files

#### Token w/o reference/alias

- If the token is a normal token, plz make sure the format is like this

```json
{
  "color": {
    "test": {
      "value": "#ff0000"
    }
  }
}
```

- If the token is deprecated, plz make sure the format is like this

```json
{
  "color": {
    "test": {
      "value": "#ff0000",
      "deprecated": true
    }
  }
}
```

### Generate the SCSS file with latest token values

- The command below will generate the public `.scss` files and testing `.module.scss` files with the latest token values from the JSON files

```sh
pnpm run build
```

## <img src="../../public/mixin.png" alt="mixin" width="24" /> How to update mixins ?

- The mixins are stored in the `mixins` folder.
  - The mixins are written in SCSS format.
  - The `-base.scss` files are the base mixins that are used in the other mixins.
  - The `.scss` files are the mixins that are used in the components.
  - The `-use-cases.scss` files are the use cases of the mixins, which contain implemented classes.
- All the mixins are eventually rolled up in the `index.scss` file.

## Usage

### Include the global styles to normalize the styling environment

```scss
// In your top-level SCSS file (e.g. App.scss)
@import '~@strategies/tokens';
```

If you are using `vite`, please remove the tide `~` in the import statement, like this

```scss
// In your top-level SCSS file (e.g. App.scss)
@import '@strategies/tokens';
```

### Using the tokens in CSS or SCSS file

```scss
@use '~@strategies/tokens/color';
@use '~@strategies/tokens/font';

.YourComponent {
  color: color.$blue;
  font-size: font.$size-small;
}
```

### Using the tokens in js/jsx/ts/tsx file

- the `token`` function is for getting the value by passing in a path string
- to use the `token` function, please install another package `@strategeies/ui`

```sh
pnpm add --save-dev @strategies/tokens
```

- usage example

```tsx
import { ConfigProvider } from 'antd'
import { token } from '@strategeies/tokens'

export const ButtonAntConfig = ({ children }) => {
  return (
    <ConfigProvider
      theme={{
        token: {
          /* token fn here */
          colorPrimary: token('color.text.danger', '#ff0000'),
        },
      }}
    >
      {children}
    </ConfigProvider>
  )
}

export default ButtonAntConfig
```

### Implement default value (for DEV)

- If the token path is not found, the default value will be used
- Both of the following formats are supported.
- If some tokens are missing in the `SCSS` built file, plz check the `convertJsonToScss` function in `utils` folder

```json
{
  "color": {
    "value": "#ff0000",
    "dark": {
      "value": "#ff0000"
    }
  }
}
```

```json
{
  "color": {
    "default": { "value": "#ff0000" },
    "dark": {
      "value": "#ff0000"
    }
  }
}
```