CSS Utils

CSS Utils is a lightweight SCSS toolkit with utility classes, responsive helpers and reusable component styles. CSS variables and cascade layers make the system easy to customize without repetitive application CSS.

What it includes

• Utilities for colors, typography, spacing, sizing, positioning, display, flex and grid
• Mobile-first responsive variants for layout, sizing, positioning and spacing
• Components for buttons, cards, forms, badges, tabs, toasts and more
• Global and component-specific design tokens
• A predefined cascade order: reset, base, components, then utilities

Install

CSS Utils ships as SCSS. Install the package and, if your toolchain does not already provide it, Dart Sass:

npm i @oardi/css-utils
npm i -D sass

Add the styles

Load CSS Utils once through your application's global stylesheet:

// styles.scss
@use '@oardi/css-utils';

No additional cascade-layer setup is required, including when importing selected public SCSS entry points directly.

When compiling directly with the Dart Sass CLI, use the Node package importer:

@use 'pkg:@oardi/css-utils';

sass --pkg-importer=node styles.scss styles.css

Build your first interface

Combine components and utilities directly in your markup:

<div class="card">
	<div class="card-body d-flex flex-column gap-2">
		<p class="h5 card-title">Welcome</p>
		<p class="mb-0 text-muted">Your CSS Utils setup is ready.</p>
		<button class="btn btn-primary btn-solid" type="button">
			<span>Continue</span>
		</button>
	</div>
</div>

Here, .card and .btn provide reusable component styles, while .d-flex, .gap-2 and .text-muted make focused adjustments.

Use responsive utilities

Responsive utilities are mobile-first. Classes without a breakpoint apply at every size; breakpoint variants apply from their breakpoint upward:

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

Display utilities intentionally override the grid container at their active breakpoint. For example, class="grid d-lg-block" uses the grid below lg and switches to block layout from lg upward.

For custom responsive SCSS, import the breakpoint mixins without loading the library's CSS again:

@use '@oardi/css-utils/breakpoints' as bp;

.sidebar {
	@include bp.media-up(md) {
		display: block;
	}
}

The Dart Sass CLI uses @use 'pkg:@oardi/css-utils/breakpoints' as bp; with --pkg-importer=node.

Import theme values without generating CSS via @use '@oardi/css-utils/theme' as theme;. To load one component's styles, use a path such as @use '@oardi/css-utils/components/button';. The Dart Sass CLI uses the same paths with a pkg: prefix.

Browser support

The minimum supported versions for the compiled library CSS are:

| Browser | Minimum version | | ----------------------------------- | --------------- | | Chrome / Edge (desktop and Android) | 122 | | Firefox (desktop and Android) | 128 | | Safari (macOS and iOS/iPadOS) | 18 |

This feature baseline includes cascade layers, :has(), color-mix() and relative rgb() colors used by component states and backdrops. Older browsers and Internet Explorer are outside the support policy. Modal entry animations using @starting-style are a progressive enhancement; the dialog remains usable without that animation.

All solid .bg-* utilities provide authored text colors and matching SVG fills. Theme colors use --on-*, surfaces use --text-color or --text-inverse, and fixed colors use black/white fallbacks selected from the Sass palette.

@supports (color: contrast-color(white)) enables automatic black/white foreground selection. Without it, every .bg-* combined with .bg-opacity-* remains opaque so its authored foreground stays readable, including nested backgrounds. With it, opacity and contrast against the composited backdrop are enabled. According to MDN browser compatibility data, contrast-color() starts at Chrome/Edge 147, Firefox 146 and Safari/iOS 26; relative RGB support establishes the lower baseline above. Feature detection determines which path runs.

When overriding theme colors, keep their --on-* tokens in sync. When changing surfaces, update their matching text tokens. Gray fallbacks are calculated at Sass compilation time; runtime gray or black/white token overrides require checking foreground contrast and, where needed, an explicit .text-* utility. Explicit text utilities continue to override the automatic foreground.

Use accent for supplementary brand or category emphasis without status meaning. The --accent, --accent-hover, --accent-active and --on-accent tokens are available in both themes and can be overridden like other theme colors. The color also generates .bg-accent, .text-accent, .text-underline-accent, .border-accent, .btn-accent, .chip-accent and .icon-btn-accent variants. Keep --on-accent readable against all three accent shades when customizing them.

These versions define the support target, not a claim that every browser release is exercised in CI. Regression tests cover the compiled fallback and enhancement branches and default light/dark contrast; application integrations should also be checked in their target browsers. The SCSS package supplies no JavaScript: interactive behavior belongs to the consuming application.

Customize the design

Define overrides after the library import to adapt the global design tokens:

@use '@oardi/css-utils';

:root {
	--primary: #0057ff;
	--primary-hover: #0047d6;
	--primary-active: #003cad;
	--on-primary: #ffffff;
	--action-color: #0047d6;
	--action-color-hover: #003cad;
	--action-color-active: #002f87;
	--focus-outline-color: var(--action-color);

	--bg-body: #fdfdfd;
	--border-radius: 0.5rem;
}

Component tokens can be changed locally without affecting the rest of the interface:

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

Learn more

• Full documentation and showcase
• Get-started guide
• Utilities, components and design tokens
• StackBlitz demo

Maintainer

Developed and maintained by Ardian Shala.

License

Released under the MIT License.

Credits

Inspired by ideas and patterns from Bootstrap, Tailwind CSS, Font Awesome and Nuxt.