Apply localized theming contexts to maximize accessibility against various surface colors.
Contextual themes apply partial style overrides to individual parts of a page's content.
For applying light/dark mode to an entire application, see global theming.
Localized theming contexts override critical color roles with accessible values based on the current surface color. These local overrides automatically adjust the default appearance of many Bolt components and styles in order to adapt to the local context.
Bolt provides pre-defined CSS background classes to apply localized contextual themes.
When a background class is applied to a container, it updates the values of context tokens within that container. Bolt components automatically update their appearance as well, because they are built using dynamic context and theme tokens.
<div class="bolt-background-darkBlue">
<bolt-button>Button on dark blue</bolt-button>
</div>Context tokens can be used to build components that are compatible with contextual theming.
See design tokens documentation for a full list of values.
Use context tokens when styling elements that are impacted by the background color of their container. For example, text and icons should use contextual color to ensure legibility¸
This text is styled with a context token, so it should be legible no matter the background color.
.custom-text {
color: var(--bolt-context-onSurface);
}Local context roles override global theme roles.
If no context applies, context tokens default to their associated theme token value.
Custom contextual themes should only be considered as a last resort.
Authors of custom contextual themes are responsible for choosing colors in accordance with brand standards and contrast minimums.
Contextual themes rely on CSS custom properties to function.
--bolt-context-surface.my-custom-background {
/* start with the surface */
--bolt-context-surface: #abc123;
/* define ALL remaining context tokens */
...
}Every CSS custom property listed in context tokens needs to be explicitly defined in a contextual theme.