@oardi/css-utils
v1.3.0
Published
Powerful set of semantic css classes with support for breakpoints, directions and spacings
Readme
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.
The package includes css-utils-reference.md and css-utils-manifest.json so developers and AI coding tools can discover its utilities and components. The reference covers imports, example HTML, variants and states, accessibility, application-owned behavior and component CSS variables. Both files are generated for the package version; the manifest's existing utility groups are complemented by integration and components entries.
Using AI coding tools
Add this instruction to your application's agent guidance, such as its AGENTS.md, so tools know where to find the installed API:
Before adding CSS or using @oardi/css-utils components, read
node_modules/@oardi/css-utils/css-utils-reference.md from the installed version.
For structured lookup, consult css-utils-manifest.json in the same directory.
Prefer existing utilities and component patterns, preserve documented native
semantics and accessibility, and implement required interactions in the app.
The package supplies styles and documentation without runtime JavaScript.These are files in the installed package, not JavaScript module exports. Adapt the path to your package manager's installation layout. Tools need an explicit instruction or file access; installing the package does not automatically load the reference into an assistant's context.
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, thenutilities
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 sassAdd 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.cssBuild 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;.
Load individual components
Load the shared design tokens once alongside the components you need:
@use '@oardi/css-utils/tokens';
@use '@oardi/css-utils/components/button';tokens emits the default CSS variables, dark-theme overrides (data-theme="dark" on <html>) and reduced-motion settings. It establishes the shared cascade order and the minimal native [hidden] protection without loading the full reset, typography, utility or component rules. Component imports require these tokens unless your application already loads the full library or supplies all required variables itself.
Every CSS-emitting library entry point includes the same [hidden] protection, so hidden controls and their descendants stay unrendered and unfocusable with selective imports too. hidden="until-found" is left to the browser. This protection does not add global margin, padding or box-sizing resets.
Form controls (.form-control, including textareas, and .form-select) and icon buttons (.icon-btn on links or buttons) set their own box-sizing: border-box. Their declared widths and icon-button heights include padding and borders, so selective imports preserve these dimensions without an application reset. Unrelated elements retain their existing box sizing.
The full @use '@oardi/css-utils'; import already includes the tokens. Sass emits them only once if both entry points are used in the same compilation. Override CSS variables after the imports as shown below.
The Dart Sass CLI uses the same paths with a pkg: prefix and --pkg-importer=node:
@use 'pkg:@oardi/css-utils/tokens';
@use 'pkg:@oardi/css-utils/components/button';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, the first opacity level is translucent and selects its foreground against the composited backdrop. If any ancestor carries .bg-opacity-*, a descendant background with its own opacity class stays opaque, including at 0% or 100% and across transparent wrappers. This safe fallback keeps arbitrary nesting readable; use sibling surfaces when each needs transparency. 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
- Migration from 0.x to 1.0.0
- 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.
