Design tokens

In the world of atomic design , if components are atoms that function as the basic building blocks of the system, design tokens are the sub-atomic particles used to build components.

Overview

A design token is an abstraction of a visual property such as color, size, or animation. Instead of using hard-coded values, such as hex values for colors, tokens are key-value pairs that represent reusable design decisions in the form of a variable. This data structure allows a design system to evolve without requiring downstream users to modify existing code or data. The key remains constant in your code, while the value can be changed at a system level or at runtime for theming.

For information on design tokens specific for data visualization, see data visualization colors.

Naming structure

Our tokens follow the CTI (Category > Type > Item > State) naming convention (e.g. color > background > input > disabled).

Structuring tokens in this manner gives us consistent and hierarchical naming of these properties. Each token starts broad and gets more specific.

• Category - The category of the token's output.

  • For example: "color" for hex values, "size" for pixels, or "duration" for seconds.

• Type - A property descriptor of the category.

  • For example: "background", "text", or "border".

• Item - The element or abstracted element group that's targeted by the token.

  • For example: "dropdown", "control", "container", or "panel".

• Sub-item - Any differentiating aspect of the token or item that isn't state, often could be component variants.

  • For example: "secondary", "primary", or "success".

• State - State-dependent aspects.

  • For example: "default", "focused", "selected", or "disabled".

No design system will ever be able to cover 100% of all customer needs, which means you may not always find what you're looking for. This is where design tokens come into play. Design tokens provide a way for you to create product-specific experiences and custom components in a way that is on-brand and visual mode compliant. For the best results, follow the guidelines below:

Tip 1: Use existing components first

Before using design tokens, double-check to make sure what you're trying to achieve can't already be done with an existing component. Design tokens are great for building custom components, but the number-one recommendation will always be to use the pre-built components provided by the design system. This is because of the time and maintenance that custom components require. Custom components also miss certain benefits, such built-in testing, accessibility, responsiveness, and consistency, that our existing components provide.

Tip 2: Be thoughtful and intentional

Design tokens are development tools that have design decisions built into them. These decisions are encapsulated in their names, so it's best to use them in ways that align with their original intent. In other words, don't use the $color-text-form-secondary token for a custom component's border color just because it's convenient.

As soon as you apply a token to an element, you create a correlation between the element and that token's purpose, not just the value. This is also a design decision and should be treated as such. Don't create unintentional connections between elements that have nothing in common. While we promise not to change the contract of intent for a component, the values may change over time.

Tip 3: Key > Value

When trying to decide which token to use, look at the token name, rather than the values that it holds. Think about the type of element you going to create, and look for similar elements that already exist in the system. Then, search the list below for key words or metaphors, such as its context ("layout", "body", "heading"), its attributes ("interactive", "disabled", "focused"), or its hierarchy ("default", "secondary"). Try to find compatible tokens, and be sure to never alter the values of existing design tokens.

Design tokens which can be used for theming are marked as "Themeable" in the tokens tables below.

Our design tokens are available from a separate package called design-tokens and are intended to be used together with Cloudscape components. If you do not have components installed, see our installation article. All of our tokens are available as Sass  variables (e.g. $color-text-body-secondary) or JavaScript variables (e.g. colorTextBodySecondary).

Installation

This package is provided via the following artifact:

• Npm module: @cloudscape-design/design-tokens

The design tokens package can only be used together with the components package. For detailed instructions, see the  package installation guide.

Sass variables

Load design tokens into your application using the Sass @use rule . @import can also work, even though it is not recommended by the Sass team .

@use '@cloudscape-design/design-tokens/index' as awsui;

.custom-panel {
  color: awsui.$color-text-body-secondary
}

JavaScript variables

import styled from 'styled-components'; // this is an example, you can use any other similar library
import * as awsui from '@cloudscape-design/design-tokens.js';

const CustomPanel = styled.div`
  color: ${awsui.colorTextBodySecondary}
`

JSON

Use index-visual-refresh.json file to retrieve the values of design tokens and further process them to suit your development stack. For example, you can generate xml files for Android native apps, or swift classes for iOS native apps. We recommend that you use the style-dictionary open source project  to convert the JSON file to the desired output format .

The JSON format is inspired by the Design Tokens Format Module  by the Design Tokens Community Group . While this module is currently not a W3C Standard, or on the W3C Standards Track, it is the closest to a standardized format.

Here is the format of the JSON object:

{
  "tokens": {}
  "contexts": {
    "navigation": {
       "tokens": {},
    }
  }
}

Refer to the Visual Contexts article for more information about contexts.

Here is the format of the tokens object, with a few examples:

{
  "font-family-base": {
    "$value": "'Helvetica Neue', Roboto, Arial, sans-serif",
    "$description": "The default font family that will be applied globally to the product interface.",
  },
  "color-background-button-primary-default": {
    "$value": {
      "light": "#aaaaaa",
      "dark": "#bbbbbb",
    },
    "$description": "The default background color of primary buttons.",
  },
  "space-container-horizontal": {
    "$value": {
      "comfortable": "20px",
      "compact": "20px"
    },
    "$description": "The horizontal padding inside a container."
  },
  "motion-duration-complex": {
      "$value": {
        "default": "250ms",
        "disabled": "0ms"
      },
      "$description": "The duration for drawing more attention or accommodating for more complexity."
  },
}

The format of each token depends on the category of the token, which is dictated by the first part of the token name. Here is the mapping:

• color- tokens have the following format: { light: string, dark: string }.

• font- tokens are strings.

• line-height- tokens are strings.

• border-radius- tokens are strings.

• space- tokens have the following format: { comfortable: string, compact: string }.

• motion- tokens have the following format: { default: string, disabled: string }, indicating the value when motion is enabled (default) or disabled.

The format of the whole JSON object is described in a JSON schema that we release as part of our artifacts (index-visual-refresh-schema.json). The JSON schema also contains patterns for most of the values. Future updates to those patterns are not considered breaking changes.