# Utilities

Atomic, single-purpose helper classes for one-off adjustments: display, flex,
grid, spacing, color, borders, and more. This is `utilities.css` in
`@layer utilities`, the layer just below your app's overrides, so utilities beat
components but your own CSS still wins.

Utilities are axis-prefixed (`.text-sm`, `.bg-soft`, `.gap-4`) and never take
`is-`. They're hand-rolled from the token surface (no build step) and cover the
most-used properties. Spacing, sizing, and color utilities read the same tokens
as everything else, so they follow the theme and dark mode.

## When to use utilities vs layout primitives

Reach for the [layout primitives](layout) (`.stack`, `.cluster`, `.row`,
`.page-shell`) for structural composition. They encode the spacing contract and
keep markup readable. Reach for utilities for local, one-off tweaks: nudging a
gap, hiding something at a breakpoint, aligning a single element. If you find
yourself rebuilding a stack out of `.flex .flex-col .gap-4`, use `.stack`
instead.

## Categories

- **Display**: `.hidden`, `.block`, `.inline-block`, `.inline`, `.flex`,
  `.inline-flex`, `.grid`, `.inline-grid`, `.contents`, plus `.visually-hidden`
  / `.sr-only` for accessible-but-invisible content.

- **Position**: `.relative`, `.absolute`, `.fixed`, `.sticky`, `.static`;
  `.inset-0`, `.inset-x-0`, `.inset-y-0`,
  `.top-0`/`.right-0`/`.bottom-0`/`.left-0`; z-index `.z-0`…`.z-50` and named
  `.z-overlay`/`.z-modal`/`.z-popover`/ `.z-tooltip`/`.z-toast`.

- **Flex**: direction, wrap, `.items-*`, `.justify-*`, `.flex-1`/`.flex-auto`/
  `.flex-none`, `.grow`/`.shrink`, and `.order-*`.

- **Grid**: `.grid-cols-1`…`-6` and `-12`, `.col-span-*`, `.col-span-full`.

- **Gap**: `.gap-*` on the spacing scale, including half-steps (`.gap-0-5`,
  `.gap-1-5`, `.gap-2-5`). Full list: `elements man style/reference/utilities`.

- **Padding / margin**: `.p-*`, `.px-*`, `.py-*`; `.m-0`, `.m-auto`, `.mx-auto`,
  `.my-auto`, and directional `.mt-*` / `.mb-*`.

- **Sizing**: `.w-full`/`.w-auto`/`.w-screen`/`.w-fit`, `.h-full`/`.h-screen`/
  `.h-dvh`/`.h-fit`, `.size-full`, `.min-w-0`/`.min-h-0`/`.min-h-screen`/
  `.min-h-dvh`, and `.max-w-*` (the container widths plus `.max-w-prose`/
  `-shell`/`-wide`/`-none`/`-full`).

- **Typography**: `.text-2xs`…`.text-8xl`, `.font-thin`…`.font-black`,
  `.font-sans`/`.font-serif`/`.font-mono`, `.italic`, case transforms,
  `.tracked-*`, `.leading-*`, text alignment, `.tabular`, `.text-balance`/
  `.text-pretty`, `.underline`/`.no-underline`.

- **Text color**, semantic: `.text-ink`, `.text-ink-soft`, `.text-ink-dim`,
  `.text-ink-faint`, `.text-ink-inverse`, `.text-accent`, `.text-accent-deep`,
  and status `.text-success`/`.text-warning`/`.text-danger`/`.text-info` (these
  map to the readable `--{status}-ink` tint). Plus `.text-current`,
  `.text-white`, `.text-black`.

- **Background**, semantic: `.bg`, `.bg-soft`, `.bg-muted`, `.bg-panel`,
  `.bg-canvas`, `.bg-inverse`, `.bg-accent`/`.bg-accent-soft`, and the status
  fills `.bg-success`/`.bg-warning`/`.bg-danger`/`.bg-info` (and their `-soft`
  variants). The solid fills also set a readable foreground color.

- **Border**: `.border`, `.border-soft`, `.border-strong`, directional
  `.border-t`/`-b`/`-l`/`-r`/`-x`/`-y`, `.border-none`, `.border-2`, and color
  overrides `.border-accent`/`.border-danger`/`.border-success`.

- **Radius**: `.rounded-*` on the radius scale, plus `.rounded-none` and
  `.rounded-full`.

- **Shadow**: `.shadow-*` on the shadow scale, plus `.shadow-none` and
  `.shadow-inner`.

- **Opacity**: `.opacity-0`/`-25`/`-50`/`-70`/`-75`/`-100`.

- **Cursor / select**: `.cursor-*`, `.select-none`/`-text`/`-all`/`-auto`,
  `.pointer-events-none`/`-auto`.

- **Overflow**: `.overflow-auto`/`-hidden`/`-visible`/`-scroll` and the
  axis-specific `.overflow-x-*` / `.overflow-y-*`.

- **Transitions**: `.transition`, `.transition-colors`/`-shadow`/`-transform`/
  `-opacity`, `.transition-none`.

## Variants

Variants are prefixed onto a utility with a colon. The package ships a focused
set (not every utility gets every variant, that would balloon the file), added
as needed.

**Hover**, a handful of essentials: `hover:bg-soft`, `hover:bg-muted`,
`hover:bg-panel`, `hover:text-ink`, `hover:text-accent`, `hover:underline`,
`hover:shadow-md`, `hover:shadow-lg`.

**Responsive**: `md:` fires at **48rem** and `lg:` at **64rem** (min-width). The
responsive set covers display, flex direction, grid columns, a few type sizes,
and a couple of paddings, for example `md:grid-cols-2`, `md:flex-row`,
`lg:grid-cols-4`, `md:text-5xl`, `md:hidden`.

```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">…</div>
<button class="hidden md:block">Menu</button>
```

Note the responsive breakpoints (48rem / 64rem) differ from where the form grid
(40rem) and app sidebar (48rem) collapse. The package uses the breakpoint that
suits each thing rather than one global value. See
[scale breakpoints](tokens/scale).