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}
`