CSS Utils v0.53.0 is a cleanup release focused on component consistency, semantic design tokens and a more predictable class naming system.

After improving the spacing utilities in the previous release, this update continues with the component layer. Several components were refactored to use clearer CSS variables, better state naming and more reusable utility patterns.

The goal of this release is simple: make the system easier to understand, easier to extend and more consistent across components.

Highlights

This release focuses on three main areas:

  • cleaner component APIs
  • more semantic theme tokens
  • better showcase documentation

Many components now follow the same structure:

Base class      → .btn, .chip, .icon-btn, .toast
Color class     → .btn-primary, .chip-primary, .icon-btn-primary
Variant class   → .btn-solid, .chip-outline, .icon-btn-text
State class     → .is-active, .is-open, .is-invalid

This makes the API more predictable and easier to use.

New additions

Semantic background tokens

A few new semantic background tokens were added to make component styling less dependent on raw gray values.

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

These tokens are now used for hover states, active states, inverse sections and component backgrounds.

Example:

--bg-highlight: var(--gray-100);
--bg-active: var(--gray-150);
--bg-inverse: var(--gray-900);

This replaces older direct usage of values like:

--highlight: rgba(0, 0, 0, 0.15);

The new tokens are easier to theme and behave better in dark mode.

Inverse background utility

A new inverse background utility was added:

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

This is useful for sections, navbars, tooltips and other UI elements that need strong contrast against the default page background.

Toast structure

Toasts were simplified and now rely on background utilities instead of custom toast color classes.

Instead of:

<div class="toast toast-success">Saved successfully</div>

use:

<div class="toast bg-success">Saved successfully</div>

Toast internals were also added:

<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 class="toast-actions">
		<button class="btn btn-text toast-action" type="button">Undo</button>
	</div>

	<button class="toast-close icon-btn icon-btn-text" type="button" aria-label="Close toast">
		×
	</button>
</div>

New classes:

.toast-content
.toast-title
.toast-message
.toast-actions
.toast-action
.toast-close

Table variants

Tables were cleaned up and simplified.

New table variants:

<table class="table table-striped"></table>
<table class="table table-hover"></table>
<table class="table table-bordered"></table>
<table class="table table-borderless"></table>
<table class="table table-sm"></table>

Responsive tables can now be wrapped with:

<div class="table-responsive">
	<table class="table">
		...
	</table>
</div>

The table component now uses semantic tokens like:

--table-header-bg-color: var(--bg-surface-hover);
--table-striped-bg-color: var(--bg-highlight);
--table-hover-bg-color: var(--bg-highlight);
--table-active-bg-color: var(--bg-active);

Drawer component

The drawer component was updated to use transform-based positioning instead of left.

The open state now uses:

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

The internal structure was also normalized:

<div class="drawer">
	<div class="drawer-header">
		<h6 class="drawer-title">Menu</h6>
	</div>

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

Expansion panels

Expansion panels now use the shared state naming convention:

<div class="expansion-panel is-open">
	<button class="expansion-panel-header" type="button">Expansion Panel Header</button>

	<div class="expansion-panel-content">
		<div class="expansion-panel-inner">Content</div>
	</div>
</div>

The header is now expected to be a real button. This improves keyboard accessibility and removes the need for tabindex on the whole panel.

The visual focus outline can still be shown around the complete panel using :focus-within.

Tabs

Tabs were updated to use .is-active instead of .active.

<div class="tabs">
	<button class="tab is-active" type="button">Tab 1</button>
	<button class="tab" type="button">Tab 2</button>
</div>

<div class="tab-contents">
	<div class="tab-content is-active">Content Tab 1</div>
	<div class="tab-content">Content Tab 2</div>
</div>

Tabs are now expected to be buttons instead of generic div elements.

Icon buttons

Icon buttons now follow the same pattern as regular buttons.

Instead of:

<button class="icon-btn icon-btn-primary-contained"></button>

use:

<button class="icon-btn icon-btn-primary icon-btn-solid"></button>

Supported variants:

.icon-btn-text
.icon-btn-solid
.icon-btn-outline

Supported sizes:

.icon-btn-xs
.icon-btn-sm
.icon-btn-md
.icon-btn-lg

Chips

Chips now follow the same base + color + variant pattern.

Instead of:

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

use:

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

Supported variants:

.chip-solid
.chip-outline
.chip-text

Lists

List hover behavior was renamed for clarity.

Instead of:

<li class="list-item has-hover">
	<span class="list-item-text">Item</span>
</li>

use:

<li class="list-item list-item-action">
	<span class="list-item-text">Item</span>
</li>

Active items now use:

<li class="list-item list-item-action is-active">
	<span class="list-item-text">Active item</span>
</li>

This separates interactivity from active state.

Tooltip tokens

Tooltips were updated to use design tokens instead of hardcoded colors.

The tooltip now uses:

--tooltip-bg-color: var(--bg-inverse);
--tooltip-color: var(--text-inverse);
--tooltip-box-shadow: var(--shadow-lg);

This makes tooltips theme-aware and more consistent with the rest of the system.

Breaking changes

State classes

Several components now use .is-* state classes.

Changed:

.active → .is-active
.open   → .is-open

Affected components include:

tabs
tab-content
expansion-panel
drawer
table rows
list items

Example:

<!-- before -->
<div class="tab active">Tab 1</div>

<!-- after -->
<button class="tab is-active" type="button">Tab 1</button>

Toast color classes removed

Toast-specific color classes were removed.

Changed:

<!-- before -->
<div class="toast toast-success">Saved</div>

<!-- after -->
<div class="toast bg-success">Saved</div>

The toast component now relies on existing background utilities.

Icon button variant naming changed

Changed:

<!-- before -->
<button class="icon-btn icon-btn-primary-contained"></button>

<!-- after -->
<button class="icon-btn icon-btn-primary icon-btn-solid"></button>

Chip variant naming changed

Changed:

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

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

List hover class renamed

Changed:

<!-- before -->
<li class="list-item has-hover">Item</li>

<!-- after -->
<li class="list-item list-item-action">Item</li>

Tabs should use buttons

Tabs are now expected to be real buttons.

Changed:

<!-- before -->
<div class="tab active">Tab 1</div>

<!-- after -->
<button class="tab is-active" type="button">Tab 1</button>

Expansion panel headers should use buttons

Expansion panel headers are now expected to use a button element.

Changed:

<!-- before -->
<div class="expansion-panel-header">Header</div>

<!-- after -->
<button class="expansion-panel-header" type="button">Header</button>

This improves accessibility and makes keyboard interaction simpler.

Deprecations

--highlight

The old --highlight token is deprecated.

Use:

--bg-highlight

instead.

Temporary alias:

--highlight: var(--bg-highlight);

--body-bg-color

The old body background token is deprecated.

Use:

--bg-body

instead.

Temporary alias:

--body-bg-color: var(--bg-body);

--text-color-inverse

The old inverse text token is deprecated.

Use:

--text-inverse

instead.

Temporary alias:

--text-color-inverse: var(--text-inverse);

.navbar-* color variants

Navbar-specific color variants are deprecated.

Use background utilities instead.

<!-- before -->
<nav class="navbar navbar-primary"></nav>

<!-- after -->
<nav class="navbar bg-primary"></nav>

For inverse navbars:

<nav class="navbar bg-inverse text-inverse"></nav>

Showcase updates

Several showcase pages were updated or added:

Colors
Spacings
Buttons
Icon Buttons
Cards
Chips
Drawer
Expansion Panels
Forms
Lists
Navbar
Tables
Tabs
Toasts
Tooltips

The showcase pages now better reflect the current utility and component API.

They also use more consistent wording, code examples and class naming.

Migration examples

Toasts

<!-- before -->
<div class="toast toast-error">Something went wrong.</div>

<!-- after -->
<div class="toast bg-error">Something went wrong.</div>

Icon buttons

<!-- before -->
<button class="icon-btn icon-btn-primary-contained">...</button>

<!-- after -->
<button class="icon-btn icon-btn-primary icon-btn-solid" type="button">...</button>

Chips

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

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

Tabs

<!-- before -->
<div class="tab active">Tab 1</div>
<div class="tab-content active">Content</div>

<!-- after -->
<button class="tab is-active" type="button">Tab 1</button>
<div class="tab-content is-active">Content</div>

Lists

<!-- before -->
<li class="list-item has-hover">Item</li>

<!-- after -->
<li class="list-item list-item-action">Item</li>

Summary

CSS Utils v0.53.0 is mainly about consistency.

The component layer now follows clearer naming rules, uses more semantic tokens and relies more on existing utilities instead of one-off component variants.

The biggest improvements are:

bg-* utilities instead of component-specific color classes
is-* state classes
semantic background tokens
button-like variant patterns for chips and icon buttons
cleaner showcase pages

This release introduces some breaking changes, but the result is a cleaner and more predictable CSS utility and component system.