Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
  • About
  • Foundation
    • Overview
  • Visual foundation
    • Colors
    • Content density
    • Data visualization colors
    • Design tokens
    • Iconography
    • Layout
    • Motion
    • Spacing
    • Theming
    • Typography
    • Visual context
    • Visual modes
    • Visual style
  • Core principles
    • Accessibility
    • Responsive design
  1. Cloudscape Design System
    • Foundation
    • Visual foundation: Design tokens

    Design tokens

    A design token is an abstraction of a visual property, such as color, size, or animation.

      On this page

      • Key UX concepts
      • Usage guidelines
      • Development guidelines
      • Tokens

      Key UX concepts

      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".

      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 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.

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

      Tokens

      Colors (235)

        • ...
        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
        • About
        • Connect
        • Privacy 
        • Site terms 
        • © 2023, Amazon Web Services, Inc. or its affiliates. All rights reserved.
        Made with love atAWS