Core Concepts

Overview

css-utils is built around a few simple concepts:

Utilities   → small single-purpose CSS classes
Components  → reusable base styles for common UI elements
Tokens      → CSS variables for theming and customization
States      → predictable state classes like .is-active or .is-open
Responsive  → mobile-first breakpoint variants

The goal is to keep styling predictable, composable and easy to customize.

Utilities

Utilities are small classes that do one specific thing.

Examples:

<div class="text-center">Centered text</div>
<div class="p-3">Padding</div>
<div class="d-flex gap-2">Flex layout</div>
<div class="bg-primary">Primary background</div>

Utilities are useful when you want to build layouts without writing custom CSS for every small spacing, color or display change.

Components

Components provide reusable base styles for common UI elements.

Examples:

Button

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

<div class="card">
	<div class="card-body">
		<h5 class="card-title">Card title</h5>
		<p class="mb-0">Card content</p>
	</div>
</div>

Components are intentionally lightweight. They define a useful default structure, but can still be adjusted with utilities or CSS variables.

Component pattern

Many components follow the same class pattern:

Base class    → .btn
Color class   → .btn-primary
Variant class → .btn-solid
Size class    → .btn-sm
State class   → .is-active

Example:

Small primary button

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

The same idea is used across multiple components.

Primary chip

<span class="chip chip-primary chip-outline">
	<span class="chip-label">Primary chip</span>
</span>

Color and variant separation

Color and visual style are separated.

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

<button class="btn btn-primary btn-outline" type="button">Outline primary</button>

<button class="btn btn-primary btn-text" type="button">Text primary</button>

This keeps the API predictable:

.btn-primary  → defines the color
.btn-solid    → defines the visual style

Design tokens

css-utils uses CSS variables as design tokens.

Tokens define shared values like colors, spacing, borders and backgrounds.

:root {
	--primary: #0057ff;
	--on-primary: #ffffff;

	--bg-body: #fdfdfd;
	--bg-surface: #ffffff;
	--bg-highlight: var(--gray-100);
	--bg-inverse: var(--gray-900);

	--text-color: var(--gray-900);
	--text-muted: var(--gray-650);
	--text-inverse: #ffffff;

	--border-radius: 0.5rem;
}

Changing these variables changes the look of the whole system.

Semantic tokens

Some tokens describe a purpose instead of a fixed color.

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

--text-color
--text-muted
--text-subtle
--text-inverse

This makes components easier to theme.

For example:

<div class="bg-inverse text-inverse">Inverted section</div>

Component variables

Components also define their own local CSS variables.

Example:

.btn {
	--button-padding-y: var(--spacer-1);
	--button-padding-x: var(--spacer-3);
	--button-border-radius: var(--border-radius);
}

You can override them locally:

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

States

State classes use a predictable is-* naming pattern.

.is-active
.is-open
.is-invalid

Examples:

<button class="tab is-active" type="button">Active tab</button>

<div class="drawer is-open">...</div>

<input class="form-control is-invalid" />

This keeps states separate from component variants.

Disabled state

Disabled elements use the native disabled attribute where possible.

<button class="btn btn-primary btn-solid" type="button" disabled>Disabled button</button>

For non-form elements, .disabled can be used when needed.

<span class="chip chip-primary chip-solid disabled">
	<span class="chip-label">Disabled chip</span>
</span>

Responsive variants

Responsive utilities are mobile-first.

<div class="col-12 col-md-6 col-lg-4">Responsive column</div>

This means:

.col-12   → applies to all screen sizes
.col-md-6 → applies from md and up
.col-lg-4 → applies from lg and up

The same pattern exists for spacing, display, flex, grid and gap utilities.

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

<section class="px-2 px-md-3 px-lg-4">...</section>

Utility naming

Utilities use predictable naming patterns.

Spacing:

m-1
mt-2
mx-3
p-2
py-4

Responsive spacing:

mt-md-2
px-lg-4
my-xl-auto

Display:

d-block
d-none
d-md-flex

Grid:

col-12
col-md-6
col-lg-4

When to use utilities

Use utilities for small layout and styling adjustments.

Good examples:

<div class="d-flex align-items-center gap-2">...</div>

<section class="my-5 py-5">...</section>

Utilities are ideal for composition, spacing, alignment and responsive behavior.

When to use components

Use components when an element has a reusable structure or behavior.

Good examples:

<div class="card">
	<div class="card-body">...</div>
</div>

<div class="toast bg-success">
	<div class="toast-content">
		<p class="toast-title">Saved</p>
		<p class="toast-message">Your changes were saved successfully.</p>
	</div>
</div>

Components provide structure. Utilities help adjust them.

Summary

css-utils is based on a simple idea:

Use utilities for composition.
Use components for reusable UI patterns.
Use tokens for customization.
Use is-* classes for state.
Use responsive variants for mobile-first layouts.

This keeps the system flexible without hiding the underlying CSS.