---
title: "Design tokens - Cloudscape Design System"
source: "https://cloudscape.design/foundation/visual-foundation/design-tokens/"
created: 2025-10-01
description: "A design token is an abstraction of a visual property, such as color, size, or animation."
---
In the world of [atomic design](https://bradfrost.com/blog/post/extending-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](https://cloudscape.design/foundation/visual-foundation/data-vis-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".
## Tokens
### Color
| Name | Description | Themeable | Light mode | Dark mode |
| --- | --- | --- | --- | --- |
| $color-charts-red-300 | Color from the 'red' data visualization palette at a contrast ratio of 3:1 | No | #ea7158 | #d63f38 |
| $color-charts-red-400 | Color from the 'red' data visualization palette at a contrast ratio of 4:1 | No | #dc5032 | #ed5958 |
| $color-charts-red-500 | Color from the 'red' data visualization palette at a contrast ratio of 5:1 | No | #d13313 | #fe6e73 |
| $color-charts-red-600 | Color from the 'red' data visualization palette at a contrast ratio of 6:1 | No | #ba2e0f | #ff8a8a |
| $color-charts-red-700 | Color from the 'red' data visualization palette at a contrast ratio of 7:1 | No | #a82a0c | #ffa09e |
| $color-charts-red-800 | Color from the 'red' data visualization palette at a contrast ratio of 8:1 | No | #972709 | #ffb3b0 |
| $color-charts-red-900 | Color from the 'red' data visualization palette at a contrast ratio of 9:1 | No | #892407 | #ffc4c0 |
| $color-charts-red-1000 | Color from the 'red' data visualization palette at a contrast ratio of 10:1 | No | #7d2105 | #ffd2cf |
| $color-charts-red-1100 | Color from the 'red' data visualization palette at a contrast ratio of 11:1 | No | #721e03 | #ffe0dd |
| $color-charts-red-1200 | Color from the 'red' data visualization palette at a contrast ratio of 12:1 | No | #671c00 | #ffecea |
### Borders
| Name | Description | Themeable | Value |
| --- | --- | --- | --- |
| $border-radius-alert | The border radius of alerts. | Yes | `12px` |
| $border-radius-badge | The border radius of badges. | Yes | `4px` |
| $border-radius-button | The border radius of buttons and segmented control's segments. | Yes | `20px` |
| $border-radius-calendar-day-focus-ring | The border radius of the focused day in date picker and date range picker. | Yes | `3px` |
| $border-radius-container | The border radius of containers. Also used in container-based components like table, cards, expandable section, and modal. | Yes | `16px` |
| $border-radius-control-circular-focus-ring | The border radius of the focus indicator of circular controls. For example: radio button. | Yes | `4px` |
| $border-radius-control-default-focus-ring | The border radius of the focus indicator of interactive elements. For example: button, link, toggle, pagination controls, expandable section header, popover trigger. | Yes | `4px` |
| $border-radius-dropdown | The border radius of dropdown containers. For example: button dropdown, select, multiselect, autosuggest, date picker, date range picker. | Yes | `8px` |
| $border-radius-dropzone | The border radius of file upload dropzone. | Yes | `12px` |
| $border-radius-flashbar | The border radius of flash messages in flashbars. | Yes | `12px` |
| $border-radius-item | The border radius of items that can be selected from a list. For example: select options, table rows, calendar days. | Yes | `8px` |
| $border-radius-input | The border radius of form controls. For example: input, select. | Yes | `8px` |
| $border-radius-popover | The border radius of popovers. | Yes | `8px` |
| $border-radius-tabs-focus-ring | The border radius of tabs' focus indicator. Used in tabs and in the code editor status bar. | Yes | `20px` |
| $border-radius-tiles | The border radius of tiles. | Yes | `8px` |
| $border-radius-token | The border radius of tokens. For example: token groups, multiselect tokens, property filter tokens. | Yes | `8px` |
| $border-radius-chat-bubble | The border radius of chat bubbles. | No | `8px` |
| $border-radius-tutorial-panel-item | The border radius of tutorials inside a tutorial panel. | Yes | `8px` |
| $border-width-alert | The border width of alerts. | Yes | `2px` |
| $border-width-button | The border width of buttons. | Yes | `2px` |
| $border-width-dropdown | The border width of dropdowns. | Yes | `2px` |
| $border-width-field | The border width of form fields. | Yes | `1px` |
| $border-width-popover | The border width of popovers. | Yes | `2px` |
| $border-width-token | The border width of tokens. | Yes | `2px` |
### Spacing
| Name | Description | Themeable | Comfortable mode | Compact mode |
| --- | --- | --- | --- | --- |
| $space-container-horizontal | The horizontal padding inside a container. | No | `20px` | `20px` |
| $space-field-horizontal | The horizontal padding inside field components. | No | `12px` | `12px` |
| $space-scaled-xxxs | The XXXS spacing unit which scales between modes. | No | `2px` | `0px` |
| $space-scaled-xxs | The XXS spacing unit which scales between modes. For example: vertical space between form field label and control. | No | `4px` | `2px` |
| $space-scaled-xs | The XS spacing unit which scales between modes. For example: horizontal space between buttons in an action stripe. | No | `8px` | `4px` |
| $space-scaled-s | The S spacing unit which scales between modes. For example: vertical padding inside a popover. | No | `12px` | `8px` |
| $space-scaled-m | The M spacing unit which scales between modes. For example: horizontal padding inside a popover. | No | `16px` | `12px` |
| $space-scaled-l | The L spacing unit which scales between modes. For example: vertical space between form fields. | No | `20px` | `16px` |
| $space-scaled-xl | The XL spacing unit which scales between modes. For example: horizontal space between wizard navigation and content. | No | `24px` | `20px` |
| $space-scaled-xxl | The XXL spacing unit which scales between modes. For example: left indentation of grouped options in a select. | No | `32px` | `24px` |
| $space-scaled-xxxl | The XXXL spacing unit which scales between modes. For example: horizontal padding for app layout and split panel content on large screens. | No | `40px` | `32px` |
| $space-static-xxxs | The static XXXS spacing unit. | No | `2px` | `2px` |
| $space-static-xxs | The static XXS spacing unit. | No | `4px` | `4px` |
| $space-static-xs | The static XS spacing unit. | No | `8px` | `8px` |
| $space-static-s | The static S spacing unit. | No | `12px` | `12px` |
| $space-static-m | The static M spacing unit. | No | `16px` | `16px` |
| $space-static-l | The static L spacing unit. | No | `20px` | `20px` |
| $space-static-xl | The static XL spacing unit. | No | `24px` | `24px` |
| $space-static-xxl | The static XXL spacing unit. | No | `32px` | `32px` |
| $space-static-xxxl | The static XXXL spacing unit. | No | `40px` | `40px` |
### Typography
| Name | Description | Themeable | Value |
| --- | --- | --- | --- |
| $font-family-base | The default font family that will be applied globally to the product interface. | Yes | `'Open Sans', 'Helvetica Neue', Roboto, Arial, sans-serif` |
| $font-family-monospace | The monospace font family that will be applied globally to the product interface. | Yes | `Monaco, Menlo, Consolas, 'Courier Prime', Courier, 'Courier New', monospace` |
| $font-size-body-m | The default font size for regular body text. For example, <p> tags in text content, or button text. | Yes | `14px` |
| $font-size-body-s | The default font size for small body text. For example, form field descriptions, or badge text. | Yes | `12px` |
| $font-size-display-l | The default font size for large display text. | Yes | `42px` |
| $font-size-heading-xl | The default font size for h1s. | Yes | `24px` |
| $font-size-heading-l | The default font size for h2s. | Yes | `20px` |
| $font-size-heading-m | The default font size for h3s. | Yes | `18px` |
| $font-size-heading-s | The default font size for h4s. | Yes | `16px` |
| $font-size-heading-xs | The default font size for h5s. | Yes | `14px` |
| $font-weight-button | The default font weight for button text. | Yes | `700` |
| $font-weight-heading-xl | The default font weight for h1s. | Yes | `700` |
| $font-weight-heading-l | The default font weight for h2s. | Yes | `700` |
| $font-weight-heading-m | The default font weight for h3s. | Yes | `700` |
| $font-weight-heading-s | The default font weight for h4s. | Yes | `700` |
| $font-weight-heading-xs | The default font weight for h5s. | Yes | `700` |
| $line-height-body-m | The default line height for regular body text. | Yes | `20px` |
| $line-height-body-s | The default line height for small body text. | Yes | `16px` |
| $line-height-display-l | The default line height for large display text. | Yes | `48px` |
| $line-height-heading-xl | The default line height for h1s. | Yes | `30px` |
| $line-height-heading-l | The default line height for h2s. | Yes | `24px` |
| $line-height-heading-m | The default line height for h3s. | Yes | `22px` |
| $line-height-heading-s | The default line height for h4s. | Yes | `20px` |
| $line-height-heading-xs | The default line height for h5s. | Yes | `18px` |
### Motion (13)
| Name | Description | Themeable | Value |
| --- | --- | --- | --- |
| $motion-duration-avatar-gen-ai-gradient | The duration for gradient motion of gen-ai avatars. | No | `3600ms` |
| $motion-duration-avatar-loading-dots | The duration for loading motion of avatars. | No | `1200ms` |
| $motion-easing-avatar-gen-ai-gradient | The easing curve for gradient motion of gen-ai avatars. | No | `cubic-bezier(0.7, 0, 0.3, 1)` |
| $motion-easing-responsive | The easing curve for providing responsive yet smooth visual feedback. | No | `cubic-bezier(0, 0, 0, 1)` |
| $motion-easing-sticky | The easing curve for making an element sticky to a certain state. | No | `cubic-bezier(1, 0, 0.83, 1)` |
| $motion-easing-expressive | The easing curve for drawing a user's attention in an expressive way. | No | `cubic-bezier(0.84, 0, 0.16, 1)` |
| $motion-duration-responsive | The duration for making the motion feel quick and responsive. | No | `115ms` |
| $motion-duration-expressive | The duration for accommodating the motion with more expressiveness. | No | `165ms` |
| $motion-duration-complex | The duration for drawing more attention or accommodating for more complexity. | No | `250ms` |
| $motion-keyframes-fade-in | The CSS keyframes for showing an element. | No | `awsui-fade-in-35003c` |
| $motion-keyframes-fade-out | The CSS keyframes for hiding an element. | No | `awsui-fade-out-35003c` |
| $motion-keyframes-status-icon-error | The CSS keyframes applied to an error status icon to draw the user's attention. | No | `awsui-status-icon-error-35003c` |
| $motion-keyframes-scale-popup | The CSS keyframes for scaling up an element to draw the user's attention. | No | `awsui-scale-popup-35003c` |
## Usage guidelines
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](https://cloudscape.design/foundation/visual-foundation/visual-modes/) compliant. For the best results, follow the guidelines below:
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.
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.
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](https://cloudscape.design/foundation/visual-foundation/theming/) are marked as "Themeable" in the [tokens tables](https://cloudscape.design/foundation/visual-foundation/design-tokens/#tokens) below.
## Development guidelines
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](https://cloudscape.design/get-started/for-developers/using-cloudscape-components/). All of our tokens are available as [Sass](https://sass-lang.com/documentation/variables) 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](https://cloudscape.design/get-started/for-developers/using-cloudscape-components/).
### Sass variables
Load design tokens into your application using the Sass [`@use` rule](https://sass-lang.com/documentation/at-rules/use). `@import` can also work, even though it is [not recommended by the Sass team](https://sass-lang.com/documentation/at-rules/import).
```scss
@use '@cloudscape-design/design-tokens/index.scss' as awsui;
.custom-panel {
color: awsui.$color-text-body-secondary
}
```
### JavaScript variables
```jsx
import styled from 'styled-components'; // this is an example, you can use any other similar library
import * as awsui from '@cloudscape-design/design-tokens/index.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](https://amzn.github.io/style-dictionary/#/) to convert the JSON file to the desired [output format](https://amzn.github.io/style-dictionary/#/formats).
The JSON format is inspired by the [Design Tokens Format Module](https://design-tokens.github.io/community-group/format/#file-format) by the [Design Tokens Community Group](https://www.designtokens.org/). 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:
```css
{
"tokens": {}
"contexts": {
"navigation": {
"tokens": {},
}
}
}
```
Refer to the [Visual Contexts article](https://cloudscape.design/foundation/visual-foundation/visual-context/) for more information about `contexts`.
Here is the format of the `tokens` object, with a few examples:
```css
{
"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.
