What is a visual context?

The concept of visual context refers to a specific area of the UI, where the visual appearance of Cloudscape components adapts to the context that they’re placed in. This adds a new dimension for visual modes: modes are global (they apply to the whole page and across pages), while visual contexts are local (they apply only to a subset of the interface). For example, components within a visual context can look different in light and dark mode. The following use cases show how visual contexts fit into our visual foundation.

Use cases in the system

  1. Top navigation

    The top navigation component uses grey as its background color, regardless of which mode the interface is displayed in. This requires that all components placed inside the top navigation, such as a button dropdown and its child elements (such as dropdown items) adapt to its visual context. This ensures they’re visible even when the overall user interface (UI) is in light mode.

  2. Dark header in visual refresh

    Cloudscape Visual Refresh offers page-level dark headers in both light and dark mode. This requires that all components placed inside the dark header adapt to the dark header by switching their visuals to those of dark mode even when the overall UI is in light mode. 

  3. Flashbar

    The flashbar component is designed so that it has a different solid background fill compared to other components, which commonly have a white background such as containers, cards and tiles. This requires that all text components placed inside a flashbar, such as buttons, visually adapt to its visual context. This ensures they maintain sufficient color contrast.

  4. Alert

    The alert component uses different colored backgrounds to communicate different types of messages. Secondary buttons, which are typically styled in blue, need to maintain sufficient color contrast. This is to avoid creating conflicting messages with status-related color in messages.

How can I use visual context in my service?

Currently, only specific Cloudscape components use visual contexts. It's not possible to use the predefined contexts in other areas of the system or to create new visual contexts.

Visual contexts are themed separately from the global design tokens.

Implementation guidelines

Visual contexts are implemented in the system by defining specific values for design tokens for each context. All the Cloudscape components embedded inside a visual context will automatically inherit the newly defined look and feel. The only exception to this rule is the modal component, which is not subject to visual contexts. This is because it’s displayed in a different layer of the application.

If you’re using design tokens to style custom components embedded in a visual context, the values for some design tokens might be different than what is documented in the design tokens table. Make sure that the custom components display correctly within a visual context, such as top navigation, high-contrast header, flashbar, and alert.