Styling with utility classes

Compose interfaces using single-purpose utility classes mapped to design tokens.

Style Zazz layouts by adding utility classes (flex, gap-md, text-h2, bg-primary, rounded-lg) directly to HTML. Each utility class sets a single CSS property and maps to a design token.

<article class="bg-card text-card-foreground p-lg flex flex-col gap-md rounded-lg shadow-sm">
  <h3 class="text-h4">Quarterly report</h3>
  <p class="text-muted-foreground">Revenue is up 12% over last quarter.</p>
  <a class="ui-button mt-sm" data-variant="primary" href="/report">View report</a>
</article>

Benefits

Token consistency: Spacing, color, and typography map to shared variables across the site.
Maintainability: Styles are tied to element markup without orphan CSS rules.
Cascade order: Utilities live in @layer zazz.utilities and override component rules without !important.

Semantic tokens and escape hatches

Prefer semantic tokens over arbitrary values:

Spacing: Use gap-md, p-lg, py-sm first. Use the --step-* scale only when no semantic gap fits.
Color: Use role classes (bg-card, text-muted-foreground, border-primary) so light/dark modes work automatically.
Typography: Use bundled text-* classes (text-h1 to text-xs, text-eyebrow) that set size, weight, leading, and tracking together.

Common utility families

Family	Examples
Layout	`flex`, `grid`, `grid-cols-3`, `flex-col`, `items-center`, `justify-between`, `basis-1/2`
Spacing	`gap-md`, `p-lg`, `px-md`, `py-sm`, `mt-sm`, `mx-auto`
Typography	`text-h2`, `text-sm`, `text-eyebrow`, `text-center`, `text-balance`, `font-heading`
Color	`bg-primary`, `text-foreground`, `text-muted-foreground`, `border-border`
Shape & depth	`rounded-lg`, `rounded-b-0`, `shadow-md`, `ring`
Sizing	`w-full`, `max-w-screen-md`, `size-8`, `aspect-square`

Full reference: Utilities reference.

Shared scale

Properties use a consistent xs, sm, md, lg, xl scale:

Property	Class
Spacing	`gap-lg`, `p-lg`, `mt-lg`
Radius	`rounded-lg`
Shadow	`shadow-lg`
Sizing	`size-lg`, `max-w-screen-lg`
Breakpoint	`@lg:grid-cols-3`

Finer steps use the --step-0_5 to --step-96 scale for spacing, and 50 to 950 for colors.

Composable edges

Spacing and border radius utilities modify individual axes without affecting others:

<!-- md padding all around, zero on left -->
<div class="p-md pl-0">...</div>

<!-- rounded card with flat bottom edge -->
<div class="rounded-lg rounded-b-0">...</div>

Utilities on components

Components define internal structure and accept data-* variants; utilities adjust spacing, alignment, and sizing on top:

<button class="ui-button mt-md w-full" data-variant="primary" data-size="lg">Continue</button>

State and responsive variants

Hover: hover:bg-primary, hover:scale-102. See States.
Responsive: @md:grid-cols-3, @lg:flex-row. See Responsive design.