Design tokens

Design tokens store visual design attributes. They help us make our UI more consistent and support custom themes

Design tokens and theming is still a work in progress.

We’re preparing a new specification of how we want theming to work in Orbit. More soon.

We use tokens instead of static values (like HEX codes) for color or sizing units.

Installation

If you’re already using @kiwicom/orbit-components, you don’t need to install the tokens because they’re included as a dependency to ensure compatibility.

You can install the package on its own.

// Using npm
npm install --save @kiwicom/orbit-design-tokens
// Using yarn
yarn add @kiwicom/orbit-design-tokens

How to use

Using @kiwicom/orbit-components

To use the default tokens, add an import in the file where you want to use the design tokens.

import defaultTheme from "@kiwicom/orbit-components/lib/defaultTheme";

Now you can use tokens by entering defaultTheme.orbit and continuing the dot-notation with the token name you want to use, such as defaultTheme.orbit.colorTextPrimary. More advanced text editors should suggest which tokens are available to you so you can find tokens quicker than by typing the entire token name.

You can also create your own tokens for themes using getTokens from @kiwicom/orbit-components and create custom uses in styled-components. See more at Theming.

Independently

To use the default tokens, add an import in the file where you want to use the design tokens.

import { defaultTokens } from "@kiwicom/orbit-design-tokens";

Now you can use tokens by typing defaultTokens and continuing the dot-notation with the token name you want to use, such as defaultTokens.colorTextPrimary. More advanced text editors should suggest which tokens are available to you so you can find tokens quicker than by typing the entire token name.

You can also create your own tokens for themes using getTokens from @kiwicom/orbit-design-tokens and create custom uses in styled-components. See more at Theming.

As XML

You can download the tokens as XML.

Formats

The main structure of the package is written in JavaScript for better usage in JavaScript projects. We’re also able to generate a JSON file, which enables us to transform this type of file into different ones. It should be possible to transform JSON into SASS, LESS, Stylus, XML, and others.

Naming conventions

Every design token in the package has a name according to the Orbit naming conventions. These conventions should be systematic and work according to the following template:

property_usage-type--state

Every token name starts with its related CSS property, such as color, background, or fontSize. This should help in using them more naturally.

Full list of design tokens

NameValue