@balena/design-tokens

Balena Design Tokens

What's this?

Design tokens are small bits of design decisions that can be used across different platforms and projects. They define the visual language of a product, and help create a consistent experience across different platforms.

Practically, this package will serve two purposes:

• Be the source of truth for design decisions: instead of using absolute values in your project, you can import this package and reference tokens in a variety of ways (currently with an ES module and CSS custom properties).
• Add a layer of semantics: tokens are more descriptive and convey meaning. For example, instead of relying on abstract naming such as primary.main or quartenary.lightest, tokens convey meaning and context. Examples: color.text.accent or color.bg.success.strong.

Usage

Install the package in your project

npm install @balena/design-tokens

TypeScript

import tokens from '@balena/design-tokens';

console.log(tokens.color.text.accent.value); // outputs '#1496e1'

You can also import categories directly:

import { color } from '@balena/design-tokens';

console.log(color.text.accent.value); // outputs '#1496e1'

CSS

The file @balena/design-tokens/build/css/tokens.css contains all the tokens as CSS custom properties.

The way you would import this file depends on the project. In a typical create-react-app project (or similar) you should be able to import it in a tsx file:

import '@balena/design-tokens/build/css/tokens.css';

The custom properties will be added to the :root element, and you can use them anywhere like so:

.alert.success {
	border: solid 1px var(--color-border-success);
	background-color: var(--color-bg-success);
	color: var(--color-text-success);
}

Note

A JSON object containing all tokens with extra information is also available for documentation purposes.

Update tokens

The tokens are exported from our Figma Design System library: https://www.figma.com/file/P7wVVPymUK4ekV6QOa3i0s/Design-System?type=design&t=hi4n82bo8vGO8noO-6

The export is a 3 steps process:

1. Download a JSON file using the Design Tokens plugin to export the tokens from Figma.
2. Replace the existing file in tokens/design-tokens.json with the one you downloaded
3. (Optional) Run npm run build to generate the new tokens in the build folder
4. Create a new branch and open a PR with the changes

TODO: this process can be greatly improved by using the "Send Design Tokens to URL" feature of the plugin, which would allow for a more streamlined process.

Plugin settings

Please replicate the settings exactly as shown in the screenshots below:

Contribute

How it works

This package uses Style Dictionary to generate the tokens. The tokens are defined in tokens/design-tokens.json, and the build process will generate the tokens in the build folder.

Install dependencies

npm install

Develop (watch the token folder)

npm start

Build the tokens

npm run build

Run the tests

npm run test

Custom formats

See scripts/transform.ts.

Custom formats were created to generate the ES module and its typescript declarations, as standard formats didn't meet our requirements:

• ES module export
• default exports to single categories for easier imports (import { color } from '@balena/design-tokens')
• Path simplification (see below)

Path simplification

The goal of this package is to offer engineers the easiest way possible to implement design decisions into their own projects. In this respect, we decided to shorten the path of the tokens as much as possible. So we don't use a "default" modifier, instead we reduce the path to the minimum:

❌ color.bg.accent.default
✅ color.bg.accent

By using a _ prefix, we can also easily filter out the default tokens from the Figma plugin in Style Dictionary CSS transform. But this is not available for JS objects, and that's the point of the flattenDefaultTokens.

Changelog

v0.10.0

(2024-10-24)

• Add hover and active colors for backgrounds [Jonathan Berger]