Key UX concepts

Cloudscape currently offers a default theme, which you can use for your own applications or products. Theming is used for modification of some visual aspects of the UI to meet product-specific needs.

  • Theming is applied to foundational elements and reflected in all elements provided by the system that uses its foundation. To promote a consistent and unified brand experience for users, Cloudscape doesn’t currently support theming individual instances of components.

  • Theming is achieved by changing specific design tokens. There are three categories of design tokens: typeface, colors, and border radii. Changes are applied globally across the UI and are reflected in all components which use the system's foundation.

  • Theming can be used to better reflect a brand identity or meet other industry-specific needs.

What can I change through theming?

Supported

  • Changing color values of brand or common UI related tokens.

  • Changing the typeface of your product.

  • Changing the border radius of elements. For example: containers, form elements, alerts, and notifications.

  • Applying visual changes globally across a product.

  • Applying visual changes to predefined visual contexts.

Color, typography, and border radius tokens that can be themed are marked as themeable in the tokens table. Data visualization color tokens that are themeable can be found in the respective color palette tables.

Not supported

  • Creating new design tokens.

  • Changing spacing, motion, iconography, grid, font size, line height, or other foundational elements not listed above.

  • Making visual changes to instances of components and not others.

If you require any of these features, open a feature request with us  and share detailed use cases and product requirements.

Accessibility

Cloudscape components are built according to accessibility guidelines and industry best practices, such as semantic markup and use of appropriate ARIA  attributes. If you modify colors, ensure that you employ proper color contrast checks.

Dark mode

Cloudscape offers a dark mode. Each color-related design token has a light mode and a dark mode value. If you don't specify a dark mode custom value, it will automatically apply the default one offered by the system. To maintain correlation and brand identity in themed interfaces, we recommend that you specify the dark mode alternative for modified color tokens.

Visual contexts

When a visual context uses a visual-context-specific value for a design token, this value is not overridden by global theming changes to the design token. To theme the design token in a visual context, you need to explicitly define a context-scoped set of overrides in your theme.

Available visual contexts

Context ID
Description
top-navigationUsed for the Top navigation component and its content.
headerUsed for the dark header area of the page.
flashbarUsed for the Flashbar component and its content.
alertUsed for the Alert component and its content.

General guidelines

Do

  • Less is more: use theming judiciously. A consistent brand experience can be achieved through calculated theming.
  • For themed interfaces, perform thorough accessibility checks.
  • While theming, configure the dark mode equivalent for each custom light mode color value.

Don't

  • Don’t theme the UI unless your product’s specific needs require you to. Think about the customer experience first.
  • Don’t override design tokens which are not modifiable. If you require more design tokens for your theming use case, open a feature request with us .

Implementation

To apply theming, you need to 1) define a theme and 2) create a custom build of Cloudscape components that uses your theme.

Defining a theme

You can define a theme by providing custom values for themeable design tokens. There are three categories of themeable tokens: typography, color, and border radius.

Typography tokens

The custom values you set for typography tokens (such as fontFamilyBase) are applied globally in the entire application, including visual contexts. When setting custom values for font families, ensure that you also bundle the corresponding font assets.

For example, a theme with a new value for fontFamilyBase looks like the following:

const theme = {
   tokens: {
        fontFamilyBase: "'Helvetica Neue', Roboto, Arial, sans-serif",
   },
};

Border radius tokens

The values you set for border radius tokens (such as borderRadiusButton) are applied globally across the entire UI, including visual contexts.

For example, a theme with a new value for borderRadiusButton looks like the following:

const theme = {
   tokens: {
        borderRadiusButton: "4px",
   },
};

Color tokens

You can set custom values for color tokens globally, and for each visual context. If you don't explicitly specify a custom value for a visual context, the default Cloudscape value will be applied.

You can also specify a value for both light and dark mode. Here is an example:

const theme = {
   tokens: {
      // Values are applied globally, except for visual contexts
      colorBackgroundLayoutMain: {
          // Specify value for light and dark mode
          light: 'white',
          dark: 'blue'
      }
      // Shorter syntax to apply the same value for both light and dark mode
      colorTextAccent: '#0073bb',
   },
   contexts: {
      // Values for visual contexts. Unless specified, default values will be applied
      'top-navigation': {
         tokens: {
            colorTextAccent: '#44b9d6',
         },
      },
      header: {...}
      flashbar: {...}
      alert: {...}
   },
};

Building themed components

To apply the defined theme to your application, use the theming module of the @cloudscape-design/components-themeable package in your build process. Note that this package supports NodeJS > v12.

API

buildThemedComponents({ theme: Theme, outputDir: string }) - returns a Promise  resolving with void. On successful completion, outputDir will contain themed components that use the passed theme.

To create a themed components package, you need to specify a theme and output directory as parameters to the buildThemedComponents function. Take a look at the following TypeScript example generating a new themed components directory with a custom font family:

import { join } from 'path';
import { Theme, buildThemedComponents } from '@cloudscape-design/components-themeable/theming';

const theme: Theme = {
   tokens: {
        fontFamilyBase: "'Helvetica Neue', Roboto, Arial, sans-serif",
   },
};

buildThemedComponents({ theme, outputDir: join(__dirname, './themed') });

After building the themed version of the artifacts, you will have two options:

  1. Publish the /components and /design-tokens folders as new packages (recommended)

  2. Use the output as a local NPM dependency: extend the dependencies section in your package.json file by "@cloudscape-design/components-themed": "file:<path to output>/components and "@cloudscape-design/design-tokens-themed": "file:<path to output>/design-tokens". Run the npm install command afterwards.

If you already have an application using the vanilla components, you will need to update the import paths throughout your application to point to the themed package.