Core Concepts

CSS Utils combines four layers:

• Utilities for layout and small adjustments
• Components for recurring UI patterns
• States for interaction and visibility
• Tokens for consistent customization

The cascade runs reset → base → components → utilities, so utilities can adjust components directly.

Utilities

Combine single-purpose classes in your markup:

<div class="d-flex flex-column flex-md-row gap-2 p-3">...</div>

Responsive variants are mobile-first: flex-column always applies; flex-md-row takes over from md.

Components

Start with the base class, then add variants as needed:

<button class="btn btn-primary btn-solid btn-sm" type="button">Save</button>

Use utilities for local adjustments:

<div class="card mt-3">...</div>

States

Prefer native attributes such as disabled. Use is-* classes when HTML has no matching state.

<button class="btn btn-primary btn-solid" type="button" disabled>Disabled</button>
<button class="tab is-active" type="button">Active</button>

.disabled is visual only and does not prevent interaction.

Design tokens

Override CSS variables globally or on one component:

:root {
	--primary: #0057ff;
	--action-color: #0047d6;
	--action-color-hover: #003cad;
	--action-color-active: #002f87;
	--focus-outline-color: var(--action-color);
	--bg-surface: #ffffff;
	--border-radius: 0.5rem;
}

<button class="btn" style="--button-border-radius: 9999px;">Rounded</button>

Prefer semantic tokens such as --bg-surface over fixed colors. The --primary* tokens define filled surfaces; --action-color* independently controls links, navigation and interactive primary foreground states. Keep custom focus colors at least 3:1 against adjacent surfaces.