tokens-to

It is somewhat cumbersome to prepare style tokens across design systems. Design and Style tokens can be defined various ways. However, once defining style tokens in Javascript(or Typescript), it is quite tedius and inefficient to write that again in other format such as css and json to be delivered or reused. tokens-to addresses that problem to ease the pain.

It was commonjs module before 0.0.5, but I decided to move on to es module. The commonjs version will be archived on branch. As the most of tokens work with UI frameworks/libaries which utilizes es module.

• Installation
• Usages
• Contributing
• License
• Authors

Install the library using npm or yarn:

npm install --save-dev tokens-to

Let's say there is a js token like following.

export const colors = {
  whites: [
    '#fffff0',
    '#fffff1'
    '#fffff2'
  ]
}

And this is what you get after the conversion.

:root {
  --colors-whites-0: #fffff0;
  --colors-whites-1: #fffff1;
  --colors-whites-2: #fffff2;
}

When there are multiple tokens like following,

export const colors = {
  whites: [
    '#fffff0',
    '#fffff1'
    '#fffff2'
  ]
}

export const curves = {
  card: [
    10,
    20,
    30,
  ]
}

And then this is what you get after the conversion.

:root {
  --colors-whites-0: #fffff0;
  --colors-whites-1: #fffff1;
  --colors-whites-2: #fffff2;
  --curves-card-0: 10;
  --curves-card-1: 20;
  --curves-card-2: 30;
}

To be converted into css, every source js module should export tokens with esm "export" as following. The "export default" will be converted into variables with prefix "default".

export { colorTokens, typographyTokens };

Please keep this form(⬆️) of exporting object to get expected output files.

To configure converting to keep consistency and reusability, you can create tokens-to.config.json

tokens-to.config.json

{
  "css": {
    "sources": ["./tokens/*.js"],
    "outFileName": "cssvariables",
    "outDir": "./dist/css",
    "bundled": true,
    "selector": ":root",
    "prefix": ""
  },
  "json": {
    "sources": ["./tokens/*.js"],
    "outFileName": "cssvariables",
    "outDir": "./dist/json",
    "bundled": true
  }
}

• sources: string[]; //Sources to be converted. Patterns are allowed.
• outFileName: string; //Output file name, in case of converting into single css file(bundled).
• outDir: string; //Directory for output files.
• bundled: boolean; //Whether output file is bundled into single file or not. If false, each sources file is converted into single css file. and outfile option is ignored.
• selector: string; //Css selector that wraps css variables.
• prefix: string; //Prefix to be prepended in front of each css variables

If configurations are missing, Default configurations are used instead of.

{
  "css": {
    "sources": [],
    "outFileName": "tokens",
    "outDir": "./dist/css",
    "bundled": true,
    "selector": ":root",
    "prefix": "",
  },
  "json": {
    "sources": [],
    "outFileName": "tokens",
    "outDir": "./dist/json",
    "bundled": true,
  }
}

When manual configurations are provided, configurations from tokens-to.config.json is overrided.

arguments

files: optional argument for source files, patterns allowed. If not specified, sources from configurations are used.

options

-o, --outFileName:  output filename.
-d, --outDir:  output directory.
-b, --bundled:  whether output is bundled.
-s, --selector: what css selector is used to define css variables.

"tokens-to": "tokens-to",
"js2css": "tokens-to js2css",
"js2json": "tokens-to js2json"

Run with configurations

npm run tokens-to js2css
npm run js2css
npm run tokens-to js2json
npm run js2json

Help

npm run tokens-to help
npm run tokens-to help js2css
npm run tokens-to help js2json

js2css

npm run js2css ./tokens/colors.js
npm run js2css --outDir=./dist/css ./tokens/colors.js
npm run js2css --outFileName=tokens ./tokens/colors.js
npm run js2css --bundled=true ./tokens/colors.js
npm run js2css --selector=html ./tokens/colors.js

js2json

npm run js2json ./tokens/*.js
npm run js2json --outDir=./dist/json ./tokens/colors.js
npm run js2json --outFileName=tokens ./tokens/colors.js
npm run js2json --bundled=true ./tokens/colors.js

We welcome contributions to this library! Here's how you can get involved:

• Bug reports: If you find a bug, please report it on the GitHub issue tracker.
• Feature requests: If you have a feature request, please submit an issue on the GitHub issue tracker.
• Pull requests: We encourage you to submit pull requests for bug fixes and new features. Please make sure to follow the coding style and guidelines outlined in the project's contribution guide (if applicable).

This library is licensed under the MIT LICENSE. See the LICENSE file for details.

• HoJoon Eum