Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
  • About

Foundation


  • 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
      • Focus management principles
      • Building accessible experiences
    • Responsive design
    • Bidirectionality
  1. Cloudscape Design System
    • Foundation
    • Visual foundation: Theming
    1. Cloudscape Design System
    2. Foundation
    3. Visual foundation: Theming

    Theming

    Theming allows for the customization of specific visual attributes across the product interface. 

    Published: June 23, 2022

    On this page

    1. Key UX concepts
    2. What can I change through theming?
    3. Accessibility
    4. Dark mode
    5. Visual contexts
    6. General guidelines
    7. Implementation

    Did this page help you?

    Tell us more - optional

    1000 character(s) available. Do not disclose any personal, commercially sensitive, or confidential information.

    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: typography, 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. To experiment with theming, you can modify the values of themeable tokens in our demos by choosing Theme on the right of the top navigation.

    Not supported

    • Creating new design tokens.

    • Changing spacing, motion, iconography, grid, 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-navigation
    Used for the Top navigation component and its content.
    header
    Used for the dark header area of the page.
    flashbar
    Used for the Flashbar component and its content.
    alert
    Used 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

    Cloudscape offers two approaches to implement theming:

    • Build-time theming: you can create a package that contains all Cloudscape components with your custom theme.

    • Runtime theming: you can apply a theme in the browser, on top of the default Cloudscape components.

    Below you will find more details about each approach, and recommendations on when to use each based on your use case.
    Both approaches require you to define a theme as input parameter.

    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 provide 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: {...}
       },
    };
    

    Applying a theme

    Build-time theming

    Build time theming allows you to create a package that contains all Cloudscape components with your custom theme.

    Generate themed artifacts

    Use the theming module of @cloudscape-design/components-themeable module as part of your build process.

    import { join } from 'path';
    import { buildThemedComponents } from '@cloudscape-design/components-themeable/theming';
    
    const theme = {...};
    
    buildThemedComponents({
      theme,
      outputDir: join(__dirname, './themed'),
    });
    

    Upon execution, the /themed folder will contain:

    • a /components folder that exports Cloudscape components with your custom theme

    • a /design-tokens folder that exports design tokens

    Use themed artifacts in your application

    Replace all imports of Cloudscape components and design tokens to direct them to these newly created folders.

    Use themed artifacts in dependencies that use Cloudscape (advanced)
    If you have additional dependencies using Cloudscape components as peer dependency, configure your bundler (e.g. Webpack ) to ensure that they also use your themed artifacts. Here is an example of configuration for Webpack.

    // webpack.config.js
    
    const path = require('path');
    
    module.exports = {
      //...
      resolve: {
        alias: {
          '@cloudscape-design/components': '[outputDir]/components',
          '@cloudscape-design/design-tokens': '[outputDir]/design-tokens',
        },
      },
    };
    

    Runtime theming

    Runtime theming injects an inline stylesheet overriding built-in design tokens values. Use the theming module of @cloudscape-design/components module in your application.

    import { Theme, applyTheme } from '@cloudscape-design/components/theming';
    
    const theme: Theme = {...};
    
    const { reset } = applyTheme({ theme });
    // Use the reset method to remove the custom theme
    

    Make sure your Content Security Policy supports inline stylesheets by adding Content-Security-Policy: style-src: 'self' 'unsafe-inline';.

    Refer to the demo pages and the theme switcher in the top of the navigation bar to try out runtime theming.

    Build-time vs runtime theming

    We recommend to use build-time theming because

    • It’s compatible with stricter Content Security Policies (CSP): unlike runtime theming, it doesn't require injection of inline styles.

    • It offers better performance: runtime theming requires to bundle a large file that contains default theme definitions, so that updated styles can be generated.

    • It provides better support for Server-Side Rendering (SSR): for SSR-based applications, runtime theming is applied only after hydration, providing a sub-optimal user experience as the user sees the non-themed application first.

    Use runtime theming only if your application allows each customer to define their own theme, In this scenario, built-time theming would require you to build and deploy a different application for each of them.

    Did this page help you?

    Tell us more - optional

    1000 character(s) available. Do not disclose any personal, commercially sensitive, or confidential information.
    • About
    • Connect
    • Privacy 
    • Site terms 
    • © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.
    Made with love atAWS