Strategies' Design System Tokens

Installation

pnpm add @strategies/tokens

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.

{
  "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

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

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

{
  "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

pnpm run build

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

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

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

Using the tokens in CSS or SCSS file

@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

pnpm add --save-dev @strategies/tokens

• usage example

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

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

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