acss-utilities Overview

acss-utilities provides a pre-built bundle of Tailwind-style atomic CSS utility classes that connect to your acss-kit theme via a token bridge.

What it includes

12 utility families

Spacing, flex, grid, display, color, typography, radius, shadow, position, and z-index — covering the utility classes you reach for most.

Token bridge

A token-bridge.css that maps utility class color names to your acss-kit --color-* roles, including dark mode parity and derived -bg / -light variants.

Commands

Command	What it does
/utility-add	Copy utilities.css + token-bridge.css into your project
/utility-list	Browse families and classes — read-only
/utility-tune	Adjust spacing, breakpoints, or family settings via natural language
/utility-bridge	Regenerate the token bridge against your active acss-kit theme

The 12 utility families

Family	Responsive	Example classes
color-bg	No	.bg-primary, .bg-surface, .bg-error
color-text	No	.text-primary, .text-muted, .text-inverse
color-border	No	.border-primary, .border-error
spacing	Yes	.m-4, .mt-2, .px-6, .gap-3
display	Yes	.hide, .show, .sr-only, .print-hide
flex	Yes	.flex, .flex-col, .justify-center, .items-center
grid	Yes	.grid, .grid-cols-2, .grid-cols-12
type	No	.text-xs, .text-lg, .font-bold, .italic
radius	No	.rounded-sm, .rounded-md, .rounded-full
shadow	No	.shadow-sm, .shadow-md, .shadow-lg
position	No	.relative, .absolute, .fixed, .sticky
z-index	No	.z-10, .z-20, .z-50, .z-auto

Responsive variants

Six families support responsive prefixes. The prefix activates the utility at that breakpoint and above:

<div className="flex-col md-flex-row lg-gap-8">
  {/* vertical on mobile, horizontal from md up, larger gap from lg up */}
</div>

Breakpoints: sm (30rem) · md (48rem) · lg (62rem) · xl (80rem)

Responsive Variants Full guide to the hyphen-prefix responsive system.

Token bridge

The token bridge (token-bridge.css) maps utility color class names to your acss-kit theme tokens and synthesizes derived variants via color-mix():

:root {
  --color-error:      var(--color-danger, #dc2626);
  --color-error-bg:   color-mix(in oklch, var(--color-danger, #dc2626) 12%, var(--color-background, #fff));
  --color-primary-light: color-mix(in oklch, var(--color-primary, #4f46e5) 80%, white);
}
[data-theme="dark"] {
  --color-error:      var(--color-danger, #f87171);
  --color-error-bg:   color-mix(in oklch, var(--color-danger, #f87171) 18%, var(--color-background, #0f172a));
}

Token Bridge How the bridge works, what it maps, and when to regenerate it.

Key design decisions

Hyphen-prefix responsive variants. Instead of the colon-prefix (md:flex) used by Tailwind (which requires escaping in JSX), acss-utilities uses md-flex. This works cleanly in className strings without escaping.

No prefix on class names. Classes are unprefixed (.flex, .bg-primary). This matches fpkit/acss conventions and keeps markup readable.

!important policy. Only display and visibility utilities use !important. All other utilities rely on normal cascade ordering — put your utility import after component styles to ensure utilities win when needed.

Standalone use. All color utilities have hardcoded hex fallbacks, so the bundle works without acss-kit. Run /utility-add --no-bridge to skip the token bridge.