Colors
Compose adaptive backgrounds, semantic surfaces, opacity levels and text colors with css-utils.
Syntax
Combine .bg-{color} with content that inherits its foreground. Use .text-* only when you intentionally need a different foreground on a known surface.
<div class="bg-primary rounded p-3">
<p class="mb-0 text-inherit">Project updates</p>
</div>Class and token reference
| Class or token family | Purpose |
|---|---|
| Theme surface and its foreground: primary, secondary, accent, success, warning or error. |
| Semantic surfaces with matching text defaults. |
.bg-opacity-{percentage} | Background-only opacity; the supported levels are shown below. |
.bg-transparent | Shows the underlying surface without resetting text color. |
| Explicit theme text or underline color. |
| Semantic text colors or inherited foreground. |
| Fixed gray values from 50 through 950 in steps of 50. |
| Interactive primary foregrounds; independent from primary filled surfaces. |
Theme-aware color system
Background utilities choose a readable foreground automatically, while text utilities provide explicit control when the surrounding surface is already known.
Every solid background includes a fallback: theme colors use --on-*, semantic surfaces use --text-color or --text-inverse, and fixed colors use black/white foregrounds. SVG fill follows the text color. Browsers with contrast-color() select black or white dynamically. See the browser support policy.
Keep --on-* and surface text tokens in sync when customizing background tokens. Gray fallbacks are selected at Sass compilation time; runtime changes to gray or black/white tokens need a contrast check and, if necessary, an explicit .text-* override.
Use .bg-transparent when an element should expose the surface behind it. It only resets background-color and does not change text color, SVG fill or background opacity.
<div class="bg-transparent">Content on the underlying surface</div>Interactive foregrounds
Filled primary surfaces and interactive foregrounds can use different colors. Links, navigation, menus, lists, tabs, pagination hover states, expansion-panel actions and primary text or outline buttons and interactive chips use the semantic action tokens. Solid primary buttons and chips, passive primary chips and current pagination items continue to use their theme-color tokens. The global focus color follows the action color by default and remains independently overridable.
:root {
--primary: #d9ccff;
--primary-hover: #cabbff;
--primary-active: #b9a7ff;
--on-primary: #24183f;
--action-color: #5b21b6;
--action-color-hover: #4c1d95;
--action-color-active: #3b1673;
--focus-outline-color: var(--action-color);
}Theme colors
Theme colors adapt between light and dark mode. Use primary for the main action hierarchy, secondary for supporting controls and accent for supplementary brand highlights or categories. Accent does not communicate a status; use success, warning and error for those meanings. The hex labels below show the light-theme defaults.
.bg-primary--primary.bg-secondary--secondary.bg-accent--accent.bg-success--success.bg-warning--warning.bg-error--error<div class="bg-primary">Primary</div>
<div class="bg-secondary">Secondary</div>
<div class="bg-accent">Accent</div>
<div class="bg-success">Success</div>
<div class="bg-warning">Warning</div>
<div class="bg-error">Error</div>Every .bg-* utility uses an authored foreground and matching SVG fill; browsers with contrast-color() select black or white against the rendered background. Add a later .text-* utility only when a deliberate, tested override is needed.
Accent color
The default accent is #b515a7 in the light theme and #f291dc in the dark theme. Its foreground token, --on-accent, remains readable on the base, hover and active shades. Use the accent variants when an extra color is useful without assigning status meaning:
<span class="chip chip-accent chip-solid">Featured</span>
<p class="text-accent">Category highlight</p>
<div class="border border-accent">Accent border</div>
<a class="text-underline-accent" href="/">Accent underline</a>
<button class="btn btn-accent btn-outline" type="button">Explore</button>The same color-map entry also provides .btn-accent, .chip-accent and .icon-btn-accent variants. --accent, --accent-hover, --accent-active and --on-accent can be overridden for each theme; keep the foreground readable on all three shades.
:root {
--accent: #b515a7;
--accent-hover: #9d128f;
--accent-active: #870c7a;
--on-accent: #ffffff;
}
:root[data-theme='dark'] {
--accent: #f291dc;
--accent-hover: #f6b0e6;
--accent-active: #f9c9ee;
--on-accent: #1a1a1a;
}Semantic surfaces
Surface utilities follow the current theme and are useful for page layers, containers, hover previews and selected regions.
bg-bodybg-surfacebg-inversebg-surface-hoverbg-highlightbg-active<div class="bg-body">Body</div>
<div class="bg-surface">Surface</div>
<div class="bg-inverse">Inverse</div>
<div class="bg-surface-hover">Surface hover</div>
<div class="bg-highlight">Highlight</div>
<div class="bg-active">Active</div>Background opacity
Combine any background utility with opacity levels from 0% to 100% in 10-point steps. The existing .bg-opacity-25 and .bg-opacity-75 levels are also available. This includes theme colors, semantic surfaces such as .bg-highlight, white, black and every gray step. In browsers with contrast-color(), the color is composited against the inherited backdrop before its foreground is selected. Without that feature, these backgrounds remain opaque and use their authored foreground colors, including when nested. This keeps fallback text readable.
bg-primarybg-opacity-90bg-opacity-80bg-opacity-75bg-opacity-70bg-opacity-60bg-opacity-50bg-opacity-40bg-opacity-30bg-opacity-25bg-opacity-20bg-opacity-10bg-opacity-0<div class="bg-primary">100%</div>
<div class="bg-primary bg-opacity-90">90%</div>
<div class="bg-primary bg-opacity-75">75%</div>
<div class="bg-primary bg-opacity-50">50%</div>
<div class="bg-primary bg-opacity-25">25%</div>
<div class="bg-primary bg-opacity-10">10%</div>
<div class="bg-primary bg-opacity-0">0%</div>
<div class="bg-highlight bg-opacity-50">Highlight at 50%</div>Layered backgrounds
An opacity utility affects only the element that carries it. A nested .bg-* starts opaque again. If any ancestor carries .bg-opacity-*, a descendant background with its own opacity class also stays opaque, even at 0% or 100% and across transparent wrappers. This safe fallback prevents text contrast from depending on an outdated ancestor composite at deeper nesting levels. Only the first opacity level is translucent; use sibling surfaces when each needs transparency.
Nested opacity uses a solid error background
<div class="bg-inverse p-3">
<div class="bg-primary bg-opacity-50 p-3">Readable on inverse</div>
</div>
<div class="bg-primary bg-opacity-25 p-3">
<div class="bg-error p-3">Opaque error background</div>
<div class="bg-error bg-opacity-50 p-3">Nested opacity uses a solid error background</div>
</div>The page body and solid background utilities publish their color through --bg-opacity-backdrop. Application-specific solid surfaces should publish that token in their stylesheet. For gradients, images or other varying backdrops, choose and test an explicit text color.
Background gray scale
Gray backgrounds remain fixed across themes. Their foreground is still selected automatically, making every step legible as a reference swatch.
bg-gray-50bg-gray-100bg-gray-150bg-gray-200bg-gray-250bg-gray-300bg-gray-350bg-gray-400bg-gray-450bg-gray-500bg-gray-550bg-gray-600bg-gray-650bg-gray-700bg-gray-750bg-gray-800bg-gray-850bg-gray-900bg-gray-950<div class="bg-gray-50">bg-gray-50</div>
<div class="bg-gray-100">bg-gray-100</div>
<div class="bg-gray-150">bg-gray-150</div>
<div class="bg-gray-200">bg-gray-200</div>
<div class="bg-gray-250">bg-gray-250</div>
<div class="bg-gray-300">bg-gray-300</div>
<div class="bg-gray-350">bg-gray-350</div>
<div class="bg-gray-400">bg-gray-400</div>
<div class="bg-gray-450">bg-gray-450</div>
<div class="bg-gray-500">bg-gray-500</div>
<div class="bg-gray-550">bg-gray-550</div>
<div class="bg-gray-600">bg-gray-600</div>
<div class="bg-gray-650">bg-gray-650</div>
<div class="bg-gray-700">bg-gray-700</div>
<div class="bg-gray-750">bg-gray-750</div>
<div class="bg-gray-800">bg-gray-800</div>
<div class="bg-gray-850">bg-gray-850</div>
<div class="bg-gray-900">bg-gray-900</div>
<div class="bg-gray-950">bg-gray-950</div>Theme text colors
Text utilities apply the corresponding theme token directly. They do not choose a contrast color, so verify them against every background on which they appear.
<p class="text-primary">Primary text</p>
<p class="text-secondary">Secondary text</p>
<p class="text-accent">Accent text</p>
<p class="text-success">Success text</p>
<p class="text-warning">Warning text</p>
<p class="text-error">Error text</p>Theme underline colors
Use .text-underline-* to add an offset underline in a theme color without changing the text color itself.
<a class="text-underline-primary" href="/">Primary underline</a>
<a class="text-underline-accent" href="/">Accent underline</a>
<span class="text-underline-success">Success underline</span>
<span class="text-underline-error">Error underline</span>Semantic text
Use semantic text colors for normal copy, supporting information and known inverse surfaces.
text-inverse<p class="text-body">Body text</p>
<p class="text-muted">Muted supporting text</p>
<p class="text-subtle">Subtle metadata</p>
<div class="bg-inverse"><p class="text-inverse">Inverse text</p></div>
<div class="bg-primary"><p class="text-inherit">Inherited foreground</p></div>Text gray scale
Raw gray text utilities are fixed values. The light half of the scale is previewed on black and the dark half on white so the class names remain readable in either site theme.
Light gray text
text-gray-50text-gray-100text-gray-150text-gray-200text-gray-250text-gray-300text-gray-350text-gray-400text-gray-450text-gray-500Dark gray text
text-gray-550text-gray-600text-gray-650text-gray-700text-gray-750text-gray-800text-gray-850text-gray-900text-gray-950<span class="text-gray-50">text-gray-50</span>
<span class="text-gray-100">text-gray-100</span>
<span class="text-gray-150">text-gray-150</span>
<span class="text-gray-200">text-gray-200</span>
<span class="text-gray-250">text-gray-250</span>
<span class="text-gray-300">text-gray-300</span>
<span class="text-gray-350">text-gray-350</span>
<span class="text-gray-400">text-gray-400</span>
<span class="text-gray-450">text-gray-450</span>
<span class="text-gray-500">text-gray-500</span>
<span class="text-gray-550">text-gray-550</span>
<span class="text-gray-600">text-gray-600</span>
<span class="text-gray-650">text-gray-650</span>
<span class="text-gray-700">text-gray-700</span>
<span class="text-gray-750">text-gray-750</span>
<span class="text-gray-800">text-gray-800</span>
<span class="text-gray-850">text-gray-850</span>
<span class="text-gray-900">text-gray-900</span>
<span class="text-gray-950">text-gray-950</span>Explicit black and white
Use raw black and white utilities only when the backdrop is known. Unlike theme colors, these values do not change between light and dark mode.
bg-white text-blackbg-black text-white<div class="bg-white text-black">Black on white</div>
<div class="bg-black text-white">White on black</div>Responsive behavior
Color utilities have no breakpoint variants. Theme tokens adapt to the active light or dark theme independently of viewport size. Use responsive layout and spacing utilities around them, and check explicit text overrides on every surface where they appear.
Recipes
Compose a neutral panel
Use semantic tokens so the same markup adapts to both themes.
Updated five minutes ago.
<div class="bg-surface border rounded p-3">
<strong class="text-body">Project activity</strong>
<p class="text-muted mb-0">Updated five minutes ago.</p>
</div>Communicate status with text
Keep the outcome readable without relying on color.
<div class="bg-success rounded p-3">Saved successfully. Your project is up to date.</div>