@uncharted.software/design-tokens

Uncharted Software Design Tokens

What are Design Tokens?

Design tokens are the atomic key-value pairs that represent design decisions. The equivalent of a single property+value in CSS, not a class or a component. Tokens can then be used as part of a design system to build higher level concepts. The tokens will capture colors, spacing, typography, etc.

The tokens in this package are for use in Uncharted products and are published by the Uncharted Design team.

Usage

Javascript or Typescript

To use the tokens in your project, install it:

yarn add @uncharted.software/design-tokens

# or

npm install @uncharted.software/design-tokens

Then include whichever files you need in your project. Currently supported:

• CSS: ./node_modules/@uncharted.software/design-tokens/build/css/uncharted-tokens.css
• SCSS: ./node_modules/@uncharted.software/design-tokens/build/scss/_uncharted-variables.css
• JS or TS
  • Available in two kinds of modules, each with Typescript declarations.
  • CommonJS: ./node_modules/@uncharted.software/design-tokens/build/js/commonjs/uncharted-tokens[.cjs|.d.ts]
    • Exported as a single large object tree.
  • ES6: ./node_modules/@uncharted.software/design-tokens/build/js/es6/uncharted-tokens[.cjs|.d.ts]
    • Exported as individual constants (similar to the CSS variables.)

Other Languages

While the initial focus is on JS-based projects, other languages are absolutely possible and could be added upon request. StyleDictionary supports a number of other formats out of the box.

How to Generate the Tokens (Create/Update/Delete)

When new tokens in JSON format are pushed from Figma, this project will transform them to various formats to support various frontends (i.e. CSS, SCSS, iOS, android.) The format, while in a (W3C draft) standard format, will expect specific custom types from the plugin.

Workflow:

• In Figma, a designer runs the "Design Tokens" plugin, then selecting "Send Design tokens to URL"
  • This dispatches a request to update the tokens on GitHub.
  • A GitHub action will accept the dispatch and overwrite the previous tokens/w3c-tokens.json file
  • OR as an alternative, they can export to a file and manually update a local copy of the git repository and push by hand.
• A GitHub action will automatically take the updated file and transform to variables for all platforms. (CSS, SCSS, android, etc.)

flowchart LR
    userExport([User: Dispatch JSON via Figma Design Tokens])
    userPush([User: Push via Git])
    githubActionAcceptDispatch[GH Action - Accept and commit JSON]
    githubActionTransform[GH Action: Transform]
    userExport-->githubActionAcceptDispatch
    githubActionAcceptDispatch-->githubActionTransform
    userPush-->githubActionTransform
    sd[Style-Dictionary]
    subgraph t [Transform]
        githubActionTransform-->sd
        sd-->css[/CSS/]
        sd-->scss[/SCSS/]
        sd-->js[/JS/JSON/]
    end

Development

A GitHub action, on push, (/.github/workflows/transform-tokens.yml) will normally be doing all the work. To test configuration changes though, we can run transformations locally:

This project uses yarn.

Install dependencies

yarn install

Transform standard tokens to variables for all platforms

This step uses Style Dictionary to create the different formats. It uses the configuration found in config.js.

# tokens/w3c-tokens.json -> build/**
yarn build

TODO

• Automate package releases
• Include assets (e.g. fonts)

Acknowledgements

Thanks goes to the open-source projects by Lukas Oppermann (Design Tokens plugin and design-tokens-transforms) from which this work was adapted.