Background
Convey meaning through background-color.
On this page
Overview
Background utility classes, in the form .bg-*, apply a color token as background-color for a background, surface, 'always' or opacity colors dynamically depending on the color mode.
Depending on the context of the element with a .bg-* class and its resulting color, it may be necessary to add a single child element with a [data-bs-theme] attribute to specify the color mode for its descendants.
This ensures that all descendant nodes adopt the correct color mode for the specific background color. As a result:
- Text nodes will automatically display in the appropriate content color.
- Components will respond to the color mode and adapt accordingly.
For some background colors, we have set the default content color directly using a CSS color attribute. This allows descendants text nodes to automatically display in the correct color. However this approach is only suitable when the .bg-* element contains only non-colorized text, if the element contains components, you must add a child container with the [data-bs-theme] attribute.
Utility classes that set the text color
.bg-surface-brand-primary.bg-surface-brand-secondary.bg-surface-brand-tertiary.bg-surface-status-accent-emphasized.bg-surface-status-accent-muted.bg-surface-status-positive-emphasized.bg-surface-status-positive-muted.bg-surface-status-negative-emphasized.bg-surface-status-negative-muted.bg-surface-status-warning-emphasized.bg-surface-status-warning-muted.bg-surface-status-info-emphasized.bg-surface-status-info-muted.bg-always-black.bg-always-white
In the following examples we always use a child element with [data-bs-theme] attribute as it is the recommended way to use the .bg-* classes and will work in every case even if we only have text in our elements.
Bootstrap
$enable-bootstrap-compatibility: true
Following are the equivalent Bootstrap background that you shouldn’t be using. Prefer using the classes below that conform to our design system.
<div class="p-3 mb-2 bg-primary">.bg-primary</div>
<div class="p-3 mb-2 bg-primary-subtle text-primary-emphasis">.bg-primary-subtle</div>
<div class="p-3 mb-2 bg-secondary">.bg-secondary</div>
<div class="p-3 mb-2 bg-secondary-subtle text-secondary-emphasis">.bg-secondary-subtle</div>
<div class="p-3 mb-2 bg-success">.bg-success</div>
<div class="p-3 mb-2 bg-success-subtle text-success-emphasis">.bg-success-subtle</div>
<div class="p-3 mb-2 bg-danger">.bg-danger</div>
<div class="p-3 mb-2 bg-danger-subtle text-danger-emphasis">.bg-danger-subtle</div>
<div class="p-3 mb-2 bg-warning">.bg-warning</div>
<div class="p-3 mb-2 bg-warning-subtle text-warning-emphasis">.bg-warning-subtle</div>
<div class="p-3 mb-2 bg-info">.bg-info</div>
<div class="p-3 mb-2 bg-info-subtle text-info-emphasis">.bg-info-subtle</div>
<div class="p-3 mb-2 bg-light">.bg-light</div>
<div class="p-3 mb-2 bg-light-subtle text-light-emphasis">.bg-light-subtle</div>
<div class="p-3 mb-2 bg-dark">.bg-dark</div>
<div class="p-3 mb-2 bg-dark-subtle text-dark-emphasis">.bg-dark-subtle</div>
<div class="p-3 mb-2 bg-body-secondary">.bg-body-secondary</div>
<div class="p-3 mb-2 bg-body-tertiary">.bg-body-tertiary</div>
<div class="p-3 mb-2 bg-body text-body">.bg-body</div>
<div class="p-3 mb-2 bg-black text-white">.bg-black</div>
<div class="p-3 mb-2 bg-white text-black">.bg-white</div>
<div class="p-3 mb-2 bg-transparent text-body">.bg-transparent</div> Nominal mode
Below are all the background utilities along with their recommended [data-bs-theme] attribute values to use when no other color mode is specified in the container's ancestry apart from the one on the root element:
.bg-inverse-high
.bg-inverse-low
.bg-primary
.bg-secondary
.bg-tertiary
.bg-surface-brand-primary
.bg-surface-inverse-high
.bg-surface-inverse-low
.bg-surface-primary
.bg-surface-secondary
.bg-surface-status-accent-emphasized
.bg-surface-status-accent-muted
.bg-surface-status-info-emphasized
.bg-surface-status-info-muted
.bg-surface-status-negative-emphasized
.bg-surface-status-negative-muted
.bg-surface-status-positive-emphasized
.bg-surface-status-positive-muted
.bg-surface-status-warning-emphasized
.bg-surface-status-warning-muted
.bg-surface-tertiary
.bg-always-black
.bg-always-white
.bg-transparent
<p class="bg-inverse-high p-large fw-bold"><span data-bs-theme="root-inverted">.bg-inverse-high</span></p>
<p class="bg-inverse-low p-large fw-bold"><span data-bs-theme="dark">.bg-inverse-low</span></p>
<p class="bg-primary p-large fw-bold">.bg-primary</p>
<p class="bg-secondary p-large fw-bold">.bg-secondary</p>
<p class="bg-tertiary p-large fw-bold">.bg-tertiary</p>
<p class="bg-surface-brand-primary p-large fw-bold"><span data-bs-theme="light">.bg-surface-brand-primary</span></p>
<p class="bg-surface-inverse-high p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-inverse-high</span></p>
<p class="bg-surface-inverse-low p-large fw-bold"><span data-bs-theme="dark">.bg-surface-inverse-low</span></p>
<p class="bg-surface-primary p-large fw-bold">.bg-surface-primary</p>
<p class="bg-surface-secondary p-large fw-bold">.bg-surface-secondary</p>
<p class="bg-surface-status-accent-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-accent-emphasized</span></p>
<p class="bg-surface-status-accent-muted p-large fw-bold">.bg-surface-status-accent-muted</p>
<p class="bg-surface-status-info-emphasized p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-status-info-emphasized</span></p>
<p class="bg-surface-status-info-muted p-large fw-bold">.bg-surface-status-info-muted</p>
<p class="bg-surface-status-negative-emphasized p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-status-negative-emphasized</span></p>
<p class="bg-surface-status-negative-muted p-large fw-bold">.bg-surface-status-negative-muted</p>
<p class="bg-surface-status-positive-emphasized p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-status-positive-emphasized</span></p>
<p class="bg-surface-status-positive-muted p-large fw-bold">.bg-surface-status-positive-muted</p>
<p class="bg-surface-status-warning-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-warning-emphasized</span></p>
<p class="bg-surface-status-warning-muted p-large fw-bold">.bg-surface-status-warning-muted</p>
<p class="bg-surface-tertiary p-large fw-bold">.bg-surface-tertiary</p>
<p class="bg-always-black p-large fw-bold"><span data-bs-theme="dark">.bg-always-black</span></p>
<p class="bg-always-white p-large fw-bold"><span data-bs-theme="light">.bg-always-white</span></p>
<p class="bg-transparent p-large fw-bold">.bg-transparent</p> We also provide opacity-based background classes, which should be used only in specific contexts where you need to adjust background opacity to enhance text readability. In most cases, .bg-secondary or .bg-surface-secondary are the preferred alternatives.
.bg-opacity-lower
.bg-opacity-lowest
<p class="bg-opacity-lower p-large fw-bold">.bg-opacity-lower</p>
<p class="bg-opacity-lowest p-large fw-bold">.bg-opacity-lowest</p> Inside a static color mode
The following examples demonstrate the proper use of [data-bs-theme] in static color mode contexts. In this case, background colors will stay the same so it's safe to use a corresponding [data-bs-theme] to set the mode for the descendant nodes.
For example in a light color mode context, dark backgrounds like .bg-inverse-high will stay dark so we must add a [data-bs-theme="dark"] child element to set the descendant in the right mode.
You’re in a static light context
.bg-inverse-high
.bg-inverse-low
.bg-primary
.bg-secondary
.bg-tertiary
.bg-surface-brand-primary
.bg-surface-inverse-high
.bg-surface-inverse-low
.bg-surface-primary
.bg-surface-secondary
.bg-surface-status-accent-emphasized
.bg-surface-status-accent-muted
.bg-surface-status-info-emphasized
.bg-surface-status-info-muted
.bg-surface-status-negative-emphasized
.bg-surface-status-negative-muted
.bg-surface-status-positive-emphasized
.bg-surface-status-positive-muted
.bg-surface-status-warning-emphasized
.bg-surface-status-warning-muted
.bg-surface-tertiary
.bg-always-black
.bg-always-white
.bg-transparent
<div class="bg-always-white p-large">
<div data-bs-theme="light">
<p class="bg-inverse-high p-large fw-bold"><span data-bs-theme="dark">.bg-inverse-high</span></p>
<p class="bg-inverse-low p-large fw-bold"><span data-bs-theme="dark">.bg-inverse-low</span></p>
<p class="bg-primary p-large fw-bold">.bg-primary</p>
<p class="bg-secondary p-large fw-bold">.bg-secondary</p>
<p class="bg-tertiary p-large fw-bold">.bg-tertiary</p>
<p class="bg-surface-brand-primary p-large fw-bold">.bg-surface-brand-primary</p>
<p class="bg-surface-inverse-high p-large fw-bold"><span data-bs-theme="dark">.bg-surface-inverse-high</span></p>
<p class="bg-surface-inverse-low p-large fw-bold"><span data-bs-theme="dark">.bg-surface-inverse-low</span></p>
<p class="bg-surface-primary p-large fw-bold">.bg-surface-primary</p>
<p class="bg-surface-secondary p-large fw-bold">.bg-surface-secondary</p>
<p class="bg-surface-status-accent-emphasized p-large fw-bold">.bg-surface-status-accent-emphasized</p>
<p class="bg-surface-status-accent-muted p-large fw-bold">.bg-surface-status-accent-muted</p>
<p class="bg-surface-status-info-emphasized p-large fw-bold"><span data-bs-theme="dark">.bg-surface-status-info-emphasized</span></p>
<p class="bg-surface-status-info-muted p-large fw-bold">.bg-surface-status-info-muted</p>
<p class="bg-surface-status-negative-emphasized p-large fw-bold"><span data-bs-theme="dark">.bg-surface-status-negative-emphasized</span></p>
<p class="bg-surface-status-negative-muted p-large fw-bold">.bg-surface-status-negative-muted</p>
<p class="bg-surface-status-positive-emphasized p-large fw-bold"><span data-bs-theme="dark">.bg-surface-status-positive-emphasized</span></p>
<p class="bg-surface-status-positive-muted p-large fw-bold">.bg-surface-status-positive-muted</p>
<p class="bg-surface-status-warning-emphasized p-large fw-bold">.bg-surface-status-warning-emphasized</p>
<p class="bg-surface-status-warning-muted p-large fw-bold">.bg-surface-status-warning-muted</p>
<p class="bg-surface-tertiary p-large fw-bold">.bg-surface-tertiary</p>
<p class="bg-always-black p-large fw-bold"><span data-bs-theme="dark">.bg-always-black</span></p>
<p class="bg-always-white p-large fw-bold"><span data-bs-theme="light">.bg-always-white</span></p>
<p class="bg-transparent p-large fw-bold">.bg-transparent</p>
</div>
</div> .bg-opacity-lower
.bg-opacity-lowest
<div class="bg-always-white p-large">
<div data-bs-theme="light">
<p class="bg-opacity-lower p-large fw-bold">.bg-opacity-lower</p>
<p class="bg-opacity-lowest p-large fw-bold">.bg-opacity-lowest</p>
</div>
</div> With a dark color mode context, light backgrounds like .bg-inverse-high will stay light so we must add a [data-bs-theme="light"] child element for descendants to set the descendant in the right mode.
You’re in a static dark context
.bg-inverse-high
.bg-inverse-low
.bg-primary
.bg-secondary
.bg-tertiary
.bg-surface-brand-primary
.bg-surface-inverse-high
.bg-surface-inverse-low
.bg-surface-primary
.bg-surface-secondary
.bg-surface-status-accent-emphasized
.bg-surface-status-accent-muted
.bg-surface-status-info-emphasized
.bg-surface-status-info-muted
.bg-surface-status-negative-emphasized
.bg-surface-status-negative-muted
.bg-surface-status-positive-emphasized
.bg-surface-status-positive-muted
.bg-surface-status-warning-emphasized
.bg-surface-status-warning-muted
.bg-surface-tertiary
.bg-always-black
.bg-always-white
.bg-transparent
<div class="bg-always-black p-large">
<div data-bs-theme="dark">
<p class="bg-inverse-high p-large fw-bold"><span data-bs-theme="light">.bg-inverse-high</span></p>
<p class="bg-inverse-low p-large fw-bold">.bg-inverse-low</p>
<p class="bg-primary p-large fw-bold">.bg-primary</p>
<p class="bg-secondary p-large fw-bold">.bg-secondary</p>
<p class="bg-tertiary p-large fw-bold">.bg-tertiary</p>
<p class="bg-surface-brand-primary p-large fw-bold"><span data-bs-theme="light">.bg-surface-brand-primary</span></p>
<p class="bg-surface-inverse-high p-large fw-bold"><span data-bs-theme="light">.bg-surface-inverse-high</span></p>
<p class="bg-surface-inverse-low p-large fw-bold">.bg-surface-inverse-low</p>
<p class="bg-surface-primary p-large fw-bold">.bg-surface-primary</p>
<p class="bg-surface-secondary p-large fw-bold">.bg-surface-secondary</p>
<p class="bg-surface-status-accent-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-accent-emphasized</span></p>
<p class="bg-surface-status-accent-muted p-large fw-bold">.bg-surface-status-accent-muted</p>
<p class="bg-surface-status-info-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-info-emphasized</span></p>
<p class="bg-surface-status-info-muted p-large fw-bold">.bg-surface-status-info-muted</p>
<p class="bg-surface-status-negative-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-negative-emphasized</span></p>
<p class="bg-surface-status-negative-muted p-large fw-bold">.bg-surface-status-negative-muted</p>
<p class="bg-surface-status-positive-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-positive-emphasized</span></p>
<p class="bg-surface-status-positive-muted p-large fw-bold">.bg-surface-status-positive-muted</p>
<p class="bg-surface-status-warning-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-warning-emphasized</span></p>
<p class="bg-surface-status-warning-muted p-large fw-bold">.bg-surface-status-warning-muted</p>
<p class="bg-surface-tertiary p-large fw-bold">.bg-surface-tertiary</p>
<p class="bg-always-black p-large fw-bold"><span data-bs-theme="dark">.bg-always-black</span></p>
<p class="bg-always-white p-large fw-bold"><span data-bs-theme="light">.bg-always-white</span></p>
<p class="bg-transparent p-large fw-bold">.bg-transparent</p>
</div>
</div> .bg-opacity-lower
.bg-opacity-lowest
<div class="bg-always-black p-large">
<div data-bs-theme="dark">
<p class="bg-opacity-lower p-large fw-bold">.bg-opacity-lower</p>
<p class="bg-opacity-lowest p-large fw-bold">.bg-opacity-lowest</p>
</div>
</div> Inside a dynamic color mode
The following examples demonstrate the proper use of [data-bs-theme] in dynamic contexts. In this case you must take into account that some background colors will change when the color mode context change. For example in a (root) light color mode, a parent container with [data-bs-theme="root-inverted"] will make the background color of a container with .bg-inverse-high light, therefore we must switch back the local color mode to root for its descendants.
You’re in a dynamic root-inverted context
.bg-inverse-high
.bg-inverse-low
.bg-primary
.bg-secondary
.bg-tertiary
.bg-surface-brand-primary
.bg-surface-inverse-high
.bg-surface-inverse-low
.bg-surface-primary
.bg-surface-secondary
.bg-surface-status-accent-emphasized
.bg-surface-status-accent-muted
.bg-surface-status-info-emphasized
.bg-surface-status-info-muted
.bg-surface-status-negative-emphasized
.bg-surface-status-negative-muted
.bg-surface-status-positive-emphasized
.bg-surface-status-positive-muted
.bg-surface-status-warning-emphasized
.bg-surface-status-warning-muted
.bg-surface-tertiary
.bg-always-black
.bg-always-white
.bg-transparent
<div class="bg-inverse-high p-large">
<div data-bs-theme="root-inverted">
<p class="bg-inverse-high p-large fw-bold"><span data-bs-theme="root">.bg-inverse-high</span></p>
<p class="bg-inverse-low p-large fw-bold"><span data-bs-theme="dark">.bg-inverse-low</span></p>
<p class="bg-primary p-large fw-bold">.bg-primary</p>
<p class="bg-secondary p-large fw-bold">.bg-secondary</p>
<p class="bg-tertiary p-large fw-bold">.bg-tertiary</p>
<p class="bg-surface-brand-primary p-large fw-bold"><span data-bs-theme="light">.bg-surface-brand-primary</span></p>
<p class="bg-surface-inverse-high p-large fw-bold"><span data-bs-theme="root">.bg-surface-inverse-high</span></p>
<p class="bg-surface-inverse-low p-large fw-bold"><span data-bs-theme="dark">.bg-surface-inverse-low</span></p>
<p class="bg-surface-primary p-large fw-bold">.bg-surface-primary</p>
<p class="bg-surface-secondary p-large fw-bold">.bg-surface-secondary</p>
<p class="bg-surface-status-accent-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-accent-emphasized</span></p>
<p class="bg-surface-status-accent-muted p-large fw-bold">.bg-surface-status-accent-muted</p>
<p class="bg-surface-status-info-emphasized p-large fw-bold"><span data-bs-theme="root">.bg-surface-status-info-emphasized</span></p>
<p class="bg-surface-status-info-muted p-large fw-bold">.bg-surface-status-info-muted</p>
<p class="bg-surface-status-negative-emphasized p-large fw-bold"><span data-bs-theme="root">.bg-surface-status-negative-emphasized</span></p>
<p class="bg-surface-status-negative-muted p-large fw-bold">.bg-surface-status-negative-muted</p>
<p class="bg-surface-status-positive-emphasized p-large fw-bold"><span data-bs-theme="root">.bg-surface-status-positive-emphasized</span></p>
<p class="bg-surface-status-positive-muted p-large fw-bold">.bg-surface-status-positive-muted</p>
<p class="bg-surface-status-warning-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-warning-emphasized</span></p>
<p class="bg-surface-status-warning-muted p-large fw-bold">.bg-surface-status-warning-muted</p>
<p class="bg-surface-tertiary p-large fw-bold">.bg-surface-tertiary</p>
<p class="bg-always-black p-large fw-bold"><span data-bs-theme="dark">.bg-always-black</span></p>
<p class="bg-always-white p-large fw-bold"><span data-bs-theme="light">.bg-always-white</span></p>
<p class="bg-transparent p-large fw-bold">.bg-transparent</p>
</div>
</div> .bg-opacity-lower
.bg-opacity-lowest
<div class="bg-inverse-high p-large">
<div data-bs-theme="root-inverted">
<p class="bg-opacity-lower p-large fw-bold">.bg-opacity-lower</p>
<p class="bg-opacity-lowest p-large fw-bold">.bg-opacity-lowest</p>
</div>
</div> Colored backgrounds
The following colored backgrounds are designed for specific use cases and can only accommodate a limited set of components, such as buttons, links, and text elements. For accessibility reasons, we need to remove the color of these components this is achieved by the colored variants of buttons and links.
.bg-surface-brand-primary
.bg-surface-status-accent-emphasized
.bg-surface-status-info-emphasized
.bg-surface-status-negative-emphasized
.bg-surface-status-positive-emphasized
.bg-surface-status-warning-emphasized
<p class="bg-surface-brand-primary p-large fw-bold"><span data-bs-theme="light">.bg-surface-brand-primary</span></p>
<p class="bg-surface-status-accent-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-accent-emphasized</span></p>
<p class="bg-surface-status-info-emphasized p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-status-info-emphasized</span></p>
<p class="bg-surface-status-negative-emphasized p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-status-negative-emphasized</span></p>
<p class="bg-surface-status-positive-emphasized p-large fw-bold"><span data-bs-theme="root-inverted">.bg-surface-status-positive-emphasized</span></p>
<p class="bg-surface-status-warning-emphasized p-large fw-bold"><span data-bs-theme="light">.bg-surface-status-warning-emphasized</span></p> Multiple backgrounds
Occasionally, you may need to layer two background colors on top of each other. This scenario arises when design requirements call for dual fill colors on containers—for example, when a parent container has a specific background and you need to place a card over it. To implement this in OUDS Web, you'll need to create two nested containers, each with its own specified background color utility class.
<div class="p-large" style="background: repeating-linear-gradient(-45deg, var(--bs-color-bg-inverse-high), var(--bs-color-bg-inverse-high) 40px, var(--bs-color-bg-secondary) 40px, var(--bs-color-bg-secondary) 80px)">
<div class="bg-secondary">
<div class="bg-surface-secondary p-large">
.bg-secondary and .bg-surface-brand-secondary
</div>
</div>
</div>
Bootstrap
$enable-bootstrap-compatibility: true
Color and background helpers shouldn’t be used in OUDS Web context please consider using our color modes directly as explained in this page.
Color and background helpers combine the power of our .text-* utilities and .bg-* utilities in one class. Using our Sass color-contrast() function, we automatically determine a contrasting color for a particular background-color.
<div class="text-bg-primary p-3">Primary with contrasting color</div>
<div class="text-bg-secondary p-3">Secondary with contrasting color</div>
<div class="text-bg-success p-3">Success with contrasting color</div>
<div class="text-bg-danger p-3">Danger with contrasting color</div>
<div class="text-bg-warning p-3">Warning with contrasting color</div>
<div class="text-bg-info p-3">Info with contrasting color</div>
<div class="text-bg-light p-3">Light with contrasting color</div>
<div class="text-bg-dark p-3">Dark with contrasting color</div>