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.

HTML
<div class="bg-primary rounded p-3">
	<p class="mb-0 text-inherit">Project updates</p>
</div>

Class and token reference

Class or token familyPurpose

.bg-{color}, –{color}, –on-{color}

Theme surface and its foreground: primary, secondary, accent, success, warning or error.

.bg-body, .bg-surface, .bg-surface-hover, .bg-highlight, .bg-active, .bg-inverse

Semantic surfaces with matching text defaults.
.bg-opacity-{percentage}Background-only opacity; the supported levels are shown below.
.bg-transparentShows the underlying surface without resetting text color.

.text-{color}, .text-underline-{color}

Explicit theme text or underline color.

.text-body, .text-muted, .text-subtle, .text-inverse, .text-inherit

Semantic text colors or inherited foreground.

.bg-gray-{level}, .text-gray-{level}

Fixed gray values from 50 through 950 in steps of 50.

–action-color, –action-color-hover, –action-color-active

Interactive primary foregrounds; independent from primary filled surfaces.
Color utilities

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.

HTML
<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.

SCSS
: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.

primary#8151dd
.bg-primary--primary
secondary#526070
.bg-secondary--secondary
accent#b515a7
.bg-accent--accent
success#087f5b
.bg-success--success
warning#b45309
.bg-warning--warning
error#d13a4b
.bg-error--error
HTML
<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:

HTML
<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.

CSS
: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.

Bodybg-body
Surfacebg-surface
Inversebg-inverse
Surface hoverbg-surface-hover
Highlightbg-highlight
Activebg-active
HTML
<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.

100%bg-primary
90%bg-opacity-90
80%bg-opacity-80
75%bg-opacity-75
70%bg-opacity-70
60%bg-opacity-60
50%bg-opacity-50
40%bg-opacity-40
30%bg-opacity-30
25%bg-opacity-25
20%bg-opacity-20
10%bg-opacity-10
0%bg-opacity-0
HTML
<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.

Translucent on inverse
Readable on the inverse background
Nested opacity reset
Opaque error background

Nested opacity uses a solid error background

HTML
<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-50
bg-gray-100
bg-gray-150
bg-gray-200
bg-gray-250
bg-gray-300
bg-gray-350
bg-gray-400
bg-gray-450
bg-gray-500
bg-gray-550
bg-gray-600
bg-gray-650
bg-gray-700
bg-gray-750
bg-gray-800
bg-gray-850
bg-gray-900
bg-gray-950
HTML
<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.

primary text#8151dd
secondary text#526070
accent text#b515a7
success text#087f5b
warning text#b45309
error text#d13a4b
HTML
<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.

HTML
<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.

Body textMuted supporting textSubtle metadata
Inverse texttext-inverse
Automatic foregroundInherited from bg-primary
HTML
<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

Aatext-gray-50
Aatext-gray-100
Aatext-gray-150
Aatext-gray-200
Aatext-gray-250
Aatext-gray-300
Aatext-gray-350
Aatext-gray-400
Aatext-gray-450
Aatext-gray-500

Dark gray text

Aatext-gray-550
Aatext-gray-600
Aatext-gray-650
Aatext-gray-700
Aatext-gray-750
Aatext-gray-800
Aatext-gray-850
Aatext-gray-900
Aatext-gray-950
HTML
<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.

Black on whitebg-white text-black
White on blackbg-black text-white
HTML
<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.

Project activity

Updated five minutes ago.

HTML
<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.

Saved successfully. Your project is up to date.
HTML
<div class="bg-success rounded p-3">Saved successfully. Your project is up to date.</div>