Design Tokens

Development guide

Note: everything in directories tokens and src don't need any manual work: it should be done automatically via scripts. We keep these files in the repo to track changes that we get after updating tokens

Pre-requisites

• Node.js – v14
• pnpm: npm i -g pnpm@6
• install dependencies: pnpm i -r
• edit file .storage.env.json in the root repo directory and write into it the following lines to replace YOUR_JSONBIN_API_KEY and YOUR_JSONBIN_BIN_ID to correct values

Scripts

pnpm run tokens:fetch

This script do a request to remote JSON storage to fetch JSON with design tokens. Then split one global JSON file to smallest JSONs by high-level keys. For example, if we have one JSON file

{"button":{...},
 "color":{...},
 "icons":{...}
}

with high-level keys as button, color, icons, after fetching it will be divided to three JSON files with names button.json, color.json, icons.json. It's done for better readability of design tokens and debug purposes.

pnpm run tokens:transform

Transform all tokens from JSON to specified format. Tokens in JSON should have proper format to be correctly transformed. Transformation is handled by Style Dictionary. Currently we have 2 options for output: scss variables and plain typescript object, but there are a much more possibilities to format the output. For example, there is an option to generate less, stylus, common css variables, styles for Android and IOS platforms, even create a custom format. After successful transformation you'll see files index.ts and index.scss inside tokens folder.

pnpm run tokens:build

Runs pnpm run tokens:fetch and pnpm run tokens:transform. To have actual design tokens run this command.

Debugging

After running pnpm run tokens:build you might see the following errors in console:

• .storage.env.json file should be created in the root level of monorepo Seems you don't have .storage.env.json in the root level of repo. Refer to Pre-requisites section of the Readme to fill it out.
• Reference doesn't exist: icons.light.2.icon.fill.disabled.value tries to reference color.grey.1100, which is not defined This error means that in icons.json file we have a token with described path (icons.light.2.icon.fill.disabled), where in value we have a reference to another token (which is ok), like {"value": '{color.grey.1100}'}. This alias color.grey.1100 follows us to the file color.json, where by path color.grey.1100 we should get a value, but we don't: value for this alias doesn't exist. To Fix this error we should request UX team to add this missed token into Figma and upload it via Figma Plugin. When it's done we'll be able to run the command again.

Development flow

When you get a task about adding new Component to UI library, first that you need is to check do you have design tokens generated for your component (inside tokens/index.ts or tokens/index.scss). If you already have them in place - nice, nothing to do, just start the development! If you don't have them - run the command pnpm run tokens:build and then see are they in place. If they are still missing - contact to UX team about Design Tokens for your component (they will create and upload tokens via Figma Plugin).

We still don't publish tokens to npm registry because currently we need them only for ui library of components, and can import them directly via monorepo.

We still stick with the mixed format of Design Token Synchronization because it's still MVP: we don't have enough validation on token creation/uploading/generation stages to build and publish it automatically. Later we can setup webhooks to trigger tokens updating and auto-publishing to npm.