Core concepts

Understand utilities, components, states and design tokens in css-utils.

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.

Utility syntax

Combine single-purpose classes in your markup:

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

Component and state reference

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

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

Use utilities for local adjustments:

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

States

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

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

Token reference

Override CSS variables globally or on one component:

SCSS
: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;
}
HTML
<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.

Responsive behavior

Responsive classes use .property-breakpoint-value naming, for example .p-md-3 or .flex-lg-row. Base classes apply everywhere; later matching breakpoints override earlier ones independently of class order. Only documented families generate responsive variants. See Breakpoints and each utility reference.

Recipes

Build a responsive content panel

Start with semantic content, then combine the existing card and layout utilities.

Project overview

A shared surface with comfortable spacing at larger widths.

HTML
<article class="card p-3 p-md-4">
	<h3 class="h5 mb-2">Project overview</h3>
	<p class="text-muted mb-0">A shared surface with comfortable spacing at larger widths.</p>
</article>

Present copyable code

Code examples show their language and include a copy button. Add showLineNumbers after the language to number a snippet:

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