@atlaskit/tokens

What is @atlaskit/tokens?

@atlaskit/tokens is a design token library provided by Atlassian. It allows developers to use a consistent set of design tokens across their applications, ensuring a unified design language. The package provides tokens for colors, spacing, typography, and other design elements, making it easier to maintain and scale design systems.

What are @atlaskit/tokens's main functionalities?

Color Tokens

This feature allows you to use predefined color tokens in your application. The `token` function retrieves the value of a specified token, ensuring consistency across your design.

import { token } from '@atlaskit/tokens';

const primaryColor = token('color.background.brand.bold', '#0052CC');
console.log(primaryColor); // Outputs: #0052CC

Spacing Tokens

This feature provides spacing tokens that can be used to maintain consistent spacing throughout your application. The `token` function retrieves the value of a specified spacing token.

import { token } from '@atlaskit/tokens';

const spacing = token('space.100', '8px');
console.log(spacing); // Outputs: 8px

Typography Tokens

This feature offers typography tokens for consistent font sizes, line heights, and other typographic properties. The `token` function retrieves the value of a specified typography token.

import { token } from '@atlaskit/tokens';

const fontSize = token('font.size.200', '14px');
console.log(fontSize); // Outputs: 14px

Other packages similar to @atlaskit/tokens

styled-system

Styled System is a collection of utility functions for building design systems with React. It provides a set of design tokens and utilities for spacing, color, typography, and layout. Compared to @atlaskit/tokens, Styled System offers more flexibility and customization options but requires more setup and configuration.

theme-ui

Theme UI is a library for creating themeable user interfaces based on constraint-based design principles. It provides a set of design tokens and utilities for styling components. Theme UI is similar to @atlaskit/tokens in that it promotes a consistent design language, but it also includes additional features like theming and CSS-in-JS support.

tailwindcss

Tailwind CSS is a utility-first CSS framework that provides low-level utility classes for building custom designs. It includes a set of design tokens for colors, spacing, typography, and more. While Tailwind CSS offers a different approach compared to @atlaskit/tokens, it also aims to provide a consistent design language through its utility classes.

README

Tokens

⚠️ This package is under development and comes with no semver guarantees, your app will break if you use this directly.

Tokens are a single source of truth to name and store Atlassian design decisions.

Installation

yarn add @atlaskit/tokens

Usage

Setup your environment

Before continuing ensure the CSS themes are installed, depending on your bundler configuration may differ.

import '@atlaskit/tokens/css/atlassian-light.css';
import '@atlaskit/tokens/css/atlassian-dark.css';

Token

Use the token function to get a CSS variable for the named token.

import { token } from '@atlaskit/tokens';

token('color.background.default');

Set global theme

Change the global theme during runtime.

import { setGlobalTheme } from '@atlaskit/tokens';

setGlobalTheme('light');

BabelPlugin

A babel plugin to optimise performance and support fallbacks for Design System tokens.

It replaces any calls to the @atlaskit/tokens token() function with the CSS value the function would return (i.e. var(--token-name) or variations with fallbacks).

If there’s no fallback, the plugin (optionally) finds the token’s value from the default Atlassian theme, and sets it as the fallback.

If there is a fallback defined in code, it’s inserted into the style (expressions are inserted using template strings).

Usage

Add the plugin to your babel configuration:

{
  "plugins": ["@atlaskit/tokens/babel-plugin"]
}

Options

Currently the plugin supports one option, shouldUseAutoFallback. When enabled, the plugin will fetch the token's value in the default Atlassian theme (currently atlassian-light) and use it as the fallback value.

This is useful for cases where tokens are in use, but token definitions aren't present in the top-level page CSS.