Color roles

µCSS defines 11 color roles. Each role is mapped to a color family via the theme file (build/mu.theme.json).

Note: pop and spark are derived roles — pop uses the same color family as accent, and spark uses the same color family as contrast, both with lighter shade values. They do not appear in the theme JSON.

Live color swatches

CSS variables per role

Each role generates 7 CSS variables, automatically adapted for light and dark modes:

Example

.custom-banner {
    color: var(--mu-info);
    background-color: var(--mu-info-background);
    border-left: 4px solid var(--mu-info);
}

.custom-banner:hover {
    color: var(--mu-info-hover);
}

Utility classes

µCSS provides 34 utility classes in css/mu.colors.css:

Text color

Text color (inverse)

Background color

Border color

<p class="c-error">Red text</p>
<div class="bg-accent">Accent background</div>
<div class="border-success" style="border:2px solid">Green border</div>

Note: On <nav> or on a parent of <nav> (e.g. <header>), .bg-* classes also apply a gradient. See Nav.

Color classes by component

The following components accept color classes for all 11 roles:

Button

Filled buttons use the role color as background. Ghost buttons use it as text and border only.

<button class="btn btn-success">Save</button>
<button class="btn btn-outline btn-error">Delete</button>
<button class="btn btn-accent">Highlight</button>
<button class="btn btn-pop">Pop action</button>
<button class="btn btn-spark">Spark action</button>

Alert

<div class="alert alert-warning">Caution: this action cannot be undone.</div>

Badge

Solid badges use the role color as background. Outline badges use it as text and border only.

<span class="badge badge-success">Active</span>
<span class="badge badge-outline badge-error">Expired</span>

Card

<article class="card-info">
    <header>Note</header>
    <p>Card content with a colored left border and tinted background.</p>
</article>

Hero

<section class="hero hero-primary">
    <h1>Welcome</h1>
</section>

Spinner

<div class="spinner spinner-success"></div>

Progress

<progress class="progress-success" value="75" max="100"></progress>

Forms

Form validation uses a subset of roles:

Link color variants

Links support 3 color variants via CSS classes:

<a href="#">Primary link (default)</a>
<a href="#" class="secondary">Secondary link</a>
<a href="#" class="contrast">Contrast link</a>

Components with implicit colors

These components use color roles internally but do not expose color classes:

Base theme colors

These variables define the overall page appearance and adapt between light and dark modes:

The full variable reference is available in Variables.

Pre-built themes

µCSS includes 20 pre-built color themes, each generating a dedicated CSS file (mu.{name}.css). The default theme is azure (mu.css).

Each theme is named after its primary color family and remaps the 11 roles accordingly. Most themes share the same defaults for secondary (slate), tertiary (sand), success (green), info (cyan), warning (amber), and error (red) — the primary, contrast, and accent roles vary per theme. The pop role always derives from accent with lighter shades, and the spark role always derives from contrast with lighter shades.

Available themes: azure (default), red, pink, fuchsia, purple, violet, indigo, blue, cyan, jade, green, lime, yellow, amber, pumpkin, orange, sand, grey, zinc, slate.

To use a theme, load its CSS file instead of the default:

<link rel="stylesheet" href="dist/mu.pink.css">

Themes are defined in build/mu.theme.json. Each entry maps the 9 configurable roles (all except pop and spark) to color families from a palette of 20 colors.

See the Themes page for a live preview of each theme and a complete table showing which color family every theme uses for each role.

Customization

Override role colors on :root to change them globally:

:root {
    --mu-primary: #e63946;
    --mu-primary-hover: #c5303b;
    --mu-primary-focus: rgba(230, 57, 70, 0.375);
    --mu-primary-inverse: #fff;
}

For theme-based color generation, edit build/mu.theme.json and rebuild:

{
    "primary": "red",
    "secondary": "slate",
    "tertiary": "sand",
    "contrast": "indigo",
    "accent": "jade",
    "success": "green",
    "info": "azure",
    "warning": "amber",
    "error": "pink"
}

php build/mu-build.php

Accessibility

• All color roles are designed to meet WCAG AA contrast requirements in both light and dark modes.
• The -inverse variant ensures readable text on filled backgrounds by providing #fff or #000 as appropriate.
• Do not rely on color alone to convey meaning — pair color indicators with text labels or icons for users with color vision deficiencies.
• The .bg-* utility classes automatically set the text and link colors to the inverse value, preventing contrast issues.