# Introduction (/docs)



**A variables-driven design framework that survives real projects.**

Most UI libraries look right until a client asks for something custom. Then you're fighting overrides, wrapping components in wrappers, or bolting on a second system that doesn't match the first.

Zazz works differently. It's built on native web standards: tokens, cascade layers, and modern browser APIs. No build step, no framework lock-in, no specificity wars, just markup that works wherever you ship code.

It's built around four commitments:

* **Professionalism:** Works across changing tools and frameworks without breaking.
* **Precision:** Variables control everything, so consistency doesn't depend on discipline.
* **Polish:** Looks great by default, ready to present without extra design passes.
* **Portability:** Built on standards that map cleanly to any stack.

## Professionalism [#professionalism]

Zazz is designed for teams that switch between design tools, frameworks, and client requirements constantly. The system works in Figma, translates to any development framework, and doesn't require you to rebuild when your toolchain changes next quarter.

* **Tool-agnostic:** The same tokens and patterns work whether you're in Figma, code, or both.
* **Framework-agnostic:** No React dependency, no Vue plugin, no build step. It runs on CSS and native HTML APIs.
* **Complete:** Every component handles light mode, dark mode, accessibility, and keyboard interaction without extra work.

## Precision [#precision]

Every spacing value, color, radius, and type size in Zazz resolves from a variable. You never hardcode a pixel value or hex color. This means changing one token updates every component that references it, and consistency happens automatically instead of through code review.

* **Semantic tokens first:** Reach for role tokens (`--primary`, `--muted-foreground`, `--gap-md`) before anything specific.
* **Scoped overrides:** Customize globally on `:root`, per-component, or per-instance inline. No source editing needed.
* **Predictable variants:** `data-variant`, `data-size`, `data-side`. The default is always the absence of the attribute.

*If you need every button in your project to be pill-shaped, set `--button-radius: var(--radius-full)` once. Done.*

## Polish [#polish]

Zazz ships with carefully chosen defaults so your UI looks finished before you've made a single design decision. Components work well together as a system because they share the same token vocabulary and spacing scale.

* **Presentable by default:** Clean, modern defaults that hold up in client presentations.
* **Unified system:** Components built from the same tokens naturally look like they belong together.
* **Dark mode included:** Role tokens handle light/dark automatically. No manual `.dark` overrides.

*You can hand a Zazz prototype to a stakeholder without apologizing for the styling.*

## Portability [#portability]

Zazz doesn't bet on a framework that might not exist in two years. It uses CSS custom properties, native HTML APIs (Popover, `<dialog>`, Invoker Commands, anchor positioning), and cascade layers. The result is a system that works today in plain HTML and adapts to whatever framework you adopt next.

* **Zero build step:** Load the styles, write the markup, ship.
* **Standards-based:** If the browser supports it natively, Zazz uses that instead of JavaScript.
* **Figma parity:** Variables in the Figma library map 1:1 to CSS tokens in code.

*Switch from Next.js to Astro? From Wordpress to Webflow? Your components still work. The markup is the same.*


# Accordion (/docs/components/accordion)



The accordion is a `.accordion` wrapping native `<details>` and `<summary>` elements.
Open/close state, keyboard support, and the height transition (via `::details-content`) are
handled by the browser.

## Default [#default]

<Preview src="accordion/default" />

There are no data-\* attributes to configure. Author each panel as a `<details class="border-b">`
with a `<summary class="font-strong hover:text-muted-foreground">`, an inline chevron `<svg>`
that rotates on open, and a `<div class="pb-sm">` body. Multiple panels can be open at once by
default; give a group of `<details>` the same `name` to make them mutually exclusive.

Theming runs through tokens: `--accordion-summary-padding-block`, `--accordion-icon-size`, and
`--accordion-icon-transform-open` (the open-state chevron rotation).


# Avatar (/docs/components/avatar)



Avatars are pure composition with no dedicated class. Stack an image over a text
fallback with `grid grid-area-pile`, clip to a circle with `rounded-full overflow-clip`, and
size with `size-*`. The image sits on top; the fallback (initials on `bg-muted` /
`text-muted-foreground`) shows when it fails to load. For an initials-only avatar, drop the
`<img>` and keep just the `<figcaption>`.

## Default [#default]

<Preview src="avatar/default" />


# Badge (/docs/components/badge)



Badges use the `.badge` class. Pick a color with `data-variant`; the **default** variant is
the absence of the attribute. Use `data-size="icon"` for a square, icon-only chip. A badge is
often a static `<span>`, but put it on a `<button type="button">` or `<a href>` when it is
interactive — those get hover/active tints, a `:disabled` / `[aria-disabled="true"]` muted state
at opacity 0.5, and a `progress` cursor under `[aria-busy="true"]`.

## Variants [#variants]

<Preview src="badge/default" />

## Icon [#icon]

An icon-only badge needs an accessible name: include a `<span class="sr-only">` label alongside
the `<svg>`.

<Preview src="badge/icon" />

## API [#api]

| Attribute      | Values                                               |
| -------------- | ---------------------------------------------------- |
| `data-variant` | `primary`, `muted`, `ghost`, `link` (omit = default) |
| `data-size`    | `icon`                                               |

Need a status badge (info / success / warning / destructive)? Override the tokens on an
instance, e.g. `style="--badge-background: var(--success); --badge-foreground: var(--success-foreground)"`.


# Breadcrumbs (/docs/components/breadcrumbs)



Breadcrumbs are a composition, not a dedicated primitive. A `<nav>` wraps a `<menu>` of
link buttons (`<a class="button" data-variant="link">`) separated by
`<span class="text-muted-foreground opacity-50">/</span>` glyphs. The current page is rendered as
a `<div class="button" data-variant="link" aria-disabled="true">` — the same link styling on a
non-interactive `<div>` instead of an `<a>`, so it reads as the active crumb.

## Default [#default]

<Preview src="breadcrumbs/default" />


# Button group (/docs/components/button-group)



Wrap two or more `.button`s in `.button-group` to fuse them into one segmented
control. The group squares off the inner corners and collapses the shared border so
the buttons read as a unit, while each button keeps its own `data-variant` and
`data-size`. Add `role="group"` and an `aria-label` so assistive tech announces the
set.

## Horizontal [#horizontal]

The default orientation lays buttons out in a row.

<Preview src="button-group/default" align="center" />

## Vertical [#vertical]

Set `data-orientation="vertical"` on the wrapper to stack them.

<Preview src="button-group/vertical" align="center" />

## API [#api]

| Attribute          | Values                                 |
| ------------------ | -------------------------------------- |
| `data-orientation` | `vertical` (omit = horizontal default) |

The group reads each child's own `--button-radius`, so the outer corners follow the
buttons' `data-size` automatically — only the inner corners are squared. Need a
divider between segments? Drop your own separator element in as a child; it inherits
the same border collapse. You never need to touch `zazz/styles/`.


# Button (/docs/components/button)



Buttons use the `.button` class on a `<button>` or `<a>`. Choose a variant with
`data-variant` and a size with `data-size`. The **default** variant is the absence
of the attribute. Colors come from theme role tokens, so light/dark modes work automatically.

## Variants [#variants]

<Preview src="button/default" />

## With icons [#with-icons]

Drop an inline `<svg>` beside the label; the button sizes the icon automatically.

<Preview src="button/with-icons" />

## Icon-only [#icon-only]

Use `data-size="icon"` (or `icon-sm`) for square, label-free buttons.

<Preview src="button/icon-only" align="center" />

## With a keyboard shortcut [#with-a-keyboard-shortcut]

Drop a `<kbd>` child to show a shortcut hint, e.g. `<button class="button">Search <kbd>⌘K</kbd></button>`.
The button trims its trailing (or leading) padding so the key sits flush, with the inset tuned
per `data-size`.

## API [#api]

| Attribute      | Values                                                              |
| -------------- | ------------------------------------------------------------------- |
| `data-variant` | `primary`, `muted`, `ghost`, `destructive`, `link` (omit = default) |
| `data-size`    | `sm`, `icon`, `icon-sm`                                             |

Restyle every button by overriding its tokens (`--button-background`, `--button-radius`,
`--button-height`, ...) at `:root`, or on a single instance inline. You never need to touch
`zazz/styles/`.


# Card (/docs/components/card)



Cards are built from utility classes. There is no `.card` primitive. Wrap a
`bg-card text-card-foreground` surface in a `rounded-md shadow-sm overflow-clip` container, then
compose a figure, a `.badge`, `text-*` content, and a footer with utilities and theme tokens.

## Default [#default]

<Preview src="card/default" />

The default above uses a full-bleed `aspect-landscape` figure, `px-sm pb-sm` / `gap-sm` spacing,
and an avatar in the footer. Because it reuses existing utilities,
dark mode and theming work automatically.

## Subgrid [#subgrid]

<Preview src="card/subgrid" />

Use `grid-rows-*` and `grid-rows-subgrid` utilities to create perfectly aligned cards.


# Carousel (/docs/components/carousel)



`<embla-carousel>` is the carousel root. Put Embla options on the element, compose the
`viewport` → `container` → `slide` structure inside, and the script wires up dragging, looping,
navigation, dots, and thumbnails from the markup. There's no JavaScript to configure.

The element uses light DOM, so the markup you write is the markup that gets styled. It initializes
when connected, defers while inside a closed `<dialog>`, and tears down its Embla instances when
removed.

## Default [#default]

<Preview src="carousel/default" />

## Anatomy [#anatomy]

Mark the structural roles with `data-embla`. Each slide sets its own responsive width with
[`basis-*`](/docs/utilities/gap-and-basis) utilities, so the same markup shows one slide on a phone
and several on a wide screen.

```html
<embla-carousel data-embla-loop="true">
  <div data-embla="viewport">
    <div data-embla="container">
      <div data-embla="slide" class="basis-full @sm:basis-1/2 @md:basis-1/3">Slide 1</div>
      <div data-embla="slide" class="basis-full @sm:basis-1/2 @md:basis-1/3">Slide 2</div>
      <div data-embla="slide" class="basis-full @sm:basis-1/2 @md:basis-1/3">Slide 3</div>
    </div>
  </div>
  <button type="button" data-embla="prev">Prev</button>
  <button type="button" data-embla="next">Next</button>
</embla-carousel>
```

| `data-embla`    | Role                                             |
| --------------- | ------------------------------------------------ |
| `viewport`      | The visible window (required)                    |
| `container`     | The flex track of slides                         |
| `slide`         | Each slide; set its width with `basis-*`         |
| `prev` / `next` | Navigation buttons (optional)                    |
| `dots` / `dot`  | Dot pagination container and template (optional) |
| `thumbs`        | Linked thumbnail carousel container (optional)   |

## Setup [#setup]

The docs preview loads the scripts for you. To use a carousel in your own page, include the Embla
CDN bundles, the shared utilities, and the init script:

```html
<script src="./zazz/scripts/utils.js"></script>
<script src="https://unpkg.com/embla-carousel/embla-carousel.umd.js"></script>
<!-- Optional plugins -->
<script src="https://unpkg.com/embla-carousel-autoplay/embla-carousel-autoplay.umd.js"></script>
<script src="https://unpkg.com/embla-carousel-auto-scroll/embla-carousel-auto-scroll.umd.js"></script>
<script src="https://unpkg.com/embla-carousel-class-names/embla-carousel-class-names.umd.js"></script>
<script src="./zazz/scripts/embla.js"></script>
```

Carousels auto-initialize on `DOMContentLoaded`.

## Options [#options]

Every Embla core option goes on `<embla-carousel>` as a `data-embla-*` attribute. Names convert from
kebab-case to camelCase and values are type-coerced, so `data-embla-loop="true"` becomes
`{ loop: true }`.

```html
<embla-carousel data-embla-loop="true" data-embla-align="start">…</embla-carousel>
```

| Attribute             | Effect                            |
| --------------------- | --------------------------------- |
| `data-embla-loop`     | `"true"` wraps around at the ends |
| `data-embla-align`    | `start`, `center`, or `end`       |
| `data-embla-keyboard` | `"false"` opts out of arrow keys  |

### Plugins [#plugins]

Enable a plugin with a bare attribute and configure it with prefixed options. Each plugin needs its
CDN bundle from the setup above.

```html
<!-- autoplay, advancing every 3 seconds -->
<embla-carousel data-embla-autoplay data-embla-autoplay-delay="3000">…</embla-carousel>
```

| Plugin      | Attribute prefix          | CDN bundle                   |
| ----------- | ------------------------- | ---------------------------- |
| Autoplay    | `data-embla-autoplay-*`   | `embla-carousel-autoplay`    |
| Auto Scroll | `data-embla-autoscroll-*` | `embla-carousel-auto-scroll` |
| Class Names | `data-embla-classnames-*` | `embla-carousel-class-names` |

## Dot navigation [#dot-navigation]

Add a `dots` container with a single template `dot`. The script clones the template once per slide
and tracks the active one with `.is-active`.

```html
<div data-embla="dots">
  <button type="button" data-embla="dot"></button>
</div>
```

## Thumbnail navigation [#thumbnail-navigation]

Nest a `data-embla="thumbs"` container inside the same `<embla-carousel>` to get a synced secondary
carousel. Thumb options take the `data-embla-thumbs-*` prefix and default to
`containScroll: "keepSnaps"` and `dragFree: true`.

```html
<embla-carousel>
  <div data-embla="viewport">
    <div data-embla="container">
      <div data-embla="slide">Full image 1</div>
      <div data-embla="slide">Full image 2</div>
    </div>
  </div>

  <div data-embla="thumbs">
    <div data-embla="viewport">
      <div data-embla="container">
        <div data-embla="slide">Thumb 1</div>
        <div data-embla="slide">Thumb 2</div>
      </div>
    </div>
  </div>
</embla-carousel>
```

## Keyboard navigation [#keyboard-navigation]

Arrow keys (`←` / `→`) scroll the active carousel: one inside an open `<dialog>`, or the one holding
the focused element. Keys are ignored when focus sits in a form field or contenteditable region. Turn
it off per carousel with `data-embla-keyboard="false"`.

## Dialog and lightbox [#dialog-and-lightbox]

A carousel can't measure its viewport until its `<dialog>` is open, so Zazz defers it: a
`MutationObserver` watches each dialog's `open` attribute and initializes any carousel inside once it
opens. Set `data-embla-start` on the trigger to open at a specific slide.

```html
<button commandfor="gallery-dialog" data-embla-start="2">Open at slide 3</button>
```

The [lightbox](/docs/components/lightbox) builds on this: the same Embla roles plus a fullscreen
`<dialog>` and a thumb strip.

When slides are clickable (a lightbox trigger with `commandfor`, say), a drag is told apart from a
click, and clicks are suppressed for a short window after a drag so a swipe never fires an accidental
tap.

## Re-initialization [#re-initialization]

After an SPA-style navigation or any dynamic content insertion, re-scan for new carousels:

```js
EmblaInit.init(newContentElement);
```

The [navigation script](/docs/getting-started/page-transitions) calls this for you after swapping
`<main>`. `init()` skips carousels it has already wired (`data-embla-init`) and defers any inside a
closed dialog.

The lower-level `data-embla="root"` wrapper still works for hand-built Embla markup, but prefer
`<embla-carousel>` for components and any markup that may be inserted or removed at runtime.


# Checkbox (/docs/components/checkbox)



The checkbox is a restyled native `<input type="checkbox">`, fully accessible, with the Zazz
check treatment. Bind it with `checked`, `name`, and `value` as usual.

## Default [#default]

<Preview src="checkbox/default" />


# Dialog (/docs/components/dialog)



Dialogs use a native `<dialog class="dialog">`. Open one from any button with
`command="show-modal"` and `commandfor="<id>"`, and close with `command="close"`. Add
`closedby="any"` for light-dismiss. Size with `data-size`.

## Default [#default]

<Preview src="dialog/default" />

## With a form [#with-a-form]

<Preview src="dialog/with-form" />

## Alert [#alert]

<Preview src="dialog/is-alert" />

## API [#api]

| Attribute    | Where      | Values                           |
| ------------ | ---------- | -------------------------------- |
| `command`    | trigger    | `show-modal`, `close`            |
| `commandfor` | trigger    | id of the `<dialog>`             |
| `data-size`  | `.dialog`  | `article`, `container`, `screen` |
| `closedby`   | `<dialog>` | `any`, `closerequest`, `none`    |


# Dropdown (/docs/components/dropdown)



A dropdown is a `.dropdown__popover` (`popover="auto"`) opened by a trigger with
`popovertarget`. Menu items are ghost buttons. Place the panel with `data-side` and
`data-align`; it light-dismisses natively.

## Default [#default]

<Preview src="dropdown/default" />

## API [#api]

| Attribute       | Where                | Values                           |
| --------------- | -------------------- | -------------------------------- |
| `popovertarget` | trigger              | id of the `.dropdown__popover`   |
| `data-side`     | `.dropdown__popover` | `top`, `bottom`, `left`, `right` |
| `data-align`    | `.dropdown__popover` | `start`, `center`, `end`         |


# Input group (/docs/components/input-group)



An `.input-group` wraps an `.input` with `.input-group__addon` elements. Place an addon with
`data-align`: inline (leading or trailing) or block (above or below).

## Default [#default]

<Preview src="input-group/default" />

## Password group [#password-group]

The password-group example wraps the field in `<input-password>`, which adds the show/hide
toggle behavior and exposes the component script in the JS tab.

<Preview src="input-group/password-group" />

## API [#api]

| Attribute    | Where                 | Values                                                   |
| ------------ | --------------------- | -------------------------------------------------------- |
| `data-align` | `.input-group__addon` | `inline-start`, `inline-end`, `block-start`, `block-end` |


# Input (/docs/components/input)



Inputs use the `.input` class and share the `--field-*` token family. Validation surfaces via
`:user-invalid` (after blur or submit, never while typing). Pair with a `.field` wrapper for
the label / hint / error layout.

## Default [#default]

<Preview src="input/default" />

## Leading icon [#leading-icon]

<Preview src="input/icon-leading" />

## Trailing icon [#trailing-icon]

<Preview src="input/icon-trailing" />


# Lightbox (/docs/components/lightbox)



The lightbox pairs an inline `<embla-carousel>` gallery with a fullscreen `<dialog>`
carousel and thumb strip, all wrapped in `<media-lightbox>`. Slides open the dialog via
`command="show-modal"`, so opening and closing still comes from HTML. The web component
only coordinates state: it opens the dialog carousel at the gallery's current slide,
focuses the viewport for keyboard navigation, and syncs the inline gallery to the last
viewed slide when the dialog closes.

The elements use light DOM, so the `.lightbox` classes and `data-embla-*` attributes style
and configure the same markup you author. The preview loads the required scripts
automatically; open the JS tab to inspect the custom elements.

## Default [#default]

<Preview src="lightbox/default" />

## API [#api]

| Markup                                                           | Where    | Purpose                                                  |
| ---------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| `<media-lightbox class="lightbox">`                              | root     | Coordinates the inline gallery and dialog carousel       |
| `<embla-carousel class="lightbox__stage">`                       | gallery  | Inline carousel; owns drag, thumbs, and stage navigation |
| `<dialog class="lightbox__dialog">`                              | root     | Fullscreen modal surface                                 |
| `<embla-carousel>`                                               | dialog   | Fullscreen carousel; initialized when the dialog opens   |
| `command="show-modal"` / `command="close"`                       | triggers | Opens and closes the dialog through Invoker Commands     |
| `data-embla="viewport"` / `"container"` / `"slide"` / `"thumbs"` | children | Embla roles for stage, slides, and thumb carousel        |

Put Embla options (`data-embla-loop`, `data-embla-classnames`, etc.) on each
`<embla-carousel>`.


# Mobile menu (/docs/components/mobile-menu)



The mobile menu composes a native `<dialog>` with nested `<details>` accordions. Open it with
`command="show-modal"` and `commandfor="<id>"`, close with `command="close"` or light-dismiss
via `closedby="any"`. No JavaScript needed.

Internally it uses `.dialog[data-size="screen"]` for full-viewport coverage and
`data-animation="slide-right"` for the entrance transition.

## Default [#default]

<Preview src="mobile-menu/default" />

## Structure [#structure]

```html
<!-- Trigger -->
<button class="button" data-size="icon" command="show-modal" commandfor="mobile-menu-1">☰</button>

<!-- Menu -->
<dialog
  id="mobile-menu-1"
  class="dialog mobile-menu"
  data-size="screen"
  data-animation="slide-right"
  closedby="any"
>
  <div class="mobile-menu__viewport">
    <div class="mobile-menu__header">…</div>
    <div class="mobile-menu__body">
      <div class="accordion">
        <details>
          <summary class="button" data-variant="ghost">Section</summary>
          <div class="flex flex-col pb-sm">
            <!-- Links / nested accordions -->
          </div>
        </details>
      </div>
    </div>
    <div class="mobile-menu__footer">…</div>
  </div>
</dialog>
```

## Tokens [#tokens]

| Token                                                 | Default                       |
| ----------------------------------------------------- | ----------------------------- |
| `--mobile-menu-background`                            | `var(--background)`           |
| `--mobile-menu-foreground`                            | `var(--foreground)`           |
| `--mobile-menu-backdrop`                              | `var(--faded-foreground)`     |
| `--mobile-menu-header-padding-inline`                 | `var(--gap-md) var(--gap-xs)` |
| `--mobile-menu-header-padding-block`                  | `var(--gap-xs)`               |
| `--mobile-menu-body-padding-inline`                   | `var(--gap-sm)`               |
| `--mobile-menu-body-padding-block`                    | `var(--gap-md)`               |
| `--mobile-menu-footer-padding`                        | `var(--gap-sm)`               |
| `--mobile-menu-footer-gap`                            | `var(--gap-xs)`               |
| `--mobile-menu-nested-accordion-padding-inline-start` | `var(--gap-sm)`               |

## API [#api]

| Attribute        | Where          | Values                        |
| ---------------- | -------------- | ----------------------------- |
| `command`        | trigger        | `show-modal`, `close`         |
| `commandfor`     | trigger        | id of the `<dialog>`          |
| `data-size`      | `.mobile-menu` | `screen`                      |
| `data-animation` | `.mobile-menu` | `slide-right`                 |
| `closedby`       | `<dialog>`     | `any`, `closerequest`, `none` |

## Composition notes [#composition-notes]

* Add `.dark` to the dialog for a dark-themed menu regardless of page theme.
* The body uses a nested `.accordion` with native `<details>` for expand/collapse sections.
* Nested accordions (accordion inside accordion) automatically indent via `--mobile-menu-nested-accordion-padding-inline-start`.
* The header and footer are `position: sticky` so they remain visible while the body scrolls.
* Use `.button[data-variant="ghost"]` for nav links inside accordion panels.


# Navigation menu (/docs/components/navigation-menu)



The navigation menu pairs triggers (`popovertarget`) with `.navigation-menu__popover` panels.
A `.navigation-menu__list` holds each `.navigation-menu__item`, whose `.navigation-menu__trigger`
opens a panel. Panels wrap a `.navigation-menu__viewport` grid of `.navigation-menu__link` rows
(title + description, filling with muted on hover), can nest flyout submenus via
`.navigation-menu__submenu` / `.navigation-menu__submenu-trigger`, and animate in. A "Featured"
callout is not a dedicated part — it is plain utilities, e.g.
`bg-muted hover:opacity-75 rounded-sm p-sm` with a `.text-eyebrow` label.

## Default [#default]

<Preview src="navigation-menu/default" />

The sign-in dialog in this example uses `<input-password>` for the password field's
show/hide toggle; open the JS tab to inspect that enhancement.

## API [#api]

| Attribute        | Where                       | Values                        |
| ---------------- | --------------------------- | ----------------------------- |
| `popovertarget`  | trigger                     | id of the panel               |
| `data-align`     | `.navigation-menu__popover` | `center`, `end`               |
| `data-variant`   | `.navigation-menu__popover` | `submenu`                     |
| `data-size`      | `.navigation-menu__popover` | `root`, `container`, `screen` |
| `data-animation` | `.navigation-menu__popover` | `slide-down`                  |


# Password group (/docs/components/password-group)



The `.password-group` is an input group whose trailing addon is a ghost button that toggles
the field's visibility. Wrap it in `<input-password>` to add the show/hide behavior while
keeping the field usable as a normal masked password input when JavaScript is unavailable.

The toggle button keeps `aria-pressed` and `aria-label` in sync, and the icon swap is driven
by CSS from that pressed state. The preview loads the required script automatically; open the
JS tab to inspect the custom element.

## Default [#default]

<Preview src="password-group/default" />

## API [#api]

| Attribute                 | Where              | Purpose                                                 |
| ------------------------- | ------------------ | ------------------------------------------------------- |
| `<input-password>`        | wrapper            | Finds the password input and toggle button              |
| `.password-group`         | label              | Field surface and addon layout                          |
| `.password-group__toggle` | button             | Button that flips the input between password/text       |
| `label-show`              | `<input-password>` | Optional accessible label while the password is hidden  |
| `label-hide`              | `<input-password>` | Optional accessible label while the password is visible |


# Prose (/docs/components/prose)



Wrap any block of rich HTML in `.prose` to get headings, paragraphs, lists, figures, and
vertical rhythm without per-element classes. Ideal for CMS or Markdown-rendered content.

## Default [#default]

<Preview src="prose/default" />


# Radio (/docs/components/radio)



Radios apply the `.radio` treatment to native `<input type="radio">` inputs. Group them with a
shared `name` (and a `.radio-group` wrapper) so only one can be selected at a time.

## Default [#default]

<Preview src="radio/default" />


# Reveal (/docs/components/reveal)



Reveal is a lightweight animation system for scroll-based viewport entry effects. It uses `IntersectionObserver` to trigger CSS transitions when elements scroll into view.

## How it works [#how-it-works]

1. Add `data-reveal` or `data-reveal-each` to your HTML.
2. The `Reveal` class discovers those elements, sets CSS custom properties, and observes them.
3. When an element enters the viewport, it receives the `.in-viewport` class.
4. CSS transitions (defined in `_reveal.css`) animate from the hidden state to visible.

No keyframes, no JavaScript animation loops, just CSS transitions triggered by a class toggle.

## Setup [#setup]

`reveal.js` ships inside the single [`main.js`](/docs/getting-started/head#script-load-order) module; its styles are part of `main.css`, which `@import`s `ui/_reveal.css`. The normal setup is one link to `main.css` plus the module:

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
<script type="module" src="./zazz/scripts/main.js"></script>
```

If you link files individually, the reveal styles live at `./zazz/styles/ui/_reveal.css`.

Reveal auto-initializes once the DOM is parsed. No manual setup needed for standard pages.

## Single elements [#single-elements]

Animate individual elements with `data-reveal`:

```html
<div data-reveal="slide-up">Slides up into view</div>
<div data-reveal="fade">Fades in</div>
<div data-reveal="slide-left">Slides in from the right</div>
```

### Available animations [#available-animations]

| Value         | Effect                        |
| ------------- | ----------------------------- |
| `slide-up`    | Translate up from below       |
| `slide-down`  | Translate down from above     |
| `slide-left`  | Translate left from the right |
| `slide-right` | Translate right from the left |
| `fade`        | Opacity only                  |
| `grow`        | Scale up from smaller         |
| `shrink`      | Scale down from larger        |

## Stagger groups [#stagger-groups]

Animate direct children with sequential delays using `data-reveal-each`:

```html
<div data-reveal-each="fade" data-reveal-step="100">
  <div>Item 1 — appears first</div>
  <div>Item 2 — 100ms later</div>
  <div>Item 3 — 200ms later</div>
</div>
```

Each child gets an incrementing delay calculated as `baseWait + (step × index)`.

### Reversed order [#reversed-order]

Animate children from last to first:

```html
<div data-reveal-each="slide-up" data-reveal-order="reversed">
  <div>Appears last</div>
  <div>Appears second</div>
  <div>Appears first</div>
</div>
```

## Combining with hover and other transitions [#combining-with-hover-and-other-transitions]

Reveal animates by controlling the element's CSS transition: the duration, the stagger delay, the timing function, and which properties move (`opacity` and `transform`). That means it owns `transition-*` on whatever element it's set on.

So don't add a `transition` (or `transition-all`) utility to the same element you put `data-reveal` on. Both want to set `transition-*`, and the utility resets the delay reveal calculated, so the stagger collapses and everything fires at once.

When an element needs its own transition too — a `hover:` border, say — wrap it. Put the reveal on an outer `div` and keep the `transition` on the inner element. Each one controls its own transitions, and they stop stepping on each other:

```html
<!-- The wrapper handles the reveal; the card keeps its hover transition -->
<div data-reveal-each="slide-up">
  <a class="card transition hover:border-primary">First card</a>
  <a class="card transition hover:border-primary">Second card</a>
</div>
```

```html
<!-- Avoid: one element doing both. The `transition` utility wipes the stagger. -->
<a class="card transition hover:border-primary" data-reveal="slide-up">Card</a>
```

## Configuration attributes [#configuration-attributes]

All attributes are optional. Set them on the element with `data-reveal` or `data-reveal-each`:

| Attribute               | Default                    | Description                                                                                                           |
| ----------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `data-reveal-duration`  | `--reveal-global-duration` | Animation duration. Defaults to the global transition duration (`--default-transition-duration`); JS fallback `400ms` |
| `data-reveal-wait`      | `0`                        | Base delay before animation starts (ms)                                                                               |
| `data-reveal-step`      | `80`                       | Delay between staggered children (ms)                                                                                 |
| `data-reveal-ease`      | `--reveal-global-ease`     | Timing function. Defaults to `--default-transition-timing-function`; JS fallback `cubic-bezier(0.4, 0, 0.2, 1)`       |
| `data-reveal-distance`  | `1rem`                     | Translation distance for slide animations                                                                             |
| `data-reveal-scale`     | —                          | Custom scale value for grow/shrink                                                                                    |
| `data-reveal-margin`    | `0px`                      | IntersectionObserver `rootMargin`                                                                                     |
| `data-reveal-threshold` | `0.2`                      | Visibility threshold (0–1) to trigger                                                                                 |
| `data-reveal-order`     | —                          | Set to `"reversed"` for reverse stagger                                                                               |

## Global configuration [#global-configuration]

Override defaults by passing a config object:

```js
const reveal = new Reveal({
  config: {
    duration: 600,
    ease: "ease-in-out",
    threshold: 0.3,
    margin: "100px",
    step: 100,
  },
});
```

Or set global CSS custom properties on `:root`:

```css
:root {
  --reveal-global-duration: 600ms;
  --reveal-global-ease: ease-in-out;
  --reveal-global-distance: 2rem;
  --reveal-global-grow: 0.97; /* scale for grow */
  --reveal-global-shrink: 1.03; /* scale for shrink */
}
```

| Token                      | Default                                     | Description                 |
| -------------------------- | ------------------------------------------- | --------------------------- |
| `--reveal-global-duration` | `var(--default-transition-duration)`        | Animation duration          |
| `--reveal-global-ease`     | `var(--default-transition-timing-function)` | Timing function             |
| `--reveal-global-wait`     | `0ms`                                       | Base delay before animation |
| `--reveal-global-distance` | `1rem`                                      | Slide translation distance  |
| `--reveal-global-grow`     | `0.97`                                      | Scale for `grow`            |
| `--reveal-global-shrink`   | `1.03`                                      | Scale for `shrink`          |

## Manual control [#manual-control]

### Disable auto-initialization [#disable-auto-initialization]

```js
Reveal.disableAutoInit();
const reveal = new Reveal({
  config: {
    /* custom */
  },
});
```

### Refresh after DOM changes [#refresh-after-dom-changes]

After dynamically inserting content, rescan for new `[data-reveal]` elements:

```js
container.innerHTML = newContent;
Reveal.getAutoInstance()?.refresh();
```

The SPA navigation script (`navigation.js`) calls `refresh()` automatically after swapping `<main>` content.

## Reduced motion [#reduced-motion]

Reveal respects `prefers-reduced-motion`. The CSS uses the standard `@media (prefers-reduced-motion: reduce)` query: when reduced motion is preferred, elements appear immediately with transitions and transforms disabled.

## CSS custom properties [#css-custom-properties]

The script sets these properties per-element for the CSS transitions to consume:

| Property            | Set by                                     |
| ------------------- | ------------------------------------------ |
| `--reveal-duration` | `data-reveal-duration`                     |
| `--reveal-ease`     | `data-reveal-ease`                         |
| `--reveal-wait`     | `data-reveal-wait` (+ stagger calculation) |
| `--reveal-distance` | `data-reveal-distance`                     |
| `--reveal-scale`    | `data-reveal-scale`                        |


# Select (/docs/components/select)



The `.select` restyles a native `<select>` using `appearance: base-select`, so the dropdown
picker matches the rest of the system where supported. Falls back to the native control
otherwise (gated behind `@supports`).

The `base-select` pattern requires a `<button><selectedcontent></selectedcontent></button>` as
the select's first child — the button is the trigger and `<selectedcontent>` mirrors the chosen
option. Keep the `<option>`s (an `<optgroup>` label works as a native fallback) after it.

## Default [#default]

<Preview src="select/default" />


# Slider (/docs/components/slider)



The slider is a restyled native `<input type="range">`. Accessible and keyboard-operable.
Use the standard `min`, `max`, `step`, and `value` attributes.

## Default [#default]

<Preview src="slider/default" />


# Switch (/docs/components/switch)



The switch is a restyled `<input type="checkbox" role="switch">` with a track and thumb.
Bind it like any checkbox (`checked`, `name`, `value`).

## Default [#default]

<Preview src="switch/default" />


# Tabs (/docs/components/tabs)



Tabs are CSS-first: grouped `input[type="radio"][role="tab"]` inputs drive the panels and
the sliding indicator. Wrap the pattern in `<tab-group class="tabs">` to add
orientation-aware keyboard navigation: Left/Right for horizontal tabs, Up/Down for vertical
tabs, plus Home/End and wrap-around. &#x2A;*Panel order must match the radio order.**

Without JavaScript, the grouped radios still select panels natively. The preview loads the
required script automatically; open the JS tab to inspect the custom element.

## Default [#default]

<Preview src="tabs/default" />

## API [#api]

| Attribute          | Where | Values                              |
| ------------------ | ----- | ----------------------------------- |
| `<tab-group>`      | root  | Custom element that carries `.tabs` |
| `data-orientation` | root  | `vertical` (horizontal is default)  |


# Textarea (/docs/components/textarea)



The `.textarea` shares the `--field-*` tokens with the other form controls, including
`:user-invalid` validation styling. It sets `field-sizing: content` unconditionally, so the box
auto-grows with its text and clamps between `--textarea-min-block-size` (`5lh`) and
`--textarea-max-block-size` (`12lh`), then scrolls — adjust those tokens to change the height
range. `rows` is not the height lever here.

## Default [#default]

<Preview src="textarea/default" />


# Toggle group (/docs/components/toggle-group)



Wrap two or more [toggles](/docs/components/toggle) in `.toggle-group` to fuse them
into one segmented control — the same border-collapse and inner-corner squaring as a
[button group](/docs/components/button-group). Make it **single-select** by giving
the toggles `radio` inputs that share a `name`; make it **multi-select** with
`checkbox` inputs. Add `role="group"` and an `aria-label` so the set is announced.

## Single select [#single-select]

Radios sharing a `name` — exactly one toggle stays on.

<Preview src="toggle-group/default" align="center" />

## Multi select [#multi-select]

Checkboxes — any number can be on at once.

<Preview src="toggle-group/multiple" align="center" />

## Vertical [#vertical]

Set `data-orientation="vertical"` on the wrapper to stack them.

<Preview src="toggle-group/vertical" align="center" />

## API [#api]

| Attribute          | Values                                 |
| ------------------ | -------------------------------------- |
| `data-orientation` | `vertical` (omit = horizontal default) |

The group reads each child's own `--toggle-radius`, so the outer corners follow the
toggles' `data-size` automatically — only the inner corners are squared. You never
need to touch `zazz/styles/`.


# Toggle (/docs/components/toggle)



A toggle is a `<label class="toggle">` wrapping a visually-hidden `<input>` and the
visible content. It looks exactly like a [button](/docs/components/button) — same
`data-variant` and `data-size` options — but the **on** state reuses the button's
*active* look, driven entirely by the native input's `:checked` state (no JS). Use a
`checkbox` for an independent on/off control; use a `radio` (sharing a `name`) when
exactly one of a set may be on.

Give icon-only toggles an accessible name with `aria-label` on the input.

## Variants [#variants]

<Preview src="toggle/default" align="center" />

## API [#api]

| Attribute      | Values                                                      |
| -------------- | ----------------------------------------------------------- |
| `data-variant` | `primary`, `muted`, `ghost`, `destructive` (omit = default) |
| `data-size`    | `sm`, `icon`, `icon-sm`                                     |

The toggle's tokens (`--toggle-background`, `--toggle-radius`, …) default to the
matching `--button-*` token, so theming the button family re-skins toggles for free.
Override a `--toggle-*` token at `:root` or inline for a one-off. To join several
toggles into one segmented control, see [toggle group](/docs/components/toggle-group).


# Tooltip (/docs/components/tooltip)



A tooltip pairs a trigger with a `.tooltip__content` hint (`popover="hint"`). Wire them with
`interestfor` on the trigger. Hover, focus, and long-press all work automatically, ARIA
included. Position the hint with `data-side`.

The hint holds a `<span class="tooltip__arrow" aria-hidden="true"></span>` that points back at
the trigger, and carries `data-use-inverted-menu="false"` to opt out of the inverted dark
popover scheme.

## Default [#default]

<Preview src="tooltip/default" />

## With keyboard shortcut [#with-keyboard-shortcut]

<Preview src="tooltip/with-kbd" />

## Sides [#sides]

<Preview src="tooltip/sides" />

## Disabled trigger [#disabled-trigger]

<Preview src="tooltip/disabled" />

## API [#api]

| Attribute                | Where               | Values                           |
| ------------------------ | ------------------- | -------------------------------- |
| `interestfor`            | trigger             | id of the `.tooltip__content`    |
| `data-side`              | `.tooltip__content` | `top`, `bottom`, `left`, `right` |
| `data-align`             | `.tooltip__content` | `center`                         |
| `data-use-inverted-menu` | `.tooltip__content` | `false`                          |


# Utils (/docs/components/utils)



`utils.js` provides two parsing helpers that other scripts depend on. It converts HTML data-attribute strings into typed JavaScript values, eliminating repetitive parsing logic across component scripts.

## Setup [#setup]

`utils.js` ships inside the single [`main.js`](/docs/getting-started/head#script-load-order) module and loads automatically — `embla.js` `import`s it directly, so there's no load order to manage by hand:

```html
<script type="module" src="./zazz/scripts/main.js"></script>
```

Exposes `window.Utils` with two functions.

## `parseValue(value)` [#parsevaluevalue]

Converts a string attribute value to its appropriate JavaScript type:

```js
Utils.parseValue("true"); // true (boolean)
Utils.parseValue("false"); // false (boolean)
Utils.parseValue("42"); // 42 (number)
Utils.parseValue("[1,2,3]"); // [1, 2, 3] (array)
Utils.parseValue("hello"); // "hello" (string)
```

## `parseDataAttributes(node, prefix)` [#parsedataattributesnode-prefix]

Extracts all data attributes matching a prefix from a DOM element, converts kebab-case names to camelCase keys, and parses values with `parseValue`:

```js
// <div data-embla-auto-play="true" data-embla-slide-count="5">
Utils.parseDataAttributes(element, "data-embla-");
// { autoPlay: true, slideCount: 5 }
```

This is how `embla.js` reads all carousel configuration from HTML: no inline scripts or JSON blobs needed.


# Colors (/docs/core-concepts/colors)



Color in Zazz is chosen by **role**, not by shade. Instead of "neutral-600," you reach for `muted-foreground`; instead of "indigo-600," you reach for `primary`. Because roles resolve through [`light-dark()`](/docs/core-concepts/dark-mode), a role-based design is correct in both themes with no extra work, and recoloring the brand is a one-line change.

```html
<div class="bg-card text-card-foreground border border-border p-md rounded-lg">
  <p class="text-muted-foreground">Role classes carry their own light/dark values.</p>
</div>
```

Every role ships `text-{role}`, `bg-{role}`, and `border-{role}` utilities.

## The roles [#the-roles]

### Surfaces and text, paired [#surfaces-and-text-paired]

Each surface has a matching foreground tuned for contrast on it:

| Surface      | Foreground          | Use for                            |
| ------------ | ------------------- | ---------------------------------- |
| `background` | `foreground`        | The page itself                    |
| `card`       | `card-foreground`   | Cards, raised panels               |
| `input`      | `input-foreground`  | Form control fills                 |
| `muted`      | `muted-foreground`  | Dimmed surfaces and secondary text |
| `faded`      | `faded-foreground`  | Faded surfaces and tertiary text   |
| `border`     | `border-foreground` | Hairlines and dividers             |

`muted` dims (it's darker than its surface in light mode); `faded` lightens. Pair a surface with its foreground and contrast takes care of itself.

The `popover` surface (`--popover` / `--popover-foreground`) is the one exception. It's a token that menu, tooltip, and dialog components read directly, with no `text-`/`bg-` utility of its own.

### Brand [#brand]

`primary`, `secondary`, `tertiary`, each with a `-foreground` for text and icons placed on it.

### Status [#status]

`info`, `success`, `warning`, `destructive`, same `-foreground` pairing. Use `destructive` for dangerous actions and error states.

## When a role won't do: scales and overlays [#when-a-role-wont-do-scales-and-overlays]

Reach past roles only when you need a specific shade: a fixed tint, a backdrop, a precise accent.

* **Brand & neutral scales:** `--primary-50`…`--primary-950` (and `--secondary-*`, `--tertiary-*`, `--neutral-*`), plus `--white` and `--black`. These are **tokens only, no utility classes**. Reach them in custom CSS or inline: `style="color: var(--primary-600)"`.
* **Overlays:** `--shade-*` darkens (from neutral-950, ideal for modal backdrops like `--shade-800`) and `--tint-*` lightens (from white). `*-none` is transparent. Overlays *do* ship `bg-shade-*` and `bg-tint-*` utilities, since dimming a surface is common.
* **Absolute:** `text-white`, `text-black`, `bg-white`, `bg-black`, `bg-transparent`.

A fixed scale step stays the same in both themes, which is exactly why roles, not scales, are the default.

## Built on oklch [#built-on-oklch]

Zazz colors are authored in [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch), a perceptually uniform color space. That's what lets the system derive consistent variant tints and overlays with `oklch(from … )` and `color-mix()`: equal lightness steps actually look equal, and a single hue shift re-skins a whole ramp cleanly. `oklch()` is [Baseline](https://web.dev/baseline) and widely available.

## Color alpha vs element opacity [#color-alpha-vs-element-opacity]

Two different fades, and it's worth not confusing them:

* **Element opacity** (`opacity-{0,25,50,75,100}`) fades the whole element *and its children*.
* **Color alpha** (`bg-opacity-*`, `text-opacity-*`, `border-opacity-*`) dims only that color channel, leaving children untouched. It's backed by `@property`-registered variables that don't inherit, so a faded background never bleeds into the text on top of it.

```html
<!-- the surface is translucent; the text stays fully opaque -->
<div class="bg-primary bg-opacity-25 text-foreground">…</div>
```

## Recoloring the brand [#recoloring-the-brand]

Because everything reads tokens, changing your brand color is a single override. See [Theme variables](/docs/base/variables) for the three scopes:

```css
:root {
  --primary: oklch(0.6 0.2 145); /* every primary surface, ring, and accent follows */
}
```

To shift the entire ramp (so derived tints match), override the numeric scale instead, then point the role at it. For where to put these overrides, see [Adding custom styles](/docs/core-concepts/custom-styles).


# Adding custom styles (/docs/core-concepts/custom-styles)



Zazz's tokens and utilities cover most of what you'll build, but every project has a one-off. When you hit one, you extend the system from the *outside*, and you never edit files in `zazz/styles/`. Keep your additions in your own stylesheet, loaded after `main.css`, and they land in the [cascade](/docs/base/layers) after Zazz's own layers.

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
<link rel="stylesheet" href="./your-styles.css" />
```

## Start with a token override [#start-with-a-token-override]

Most customizations aren't new CSS at all; they're a different value for an existing token. Reach for this first, at the [narrowest scope that works](/docs/base/variables):

```css
/* your-styles.css */
:root {
  --primary: oklch(0.6 0.2 145); /* global: re-skin the brand */
  --button-radius: var(--radius-full); /* component default: pill buttons */
}
```

```html
<!-- instance: this element only -->
<div class="card" style="--card: var(--muted)">…</div>
```

A token override is the most durable kind of custom style: it composes with dark mode, stays consistent with the rest of the system, and never fights a component rule.

## Add your own utilities [#add-your-own-utilities]

When you want a reusable class that isn't in the set, add it to `@layer zazz.utilities` so it lands in the right layer, winning over components like every other utility. Wrap the selector in `:where()` to keep it zero-specificity and overridable:

```css
@layer zazz.utilities {
  :where(.text-gradient) {
    background: linear-gradient(90deg, var(--primary), var(--secondary));
    background-clip: text;
    color: transparent;
  }
}
```

Compose from tokens (`var(--primary)`, `var(--gap-md)`) rather than literals, and your utility inherits the theme and dark-mode behavior automatically.

## Add your own components [#add-your-own-components]

For a larger pattern with variants, write it in `@layer zazz.components` and give it token hooks, mirroring how Zazz components are built. See [File anatomy](/docs/base/file-anatomy):

```css
@layer zazz.components {
  :where(.callout) {
    --callout-background: var(--muted);
    background: var(--callout-background);
    border-inline-start: var(--step-1) solid var(--primary);
    padding: var(--gap-md);
    border-radius: var(--radius-md);
  }
}
```

Because it's in `components`, your utilities still override it, so a `.callout p-xl` works as expected.

## The escape hatch: unlayered CSS [#the-escape-hatch-unlayered-css]

A rule written **outside any layer** beats everything in Zazz (every component and every utility) regardless of specificity:

```css
/* No @layer wrapper. This wins over all layered styles. */
.button {
  border-radius: 0;
}
```

That makes it powerful and easy to misuse. It's the right tool when you deliberately need to trump the system; the rest of the time, a token override or a properly layered rule keeps you inside it. See [`layers.css`](/docs/base/layers) for why unlayered styles win.

## Pick the smallest tool [#pick-the-smallest-tool]

In order of preference:

1. **Token override:** a different value for an existing variable. Composes with everything.
2. **Layered rule:** a new utility or component in `@layer zazz.utilities` / `@layer zazz.components`.
3. **Unlayered rule:** only when you intend to override all of Zazz.

The one rule that doesn't bend: don't edit `zazz/styles/`. Every customization above lives in your own files, so updating Zazz never clobbers your work.


# Dark mode (/docs/core-concepts/dark-mode)



Zazz ships dark mode by default. `:root` declares `color-scheme: light dark`, and every theme [role](/docs/core-concepts/colors) resolves through `light-dark()`. Use a role (`bg-background`, `text-foreground`, `bg-card`, `text-muted-foreground`) and it's right in both themes automatically. There are no parallel dark styles to write or keep in sync.

```html
<!-- Correct in light and dark. Nothing else to do. -->
<section class="bg-background text-foreground p-lg">
  <h2 class="text-h3">Works in both themes</h2>
  <p class="text-muted-foreground">Because the roles swap, this does too.</p>
</section>
```

## How a role resolves [#how-a-role-resolves]

Each role is defined once with a light value and a dark value, and the browser picks based on the active `color-scheme`:

```css
/* from _variables.css */
--background: light-dark(var(--white), var(--neutral-900));
--foreground: light-dark(var(--neutral-900), var(--white));
--muted-foreground: light-dark(var(--shade-600), var(--tint-600));
```

That's why the rule is: &#x2A;*use roles, not raw scales.** A role like `--primary` swaps; a fixed scale step like `--primary-600` does not. Reach for scales only when you specifically want a color that stays put across themes.

## Three ways the scheme is decided [#three-ways-the-scheme-is-decided]

### 1. Follow the system (default) [#1-follow-the-system-default]

By default, the page follows the operating system's light/dark setting. Nothing required beyond the [`color-scheme` meta tag](/docs/getting-started/head) in your `<head>`, which paints the right canvas, scrollbars, and form controls before your CSS even loads.

```html
<meta name="color-scheme" content="light dark" />
```

### 2. Force a theme with `.dark` [#2-force-a-theme-with-dark]

To pin dark mode regardless of system preference, add the `.dark` class, usually on `<html>`. It re-declares the role tokens and sets `color-scheme: dark` so native UI follows:

```html
<html class="dark"></html>
```

### 3. Inverted surfaces [#3-inverted-surfaces]

Popovers and menus render dark-on-light by default (a common design touch) via a container style query (`@container style(--use-inverted-popovers: true)`). To opt a subtree out, flip the flag or use the `data-use-inverted-menu="false"` attribute on the popover:

```css
:root {
  --use-inverted-popovers: false;
}
```

```html
<div popover data-use-inverted-menu="false">…</div>
```

## Don't hand-write dark overrides [#dont-hand-write-dark-overrides]

If a value is driven by a role token, dark mode is already handled. Writing `.dark .my-thing { … }` to recolor something that uses roles is redundant and will drift. Let the tokens do it.

```css
/* Don't. The role already swaps. */
.dark .panel {
  background: var(--neutral-900);
}

/* Do. One declaration, correct in both themes. */
.panel {
  background: var(--card);
}
```

## Building a theme toggle [#building-a-theme-toggle]

For a user-facing switch, keep the CSS defaulting to the system preference and override only when the user has chosen, so the page is still correct if your script never runs.

* Update the `<meta name="color-scheme">` content to the chosen value (`light dark` for system, or `light` / `dark` to pin one), and toggle the `.dark` class to match.
* Persist the choice in `localStorage`.
* Apply it from an **inline, non-deferred** script at the top of `<head>` so there's no flash before the rest of the page loads.

```html
<meta name="color-scheme" content="light dark" />
<script>
  {
    const choice = localStorage.getItem("color-scheme");
    if (choice) {
      document.querySelector('meta[name="color-scheme"]').content = choice;
      document.documentElement.classList.toggle("dark", choice === "dark");
    }
  }
</script>
```

<Callout>
  Offer two states, **system** and **its opposite**, not three. A pinned choice should stay pinned
  even when the OS setting later changes, and a three-way "system / light / dark" control always has
  two options that look identical, which reads as a broken toggle.
</Callout>

## Forcing one section light or dark [#forcing-one-section-light-or-dark]

Set `color-scheme` on any element to lock it, handy for a code block or media player that should stay dark on a light page:

```css
pre {
  color-scheme: dark;
}
```

## Browser support [#browser-support]

`color-scheme` is [Baseline](https://web.dev/baseline) widely available (since 2022); browsers without it simply render light mode. `light-dark()` is Baseline newly available: Chrome/Edge 123, Firefox 120, Safari 17.5 (2024). If you need to support browsers older than that, define light/dark values as separate custom properties and switch them with a `prefers-color-scheme` media query, then layer `light-dark()` on top with `@supports`.


# Responsive design (/docs/core-concepts/responsive-design)



Zazz is responsive before you write a single breakpoint: type and spacing already scale fluidly. When you *do* reach for breakpoints, they read one centralized set of widths that the page publishes to every component, so your layouts cross them together and predictably.

## Fluid by default [#fluid-by-default]

Before you reach for a single breakpoint, two systems are already responding to the viewport:

* **Type:** every `text-*` class is a `clamp()` that grows smoothly between a min and max size. `text-h1` is large on a desktop and proportionally smaller on a phone, with no breakpoint in between.
* **Spacing:** the `--step-*` scale derives from a fluid interval, so `gap-md`, `p-lg`, and the rest tighten on small screens and open up on large ones.

A lot of layouts need no breakpoints at all because of this.

## Responsive prefixes read centralized breakpoints [#responsive-prefixes-read-centralized-breakpoints]

When you need a layout to change shape, prefix a utility with a breakpoint: `@xs:` `@sm:` `@md:` `@lg:` `@xl:`. The `@` marks them as container style queries. Each one reads a shared breakpoint flag that the page **body** publishes off its own width, so the prefixes are centralized: a width is defined once, and every component crosses it at the same moment.

```html
<div class="grid grid-cols-1 @md:grid-cols-3 gap-md">
  <article class="card">…</article>
  <article class="card">…</article>
  <article class="card">…</article>
</div>
```

Thresholds line up with the `--breakpoint-*` tokens. Each prefix is min-width: it activates at or above its width, so you write the small layout as the base and override upward.

| Prefix | Page width | Token             |
| ------ | ---------- | ----------------- |
| `@xs:` | ≥ 40rem    | `--breakpoint-xs` |
| `@sm:` | ≥ 48rem    | `--breakpoint-sm` |
| `@md:` | ≥ 64rem    | `--breakpoint-md` |
| `@lg:` | ≥ 80rem    | `--breakpoint-lg` |
| `@xl:` | ≥ 96rem    | `--breakpoint-xl` |

## Smallest first [#smallest-first]

Base utilities apply at every size; a prefixed utility layers on at its breakpoint and up. So you write the small-screen layout as the default and add overrides for wider pages:

```html
<!-- stacked by default, row from md up -->
<div class="flex flex-col @md:flex-row gap-md">…</div>
```

The families available at each breakpoint: the page `container`, `display`, `grid-cols` / `grid-rows`, `flex-direction`, `text-align`, `align-items`, `justify-content`, `col-span`, `row-span`, and `basis`. Less-toggled families (self-alignment, place-items, visibility) ship as base classes only, so apply them outside the responsive layer. The [utilities reference](/docs/utilities/responsive-design) has the full breakpoint table and the exact family list.

## Layouts that respond without breakpoints [#layouts-that-respond-without-breakpoints]

Some Zazz utilities adapt on their own, so you can often skip prefixes entirely:

* **Auto-fitting grids:** `grid-flow-row` with `grid-cols-N` (N > 1) wraps items responsively using a smart `auto-fill` formula. Items flow into as many columns as fit.
* **Gap-aware basis:** `basis-1/2`, `basis-1/3`, and friends subtract the gap automatically, so flex children wrap cleanly with no manual math.

```html
<!-- wraps from 1 to N columns based on available width, no prefixes -->
<div class="grid grid-flow-row grid-cols-3 gap-md">…</div>
```

## Browser support [#browser-support]

Zazz's responsive model is built on [container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries), which are [Baseline](https://web.dev/baseline) and widely available. The style-query form it uses to read the breakpoint flags is newer but supported across current Chrome, Safari, and Firefox. In a browser without it, components fall back to their base (smallest) layout: usable, just not adaptive.

The breakpoints already track the page width, so you rarely need `@media` at all. When you want one piece to respond to the size of its own box instead of the page, write a scoped `@container` query in [your own stylesheet](/docs/core-concepts/custom-styles).


# Hover, focus, and other states (/docs/core-concepts/states)



Interactive states in Zazz come from two places: `hover:` utilities you add yourself, and defaults the framework already handles: focus rings, validation feedback, and disabled styling. Most of the time you write less than you'd expect.

## Hover [#hover]

Prefix a utility with `hover:` and it applies while the pointer is over the element. The prefix works on color, opacity, and scale:

```html
<a class="button hover:bg-primary hover:scale-105">Hover me</a>

<div class="card hover:opacity-75 transition">…</div>
```

<Callout>
  In your HTML you write `hover:bg-primary`, with no backslash. The backslash you'll see in the
  source (`.hover\:bg-primary`) is only CSS escaping the colon in the selector; the class attribute
  uses a plain colon.
</Callout>

What `hover:` covers:

* **Text color:** `hover:text-primary` and every other theme [role](/docs/core-concepts/colors).
* **Background:** `hover:bg-primary`, plus `hover:bg-transparent` and `hover:bg-none`.
* **Border:** `hover:border-primary`, `hover:border-destructive`, and the other roles.
* **Opacity:** `hover:opacity-{0,25,50,75,100}`.
* **Scale:** `hover:scale-{50,75,90,95,100,105,110,125,150}`.

Pair them with `transition` so the change eases instead of snapping. Motion respects `prefers-reduced-motion` automatically, so you don't have to guard it.

## Focus [#focus]

You rarely write focus styles. The [reset](/docs/base/reset) applies a `:focus-visible` ring to every focusable element, so keyboard users get a clear, consistent indicator everywhere. And `:focus-visible` means it shows for keyboard navigation without firing on every mouse click.

```css
/* Already handled globally — shown for reference, not something you write */
:where(:focus-visible) {
  outline: var(--outline-width) var(--outline-style) var(--ring);
}
```

To recolor the ring in a given context, override `--ring-color` (not `--ring`, which recomputes from it):

```html
<form style="--ring-color: var(--destructive)">…</form>
```

Add the `ring` utility when you want a persistent ring on an element regardless of focus. The ring renders as a box-shadow from Tailwind/shadcn-compatible tokens, and a matching transparent outline is kept so focus stays visible in forced-colors mode.

## Pressed and active [#pressed-and-active]

There are no `active:` utilities. Express pressed feedback in a component's own CSS with `:active`. That keeps tactile, per-component motion where it belongs rather than scattering it across markup. The built-in components already do this.

## Validation states [#validation-states]

Form fields validate on `:user-invalid`, which only matches **after** the user has interacted, on blur or submit, never while they're still typing. That timing is the difference between helpful and nagging, and you get it for free; no `was-touched` class to toggle.

```html
<div class="field">
  <label for="email">Email</label>
  <input id="email" type="email" required />
  <p class="field__error">Enter a valid email address.</p>
</div>
```

The shared field family crossfades label, hint, and error for you. `:user-invalid` is [Baseline](https://web.dev/baseline) and widely available. See [Input](/docs/components/input) for the full form markup.

## Disabled [#disabled]

Components style their disabled state through `:not(:disabled)` guards rather than order-dependent overrides, so a `disabled` attribute is all you add:

```html
<button class="button" data-variant="primary" disabled>Saving…</button>
```

## Component states via data attributes [#component-states-via-data-attributes]

Open/closed, selected, and side/alignment states are driven by `data-*` attributes that the framework and native APIs toggle: `data-state`, `data-side`, and friends. You set the variant; the component handles the transitions. See any [component page](/docs/components/dropdown) for its attribute API.


# Styling with utility classes (/docs/core-concepts/utility-classes)



You style a Zazz interface by adding utility classes to your HTML (`flex`, `gap-md`, `text-h2`, `bg-primary`, `rounded-lg`) instead of writing CSS. Each class does one thing and maps to a [design token](/docs/base/variables), so a layout assembled from utilities is consistent by construction and adapts to your theme for free.

```html
<article class="card 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="button mt-sm" data-variant="primary" href="/report">View report</a>
</article>
```

No new CSS file, no class to name, no stylesheet to keep in sync with the markup, and nothing left behind when you delete the element.

## Why utilities [#why-utilities]

* **Stay on-system.** Every utility resolves to a token, so spacing, color, and type come from the same shared vocabulary across the whole site. You compose from a palette instead of inventing values.
* **No naming, no dead CSS.** You never invent `.card-inner-wrapper`, and removing markup removes its styling, so there's no orphaned rule to track down later.
* **They win the cascade cleanly.** Utilities live in `@layer zazz.utilities`, the last [cascade layer](/docs/base/layers), so a utility overrides a component's own rule with no `!important` and no specificity battle.

## Semantic first, specific as the escape hatch [#semantic-first-specific-as-the-escape-hatch]

Reach for the most semantic option that fits, and only get specific when nothing semantic works. This is what keeps a project coherent: you spend the shared design language instead of writing one-off values.

* **Spacing** → `gap-md`, `p-lg`, `py-sm` first; the `--step-*` scale only when no semantic gap fits. Never a raw pixel value.
* **Color** → role classes like `bg-card`, `text-muted-foreground`, `border-primary`, so [light and dark](/docs/core-concepts/dark-mode) swap automatically. Numeric [color scales](/docs/core-concepts/colors) are the last resort.
* **Type** → a single `text-*` class (`text-h1`…`text-xs`, `text-eyebrow`) that bundles size, weight, leading, and tracking. Never compose type from separate utilities.

If you find yourself wanting a brand-new rule, that's the signal to browse the [Utilities](/docs/base/utilities) reference first. There's usually a class for it.

## The families you'll use most [#the-families-youll-use-most]

| 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`                                    |
| Type          | `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`                                    |

The full catalog, organized by family, lives in the [Utilities](/docs/base/utilities) reference; this is the everyday subset.

## One scale, everywhere [#one-scale-everywhere]

Look closely at those class names and the same five rungs keep reappearing: `xs sm md lg xl`. That t-shirt scale isn't a spacing quirk; it's the measuring stick for the whole system. `lg` means "the large step" whether you're setting a gap, a corner, a shadow, a width, or a breakpoint:

| 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`             |

Repeating one scale instead of inventing a new set of values per property buys two things:

* **Predictability.** Learn the rungs once and you can guess a class you've never typed. If `gap-md` exists, so do `p-md`, `rounded-md`, and `shadow-md`; the steps line up across every family, so you compose from memory instead of searching the docs.
* **A slim system.** Every property draws from the same five steps rather than shipping its own bespoke list, so the utility layer stays small. The bonus is visual rhythm: sizes relate to each other because they come off one ladder, not from values picked in isolation.

The escape-hatch scales follow the same idea: a single, predictable ladder you reach into only when a named rung won't do, `--step-0_5`…`--step-96` for spacing and `50`…`950` for [color](/docs/core-concepts/colors). Same instinct, finer resolution.

## Touch one thing, leave the rest [#touch-one-thing-leave-the-rest]

Padding, margin, and radius utilities use a composition system: each class sets one axis or edge without disturbing the others. So you can stack a broad value and then carve out an exception.

```html
<!-- md padding all around, but flush on the left -->
<div class="p-md pl-0">…</div>

<!-- rounded card with a squared-off bottom edge -->
<div class="rounded-lg rounded-b-0">…</div>
```

## Utilities and components work together [#utilities-and-components-work-together]

Components carry their own look and expose variants through [`data-*` attributes](/docs/components/button); utilities handle placement, spacing, and one-off color. Combine them freely; the utility always has the final say:

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

## Beyond the base state [#beyond-the-base-state]

Utilities also cover interaction and layout that responds to space:

* **State variants:** `hover:bg-primary`, `hover:scale-105`, plus the automatic focus ring. See [Hover, focus, and other states](/docs/core-concepts/states).
* **Responsive variants:** `@md:grid-cols-3`, `@lg:flex-row`, driven by container style queries rather than viewport media queries. See [Responsive design](/docs/core-concepts/responsive-design).

When utilities genuinely can't express something, you extend the system without editing source. See [Adding custom styles](/docs/core-concepts/custom-styles).


# File anatomy (/docs/foundation/file-anatomy)



Every stylesheet in `zazz/styles/` follows the same anatomy. Learn it once and you can read any file, find the token you need to override, and extend a component without fighting the cascade.

## The base files [#the-base-files]

`zazz/styles/` splits in two. The `base/` folder holds the base system, and `ui/` holds one file per component. This section documents the base files; the [Components](/docs/components) section covers `ui/`.

| File                    | What it does                                                   | Docs                                            |
| ----------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
| `_layers.css`           | Declares the cascade-layer order, loaded first                 | [Layers](/docs/base/layers)                     |
| `_variables.css`        | Global design tokens (colors, type, spacing, and more)         | [Theme variables](/docs/base/variables)         |
| `_reset.css`            | Native-element baselines and re-skinned controls               | [Reset](/docs/base/reset)                       |
| `_typography.css`       | The `.prose` container and the `.text-*` / `.font-*` utilities | [Typography](/docs/base/typography)             |
| `_view-transitions.css` | Cross-document page transitions                                | [View transitions](/docs/base/view-transitions) |
| `_utilities.css`        | The atomic utility classes                                     | [Utilities](/docs/base/utilities)               |
| `_layout.css`           | The container and layout-grid utilities                        | [Layout](/docs/base/utilities/layout)           |

`main.css` `@import`s all of them, in cascade order, so a page links one stylesheet. The rest of this page is the shape each file shares.

## File anatomy [#file-anatomy]

A component file is written top-to-bottom in this order:

| # | Section                  | Layer                    | Required?                     |
| - | ------------------------ | ------------------------ | ----------------------------- |
| 1 | CSSDoc header            | —                        | always                        |
| 2 | Component token hooks    | `@layer variables`       | when the component has tokens |
| 3 | Native-element baselines | `@layer reset`           | only if it redraws native UI  |
| 4 | Component rules          | `@layer zazz.components` | the component itself          |
| 5 | Utility classes          | `@layer zazz.utilities`  | only if it ships utilities    |

```css
/**
 * _button.css — Button (.button)
 *
 * @layer      variables, components
 * @requires   layers.css, _variables.css, _reset.css
 * @uses       color-mix(), oklch(from …) — variant hover/active tints
 * @tokens     --button-* (@layer variables)
 */
@layer variables {
  :root {
    /* the component's override hooks */
  }
}

@layer zazz.components {
  .button {
    /* rules that consume the hooks above */
  }
}
```

## CSSDoc headers [#cssdoc-headers]

Every `.css` file opens with a JSDoc-style block comment. A summary line comes first, then block tags:

```css
/**
 * _fields.css — Shared form field family (Tier 3 owner for --field-*)
 *
 * @layer      variables, components
 * @requires   layers.css, _variables.css
 * @uses       :user-invalid — validation after commit (not while typing)
 * @uses       :has(:user-invalid) — label/hint/error crossfade
 * @uses       @starting-style + visibility allow-discrete — hint ↔ error swap
 * @tokens     --field-*, --field-group-* (Tier 3 owner; @layer variables)
 * @consumedby _input.css, _textarea.css, _select.css, _input-group.css,
 *             _password-group.css, _radio.css (.radio-group)
 */
```

### Tag reference [#tag-reference]

| Tag           | Required        | Meaning                                                       |
| ------------- | --------------- | ------------------------------------------------------------- |
| *(summary)*   | yes             | First line: `_file.css — Component (.selector)`               |
| `@layer`      | yes             | Cascade layers this file contributes to, in order             |
| `@requires`   | yes             | Files that must load before this one. `none` for `layers.css` |
| `@uses`       | —               | One modern CSS API/feature per line with support caveat       |
| `@tokens`     | when owned      | The token namespace this file exposes                         |
| `@consumedby` | when applicable | Files that depend on this one                                 |
| `@see`        | —               | External URL or cross-file reference                          |
| `@example`    | —               | Usage markup for non-obvious components                       |

## Token naming [#token-naming]

Component tokens follow a strict naming convention:

* `--{component}-{property}`: the default value, like `--button-background` or `--dialog-radius`
* `--{component}-{property}--{state}`: state variation with a **double-dash** before the state, like `--button-background--hover` or `--field-border--focus`

### Tiered tokens [#tiered-tokens]

Global tokens in `_variables.css` are organized in tiers:

| Tier                 | Example                                                    | Where               |
| -------------------- | ---------------------------------------------------------- | ------------------- |
| Brand/literal scales | `--primary-600`, `--neutral-100`                           | `_variables.css`    |
| Semantic roles       | `--background`, `--foreground`, `--primary`, `--muted`     | `_variables.css`    |
| Metrics & systems    | `--step-*`, `--radius-*`, `--gap-*`, `--font-size-*`       | `_variables.css`    |
| Component tokens     | `--button-background`, `--field-border`, `--dialog-radius` | each component file |

The full map of which token to reach for, and when, lives in [Theme variables](/docs/base/variables) and [Colors](/docs/core-concepts/colors).

### Local component tokens [#local-component-tokens]

Every component declares a namespace in its own `@layer variables` block, defaulting to a global token:

```css
@layer variables {
  :root {
    /* surface */
    --button-background: var(--card);
    --button-background--hover: var(--muted);
    /* metrics */
    --button-height: var(--step-8);
    --button-radius: var(--radius-md);
  }
}
```

Rules reference a token **once**. Variants swap the token value; they never restate the rule:

```css
@layer zazz.components {
  .button {
    background-color: var(--button-background);
  }

  .button[data-variant="primary"] {
    --button-background: var(--primary);
    --button-background--hover: oklch(from var(--primary) l c h / 0.9);
  }

  .button[data-size="sm"] {
    --button-height: var(--step-6);
    --button-radius: var(--radius-sm);
  }
}
```

## Selector conventions [#selector-conventions]

* **Blocks & elements**: `.component` and `.component__part` (`.input-group__addon`). No BEM modifier classes; use attributes instead.
* **Variants & sizes**: data attributes such as `[data-variant="primary"]`, `[data-size="sm"]`, `[data-side]`, `[data-align]`.
* **Zero specificity**: `:where()` wraps reset and utility selectors so they stay overridable.
* **Logical properties**: `inline-size`/`block-size`, `padding-inline`/`margin-block` for RTL support.
* **Focus**: rings render as box-shadows from Tailwind/shadcn-compatible tokens (`--ring`, `--ring-width`, `--ring-offset-width`, `--ring-offset-color`), composed with the component's own shadow; a same-geometry transparent outline (`--outline-*`) is kept for forced-colors modes. Never `outline: none` without a replacement.
* **State exclusion**: `:not(:disabled)` over order-dependent overrides.

## Comment styles [#comment-styles]

Three comment styles, each with a specific role:

**Section banners** separate major regions inside a layer:

```css
/* ===========================================================================
  BUTTON VARIANTS
  =========================================================================== */
```

**Token group labels** group related hooks inside `@layer variables`:

```css
:root {
  /* surface */
  --button-background: var(--card);
  --button-background--hover: var(--muted);
  /* metrics */
  --button-height: var(--step-8);
}
```

**Inline rule comments** explain intent: the *why*, not the *what*:

```css
/* thumb centered on the track via a calc'd negative margin so retuning
   either size keeps it aligned. */
```

## Dark mode [#dark-mode]

Dark mode is a token concern, not a per-file one. Components read role tokens (`--background`, `--foreground`, `--primary`…) that resolve through `light-dark()`, so a well-written file works in both modes without a single `.dark` override. See [Dark mode](/docs/core-concepts/dark-mode) for how the roles resolve and how to force a scheme.

## Allowed variations [#allowed-variations]

These deviate from the canonical shape on purpose, and each is documented in-file:

* **Split `@layer variables` blocks:** when a component has motion tokens and sizing tokens that read better separated.
* **Component in `@layer reset`:** when redrawing native UI (e.g. `_switch.css` redraws `input[role="switch"]`). See [`_reset.css`](/docs/base/reset).
* **`@supports`-gated enhancement:** when anchor positioning or other newer APIs need a documented fallback.
* **Attribute-hook components:** when styling depends on `[data-*]` attributes driven by JavaScript.


# layers.css (/docs/foundation/layers)



`_layers.css` is the smallest file in Zazz and the most important. It declares the order of the [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) every other stylesheet writes into, and that order, not selector specificity, decides which rule wins.

```css
@layer variables, reset, legacy, zazz, migrations;

@layer zazz {
  @layer components, utilities;
}
```

That's the entire file. Because it has to establish the order before any layer has content, it loads first; `main.css` `@import`s it ahead of everything else.

## Why layers instead of specificity [#why-layers-instead-of-specificity]

In ordinary CSS, the more specific selector wins. That's why you end up with `.card .button.is-primary` and the occasional `!important`: you're escalating specificity to override something.

Cascade layers change the rule: &#x2A;*a later layer beats an earlier layer regardless of specificity.** A single-class utility in `utilities` overrides a multi-selector component rule in `components`, every time, with no specificity tricks.

```html
<!-- .button sets its own background in @layer zazz.components.
     .bg-primary sets one in @layer zazz.utilities — and wins, cleanly. -->
<button class="button bg-primary">Save</button>
```

This is the mechanism behind Zazz's [golden rule](/docs/core-concepts/utility-classes): compose with utilities and they always have the final say, so you rarely write custom CSS to override a component.

## The layer order [#the-layer-order]

Five top-level layers, reading from lowest priority to highest:

| Layer        | Holds                                                                                                    | File                                                                                 |
| ------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `variables`  | Design tokens, the `:root` custom properties everything reads                                            | [`_variables.css`](/docs/base/variables) + each component's `@layer variables` block |
| `reset`      | Native-element baselines and re-skinned controls                                                         | [`_reset.css`](/docs/base/reset)                                                     |
| `legacy`     | Your existing (pre-Zazz) CSS, imported with `layer(legacy)`. Zazz overrides it wherever the two overlap. | your app's entry stylesheet                                                          |
| `zazz`       | Everything Zazz ships, as two sublayers: `components` then `utilities`                                   | `ui/_*.css` (components) and [`_utilities.css`](/docs/core-concepts/utility-classes) |
| `migrations` | Temporary shims for old markup during migration. On top, so it can override anything mid-rewrite.        | optional `migrations.css` you add                                                    |

Inside `zazz`, `utilities` comes after `components`, so a utility class always beats a component rule. The full priority order, lowest to highest, is `variables`, `reset`, `legacy`, `zazz.components`, `zazz.utilities`, `migrations`.

Two parts of the order are worth calling out. **`variables` and `reset` are their own top-level layers, below the rest of Zazz*&#x2A;, so component and utility rules always outrank both design-token defaults and native-element baselines. And &#x2A;*`legacy` sits above them but below `zazz`,** so the framework wins over your pre-Zazz CSS wherever they overlap, while `migrations` sits at the very top so a translation shim can win over even a utility class for old markup that hasn't been rewritten yet.

`@property` registrations live inline in [`_variables.css`](/docs/base/variables). Registration is layer-independent, but the tokens it types are consumed throughout.

## Unlayered styles beat everything [#unlayered-styles-beat-everything]

There's one level above all five layers: &#x2A;*unlayered CSS.** Any rule you write outside a `@layer` block overrides every layered rule, no matter how specific the layered selector is.

```css
/* No @layer wrapper — this beats Zazz's components, utilities, and migrations. */
.button {
  border-radius: 0;
}
```

That makes unlayered CSS the ultimate escape hatch and an easy footgun. Prefer overriding a token, or adding your rule to the right layer, so you stay inside the system. See [Adding custom styles](/docs/core-concepts/custom-styles). Reach for unlayered CSS only when you deliberately want to trump everything.

## Beating Zazz utilities [#beating-zazz-utilities]

When overriding a token isn't enough and an app rule has to win over a utility, declare your own layer **after** Zazz instead of dropping to unlayered CSS. The first `@layer` statement sets the order, so a name added at the end outranks everything Zazz ships:

```css
@layer variables, reset, legacy, zazz, migrations, app;

@layer app {
  /* beats Zazz utilities, without the footgun of unlayered CSS */
  .button {
    border-radius: 0;
  }
}
```

This keeps your overrides layered and predictable. Reach for it only when overriding a [token](/docs/base/variables) won't do.

## Bringing along legacy CSS [#bringing-along-legacy-css]

Migrating an existing project? Import your old stylesheet into the `legacy` layer. `main.css` leaves a commented slot for exactly this:

```css
/* main.css — uncomment and point at your stylesheet */
@import "./your-legacy.css" layer(legacy);
```

Because `legacy` sits below `zazz`, Zazz wins wherever the two overlap, and your untouched markup keeps rendering from its old rules until you convert it. For shims that have to win *over* Zazz during the rewrite — mapping an old class name onto Zazz tokens, say — add a `migrations.css` at the top of the stack (there's a commented `@import` slot for it at the bottom of `main.css`); the `migrations` layer outranks the utilities. For surgical, per-region isolation you can also reach for [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope) donut scoping. See [Migrating to Zazz](/docs/getting-started/migrating) for the full walkthrough.

## Browser support [#browser-support]

Cascade layers are [Baseline](https://web.dev/baseline) and widely available, supported since 2022 across Chrome, Edge, Firefox, and Safari. No fallback is required.


# _reset.css (/docs/foundation/reset)



`_reset.css` normalizes the browser's defaults and gives native controls a Zazz look. The whole file sits in `@layer reset`, the second-lowest [layer](/docs/base/layers), so every component and utility you write overrides it without effort.

## Zero specificity by design [#zero-specificity-by-design]

Almost every selector is wrapped in `:where()`, which contributes **zero specificity**. A reset rule for `:where(a)` is trivially overridden by your `.text-link` class or a component rule, so you never have to out-specify the reset.

```css
:where(a) {
  color: unset;
  text-decoration: inherit;
}
```

## What it sets up [#what-it-sets-up]

### Box model and layout [#box-model-and-layout]

A universal reset zeroes margins, padding, and borders and sets `box-sizing: border-box` on every element (and the relevant pseudo-elements):

```css
:where(*, ::before, ::after, ::backdrop, ::file-selector-button) {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
  border: 0 solid;
}
```

`<body>` becomes a flex column that fills the viewport (`100svh`), reserves the scrollbar gutter (`scrollbar-gutter: stable`, so page width doesn't jump between scrolling and non-scrolling pages), and opens a container context. `<main>` and the section landmarks each get their own container context too, which is what makes [container-query responsiveness](/docs/core-concepts/responsive-design) work with no setup.

### Theme-aware from the start [#theme-aware-from-the-start]

The reset reads role tokens, so the baseline itself is correct in light and dark mode:

```css
:where(html) {
  background-color: var(--background);
}
:where(body) {
  color: var(--foreground);
  background-color: var(--background);
}
```

You get [dark mode](/docs/core-concepts/dark-mode) at the reset level, with no `.dark` overrides needed for the page chrome.

### Typography [#typography]

Headings inherit their size and weight rather than carrying the browser's defaults, so the [`text-*` classes](/docs/core-concepts/utility-classes) drive type entirely:

```css
:where(h1, h2, h3, h4, h5, h6) {
  font-size: inherit;
  font-weight: inherit;
}
```

Lists drop their markers and indentation, tables collapse their borders, and `text-wrap: pretty` is on by default for nicer line breaks.

### Native controls, re-skinned with tokens [#native-controls-re-skinned-with-tokens]

Inline `<code>`, `<kbd>`, the search-field clear button, date/time pickers, and `<select>` internals are normalized and styled through their own token hooks (`--code-*`, `--kbd-*`, `--search-cancel-*`, `--placeholder-color`). Form controls inherit your font and color instead of the browser's. Text selection picks up a primary-tinted highlight via `::selection`.

### Focus, logical properties, and forced colors [#focus-logical-properties-and-forced-colors]

A global `:focus-visible` rule paints the [focus ring](/docs/core-concepts/states) on every focusable element. Sizing uses logical properties (`inline-size`, `block-size`, `padding-inline`) so layouts mirror correctly in RTL. The reset never does `outline: none` without a replacement.

## Where some resets live instead [#where-some-resets-live-instead]

To keep styling modular, a few controls are reset alongside their component rather than here: checkbox (`_checkbox.css`), range slider (`_slider.css`), switch (`_switch.css`), and the `<select>` picker panel (`_select.css`). They still write into `@layer reset`; they just live next to the component they redraw, an [allowed variation](/docs/base/file-anatomy#allowed-variations) on the standard file shape.

## Overriding the reset [#overriding-the-reset]

Because the reset is a *layer* and not a pile of high-specificity global rules, you override it the same way you override anything else in Zazz: a utility class, a component rule, or a token. There's no `!important`, and nothing to undo.


# Typography (/docs/foundation/typography)



`_typography.css` turns the type tokens in [`_variables.css`](/docs/base/variables) into something you can use. It does two jobs. It styles raw HTML inside a `.prose` container, and it exposes the `.text-*` and `.font-*` utility classes you reach for everywhere else.

The tokens themselves (font families, sizes, weights, line-heights, letter-spacing) live in `_variables.css`. This file consumes them.

## Font stacks [#font-stacks]

Zazz ships three raw stacks and two semantic aliases. The aliases are the ones you override:

```css
--font-family-body: var(--font-sans);
--font-family-heading: var(--font-sans);
```

Point `--font-family-heading` at `--font-serif` and every heading switches, with no other change. The raw `--font-sans`, `--font-serif`, and `--font-mono` stacks back the `.font-sans` / `.font-serif` / `.font-mono` utilities when you want a one-off.

Zazz defaults to Geist. See [Structuring your head tag](/docs/getting-started/head#loading-geist-default-typeface) for how to load it.

## The type scale [#the-type-scale]

Every size in the scale is a fluid `clamp()` value, so text grows with the viewport instead of jumping at breakpoints. The scale runs from `--font-size-eyebrow` up through the body sizes (`xs` to `xl`), the heading steps (`h6` to `h1`), and `--font-size-display` at the top.

Each step pairs a size token with matching weight, line-height, and letter-spacing tokens (`--font-weight-*`, `--leading-*`, `--tracking-*`). Larger steps get tighter tracking and shorter leading so headings read as dense and deliberate. Body sizes get looser tracking and taller leading for comfortable reading. The exact values live in `_variables.css`; the [variables reference](/docs/base/variables) lists the tiers.

## The `.text-*` and `.font-*` utilities [#the-text--and-font--utilities]

`.text-{step}` applies a full scale step at once. The class sets the font-size, line-height, letter-spacing, and weight together, so you get the whole treatment from one class:

```html
<span class="text-display">Big launch headline</span>
<p class="text-sm text-muted-foreground">Caption text</p>
```

`.font-*` covers weight on its own. You get the Tailwind-style numeric weights (`.font-thin` through `.font-black`) plus three semantic ones that track the tokens: `.font-body`, `.font-heading`, and `.font-strong`. For the full catalog, with text alignment, transform, wrapping, and line-clamp, see [Text and font](/docs/base/utilities/text-and-font). For color, see [Text color](/docs/base/utilities/text-color).

## The `.prose` container [#the-prose-container]

Most utilities expect you to class each element. `.prose` is the exception. Wrap a block of HTML you do not control (markdown output, a CMS body, an article) and the descendants pick up the type system on their own:

```html
<article class="prose">
  <h1>Page title</h1>
  <p>Body text gets proper measure and spacing.</p>
</article>
```

Inside `.prose`, headings take their matching `--font-size-h*`, `--leading-h*`, and `--tracking-h*`. Paragraphs, lists, definition lists, blockquotes, and figures all get sensible spacing and rhythm. Links use `--prose-link-color` (the primary role by default), and images round to `--prose-img-radius`.

A few `--prose-*` hooks let you retune it without editing the file:

| Token                       | Default               | Controls                          |
| --------------------------- | --------------------- | --------------------------------- |
| `--prose-link-color`        | `var(--primary)`      | Link color inside prose           |
| `--prose-img-radius`        | `var(--radius-md)`    | Corner radius on images and video |
| `--prose-img-border`        | `none`                | Border on images and video        |
| `--prose-figcaption-margin` | `var(--gap-xs) 0 0 0` | Spacing above a figure caption    |

Vertical rhythm between blocks runs off the `--paragraph-spacing-*` tokens, so you can tighten or loosen a whole document from one place.

## Where this sits [#where-this-sits]

`_typography.css` writes into four layers: `variables` (the `--prose-*` hooks), `reset` (the figcaption baseline it shares with `_reset.css`), `components` (`.prose`), and `utilities` (`.text-*`, `.font-*`). For why a single file spans that many layers, see [File anatomy](/docs/base/file-anatomy).


# Theme variables (/docs/foundation/variables)



Zazz has no hardcoded values. Spacing, color, type, radius, shadow: all of it is a CSS custom property on `:root`, and every component reads `var(--token)` rather than a literal. That single decision is what makes the system themeable: to restyle, you reassign tokens, you never rewrite rules.

```css
/* Re-skin every button on the site by changing one variable. */
:root {
  --primary: oklch(0.6 0.2 145);
}
```

Tokens resolve lazily, so an override on `:root` cascades to everything that references it. No rebuild, no find-and-replace.

## The token tiers [#the-token-tiers]

Tokens are organized from raw values up to component hooks. Reach for the most semantic tier that fits.

| Tier                       | What it is                   | Examples                                                                                         |
| -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| **Brand & literal scales** | Fixed color ramps            | `--primary-50`…`--primary-950`, `--neutral-*`, `--shade-*`, `--tint-*`                           |
| **Semantic roles**         | Theme-aware meaning          | `--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--destructive`              |
| **Metrics & systems**      | Spacing, type, shape, layout | `--gap-*`, `--step-*`, `--font-size-*`, `--radius-*`, `--shadow-*`, `--breakpoint-*`, `--ring-*` |
| **Component tokens**       | Per-component hooks          | `--button-background`, `--field-border`, `--dialog-radius`                                       |

Roles resolve through [`light-dark()`](/docs/core-concepts/dark-mode), so choosing a role instead of a scale step keeps both themes correct. Component tokens default to a global token, so they inherit your theme until you deliberately override one.

## Override at the narrowest scope that works [#override-at-the-narrowest-scope-that-works]

There are three places to set a token. Pick the most local one that solves the problem.

### Global: re-skin the whole system [#global-re-skin-the-whole-system]

Redefine a token on `:root` and every consumer updates:

```css
:root {
  --radius-md: 0; /* square every medium-radius corner */
  --primary: oklch(0.55 0.18 264);
}
```

### Component default: restyle one component everywhere [#component-default-restyle-one-component-everywhere]

Reassign a component token to change every instance of it:

```css
:root {
  --button-radius: var(--radius-full); /* all buttons go pill-shaped */
}
```

### Instance: one element only [#instance-one-element-only]

Set the token inline, or let a `data-*` variant do it:

```html
<button class="button" style="--button-background: var(--secondary)">One-off secondary</button>
```

## The token families [#the-token-families]

* **Spacing:** semantic `--gap-xs…xl` first; the `--step-*` scale (`--step-0_5` … `--step-96`, fluid) as the escape hatch. Both feed the `gap-*`, `p-*`, and `m-*` [utilities](/docs/core-concepts/utility-classes).
* **Type:** `text-*` classes bundle `--font-size-*`, `--font-weight-*`, `--leading-*`, and `--tracking-*`. Sizes are fluid `clamp()` values that scale with the viewport.
* **Color:** roles and scales, covered in depth on the [Colors](/docs/core-concepts/colors) page.
* **Radius:** `--radius-none…full`, scaled by `--radius-multiplier`. `md` for buttons/inputs, `lg` for cards/dialogs.
* **Shadow:** `--shadow-xs…xl`, soft multi-layer elevations. Surfaces are flat by default; add depth intentionally.
* **Layout:** `--breakpoint-xs…xl` for the responsive [breakpoints](/docs/core-concepts/responsive-design), `--gutters` for the page margin, and `--article-xs…xl` (in `ch`) for reading-column widths. The container [bands](/docs/base/utilities/layout#containers) are carved from the breakpoint tokens.
* **Motion:** `--spring-easing`, `--spring-duration`, and the `--default-transition*` bundle. Everything zeroes under `prefers-reduced-motion`.

## Where the real values live [#where-the-real-values-live]

The authoritative values live in `zazz/styles/base/_variables.css` (global tiers) and each component's own file (component tokens). Read those when you need an exact number. For how those files are organized, see [File anatomy](/docs/base/file-anatomy); for putting your overrides somewhere sensible, see [Adding custom styles](/docs/core-concepts/custom-styles).


# View transitions (/docs/foundation/view-transitions)



Zazz includes built-in view transitions that make multi-page sites feel like single-page apps. When a
visitor clicks a same-origin link, only the `<main>` content swaps. The header and footer stay in
place, and a view transition fades the old content into the new.

Two web platform features do the work, with no framework involved:

1. **The Navigation API** intercepts the link click and replaces `<main>` with a `fetch()`, so the
   browser never tears down and rebuilds the whole page.
2. **The View Transitions API** wraps that swap in an animation, so the change reads as deliberate
   instead of abrupt.

## What visitors get [#what-visitors-get]

* The header and footer hold still, with no flicker or repaint.
* Page content fades (and, if you ask for it, scales or slides) between states.
* Back and forward buttons work normally, with the same animation.
* Scroll position is restored.
* Focus moves to the new page's heading, so screen reader users hear that the page changed.

## Setup [#setup]

Include the stylesheet and the `main.js` module (it bundles `navigation.js`). The transition styles
live in `base/_view-transitions.css`, which `main.css` already `@import`s, so the single link covers
them:

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
<script type="module" src="./zazz/scripts/main.js"></script>
```

Mark your header and footer. `<main>` gets its view-transition name automatically — it needs no
attribute:

```html
<header data-transition-layer="global-header">…</header>
<main>…</main>
<footer data-transition-layer="global-footer">…</footer>
```

Every same-origin link now swaps `<main>` in place. The header and footer carry their own
view-transition names, so they persist across the swap without animating.

## Turning on the animation [#turning-on-the-animation]

The crossfade ships **off**: `--view-transition-duration` defaults to `0ms`, so content swaps
instantly until you give it a duration. Set one on `:root`, and optionally scale or slide the content
as it moves:

```css
:root {
  --view-transition-duration: 400ms;
  --view-transition-scale--old: 0.98;
}
```

| Token                              | Default                | Effect                                        |
| ---------------------------------- | ---------------------- | --------------------------------------------- |
| `--view-transition-duration`       | `0ms`                  | Length of the animation; set it to turn it on |
| `--view-transition-ease`           | `var(--bezier-easing)` | Easing curve                                  |
| `--view-transition-wait`           | `0ms`                  | Delay before the incoming content animates in |
| `--view-transition-origin`         | `center top`           | Transform origin for scale and translate      |
| `--view-transition-scale--old`     | `1`                    | Scale of the outgoing content                 |
| `--view-transition-scale--new`     | `1`                    | Scale of the incoming content                 |
| `--view-transition-translate--old` | `0, 0, 0`              | `translate3d` of the outgoing content         |
| `--view-transition-translate--new` | `0, 0, 0`              | `translate3d` of the incoming content         |
| `--view-transition-opacity--old`   | `0`                    | Opacity the outgoing content fades to         |
| `--view-transition-opacity--new`   | `0`                    | Opacity the incoming content fades from       |

## What gets transitioned [#what-gets-transitioned]

| View-transition name | Behavior                                                  |
| -------------------- | --------------------------------------------------------- |
| `main-content`       | Animated: the old content fades out, the new one fades in |
| `global-header`      | Persists without animating                                |
| `global-footer`      | Persists without animating                                |

Keeping the chrome named and static is what makes navigation feel stable while the body changes.

## Under the hood [#under-the-hood]

The `navigation.js` script drives the swap:

1. It listens for the browser's [`navigate`](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API)
   event.
2. For a qualifying navigation, it fetches the destination, pulls out its `<main>`, and replaces the
   current one. When the browser supports
   [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition),
   the swap is animated.
3. After the swap it updates `document.title`, restores scroll position, refreshes
   [Reveal](/docs/components/reveal) so new `[data-reveal]` elements animate, re-initializes any
   [carousels](/docs/components/carousel) in the new content, and moves focus to the new `<h1>`.

A navigation qualifies when it is same-origin, not a hash-only change, not a download, not a form
submission, and interceptable. Everything else (external links, `target="_blank"`, downloads, form
posts) behaves normally.

## Graceful degradation [#graceful-degradation]

Page transitions are an enhancement, and every page still works as a standalone document.

* **No Navigation API** (Firefox, as of 2025): links do standard full-page loads.
* **No View Transitions:** the content still swaps instantly, just without the animation.
* **Fetch failure:** the script falls back to `location.assign()` for a normal navigation.
* **Missing `<main>`** on either page: it falls back to a full page load.
* **JavaScript off:** links behave normally.

Motion respects `prefers-reduced-motion`. When a visitor prefers reduced motion, content swaps
instantly with no animation.


# Structuring your head tag (/docs/getting-started/head)



A Zazz page is plain HTML. No app shell, no build output. What you put in `<head>` and how you mark up landmarks affects how styles and scripts load.

## The minimum head [#the-minimum-head]

This is all most pages need:

```html
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />

  <!-- Paint the right theme (background, form controls, scrollbars) before CSS loads -->
  <meta name="color-scheme" content="light dark" />

  <!-- One stylesheet: @imports every layer in cascade order -->
  <link rel="stylesheet" href="./zazz/styles/main.css" />

  <title>Page title</title>
</head>
```

### Declare your color scheme first [#declare-your-color-scheme-first]

The `<meta name="color-scheme" content="light dark">` tag tells the browser you support both themes *before it starts rendering*. The canvas background, scrollbars, and form controls paint in the right mode right away. No white flash while CSS loads.

<Callout type="warn">
  Keep the meta tag and the CSS `color-scheme` on `:root` in agreement: both declare `light dark`.
  The meta tag handles the pre-render paint; the CSS property drives
  [`light-dark()`](/docs/core-concepts/dark-mode) once styles load.
</Callout>

`color-scheme` is [Baseline](https://web.dev/baseline) and widely available (since 2022). Older browsers ignore the tag and render light mode.

### Link one stylesheet [#link-one-stylesheet]

Point a single `<link>` at `main.css`. It `@import`s every Zazz file in the correct [cascade order](/docs/base/layers). One link, every token, component, and utility:

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
```

<Callout>
  A separate `<link rel="preload" as="style">` for `main.css` is **not** needed. A same-document stylesheet link is already the highest-priority, render-blocking fetch. `preload` is for *late-discovered* resources (web fonts, CSS pulled in by JS), not the stylesheet you link in `<head>`.
</Callout>

For production, keep the single link and turn on **brotli or gzip** at your host. CSS this regular compresses to roughly 10–15% of its raw size. Better than splitting files by hand, and nothing to keep in sync.

### Add your overrides after Zazz [#add-your-overrides-after-zazz]

Your own stylesheet loads *after* `main.css` so it can reassign any token. See [Adding custom styles](/docs/core-concepts/custom-styles) for what to put in it.

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
<link rel="stylesheet" href="./your-styles.css" />
```

### Loading Geist (default typeface) [#loading-geist-default-typeface]

Zazz defaults to **Geist** through `--font-family-body` and `--font-family-heading`. Load it from Google Fonts with `preconnect` so the CSS request starts early:

```html
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Geist+Mono:ital,wght@0,100..900;1,100..900&family=Geist:ital,wght@0,100..900;1,100..900&display=swap"
  rel="stylesheet"
/>
```

Self-hosting instead? `preload` the `.woff2` file. That's when `preload` actually helps for fonts.

### Inline theme script [#inline-theme-script]

If you persist a user's theme choice (see [Dark mode](/docs/core-concepts/dark-mode)), add a small inline script in `<head>`. No `defer`. It runs while the parser is still in `<head>`, toggles `.dark` on `<html>`, and beats the first paint.

```html
<script>
  /**
   * Synchronizes the preview theme with the user's preference.
   * - Reads "theme" from localStorage.
   * - Falls back to "prefers-color-scheme: dark" media query if unset.
   * - Applies the "dark" class to document.documentElement if theme is "dark".
   * - Saves the resolved theme to localStorage for consistency.
   * This block runs synchronously before dom load to prevent theme flash on load.
   */
  (() => {
    try {
      const storedTheme = localStorage.getItem("theme");
      const prefersDark = matchMedia("(prefers-color-scheme: dark)").matches;
      const theme = storedTheme ?? (prefersDark ? "dark" : "light");
      document.documentElement.classList.toggle("dark", theme === "dark");
    } catch {
      document.documentElement.classList.toggle(
        "dark",
        matchMedia("(prefers-color-scheme: dark)").matches,
      );
    }
  })();
</script>
```

Put this block last in `<head>`, after stylesheets and deferred `<script src>` tags.

### Optional head hints [#optional-head-hints]

Preload the script bundle so the browser fetches it alongside CSS. `main.js` is an ES module, so use `modulepreload` — it primes the module **and** its imports:

```html
<link rel="modulepreload" href="./zazz/scripts/main.js" />
```

Prefetch pages visitors are likely to open next. Low priority, won't block render:

```html
<link rel="prefetch" href="./products.html" />
```

## The full document skeleton [#the-full-document-skeleton]

Put styles, scripts, and the theme block in `<head>`. Deferred scripts keep their order. Wrap page content in three landmarks:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="color-scheme" content="light dark" />
    <title>Page title</title>

    <!-- Google Fonts -->
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link
      href="https://fonts.googleapis.com/css2?family=Geist+Mono:ital,wght@0,100..900;1,100..900&family=Geist:ital,wght@0,100..900;1,100..900&display=swap"
      rel="stylesheet"
    />

    <link rel="stylesheet" href="./zazz/styles/main.css" />
    <link rel="stylesheet" href="./your-styles.css" />

    <link rel="modulepreload" href="./zazz/scripts/main.js" />
    <link rel="prefetch" href="./products.html" />

    <!-- CDN scripts: demos only. Pin SRI hashes if you use them. -->
    <script
      src="https://cdn.jsdelivr.net/npm/@oddbird/popover-polyfill@latest"
      integrity="sha384-Gl/j23IcIIiDfqcDI5gpHCxd5EuslCYvs07HAw3KHGx5UcbxizoF/deDnkeEcFXW"
      crossorigin="anonymous"
      defer
    ></script>
    <script
      type="module"
      src="https://esm.sh/invokers/compatible"
      integrity="sha384-fzLqSi8WSEqp/tW3neqEgzl53fvLw4u32RAvoNQSSSAfKGsOrfA2B49xhrObWFnr"
      crossorigin="anonymous"
      defer
    ></script>
    <script
      src="https://unpkg.com/embla-carousel/embla-carousel.umd.js"
      integrity="sha384-XGqLM9+dJ+PFOMZn6IuZgRRIoxcAT5fx4eIZCx7K3O2Dj5RA7EOlJ3yOS8Jd+kiY"
      crossorigin="anonymous"
      defer
    ></script>
    <script
      src="https://unpkg.com/embla-carousel-autoplay/embla-carousel-autoplay.umd.js"
      integrity="sha384-rs7pDLCh+QtEjJg2VChAoKZHaaz7apuon6rM57E3FdzC83xaJH4n9mQZn4E2s3f4"
      crossorigin="anonymous"
      defer
    ></script>
    <script
      src="https://unpkg.com/embla-carousel-auto-scroll/embla-carousel-auto-scroll.umd.js"
      integrity="sha384-5x3y2MLuLA5c1LQceYM+lo59GGkQmLzQGzbuHhDUDbnOJkFeTl5jUSdBy3JehMcM"
      crossorigin="anonymous"
      defer
    ></script>
    <script
      src="https://unpkg.com/embla-carousel-class-names/embla-carousel-class-names.umd.js"
      integrity="sha384-nZNIZhV6WSQVCeWMj8JFfOgQZyzPoGSTh0eohtAOu5aluevIpIblZcupMSdl/EEH"
      crossorigin="anonymous"
      defer
    ></script>
    <script
      src="https://unpkg.com/embla-carousel-ssr/embla-carousel-ssr.umd.js"
      integrity="sha384-apu0WDHR0c+4Z5qNk7egPNoCxXkYq80e+Qh6xJ6f67S53mSyYdKE6tIeXxvKJ6x9"
      crossorigin="anonymous"
      defer
    ></script>

    <!-- Zazz scripts: one ES module bundles every component script -->
    <script type="module" src="./zazz/scripts/main.js"></script>

    <script>
      (() => {
        const storedTheme = localStorage.getItem("theme");
        const prefersDark = matchMedia("(prefers-color-scheme: dark)").matches;
        const theme = storedTheme ?? (prefersDark ? "dark" : "light");
        document.documentElement.classList.toggle("dark", theme === "dark");
      })();
    </script>
  </head>
  <body>
    <header data-transition-layer="global-header">
      <!-- Navigation -->
    </header>

    <main>
      <!-- Page content -->
    </main>

    <footer data-transition-layer="global-footer">
      <!-- Footer -->
    </footer>
  </body>
</html>
```

<Callout type="warn">
  CDN scripts are fine for demos. For production, vendor locally or pin exact versions with
  [SRI](https://srihash.org/) `integrity` hashes. Update the hashes when you bump versions.
</Callout>

The reset gives `<body>`, `<main>`, and section landmarks their own layout and container context. See [`_reset.css`](/docs/base/reset).

## Stylesheet load order [#stylesheet-load-order]

`main.css` handles this for you. If you link files individually, keep this order:

1. `base/_layers.css`: declares `@layer variables, reset, legacy, zazz, migrations;` ([why this comes first](/docs/base/layers))
2. `base/_variables.css`: global design tokens (and the inline `@property` registrations)
3. `base/_reset.css`: element baselines
4. `base/_typography.css`: type system and `.prose`
5. `base/_view-transitions.css`: cross-document page transitions
6. `ui/_*.css` component files, in any order
7. `base/_utilities.css`, then `base/_layout.css`: atomic overrides and the container/layout grid (load last)

With HTTP/2–3 multiplexing and server compression, the single `main.css` link is usually enough. No manual ordering to maintain.

## Script load order [#script-load-order]

Every Zazz behavior ships in one ES module, `main.js`, which `import`s the rest in the right internal order. You load it once. A module is deferred automatically, so it runs after the document is parsed but before `DOMContentLoaded` — no `defer` attribute needed.

What still has to come *before* the module, in document order:

1. **Polyfills** (optional): Popover API (`@oddbird/popover-polyfill`), Invokers/tooltip (`invokers/compatible`)
2. **Embla CDN bundles** (only if a page has carousels): core UMD build, then plugins (`autoplay`, `auto-scroll`, `class-names`, `ssr`). `embla.js` reads these as globals.
3. **`main.js`** (`<script type="module">`): utils, reveal, embla, carousel, lightbox, password, tabs, and navigation, in dependency order.
4. **Inline theme script** (last, no `type="module"`): applies `.dark` before first paint.

Classic `defer` scripts and module scripts share one execution queue and run in document order, so placing the Embla CDN `<script defer>` tags ahead of the module guarantees its globals exist first.

Everything auto-initializes once the DOM is parsed. No manual init on a normal page. See [Scripting](/docs/scripts/scripting) for how these files work.

## View transition layers [#view-transition-layers]

For page transitions (cross-document or SPA-style via `navigation.js`), mark the header and footer with `data-transition-layer`. `<main>` gets its view-transition name automatically and needs no attribute:

```html
<header data-transition-layer="global-header">...</header>
<main>...</main>
<footer data-transition-layer="global-footer">...</footer>
```

These map to `view-transition-name` values in `base/_view-transitions.css`. The `<main>` content animates on navigation; header and footer stay put.


# Installation (/docs/getting-started/installation)



Zazz runs on plain CSS and native HTML APIs. No bundler and no framework required. Copy the files, link the stylesheet, write markup.

## Download [#download]

Grab what you need from the repository. For most projects, copy both folders:

* [`zazz/styles/`](https://github.com/dereknelsen/zazz-docs/tree/main/zazz/styles)
* [`zazz/scripts/`](https://github.com/dereknelsen/zazz-docs/tree/main/zazz/scripts)

`styles` is always required. `scripts` is needed for JS-driven components and behaviors.

### Fast copy with degit [#fast-copy-with-degit]

Use degit to copy only the directories you need, without cloning the whole repo.

**With npm:**

```bash
npm install -g degit
npx degit dereknelsen/zazz-docs/zazz/styles ./src/zazz/styles
npx degit dereknelsen/zazz-docs/zazz/scripts ./src/zazz/scripts
```

**With pnpm:**

```bash
pnpm add -g degit
pnpm dlx degit dereknelsen/zazz-docs/zazz/styles ./src/zazz/styles
pnpm dlx degit dereknelsen/zazz-docs/zazz/scripts ./src/zazz/scripts
```

Need one file only?

```bash
pnpm dlx degit dereknelsen/zazz-docs/zazz/styles/ui/_dialog.css ./src/zazz/styles/ui/_dialog.css
```

<Callout type="warn">
  If you install individual style files, update your local `main.css` imports to include them in the
  right order.
</Callout>

## Link the stylesheet [#link-the-stylesheet]

Add a single `<link>` to your HTML. Point it at `main.css`; it imports everything in the correct cascade order:

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
```

That's it. Every component, token, and utility is now available.

### Production: keep `main.css`, compress on the server [#production-keep-maincss-compress-on-the-server]

Stick with the single `main.css` link. CSS this regular compresses extremely well. Turn on **brotli or gzip** at your host and the whole bundle ships at roughly 10–15% of its raw size, with zero source changes. That's a far bigger win than hand-splitting files, and there's nothing to keep in sync.

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
```

<Callout>
  A separate `<link rel="preload" as="style">` for `main.css` is **not** needed. A same-document stylesheet link is already the highest-priority, render-blocking fetch. `preload` is for *late-discovered* resources (web fonts, CSS pulled in by JS), not the stylesheet you link in `<head>`.
</Callout>

You *can* instead link each `_*.css` file individually (with `preload` hints) to avoid `main.css`'s `@import` chain, but with HTTP/2-3 multiplexing and server compression it's rarely worth the upkeep. If you do, keep the cascade order: `base/_layers.css` first, then `base/_variables.css`, `base/_reset.css`, `base/_typography.css`, `base/_view-transitions.css`; the `ui/_*.css` component files in any order; then `base/_utilities.css` and `base/_layout.css` last.

## Verify it works [#verify-it-works]

Create an HTML file and add a button:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- Paint the right theme before CSS loads -->
    <meta name="color-scheme" content="light dark" />
    <link rel="stylesheet" href="./zazz/styles/main.css" />
    <title>Zazz Test</title>
  </head>
  <body>
    <button class="button" data-variant="primary">It works</button>
  </body>
</html>
```

Open it in a browser. If you see a styled button, you're ready.

## Project structure [#project-structure]

A typical project looks like this:

```
my-project/
├── index.html
├── zazz/
│   ├── styles/
│   │   ├── main.css                ← entry point (@imports everything)
│   │   ├── base/
│   │   │   ├── _layers.css         ← cascade order (loads first)
│   │   │   ├── _variables.css      ← global design tokens
│   │   │   ├── _reset.css          ← element baselines
│   │   │   ├── _typography.css     ← type system + .prose
│   │   │   ├── _view-transitions.css ← cross-document page transitions
│   │   │   ├── _utilities.css      ← atomic helper classes
│   │   │   └── _layout.css         ← container + layout grid
│   │   └── ui/
│   │       ├── _button.css         ← component styles
│   │       ├── _dialog.css
│   │       └── ...
│   └── scripts/
│       ├── main.js                 ← entry module (imports all scripts)
│       ├── navigation.js           ← page transitions and link handling
│       ├── reveal.js               ← reveal effects
│       └── ...
└── your-styles.css                 ← your overrides (optional)
```

## Customizing [#customizing]

Override any token on `:root` in your own stylesheet. Load it after `main.css`:

```html
<link rel="stylesheet" href="./zazz/styles/main.css" />
<link rel="stylesheet" href="./your-styles.css" />
```

```css
/* your-styles.css */
:root {
  --primary: oklch(0.6 0.2 145);
  --radius-md: 0;
}
```

Every component that references `--primary` or `--radius-md` updates automatically.

## Using with a bundler [#using-with-a-bundler]

If you're using Vite, webpack, or esbuild, import `main.css` directly:

```js
import "./zazz/styles/main.css";
```

The `@import` statements resolve at build time. No additional configuration needed.

## Next steps [#next-steps]

* Read [Overview](/docs/getting-started/overview) to understand how the layer system works.
* Browse [Components](/docs/components) to see what's available.


# LLMs (/docs/getting-started/llms)



Zazz ships with structured context files that AI coding assistants can consume directly. These skills teach LLMs how the token system works, what modern CSS APIs are in use, and how to write components that follow Zazz conventions.

## Available skills [#available-skills]

The `zazz-pass` skill lives in the repository at [`.claude/skills/zazz-pass/`](https://github.com/dereknelsen/zazz-docs/tree/main/.claude/skills/zazz-pass) and contains:

| File                       | What it provides                                    |
| -------------------------- | --------------------------------------------------- |
| `SKILL.md`                 | Entry point — when to trigger, how the system works |
| `DESIGN.md`                | Design system principles and token architecture     |
| `PATTERNS.md`              | Component authoring patterns and conventions        |
| `references/tokens.md`     | Full token reference (scales, roles, metrics)       |
| `references/components.md` | Component markup and variant API                    |
| `references/apis.md`       | Modern CSS APIs used across the system              |

## How to use with AI assistants [#how-to-use-with-ai-assistants]

### Claude (via `.claude/skills/`) [#claude-via-claudeskills]

The skill is already installed. Any Claude-based tool that reads `.claude/skills/` will automatically pick up Zazz conventions when you ask it to build or modify UI.

### Other AI assistants [#other-ai-assistants]

Point your assistant at the skill files in the repository. The key files to feed as context:

1. **`SKILL.md`** gives the assistant the full picture of when and how to apply Zazz
2. **`references/tokens.md`** lists token names and values it can use directly in generated code
3. **`references/components.md`** shows correct markup patterns for every component

### LLM-friendly docs [#llm-friendly-docs]

This documentation site also exposes full-text endpoints for LLM consumption:

* [`/llms.txt`](/llms.txt): condensed site overview
* [`/llms-full.txt`](/llms-full.txt): complete documentation in plain text

## What the skill teaches [#what-the-skill-teaches]

The `zazz-pass` skill instructs AI assistants to:

* Use the four-layer cascade (`variables`, `reset`, `components`, `utilities`)
* Reach for semantic tokens (`--primary`, `--gap-md`) over hardcoded values
* Apply variants via `data-*` attributes, not modifier classes
* Use `light-dark()` for theme-aware colors
* Follow component token naming (`--{component}-{property}--{state}`)
* Write new components that match existing file anatomy

## GitHub [#github]

Full source and skill files:

**[github.com/dereknelsen/zazz-docs](https://github.com/dereknelsen/zazz-docs)**


# Migrating to Zazz (/docs/getting-started/migrating)



You don't have to rewrite your CSS to start using Zazz. Because Zazz lives entirely in cascade
layers and styles at zero specificity, you can drop it into an existing project and let it take
over screen by screen. No big-bang rewrite, no `!important` war with your old styles.

## The core problem: unlayered styles beat layered ones [#the-core-problem-unlayered-styles-beat-layered-ones]

Zazz puts every rule inside a layer (`variables`, `reset`, `legacy`, `zazz.*`, or `migrations`). The
cascade has a rule that surprises people: &#x2A;*any unlayered author rule beats every layered rule,
regardless of specificity.** Your existing CSS is almost certainly unlayered, so on its own it would
override Zazz's components and utilities everywhere the two overlap.

The fix is to give your old CSS a layer of its own, ordered *below* Zazz. From there, everything
else follows.

## Step 1: Layer your old CSS below Zazz [#step-1-layer-your-old-css-below-zazz]

In the entry stylesheet you load before Zazz, declare the full layer order up front, then import
your legacy CSS into the `legacy` layer:

```css
/* entry.css - loaded before Zazz */
@layer variables, reset, legacy, zazz, migrations;

@import "./legacy/app.css" layer(legacy); /* old CSS → below Zazz */
@import "./zazz/styles/main.css"; /* re-declares the same order */
```

The **first** `@layer` statement wins for ordering, so declaring it here (before `main.css`
re-declares the same order) locks `legacy` underneath everything Zazz ships. Now where both
systems style the same thing, Zazz wins; everywhere Zazz is silent, your old CSS still applies. On
day one, nothing visually breaks.

`main.css` already leaves a commented slot for this import, so if you load Zazz directly you can
uncomment it there instead:

```css
/* main.css */
@import "./your-legacy.css" layer(legacy);
```

<Callout>
  The `migrations` layer sits at the very top of the stack, above `zazz.utilities`. That ordering
  matters in Step 4: a translated class like `.btn-primary` outranks everything in Zazz, so old
  markup renders correctly even against utility classes. Once you rewrite the markup and delete the
  shim, native Zazz classes and utilities take over as usual.
</Callout>

## Step 2: Isolate regions with `@scope` [#step-2-isolate-regions-with-scope]

`@scope` applies a block of rules to a region and, with a lower boundary, stops them at a subtree:
"**donut scoping**." The donut hole is the part you leave alone:

```css
@scope (.app) to (.legacy-widget) {
  /* matches inside .app, but NOT inside any .legacy-widget */
}
```

This is how you wall off converted and unconverted sections from each other. Combine it with
`all: revert-layer` to strip one system's styles from a subtree without touching the others — for
example, drop a `revert-layer` reset inside the `legacy` layer to remove your old styles from a
converted section while Zazz keeps applying on top. Unlike a `.app :not(.legacy-widget *)` selector,
`@scope` accounts for hierarchical proximity, so it still behaves correctly when regions nest inside
each other.

## Step 3: Blank-slate a region with `all: revert` [#step-3-blank-slate-a-region-with-all-revert]

Once Zazz is on the page, its `reset` layer restyles native elements globally. That's what you
want for new UI, but it also reaches into old markup. To hand a region fully to Zazz, reset it to
the browser's defaults first with `all: revert`, which drops **every** property back to the
user-agent value, erasing both your legacy styles and Zazz's on that element:

```css
@scope (.takeover) to (.legacy-widget) {
  :scope,
  :scope * {
    all: revert; /* ignore all author CSS; start from UA defaults */
  }
}
```

Bounding the reset inside `@scope` is what lets you avoid a global `* { all: revert }`, which the
cascade can't cleanly override and which web components and lower layers can't escape.

<Callout>
  `all: revert` is the sledgehammer. It removes Zazz too. Its surgical sibling, `all: revert-layer`,
  drops only to the **previous cascade layer**. Put a `revert-layer` reset inside the `legacy` layer
  and it strips your old styles while Zazz's higher layers keep applying on top. Reach for
  `revert-layer` when you mean "remove my old styles but keep Zazz," and `revert` when you want a
  true blank slate (for example, to quarantine a third-party widget from both systems).
</Callout>

## Step 4: Translate old class names in the `migrations` layer [#step-4-translate-old-class-names-in-the-migrations-layer]

The last piece bridges markup you haven't rewritten yet. A shim in the `migrations` layer re-points
your old class names at Zazz's component tokens, so existing HTML renders as Zazz **before** you
touch it. These rules live in a `migrations.css` you create and load (import it at the commented
slot at the bottom of `main.css`) inside `@layer migrations`. Because Zazz components are
token-driven, the shim is small and stays themeable, so light/dark and brand changes flow through
for free.

Here `.btn-primary` is translated to the Zazz button semantic tokens. Old modifier classes map to
Zazz variants the same way `data-variant` does, by reassigning the component tokens, not restating
the component rule:

```css
/* migrations.css — a temporary bridge. Delete each rule as you rewrite the markup. */

@layer migrations {
  @scope (.app) to (.legacy-widget) {
    .btn-primary {
      --button-background: var(--primary);
      --button-foreground: var(--primary-foreground);
    }
  }
}
```

The same move works for any component: a legacy `.card` can adopt card tokens, a `.tag` can adopt
badge tokens, and so on. Each translated rule is a stepping stone. Once a screen's markup is
updated to native Zazz classes and attributes, delete its shim. When the `migrations` layer is
empty, the migration is done.

## A migration path [#a-migration-path]

1. **Layer.** Add the `@layer` order and import your old CSS into `legacy` (Step 1). Ship it.
   Nothing should change yet.
2. **Isolate.** Use `@scope` donut scoping (with `revert-layer` where needed) to wall off converted
   and unconverted sections (Step 2).
3. **Reset where needed.** Blank-slate stubborn regions with `all: revert` / `revert-layer` so
   legacy styling stops leaking in (Step 3).
4. **Translate, then replace.** Add `migrations`-layer shims to make old markup look right now
   (Step 4), then rewrite the HTML to real Zazz classes and delete the shim, screen by screen.

## Browser support [#browser-support]

<Callout type="warn">
  `@layer`, `all: revert`, and `revert-layer` are **Baseline widely available**, safe everywhere
  with no fallback. `@scope` is &#x2A;*Baseline 2024 (newly available)**: Chrome/Edge 118, Safari 17.4,
  Firefox 128. If you must support older browsers, skip the `@scope` steps and lean on `@layer`
  plus `migrations`-layer shims instead.
</Callout>

## Next steps [#next-steps]

* Set up the entry stylesheet in [Installation](/docs/getting-started/installation).
* Read [Overview](/docs/getting-started/overview) for the full layer cascade model that makes
  all of this predictable.


# Overview (/docs/getting-started/overview)



Zazz replaces specificity-based CSS architecture with a layered cascade. Once you see how the layers, tokens, and conventions fit together, you can customize and extend the system without fighting it. This page is the map; each section links to the page that covers it in full.

## The cascade layers [#the-cascade-layers]

Every stylesheet in Zazz slots into a cascade layer, declared once, in order, in `_layers.css`:

```css
@layer variables, reset, legacy, zazz, migrations;

@layer zazz {
  @layer components, utilities;
}
```

Later layers override earlier ones regardless of selector specificity, so you never need `!important`, BEM modifiers, or naming hacks:

| Layer             | Purpose                                              | Example                                        |
| ----------------- | ---------------------------------------------------- | ---------------------------------------------- |
| `variables`       | Token declarations only (lowest)                     | `:root { --button-radius: var(--radius-md); }` |
| `reset`           | Native element baselines                             | `html`, `body`, `input`, `select` defaults     |
| `legacy`          | Your pre-Zazz CSS during a migration                 | `@import "old.css" layer(legacy)`              |
| `zazz.components` | Component rules                                      | `.button`, `.dialog`, `.field`                 |
| `zazz.utilities`  | Atomic override classes                              | `.text-primary`, `.gap-md`, `.rounded-full`    |
| `migrations`      | Class-translation shims during a migration (highest) | `.btn-primary { --button-background: … }`      |

A plain `.button` rule in `components` is overridden by a utility in `utilities`, with no `!important`. The outer `legacy` and `migrations` layers bracket the stack for [incremental adoption](/docs/getting-started/migrating); day to day you work in the two Zazz sublayers. For the full model, see [`_layers.css`](/docs/base/layers).

## base files [#base-files]

Four files form the foundation, and every other file depends on them:

* [`_layers.css`](/docs/base/layers) declares the cascade order and must load first.
* [`_variables.css`](/docs/core-concepts/theme-variables) holds every global token: brand scales, semantic roles, and the metric systems for spacing, type, radius, and shadow.
* [`_reset.css`](/docs/base/reset) sets native-element defaults, all wrapped in `:where()` for zero specificity so component rules always win.
* [`_utilities.css`](/docs/base/utilities) is the atomic override layer, also zero-specificity.

## Tokens and theming [#tokens-and-theming]

Nothing in Zazz is hardcoded. Components read `var(--token)`, so you restyle by reassigning variables rather than rewriting rules. Tokens run from raw scales up to per-component hooks, and you override at the narrowest scope that fits:

```css
:root {
  --primary: oklch(0.6 0.2 145); /* global: re-skin the brand */
  --button-radius: var(--radius-full); /* component: all buttons go pill-shaped */
}
```

```html
<button class="button" style="--button-background: var(--secondary)">Instance: this button only</button>
```

The token tiers and the three override scopes are covered in full on [Theme variables](/docs/core-concepts/theme-variables).

## Typography [#typography]

Zazz ships a fluid type system: every size is a `clamp()` that scales smoothly from phone to desktop with no breakpoints. A single `text-*` class bundles the right size, weight, line-height, and letter-spacing for its step, and `.prose` applies the whole rhythm to long-form content automatically.

```html
<span class="text-display">Big launch headline</span>
<p class="text-sm text-muted-foreground">Caption text</p>
```

See [Text & font](/docs/base/utilities/text-and-font) for the type utilities and [Prose](/docs/components/prose) for long-form content.

## Variants and sizes [#variants-and-sizes]

Components expose their styles through `data-*` attributes instead of BEM modifier classes. The default variant is always the absence of the attribute:

```html
<button class="button" data-variant="primary" data-size="sm">Save</button>
```

Each component documents its own `data-variant` and `data-size` values; see [Button](/docs/components/button) for a worked example.

## Dark mode [#dark-mode]

Dark mode is on from the first line. `:root` sets `color-scheme: light dark`, and every role token resolves through `light-dark()`, so a role-based design is correct in both themes with no parallel styles. See [Dark mode](/docs/core-concepts/dark-mode) for the system toggle, the `.dark` override, and inverted surfaces.

## Next steps [#next-steps]

* Read [Core concepts](/docs/core-concepts/utility-classes) for utilities, states, responsive design, and theming.
* Read [base](/docs/base/file-anatomy) for file anatomy, token naming, and selector rules.
* Browse [Components](/docs/components), including [scroll reveals](/docs/components/reveal) and [carousels](/docs/components/carousel).


# Scripting (/docs/scripts/scripting)



Scripts in `zazz/scripts/` are served directly at `/zazz/scripts/*.js`, with no bundler or transpiler. They are native ES modules and run as-is in modern browsers. A single entry module, `main.js`, `import`s every component script, so a page loads behavior with one `<script type="module" src="./zazz/scripts/main.js">` tag (see [Structuring your head tag](/docs/getting-started/head#script-load-order)).

## Philosophy [#philosophy]

* **Vanilla JS only.** No framework, no npm runtime deps, no build step — just native ES modules. Cross-script dependencies use `import`; external libraries Zazz doesn't ship (the Embla CDN UMD bundles) are still read as globals loaded by prior `<script>` tags.
* **HTML-first.** Markup and data attributes drive behavior. Authors configure components in HTML; scripts discover and enhance the DOM.
* **Progressive enhancement.** Feature-detect APIs before use. When unsupported, degrade gracefully.
* **Minimal surface area.** Export a small public API. Keep helpers private.

## File structure [#file-structure]

Every script follows this layout:

```js
"use strict";

/**
 * @fileoverview Module title.
 * @description What this module does.
 */

import { Dependency } from "./dependency.js"; // only when this module needs another

// Implementation

// Auto-initialize when DOM is ready (only in browser environment)
if (typeof window !== "undefined" && typeof document !== "undefined") {
  // ...
}

// Attach to window for the documented public API, then export for module consumers
// (the main.js entry and any sibling script that imports this one).
if (typeof window !== "undefined") {
  window.MyExport = MyExport;
}

export { MyExport };
```

## Module exports [#module-exports]

Each script attaches its public API to `window` (the documented surface) **and** provides a matching named `export` that the `main.js` bundle and sibling modules `import`:

| File            | Global             | Export shape                                     |
| --------------- | ------------------ | ------------------------------------------------ |
| `utils.js`      | `window.Utils`     | `{ parseValue, parseDataAttributes }`            |
| `reveal.js`     | `window.Reveal`    | `Reveal` class                                   |
| `embla.js`      | `window.EmblaInit` | `{ init, initRoot, addDotBtnsAndClickHandlers }` |
| `navigation.js` | *(none)*           | Side-effect only; no export                      |

The web-component scripts (`carousel.js`, `lightbox.js`, `password.js`, `tabs.js`) export their element class and register the custom element as a side effect.

## Auto-initialization [#auto-initialization]

Scripts that enhance the page on load use a guarded auto-init block:

```js
if (typeof window !== "undefined" && typeof document !== "undefined") {
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", init);
  } else {
    init();
  }
}
```

Initialization is **idempotent**: guarded with attributes (`data-embla-init`), flags, or instance checks so re-running is safe.

## Data-attribute configuration [#data-attribute-configuration]

Component scripts read configuration from HTML data attributes rather than JS options objects:

* Use a consistent prefix per component: `data-embla-*`, `data-reveal-*`.
* Parse attributes with `Utils.parseDataAttributes(node, "data-embla-")`.
* Boolean flags can be bare attributes (`data-embla-autoplay`) or explicit values (`data-embla-keyboard="false"`).

## Dependencies and load order [#dependencies-and-load-order]

Cross-script dependencies are real ES `import`s, so the module graph resolves order — you load `main.js` and nothing else needs sequencing:

| Script          | Imports       | Notes                                            |
| --------------- | ------------- | ------------------------------------------------ |
| `utils.js`      | —             | Provides `window.Utils`                          |
| `reveal.js`     | —             | Standalone                                       |
| `embla.js`      | `utils.js`    | Also needs the Embla CDN globals (see below)     |
| `carousel.js`   | `embla.js`    | `<embla-carousel>` calls `EmblaInit.initRoot`    |
| `lightbox.js`   | `carousel.js` | `<media-lightbox>` coordinates carousel elements |
| `password.js`   | —             | Standalone (`<input-password>`)                  |
| `tabs.js`       | —             | Standalone (`<tab-group>`)                       |
| `navigation.js` | —             | App-level; inert in component preview iframes    |

The one ordering the module graph can't enforce is the **Embla CDN UMD bundles**: `embla.js` reads them as globals, so their `<script defer>` tags must precede the `main.js` module in the document. Where these tags go is covered in [Structuring your head tag](/docs/getting-started/head#script-load-order).

## DOM interaction patterns [#dom-interaction-patterns]

* **Query within scope.** Accept an optional root element so init can target a subtree.
* **Early returns for guards.** Check required elements and skip gracefully.
* **Store instances on DOM nodes** when external access is needed: `emblaNode._emblaApi = emblaApi`.
* **Observe DOM changes** with `MutationObserver` for elements hidden at init time (closed dialogs).
* **Delegate events** at `document` level when triggers can appear anywhere.
* **Respect focus and input context.** Skip keyboard handlers in form fields or contenteditable.

## Classes vs functions [#classes-vs-functions]

* Use a **class** when the module manages persistent instance state (`Reveal` with observers and config).
* Use **functions** for stateless init and helpers (`initEmblaCarousels`, `parseValue`).
* Use **private class fields** (`#observers`, `#getObserver`) for encapsulation.

## JSDoc conventions [#jsdoc-conventions]

Every JSDoc block must include `@description`. Tag order:

```
@description
@param
@returns
@private
@see
@example
```

### Required tags [#required-tags]

| Tag             | Required on                           |
| --------------- | ------------------------------------- |
| `@fileoverview` | Every file                            |
| `@description`  | Every JSDoc block                     |
| `@param`        | Functions with parameters             |
| `@returns`      | Functions that return a value         |
| `@private`      | Non-exported helpers                  |
| `@typedef`      | Config/option objects                 |
| `@namespace`    | Export objects (`Utils`, `EmblaInit`) |

### Section dividers [#section-dividers]

Use thin single-line markers to group related code:

```js
// --- Dot navigation ---
```

Do not use banner block comments (`/* ==== ... ==== */`).

## Syntax and style [#syntax-and-style]

* Double quotes for strings.
* Semicolons required.
* Optional chaining (`?.`) and nullish coalescing where they simplify guards.
* No TypeScript source files; types live in JSDoc and `globals.d.ts`.
* Type-checking enabled via `tsconfig.json` (`checkJs: true`).


# Backgrounds (/docs/foundation/utilities/backgrounds)



`bg-*` utilities set `background-color` from the **theme role tokens**, so surfaces swap correctly
between light and dark. Like the text utilities, each value is
`oklch(from var(--role) l c h / calc(alpha × --_background-alpha))`, so
[color-opacity](/docs/base/utilities/color-opacity) can dim just the background channel.

Background color is the one place Zazz also ships utilities for a numeric scale, the **shade**
and **tint** overlays, because dimming or lightening a surface is so common.

## Surfaces & roles [#surfaces--roles]

| Class                                | Token                              |
| ------------------------------------ | ---------------------------------- |
| `bg-background` / `bg-foreground`    | `--background` / `--foreground`    |
| `bg-card` / `bg-card-foreground`     | `--card` / `--card-foreground`     |
| `bg-input` / `bg-input-foreground`   | `--input` / `--input-foreground`   |
| `bg-border` / `bg-border-foreground` | `--border` / `--border-foreground` |
| `bg-muted` / `bg-muted-foreground`   | `--muted` / `--muted-foreground`   |
| `bg-faded` / `bg-faded-foreground`   | `--faded` / `--faded-foreground`   |

## Brand & status [#brand--status]

| Brand                                      | Status                                         |
| ------------------------------------------ | ---------------------------------------------- |
| `bg-primary` / `bg-primary-foreground`     | `bg-info` / `bg-info-foreground`               |
| `bg-secondary` / `bg-secondary-foreground` | `bg-success` / `bg-success-foreground`         |
| `bg-tertiary` / `bg-tertiary-foreground`   | `bg-warning` / `bg-warning-foreground`         |
|                                            | `bg-destructive` / `bg-destructive-foreground` |

## Absolute & empty [#absolute--empty]

| Class            | Result                                    |
| ---------------- | ----------------------------------------- |
| `bg-white`       | `--white` (does not flip in dark mode)    |
| `bg-black`       | `--black` (does not flip in dark mode)    |
| `bg-transparent` | `background-color: transparent`           |
| `bg-none`        | `background: none` (clears image + color) |

## Overlay scales [#overlay-scales]

Two alpha-based overlay ramps for dimming and lightening any surface. `*-none` is fully
transparent; `*-full` is the most opaque step.

| Scale              | Classes                                                        | Built from                       | Use                                           |
| ------------------ | -------------------------------------------------------------- | -------------------------------- | --------------------------------------------- |
| **Shade** (darken) | `bg-shade-none`, `bg-shade-50 … bg-shade-950`, `bg-shade-full` | `--shade-*` (from `neutral-950`) | scrims, modal backdrops (e.g. `bg-shade-800`) |
| **Tint** (lighten) | `bg-tint-none`, `bg-tint-50 … bg-tint-950`, `bg-tint-full`     | `--tint-*` (from white)          | frosted highlights over imagery               |

Because they're alpha overlays, they read the underlying surface through. Layer one over media or
a colored panel rather than painting a solid fill.

```html
<div class="grid grid-area-pile">
  <img src="…" alt="…" class="size-full object-cover" />
  <div class="bg-shade-700"></div>
  <h2 class="text-white self-end p-md">Readable over any photo</h2>
</div>
```

## Variants [#variants]

* **Hover:** every role plus `transparent`/`none` has a `hover:bg-*` counterpart. See
  [Hover states](/docs/base/utilities/hover).
* **Opacity:** dim just the background channel with `bg-opacity-*`. See
  [Color opacity](/docs/base/utilities/color-opacity). It multiplies into the token's own alpha, so
  shade/tint/faded keep their built-in translucency.

<Callout type="info">
  The full numeric brand scales (`--primary-600`, `--neutral-100`, …) have **no** `bg-` utility
  classes by design. Reach a fixed shade through the token in custom CSS or inline. The role tokens
  above cover the everyday cases. See the [token
  reference](/docs/getting-started/overview#core-files) for the scale model.
</Callout>


# Borders (/docs/foundation/utilities/borders)



Borders and radius are both **token-driven and composable**. Border color flows through a
`--_border-color` indirection (so `border-opacity-*` can dim it), and radius uses the same
composing-rule pattern as padding: touch one corner, leave the rest intact.

## Border [#border]

Add a border, then optionally recolor or restyle it. The default color is `--border`.

### Sides [#sides]

| Class                                                           | Result                 |
| --------------------------------------------------------------- | ---------------------- |
| `border`                                                        | 1px solid on all sides |
| `border-t` `border-r` `border-b` `border-l`                     | 1px solid on that side |
| `border-none`                                                   | removes all borders    |
| `border-t-none` `border-r-none` `border-b-none` `border-l-none` | removes that side      |

### Color [#color]

Color utilities set `--_border-color`; the border-drawing classes read it. Set both, e.g.
`border border-primary`.

| Class                                                                | Token        |
| -------------------------------------------------------------------- | ------------ |
| *(default)*                                                          | `--border`   |
| `border-primary` `border-secondary` `border-tertiary`                | brand roles  |
| `border-muted` `border-faded`                                        | dim / fade   |
| `border-info` `border-success` `border-warning` `border-destructive` | status roles |

### Style [#style]

| Class           | Declaration            |
| --------------- | ---------------------- |
| `border-dashed` | `border-style: dashed` |
| `border-dotted` | `border-style: dotted` |
| `border-double` | `border-style: double` |

```html
<div class="border border-dashed border-muted rounded-md p-md">Dashed, muted, rounded.</div>
```

The drawn color is `oklch(from var(--_border-color) l c h / calc(alpha × --_border-alpha))`, so
`border-opacity-*` ([Color opacity](/docs/base/utilities/color-opacity)) dims the line, and
`hover:border-*` ([Hover states](/docs/base/utilities/hover)) recolors it on hover.

## Border radius [#border-radius]

Radius uses the **radius scale** (`--radius-xs` … `--radius-full`, scaled by
`--radius-multiplier`). Conventions: `md` for buttons/inputs, `lg` for cards/dialogs, `sm` for
badges, `full` for pills and circles.

### All corners [#all-corners]

| Class          | Value                |
| -------------- | -------------------- |
| `rounded-0`    | `0`                  |
| `rounded-xs`   | `var(--radius-xs)`   |
| `rounded-sm`   | `var(--radius-sm)`   |
| `rounded-md`   | `var(--radius-md)`   |
| `rounded-lg`   | `var(--radius-lg)`   |
| `rounded-xl`   | `var(--radius-xl)`   |
| `rounded-full` | `var(--radius-full)` |

### Per edge & per corner [#per-edge--per-corner]

Each of these takes the full size range (`0`, `xs`–`xl`, `full`):

| Scope             | Classes                                                     |
| ----------------- | ----------------------------------------------------------- |
| Top / bottom edge | `rounded-t-*` · `rounded-b-*`                               |
| Left / right edge | `rounded-l-*` · `rounded-r-*`                               |
| Single corner     | `rounded-tl-*` `rounded-tr-*` `rounded-br-*` `rounded-bl-*` |

## Composition variables [#composition-variables]

Like padding, radius is built from four `@property`-registered, **non-inheriting** corner
variables. A composing rule draws each corner from its variable, and each utility sets only the
corner(s) it owns, so a per-edge class flattens just that edge and leaves a component's other
corners untouched.

```css
@property --_radius-top-left {
  syntax: "<length-percentage>";
  inherits: false;
  initial-value: 0;
}

/* rounded-b-0 sets only the two bottom corners → top corners keep their value */
:where(.rounded-b-0) {
  --_radius-bottom-left: 0px;
  --_radius-bottom-right: 0px;
}
```

| Variable                 | Syntax                | Initial | Set by                                           |
| ------------------------ | --------------------- | ------- | ------------------------------------------------ |
| `--_radius-top-left`     | `<length-percentage>` | `0`     | `rounded-* rounded-t-* rounded-l-* rounded-tl-*` |
| `--_radius-top-right`    | `<length-percentage>` | `0`     | `rounded-* rounded-t-* rounded-r-* rounded-tr-*` |
| `--_radius-bottom-right` | `<length-percentage>` | `0`     | `rounded-* rounded-b-* rounded-r-* rounded-br-*` |
| `--_radius-bottom-left`  | `<length-percentage>` | `0`     | `rounded-* rounded-b-* rounded-l-* rounded-bl-*` |

```html
<!-- flatten where a card meets a flush element, keep the outer corners round -->
<div class="rounded-lg rounded-b-0">…</div>
```

`--_border-color` is a related, single-purpose indirection (not `@property`-registered): the
color classes set it, the drawing classes read it through the alpha-multiply pattern. See the
[overview](/docs/base/utilities#composition-variables-registered-non-inheriting) for the full model.


# Color opacity (/docs/foundation/utilities/color-opacity)



Color-opacity utilities dim **one color channel** and nothing else. Unlike
[`opacity-*`](/docs/base/utilities/effects#opacity), which fades the whole element (children included),
these multiply into a single token's alpha, so text stays crisp while a background softens, and a
child never inherits the dimming.

## The two opacity systems [#the-two-opacity-systems]

|                     | What it affects                   | Classes                                                                     |
| ------------------- | --------------------------------- | --------------------------------------------------------------------------- |
| **Element opacity** | the entire element + its children | `opacity-0 … opacity-100` ([Effects](/docs/base/utilities/effects#opacity)) |
| **Channel alpha**   | only the named color channel      | `text-opacity-*` · `bg-opacity-*` · `border-opacity-*`                      |

Both use the same quartile scale: `0`, `25`, `50`, `75`, `100`.

## Channel alpha utilities [#channel-alpha-utilities]

Compose one with any matching color class: `bg-primary bg-opacity-50`, `text-foreground
text-opacity-75`, `border border-destructive border-opacity-25`.

| Channel    | Classes                                 | Sets                  |
| ---------- | --------------------------------------- | --------------------- |
| Text       | `text-opacity-0 … text-opacity-100`     | `--_text-alpha`       |
| Background | `bg-opacity-0 … bg-opacity-100`         | `--_background-alpha` |
| Border     | `border-opacity-0 … border-opacity-100` | `--_border-alpha`     |

```html
<span class="bg-primary bg-opacity-50 text-primary-foreground rounded-sm px-sm">50% surface</span>
<p class="text-foreground text-opacity-75">Slightly softened body text.</p>
```

## How it works: non-inheriting alpha variables [#how-it-works-non-inheriting-alpha-variables]

Every `text-*`, `bg-*`, and `border-*` color value is computed as a multiply, not a fixed alpha:

```css
:where(.bg-primary) {
  background-color: oklch(from var(--primary) l c h / calc(alpha * var(--_background-alpha, 1)));
}
```

`alpha` is the token's **own** alpha; `--_background-alpha` is the multiplier the opacity utility
sets. Multiplying (rather than replacing) means a translucent token keeps its built-in
translucency: `bg-faded bg-opacity-50` halves the *faded* alpha rather than forcing a flat 0.5.

The three multipliers are `@property`-registered with `inherits: false` and an `initial-value` of
`1`, so the default is "unchanged" and **a value set on one element never leaks to its children**:

```css
@property --_background-alpha {
  syntax: "<number>";
  inherits: false;
  initial-value: 1;
}

:where(.bg-opacity-50) {
  --_background-alpha: 0.5;
}
```

| Variable              | Syntax     | Initial | Set by             |
| --------------------- | ---------- | ------- | ------------------ |
| `--_text-alpha`       | `<number>` | `1`     | `text-opacity-*`   |
| `--_background-alpha` | `<number>` | `1`     | `bg-opacity-*`     |
| `--_border-alpha`     | `<number>` | `1`     | `border-opacity-*` |

These sit alongside the padding/margin/radius composition variables as the non-inheriting half of
the system. See the [overview](/docs/base/utilities#composition-variables-registered-non-inheriting).


# Effects (/docs/foundation/utilities/effects)



Effect utilities cover elevation, element opacity, scale, and transitions. For dimming a single
color channel (rather than the whole element) see [Color opacity](/docs/base/utilities/color-opacity).

## Box shadow [#box-shadow]

Soft, multi-layer shadows from the elevation scale. Surfaces are flat by default. Apply
elevation intentionally (`md` ≈ popovers and modals).

| Class         | Token              |
| ------------- | ------------------ |
| `shadow-none` | `none`             |
| `shadow-xs`   | `var(--shadow-xs)` |
| `shadow-sm`   | `var(--shadow-sm)` |
| `shadow-md`   | `var(--shadow-md)` |
| `shadow-lg`   | `var(--shadow-lg)` |
| `shadow-xl`   | `var(--shadow-xl)` |

## Opacity [#opacity]

Sets the whole element's `opacity`, so **children fade too**. To dim only a color channel and leave
content fully opaque, use [Color opacity](/docs/base/utilities/color-opacity) instead.

| Class         | Value  |
| ------------- | ------ |
| `opacity-0`   | `0`    |
| `opacity-25`  | `0.25` |
| `opacity-50`  | `0.5`  |
| `opacity-75`  | `0.75` |
| `opacity-100` | `1`    |

`opacity-*` also has `hover:` variants ([Hover states](/docs/base/utilities/hover)). `hover:opacity-75`
is a common image-hover treatment.

## Scale [#scale]

Transform an element's size. Most useful paired with a transition and a hover variant.

| Class                                           | Transform           |
| ----------------------------------------------- | ------------------- |
| `scale-0`                                       | `scale(0)`          |
| `scale-50` `scale-75` `scale-90` `scale-95`     | `scale(0.5 … 0.95)` |
| `scale-100`                                     | `scale(1)`          |
| `scale-105` `scale-110` `scale-125` `scale-150` | `scale(1.05 … 1.5)` |

The full set also exists as `hover:scale-*`.

## Transitions [#transitions]

Animate property changes using the system's motion tokens (`--default-transition-*`, which respect
`prefers-reduced-motion`).

| Class                  | Animates                                           |
| ---------------------- | -------------------------------------------------- |
| `transition`           | the default bundle of commonly animated properties |
| `transition-all`       | `all`                                              |
| `transition-opacity`   | `opacity`                                          |
| `transition-transform` | `transform`                                        |

```html
<img class="rounded-md transition hover:scale-105 hover:opacity-75" src="…" alt="…" />
```

<Callout type="info">
  `prefers-reduced-motion: reduce` zeroes the transition duration globally, so you don't need to
  guard hover effects yourself. See the [motion tokens](/docs/getting-started/overview) for the
  easing and duration values.
</Callout>


# Flexbox (/docs/foundation/utilities/flexbox)



Turn on a flex container with `flex` or `inline-flex`, then set direction, item sizing, and
alignment. For flex-basis fractions and gaps see [Gap & basis](/docs/base/utilities/gap-and-basis);
for reordering see [order](/docs/base/utilities/layout#order).

## Container & direction [#container--direction]

<Preview src="utilities/flex-direction" />

| Class              | Declaration                      |
| ------------------ | -------------------------------- |
| `flex`             | `display: flex`                  |
| `inline-flex`      | `display: inline-flex`           |
| `flex-row`         | `flex-direction: row`            |
| `flex-row-reverse` | `flex-direction: row-reverse`    |
| `flex-col`         | `flex-direction: column`         |
| `flex-col-reverse` | `flex-direction: column-reverse` |

`flex`, `inline-flex`, `flex-row`, and `flex-col` have responsive variants. `flex-col @md:flex-row`
is the canonical stack-then-row pattern ([Responsive design](/docs/base/utilities/responsive-design)).

## Grow & shrink [#grow--shrink]

The `flex` shorthands cover the common grow/shrink intents.

<Preview src="utilities/flex-grow" />

| Class          | Declaration     | Meaning                              |
| -------------- | --------------- | ------------------------------------ |
| `flex-1`       | `flex: 1`       | grow and shrink, ignore initial size |
| `flex-auto`    | `flex: auto`    | grow and shrink from content size    |
| `flex-initial` | `flex: initial` | shrink but don't grow                |
| `flex-none`    | `flex: none`    | neither grow nor shrink              |

## Align & justify [#align--justify]

<Preview src="utilities/flex-align" />

`items-*` aligns on the cross axis, `justify-*` distributes on the main axis. Values use the
modern CSS Box Alignment keywords (`start`/`end`, not `flex-start`/`flex-end`).

| Cross axis — `align-items` | Main axis — `justify-content` |
| -------------------------- | ----------------------------- |
| `items-start`              | `justify-start`               |
| `items-center`             | `justify-center`              |
| `items-end`                | `justify-end`                 |
| `items-stretch`            | `justify-stretch`             |
|                            | `justify-between`             |
|                            | `justify-around`              |

`items-*` and `justify-*` both have responsive variants.

### Per-item alignment [#per-item-alignment]

Override the container's cross-axis alignment on a single child with `self-*`. (These are
base-only, with no responsive variants.)

| Class          | Declaration           |
| -------------- | --------------------- |
| `self-auto`    | `align-self: auto`    |
| `self-start`   | `align-self: start`   |
| `self-center`  | `align-self: center`  |
| `self-end`     | `align-self: end`     |
| `self-stretch` | `align-self: stretch` |

`justify-self-auto`, `justify-self-start`, `justify-self-center`, `justify-self-end`, and
`justify-self-stretch` are also available (most relevant inside grid).


# Gap & basis (/docs/foundation/utilities/gap-and-basis)



`gap-*` sets the space between flex or grid children; `basis-*` sets a flex item's base size. They
share one coordination variable (`--_gap`) so fraction widths subtract the gap automatically, with no
off-by-a-gutter math.

## Gap [#gap]

<Preview src="utilities/gap" />

Gaps use the **semantic gap scale**, the same `--gap-*` tokens that drive padding and margin, so
spacing stays consistent across layout primitives.

| Class       | Value           |
| ----------- | --------------- |
| `gap-0`     | `0`             |
| `gap-0.5px` | `0.5px`         |
| `gap-px`    | `1px`           |
| `gap-xs`    | `var(--gap-xs)` |
| `gap-sm`    | `var(--gap-sm)` |
| `gap-md`    | `var(--gap-md)` |
| `gap-lg`    | `var(--gap-lg)` |
| `gap-xl`    | `var(--gap-xl)` |

### Axis gaps [#axis-gaps]

Set column and row gaps independently. `gap-x-*` maps to `column-gap`, `gap-y-*` to `row-gap`,
using the same size keywords as `gap-*` (`0`, `0.5px`, `px`, `xs`–`xl`).

```html
<div class="grid grid-cols-3 gap-x-lg gap-y-sm"><!-- wide columns, tight rows --></div>
```

## Flex basis [#flex-basis]

<Preview src="utilities/basis" />

The fractions are **gap-aware**: each subtracts its share of the gap so N items per row actually
fit on one line. `basis-1/3` resolves to `calc((100% - 2 × gap) / 3)`, reading the gap the
container set.

| Class        | Resolves to            |
| ------------ | ---------------------- |
| `basis-0`    | `flex-basis: 0`        |
| `basis-auto` | `flex-basis: auto`     |
| `basis-full` | `flex-basis: 100%`     |
| `basis-1/2`  | `(100% − 1 × gap) / 2` |
| `basis-1/3`  | `(100% − 2 × gap) / 3` |
| `basis-1/4`  | `(100% − 3 × gap) / 4` |
| `basis-1/5`  | `(100% − 4 × gap) / 5` |
| `basis-1/6`  | `(100% − 5 × gap) / 6` |

`basis-*` has responsive variants, so `basis-full @md:basis-1/3` gives full-width rows that become
thirds on a wider container.

<Callout type="info">
  For the fractions to subtract the right gutter, set a `gap-*` class on the same flex container.
  That's what populates `--_gap`. With no gap class, `--_gap` defaults to `0px` and the fractions
  fall back to even splits.
</Callout>

## The `--_gap` coordination variables [#the---_gap-coordination-variables]

`gap-*` doesn't only set the `gap` property; it also publishes the value as an **inheriting**
variable that `basis-*` and the [responsive auto-fill grid](/docs/base/utilities/grid#responsive-auto-fill-grid)
read back.

| Variable   | Default            | Set by    | Read by                                    |
| ---------- | ------------------ | --------- | ------------------------------------------ |
| `--_gap`   | `0px` (on `:root`) | `gap-*`   | `basis-1/2…1/6`, `grid-flow-row` auto-fill |
| `--_gap-x` | —                  | `gap-x-*` | `column-gap`                               |
| `--_gap-y` | —                  | `gap-y-*` | `row-gap`                                  |

These are left unregistered (and therefore inheriting) on purpose: a value set on the container
must reach the children that compute their width from it. This is the opposite of the
non-inheriting composition variables behind padding/margin/radius; see the
[overview](/docs/base/utilities#private-composition-and-coordination-variables) for the contrast.


# Grid (/docs/foundation/utilities/grid)



`grid` turns on a grid container; `grid-cols-N` / `grid-rows-N` define the tracks; `col-span-*` /
`row-span-*` place children. A grid child also gets `min-inline-size: 0` automatically so long
content can't blow out a track.

## Container, columns & rows [#container-columns--rows]

<Preview src="utilities/grid-cols" />

| Class                        | Declaration                                                    |
| ---------------------------- | -------------------------------------------------------------- |
| `grid`                       | `display: grid` (also sets `--_grid-col-min: min(100%, 25ch)`) |
| `grid-cols-1 … grid-cols-12` | `grid-template-columns: repeat(N, minmax(0, 1fr))`             |
| `grid-rows-1 … grid-rows-12` | `grid-template-rows: repeat(N, auto)`                          |
| `grid-flow-row`              | `grid-auto-flow: row`                                          |
| `grid-flow-col`              | `grid-auto-flow: column`                                       |

`grid-cols-N` and `grid-rows-N` also set the coordination variables `--_grid-cols` / `--_grid-rows`
(see [below](#coordination-variables)). Display (`grid`), `grid-cols-*`, and `grid-rows-*` all have
responsive variants.

## Spanning [#spanning]

<Preview src="utilities/col-span" />

Spans are **clamped to the track count** so a child can never span past the grid: each is
`span min(N, var(--_grid-cols))`, reading the count the container set.

| Class                      | Declaration                                   |
| -------------------------- | --------------------------------------------- |
| `col-span-1 … col-span-12` | `grid-column: span min(N, var(--_grid-cols))` |
| `row-span-1 … row-span-12` | `grid-row: span min(N, var(--_grid-rows))`    |

`col-span-*` and `row-span-*` have responsive variants.

## Subgrid [#subgrid]

Adopt the parent grid's tracks so nested content lines up across cards or rows.

| Class               | Declaration                      |
| ------------------- | -------------------------------- |
| `grid-cols-subgrid` | `grid-template-columns: subgrid` |
| `grid-rows-subgrid` | `grid-template-rows: subgrid`    |

Both have responsive variants. See the [Card](/docs/components/card) subgrid example for a
real-world layout.

## Stacking: grid-area-pile [#stacking-grid-area-pile]

<Preview src="utilities/grid-pile" />

`grid-area-pile` stacks every direct child into one cell and centers them (`place-items: center`):
the clean way to layer an overlay on media, or an avatar fallback under an image. Override an
individual child's placement with `self-*` / `justify-self-*`.

## Place items [#place-items]

Shorthand for aligning all grid children in both axes at once.

| Class                | Declaration           |
| -------------------- | --------------------- |
| `place-items-start`  | `place-items: start`  |
| `place-items-center` | `place-items: center` |
| `place-items-end`    | `place-items: end`    |

## Responsive auto-fill grid [#responsive-auto-fill-grid]

<Preview src="utilities/grid-responsive" />

Combine `grid-flow-row` with `grid-cols-N` (N > 1) and the grid switches to a &#x2A;*gap-aware
`auto-fill`** track formula: items fill across, then wrap to the next row as the container
narrows: responsive columns with no breakpoints. The track floor is the larger of
`--_grid-col-min` (`min(100%, 25ch)`) and an even `1/N` share of the row minus gaps, so columns
never get narrower than readable.

```html
<div class="grid grid-flow-row grid-cols-4 gap-md">
  <!-- up to 4 equal columns, wrapping as space runs out -->
</div>
```

## Coordination variables [#coordination-variables]

Grid utilities expose three **inheriting** coordination variables: set on the container, read by
descendants. They're left unregistered so normal inheritance carries them down.

| Variable          | Set by        | Default           | Read by                                 |
| ----------------- | ------------- | ----------------- | --------------------------------------- |
| `--_grid-cols`    | `grid-cols-N` | `1`               | `col-span-*` (clamp), auto-fill formula |
| `--_grid-rows`    | `grid-rows-N` | `1`               | `row-span-*` (clamp)                    |
| `--_grid-col-min` | `.grid`       | `min(100%, 25ch)` | `grid-flow-row` auto-fill track floor   |

Because `--_grid-cols` inherits, a `col-span-3` placed inside a `grid-cols-2` clamps to `span 2`
instead of overflowing: the span reads the same count the container declared. See the
[utilities overview](/docs/base/utilities#coordination-variables-inheriting-on-purpose) for how these
differ from the non-inheriting composition variables.


# Hover states (/docs/foundation/utilities/hover)



Color, opacity, and scale utilities ship `hover:` variants that apply on `:hover`, with no JavaScript
and no component code. Pair them with a [transition](/docs/base/utilities/effects#transitions) for a smooth
change.

```html
<a href="#" class="text-muted-foreground hover:text-primary transition">Hover me</a>
<img class="rounded-md transition hover:scale-105 hover:opacity-75" src="…" alt="…" />
```

<Callout type="info">
  In HTML the class name literally contains a colon, so write `class="hover:bg-primary"`. The
  stylesheet escapes it as `.hover\:bg-primary` in the selector; you never type the backslash.
</Callout>

## Hover text color [#hover-text-color]

`hover:text-{role}` for every [text color role](/docs/base/utilities/text-color): `background`,
`foreground`, `card`, `input`, `muted`, `faded`, `primary`, `secondary`, `tertiary`, `info`,
`success`, `warning`, `destructive`, and each `-foreground` pair.

```html
<a class="text-foreground hover:text-primary transition">Link</a>
```

## Hover background [#hover-background]

`hover:bg-{role}` for every [background role](/docs/base/utilities/backgrounds), plus
`hover:bg-transparent` and `hover:bg-none`.

```html
<button class="bg-card hover:bg-muted rounded-md p-sm transition">Row</button>
```

## Hover border [#hover-border]

`hover:border-{color}`: `primary`, `secondary`, `tertiary`, `muted`, `faded`, `info`, `success`,
`warning`, `destructive`. Pair with a `border` class so there's a line to recolor.

```html
<div class="border hover:border-primary rounded-md p-md transition">Card</div>
```

## Hover opacity & scale [#hover-opacity--scale]

| Family  | Classes                                                                                                                                                                       |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Opacity | `hover:opacity-0` `hover:opacity-25` `hover:opacity-50` `hover:opacity-75` `hover:opacity-100`                                                                                |
| Scale   | `hover:scale-0` `hover:scale-50` `hover:scale-75` `hover:scale-90` `hover:scale-95` `hover:scale-100` `hover:scale-105` `hover:scale-110` `hover:scale-125` `hover:scale-150` |

<Callout type="warn">
  There are no `active:` (pressed) variants. Express `:active` / pressed feedback in the component's
  own CSS, not via utilities. See [Hover, focus, and other states](/docs/core-concepts/states).
</Callout>


# Utilities (/docs/foundation/utilities)



Utilities are Zazz's atomic classes: one job each, applied in markup. They live in the **last**
cascade layer (`@layer zazz.utilities`), so a utility always wins over a component rule. No
`!important`, no specificity tricks. Every utility is wrapped in `:where()` for zero specificity,
which means your own selectors can still override them when you need to.

<Preview src="utilities/compose" />

Reach for utilities to compose layout and one-off overrides on top of components. They read the
same semantic tokens (`--gap-md`, `--primary`, `--radius-lg`) the rest of the system does, so a
utility-built panel stays on-brand and theme-aware for free.

## The rules that govern every utility [#the-rules-that-govern-every-utility]

The [why, and the everyday subset](/docs/core-concepts/utility-classes), live in Core concepts; this
page is the reference. Two mechanics set up everything below:

1. **Cascade, not specificity.** Inside Zazz the sublayers run `variables, components, utilities`.
   A plain `.button` rule lives in `components`; a `.rounded-full` utility lives in `utilities`
   and wins. See [`_layers.css`](/docs/core-files/layers) for the full layer model.
2. **Zero specificity.** Each rule is `:where(.utility) { … }`, specificity `(0,0,0)`. Utilities
   override components by layer position, and *your* rules override utilities by ordinary
   specificity. No arms race.

## How these pages are grouped [#how-these-pages-are-grouped]

The atomic classes in `zazz/styles/base/_utilities.css` are organized here into the same families
Tailwind uses, so you can scan by intent:

| Group                                                                                                                           | Covers                                                                |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Layout](/docs/base/utilities/layout)                                                                                           | display, position, overflow, z-index, aspect-ratio, object-fit, order |
| [Flexbox](/docs/base/utilities/flexbox) · [Grid](/docs/base/utilities/grid) · [Gap & basis](/docs/base/utilities/gap-and-basis) | flex/grid containers, alignment, spans, gaps, flex-basis              |
| [Spacing](/docs/base/utilities/spacing) · [Sizing](/docs/base/utilities/sizing)                                                 | padding, margin · width, height, size, min/max                        |
| [Text color](/docs/base/utilities/text-color) · [Text & font](/docs/base/utilities/text-and-font)                               | color roles · alignment, transform, wrap, clamp, family               |
| [Backgrounds](/docs/base/utilities/backgrounds) · [Borders](/docs/base/utilities/borders)                                       | surface colors, overlays · border, radius                             |
| [Effects](/docs/base/utilities/effects) · [Color opacity](/docs/base/utilities/color-opacity)                                   | shadow, opacity, scale, transition · channel alpha                    |
| [Interactivity](/docs/base/utilities/interactivity) · [Hover states](/docs/base/utilities/hover)                                | cursor, focus ring, screen readers · `hover:` variants                |
| [Responsive design](/docs/base/utilities/responsive-design)                                                                     | the `@xs: @sm: @md: @lg: @xl:` container-query prefixes               |

## Private composition and coordination variables [#private-composition-and-coordination-variables]

Several utilities don't set a CSS property directly; instead they set an internal `--_`-prefixed
variable that a shared rule reads. This is what lets you touch one edge, axis, or channel without
disturbing the others. There are two kinds, and they behave differently on purpose.

### Composition variables (registered, non-inheriting) [#composition-variables-registered-non-inheriting]

Padding, margin, radius, and color-alpha utilities are built from `@property`-registered
variables declared with `inherits: false`. A value set on one element therefore **never bleeds
onto its descendants** through the shared composing rule, and the registration's `initial-value`
doubles as the default (no `:root` fallback needed).

```css
/* One composing rule reads the vars… */
:where(.p-0, .p-xs, .p-sm, .p-md, .p-lg, .p-xl, [class*="px-"], [class*="pl-"], [class*="pr-"]) {
  padding-inline: var(--_padding-inline-start) var(--_padding-inline-end);
}

/* …and each utility only sets the var it owns. */
:where(.pl-0) {
  --_padding-inline-start: 0;
}
```

Because `p-md` sets all four edges and `pl-0` sets only the inline-start, `class="p-md pl-0"`
resolves to *medium padding everywhere except a zeroed left*: the other three edges are
untouched. The same pattern powers per-edge `rounded-*` and per-channel color opacity.

| Variable                                                    | Registered syntax             | Initial | Set by                                         | Documented in                                       |
| ----------------------------------------------------------- | ----------------------------- | ------- | ---------------------------------------------- | --------------------------------------------------- |
| `--_padding-{inline,block}-{start,end}`                     | `<length-percentage>`         | `0`     | `p-* px-* py-* pt-* pr-* pb-* pl-*`            | [Spacing](/docs/base/utilities/spacing)             |
| `--_margin-{inline,block}-{start,end}`                      | `<length-percentage> \| auto` | `0`     | `m-* mx-* my-* mt-* … -m-* mx-auto`            | [Spacing](/docs/base/utilities/spacing)             |
| `--_radius-{top-left,top-right,bottom-right,bottom-left}`   | `<length-percentage>`         | `0`     | `rounded-* rounded-t-* rounded-tl-* …`         | [Borders](/docs/base/utilities/borders)             |
| `--_text-alpha` · `--_background-alpha` · `--_border-alpha` | `<number>`                    | `1`     | `text-opacity-* bg-opacity-* border-opacity-*` | [Color opacity](/docs/base/utilities/color-opacity) |

### Coordination variables (inheriting on purpose) [#coordination-variables-inheriting-on-purpose]

A second set stays *inheriting* (left unregistered, so default inheritance applies). These are
set on a container and **read by descendants**: the gap variable feeds the gap-aware `basis-*`
fractions and the responsive auto-fill grid, and the column/row counts let `col-span-*` clamp
themselves so a span never exceeds the track count.

| Variable                        | Default                        | Set by                        | Read by                                    |
| ------------------------------- | ------------------------------ | ----------------------------- | ------------------------------------------ |
| `--_gap`                        | `0px` (on `:root`)             | `gap-*`                       | `basis-1/2…1/6`, `grid-flow-row` auto-fill |
| `--_gap-x` · `--_gap-y`         | —                              | `gap-x-*` · `gap-y-*`         | `column-gap` · `row-gap`                   |
| `--_grid-cols` · `--_grid-rows` | `1`                            | `grid-cols-N` · `grid-rows-N` | `col-span-*` · `row-span-*`, auto-fill     |
| `--_grid-col-min`               | `min(100%, 25ch)` (on `.grid`) | `.grid`                       | `grid-flow-row` auto-fill track floor      |

These are covered alongside their classes in [Gap & basis](/docs/base/utilities/gap-and-basis) and
[Grid](/docs/base/utilities/grid).

## Responsive & state variants [#responsive--state-variants]

Every layout-related utility has container-query-prefixed variants (`@xs: @sm: @md: @lg: @xl:`) gated
on centralized breakpoint flags the **body** publishes off the page width. Color, opacity, and scale
utilities also ship `hover:` variants that need no JavaScript.

```html
<div class="flex flex-col @md:flex-row gap-md">
  <aside class="@md:basis-1/3">Sidebar</aside>
  <main class="flex-1 hover:bg-muted transition">Content</main>
</div>
```

See [Responsive design](/docs/base/utilities/responsive-design) for the breakpoint table and exactly
which families are available per breakpoint, and [Hover states](/docs/base/utilities/hover) for the
full `hover:` catalog.


# Interactivity (/docs/foundation/utilities/interactivity)



A small set of utilities for pointer behavior, focus, and assistive technology. For hover-driven
color and motion, see [Hover states](/docs/base/utilities/hover).

## Pointer & cursor [#pointer--cursor]

| Class                 | Declaration            | Use                                  |
| --------------------- | ---------------------- | ------------------------------------ |
| `pointer-events-none` | `pointer-events: none` | make an overlay click-through        |
| `pointer-cursor`      | `cursor: pointer`      | signal interactivity on a non-button |
| `pointer-default`     | `cursor: default`      | suppress the text/pointer cursor     |

## Focus ring [#focus-ring]

`ring` opts an element into the Tailwind/shadcn-compatible focus ring. It renders as layered
box-shadows (an **offset ring** plus the ring itself) and only appears on `:focus-visible`, so
keyboard focus is clear while mouse clicks stay quiet.

```html
<a href="#" class="ring rounded-md">Keyboard-focusable</a>
```

How it composes:

* Transparent until focus: the ring widths (`--_ring-width`, `--_ring-offset-width`) sit at `0`
  and expand to `--ring-width` / `--ring-offset-width` on `:focus-visible`.
* The ring color is `--primary`; the offset gap uses `--ring-offset-color` (the page background),
  so the ring reads as a clean halo.
* A same-geometry &#x2A;*transparent `outline`** is kept as a twin for forced-colors / high-contrast
  modes, where box-shadows don't render, so focus never silently disappears.

<Callout type="info">
  Components draw their own focus rings from the same `--ring-*` tokens; `ring` is for plain
  elements (links, custom controls) that don't already have one. To recolor, override `--ring-color`
  rather than `--ring`. See the [focus-ring
  conventions](/docs/base/file-anatomy#selector-conventions).
</Callout>

## Screen-reader only [#screen-reader-only]

`sr-only` hides content visually while keeping it in the accessibility tree: for labels an icon
button needs but a sighted user doesn't.

```html
<button class="button" data-size="icon">
  <svg aria-hidden="true"><!-- icon --></svg>
  <span class="sr-only">Close menu</span>
</button>
```


# Layout (/docs/foundation/utilities/layout)



Layout utilities control how a box renders and where it sits: its display mode, positioning,
overflow, stacking, intrinsic ratio, and paint order, plus the page-level container wrappers
below. For the responsive breakpoint system, see [Responsive design](/docs/base/utilities/responsive-design).

## Containers [#containers]

`.container` is the page's width system. Put it on (or directly inside) a region (`main`, `section`,
`header`, `footer`, `article`) and the region turns into a shared column grid. The container spans
that grid and drops each of its children into a centered **band**, so one class handles page width,
gutters, and which children sit wider or narrower, with no extra wrapper divs.

```html
<section class="container">
  <h1>Centered in the large band, with page gutters.</h1>
  <p>Body copy lines up to the same width.</p>
</section>
```

### The bands [#the-bands]

Every container exposes the same set of bands. A band caps and centers its content while the region
is wider than the cap, then fills to the gutters once it isn't, with no breakpoint snap in between.
Children land in the `md` band unless you say otherwise.

| Band                       | Caps at                     | Use                                       |
| -------------------------- | --------------------------- | ----------------------------------------- |
| `xs`                       | `--breakpoint-xs` (40rem)   | a very narrow column                      |
| `sm`                       | `--breakpoint-sm` (48rem)   | forms, sign-in cards                      |
| `md&#x60; &#x2A;(default)* | `--breakpoint-md` (64rem)   | standard page width                       |
| `lg`                       | `--breakpoint-lg` (80rem)   | wide sections                             |
| `xl`                       | `--breakpoint-xl` (96rem)   | wide dashboards and galleries             |
| `full`                     | region width, minus gutters | edge-aligned rows that still keep gutters |
| `bleed`                    | edge to edge, no gutter     | full-bleed media and color bands          |

### Set the default band [#set-the-default-band]

`data-container` on the container changes the band every child lands in:

```html
<!-- the whole section caps at the medium width -->
<section class="container" data-container="md">
  <h2>A narrower section</h2>
  <p>Everything here lines up to the md band.</p>
</section>
```

### Break a child out [#break-a-child-out]

`data-container` on a direct child overrides that one child's band, so it can run wider (or tuck
narrower) than its siblings without leaving the container:

```html
<section class="container">
  <h1>Title in the large band</h1>
  <p>Reading-width copy.</p>

  <!-- this figure runs edge to edge -->
  <figure data-container="bleed">
    <img src="/wide.jpg" alt="" />
  </figure>
</section>
```

The default and the override draw from the same band names, so an `md` section can hold one `full`
row and an `lg` section can hold one `sm` form. Every band is a pair of named grid lines in a single
shared column template, which is what lets a child jump to any of them by name.

### The article variant [#the-article-variant]

For long-form reading, add `data-variant="article"`. Instead of a band, the container becomes a
centered column measured in `ch` for a comfortable line length. This replaces the old `.article`
class.

```html
<article class="container" data-variant="article">
  <h1>A reading column</h1>
  <p>Measured for a comfortable line length and centered with page gutters.</p>
</article>
```

`data-container` picks the measure:

| Value                      | Width |
| -------------------------- | ----- |
| `xs`                       | 45ch  |
| `sm`                       | 50ch  |
| `md`                       | 65ch  |
| `lg&#x60; &#x2A;(default)* | 70ch  |
| `xl`                       | 75ch  |

### Responsive containers [#responsive-containers]

The container takes the same breakpoint variants as the other layout utilities (see
[Responsive design](/docs/base/utilities/responsive-design)). A `@md:container` is a plain block below
its breakpoint and becomes a banded grid from `md` up; `@max-md:container` does the reverse, banding
only below `md`. Both forms work with `data-variant="article"` too.

```html
<!-- a banded grid from md up, a plain block below it -->
<section class="@md:container">…</section>
```

## Display [#display]

| Class          | Declaration             |
| -------------- | ----------------------- |
| `block`        | `display: block`        |
| `inline-block` | `display: inline-block` |
| `inline`       | `display: inline`       |
| `flex`         | `display: flex`         |
| `inline-flex`  | `display: inline-flex`  |
| `grid`         | `display: grid`         |
| `hidden`       | `display: none`         |

`flex` and `grid` are covered in depth in [Flexbox](/docs/base/utilities/flexbox) and
[Grid](/docs/base/utilities/grid). `block`, `flex`, `inline-flex`, `grid`, and `hidden` are the
display values that also have responsive variants ([Responsive design](/docs/base/utilities/responsive-design)).

### Visibility [#visibility]

`visibility` keeps an element's box (and its space) but toggles its paint, distinct from
`hidden`, which removes the box entirely.

| Class       | Declaration           |
| ----------- | --------------------- |
| `visible`   | `visibility: visible` |
| `invisible` | `visibility: hidden`  |

## Position [#position]

<Preview src="utilities/position" />

| Class      | Declaration          |
| ---------- | -------------------- |
| `static`   | `position: static`   |
| `relative` | `position: relative` |
| `absolute` | `position: absolute` |
| `fixed`    | `position: fixed`    |
| `sticky`   | `position: sticky`   |

### Inset & edge offsets [#inset--edge-offsets]

Offsets use the **semantic gap scale** (`--gap-xs` … `--gap-xl`), so a positioned element's
offset matches the spacing rhythm of the rest of the page. `inset-*` sets all four edges at once.

| Class                   | Declaration                          |
| ----------------------- | ------------------------------------ |
| `inset-0`               | `top/right/bottom/left: 0`           |
| `inset-xs … inset-xl`   | all four edges `= var(--gap-{size})` |
| `top-xs … top-xl`       | `top: var(--gap-{size})`             |
| `right-xs … right-xl`   | `right: var(--gap-{size})`           |
| `bottom-xs … bottom-xl` | `bottom: var(--gap-{size})`          |
| `left-xs … left-xl`     | `left: var(--gap-{size})`            |

```html
<div class="relative">
  <span class="absolute top-sm right-sm badge" data-variant="primary">New</span>
</div>
```

## Overflow [#overflow]

<Preview src="utilities/overflow" />

| Class              | Declaration                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| `overflow-visible` | `overflow: visible`                                                               |
| `overflow-hidden`  | `overflow: hidden`                                                                |
| `overflow-clip`    | `overflow: clip`                                                                  |
| `overflow-auto`    | `overflow: auto`                                                                  |
| `overflow-x-auto`  | `overflow-x: auto; overflow-y: clip`                                              |
| `overflow-y-auto`  | `overflow-y: auto; overflow-x: clip`                                              |
| `no-scrollbar`     | hides the scrollbar while keeping scroll (Firefox, IE, and `::-webkit-scrollbar`) |

`no-scrollbar` is a modifier. Pair it with one of the scrolling classes (e.g.
`overflow-y-auto no-scrollbar`) when you want scroll without the visible track.

## Z-index [#z-index]

A small, intentional stacking scale plus an isolation helper. `z-isolate` creates a new stacking
context (`isolation: isolate`) so a subtree's z-indexes can't escape it.

| Class                              | Declaration          |
| ---------------------------------- | -------------------- |
| `z-isolate`                        | `isolation: isolate` |
| `z-0`                              | `z-index: 0`         |
| `z-10` `z-20` `z-30` `z-40` `z-50` | `z-index: 10 … 50`   |

## Aspect ratio [#aspect-ratio]

<Preview src="utilities/aspect-ratio" />

Named ratios for media boxes, with no custom values to remember.

| Class               | Ratio      | Use                 |
| ------------------- | ---------- | ------------------- |
| `aspect-square`     | `1 / 1`    | avatars, thumbnails |
| `aspect-landscape`  | `3 / 2`    | photography         |
| `aspect-portrait`   | `2 / 3`    | portrait media      |
| `aspect-widescreen` | `16 / 9`   | video               |
| `aspect-univisium`  | `2 / 1`    | wide editorial      |
| `aspect-anamorphic` | `2.39 / 1` | cinematic           |

## Object fit [#object-fit]

<Preview src="utilities/object-fit" />

Controls how a replaced element (`<img>`, `<video>`) fills its box. Pair with an
[aspect ratio](#aspect-ratio) or explicit [size](/docs/base/utilities/sizing).

| Class               | Declaration                                   |
| ------------------- | --------------------------------------------- |
| `object-contain`    | `object-fit: contain` (fit inside, letterbox) |
| `object-cover`      | `object-fit: cover` (fill, crop)              |
| `object-fill`       | `object-fit: fill` (stretch)                  |
| `object-none`       | `object-fit: none` (intrinsic size)           |
| `object-scale-down` | `object-fit: scale-down`                      |

## Order [#order]

<Preview src="utilities/order" />

Reorder a flex or grid child visually without touching source order.

| Class         | Declaration    |
| ------------- | -------------- |
| `order-first` | `order: -9999` |
| `order-last`  | `order: 9999`  |
| `order-none`  | `order: 0`     |


# Responsive design (/docs/foundation/utilities/responsive-design)



Responsive utilities in Zazz wear an `@` prefix: `@xs:`, `@sm:`, `@md:`, `@lg:`, `@xl:`. Each prefix
is a **container style query** that reads a centralized breakpoint flag, so `@md:grid-cols-3` turns
on once the page passes the `md` width. The breakpoints are defined in one place and published to
the whole page, so everything crosses them in step.

<Preview src="utilities/responsive-grid" />

## The prefixes [#the-prefixes]

Five breakpoints, written like Tailwind's container variants: prefix a utility with `@xs:`, `@sm:`,
`@md:`, `@lg:`, or `@xl:`. Each is min-width style, active **at or above** its width, so the
unprefixed class is your base and prefixes layer on as the page grows.

| Prefix   | Activates at or above | Token             |
| -------- | --------------------- | ----------------- |
| *(none)* | always — the base     | —                 |
| `@xs:`   | `40rem`               | `--breakpoint-xs` |
| `@sm:`   | `48rem`               | `--breakpoint-sm` |
| `@md:`   | `64rem`               | `--breakpoint-md` |
| `@lg:`   | `80rem`               | `--breakpoint-lg` |
| `@xl:`   | `96rem`               | `--breakpoint-xl` |

```html
<!-- 1 column by default, 2 from xs, 3 from sm, 4 from lg -->
<div class="grid grid-cols-1 @xs:grid-cols-2 @sm:grid-cols-3 @lg:grid-cols-4 gap-md">…</div>
```

The prefixes are min-width only. To target small screens, write the small layout as the unprefixed
base and let a prefix override it from its breakpoint up.

## Where the breakpoints come from [#where-the-breakpoints-come-from]

The breakpoints live in one place. `--breakpoint-xs` through `--breakpoint-xl` are length tokens in
[`_variables.css`](/docs/base/variables), and a matching set of boolean flags,
`--is-breakpoint-xs` through `--is-breakpoint-xl`, tracks which ones the page has passed.

The page **body** is a container (`container-name: body`), and one block of size queries flips each
flag to `true` once the body reaches that width:

```css
@container (width >= 64rem) {
  :where(body *) {
    --is-breakpoint-md: true;
  }
}
```

Every responsive utility then reads the flag through a **style query** instead of carrying its own
`min-width`:

```css
@container style(--is-breakpoint-md: true) {
  :where(.\@md\:grid-cols-3) {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
```

Two things follow. The breakpoints are **centralized**: change `--breakpoint-md` once and every
`@md:` utility moves with it, with no `min-width` repeated across the stylesheet. And because the
flags come from the body, every element crosses a breakpoint at the same page width, so a layout
never disagrees with itself from one region to the next.

<Callout type="info">
  The size queries are authored as literal `rem` values, because `var()` isn't allowed in a
  `@container` prelude. The tokens and the queries are kept in lockstep by hand, and you can still
  use `--breakpoint-*` inside `calc()` everywhere else.
</Callout>

## Which utilities are responsive [#which-utilities-are-responsive]

Responsive variants exist for the **layout** families, the ones you actually rearrange across
breakpoints. Each is available at every prefix (`@xs:` through `@xl:`):

| Family          | Responsive classes                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------- |
| Container       | `container` (with `data-variant="article"`)                                                         |
| Display         | `hidden` `block` `flex` `inline-flex` `grid`                                                        |
| Subgrid         | `grid-cols-subgrid` `grid-rows-subgrid`                                                             |
| Grid tracks     | `grid-cols-1…12` `grid-rows-1…12`                                                                   |
| Grid spans      | `col-span-1…12` `row-span-1…12`                                                                     |
| Flex direction  | `flex-row` `flex-col`                                                                               |
| Flex basis      | `basis-0` `basis-auto` `basis-full` `basis-1/2…1/6`                                                 |
| Align items     | `items-start` `items-center` `items-end` `items-stretch`                                            |
| Justify content | `justify-start` `justify-center` `justify-end` `justify-stretch` `justify-around` `justify-between` |
| Text align      | `text-left` `text-center` `text-right` `text-justify`                                               |

The container variants drive the page width system; see [Containers](/docs/base/utilities/layout#containers).

### What is base-only (no prefix) [#what-is-base-only-no-prefix]

To keep the stylesheet lean, less-toggled families ship **only** as base classes. Apply them
outside the responsive layer:

* `self-*`, `justify-self-*`, `place-items-*`
* `visible` / `invisible`, and the `inline` / `inline-block` display values
* spacing (`p-*`, `m-*`, `gap-*`), sizing (`w-*`, `h-*`, `size-*`), and negative margins
* color, border, radius, shadow, opacity, and scale

If you need one of these to change at a breakpoint, drive it from a parent that *does* flip (e.g.
restructure with `@md:flex-row`) rather than reaching for a per-breakpoint spacing class.

## Ordering [#ordering]

Source order in `_utilities.css` puts the base classes **before** the `@container` blocks, so a
prefixed variant always wins over its base when its breakpoint is active. Write them in natural
reading order: base first, then ascending prefixes:

```html
<div class="flex-col @sm:flex-row @lg:items-center">…</div>
```

## Style queries, not media queries [#style-queries-not-media-queries]

These prefixes compile to container **style** queries, not `@media`. Two practical differences from
a media-query framework:

* **One source of truth.** The widths are tokens, not values scattered through `min-width` rules,
  so you retune the whole system from `_variables.css` and every prefix follows.
* **They live inside the cascade layers.** A style query is just another layered rule, so a
  responsive variant overrides its base by layer order, the same way every utility does, with no
  specificity to manage.

The flags are page-wide, so these behave like classic min-width breakpoints: a layout reshapes at
the same width everywhere on the page. When you need one piece to respond to the size of its own box
instead of the page, write a scoped `@container` query in
[your own stylesheet](/docs/core-concepts/custom-styles).

<Preview src="utilities/responsive-flex" />

## Browser support [#browser-support]

[Container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries)
are [Baseline](https://web.dev/baseline) and widely available. The style-query form Zazz reads the
breakpoint flags with is newer but supported across current Chrome, Safari, and Firefox. In a
browser without it, components fall back to their base (smallest) layout: usable, just not adaptive.
Hit **Expand** on the previews above to widen their frame and watch the breakpoints fire.


# Sizing (/docs/foundation/utilities/sizing)



Sizing utilities use **logical properties** (`inline-size`/`block-size`) so they follow writing
direction. Width and height share one named scale; the `size-*` shorthand sets both at once for
squares.

## Width & height [#width--height]

<Preview src="utilities/width" />

Width (`w-*`) sets `inline-size`; height (`h-*`) sets `block-size`. The named sizes come from the
**step scale**, so they scale fluidly with the viewport.

| Class                       | Width / height value                     |
| --------------------------- | ---------------------------------------- |
| `w-0` / `h-0`               | `0`                                      |
| `w-px` / `h-px`             | `1px`                                    |
| `w-auto` / `h-auto`         | `auto`                                   |
| `w-full` / `h-full`         | `100%`                                   |
| `w-xs` / `h-xs`             | `var(--step-8)`                          |
| `w-sm` / `h-sm`             | `var(--step-24)`                         |
| `w-md` / `h-md`             | `var(--step-56)`                         |
| `w-lg` / `h-lg`             | `var(--step-72)`                         |
| `w-xl` / `h-xl`             | `var(--step-96)`                         |
| `w-screen`                  | `100vi` (viewport inline)                |
| `h-screen`                  | `100svh` (small viewport height)         |
| `w-screen-xs … w-screen-xl` | `var(--breakpoint-xs … --breakpoint-xl)` |
| `h-screen-xs … h-screen-xl` | `var(--breakpoint-xs … --breakpoint-xl)` |

The `screen-*` sizes resolve to the breakpoint widths (`xs` 40rem → `xl` 96rem), handy for
capping reading or layout columns to a known breakpoint.

## Size (square shorthand) [#size-square-shorthand]

<Preview src="utilities/size" />

`size-*` sets `inline-size` and `block-size` together. Its named sizes draw from the **gap scale**
(not the step scale), which keeps them in the small, icon-friendly range, ideal for avatars,
dots, and square media.

| Class                             | Value (both axes)               |
| --------------------------------- | ------------------------------- |
| `size-0`                          | `0`                             |
| `size-auto`                       | `auto`                          |
| `size-full`                       | `100%`                          |
| `size-xs`                         | `var(--gap-xs)`                 |
| `size-sm`                         | `var(--gap-sm)`                 |
| `size-md`                         | `var(--gap-md)`                 |
| `size-lg`                         | `var(--gap-lg)`                 |
| `size-xl`                         | `var(--gap-xl)`                 |
| `size-screen`                     | `100vi` × `100svh`              |
| `size-screen-xs … size-screen-xl` | `var(--breakpoint-*)` both axes |

```html
<img class="size-lg rounded-full object-cover" src="…" alt="…" />
```

## Min & max constraints [#min--max-constraints]

Clamp an element's size while letting it flex otherwise. Pair `max-w-*` with `w-full` for the
common "fluid up to a cap" pattern.

| Max width              | Max height             | Min width              | Min height             |
| ---------------------- | ---------------------- | ---------------------- | ---------------------- |
| `max-w-0`              | `max-h-0`              | `min-w-0`              | `min-h-0`              |
| `max-w-auto`           | `max-h-auto`           | `min-w-auto`           | `min-h-auto`           |
| `max-w-full`           | `max-h-full`           | `min-w-full`           | `min-h-full`           |
| `max-w-xs … max-w-xl`  | `max-h-xs … max-h-xl`  | —                      | —                      |
| `max-w-screen`         | `max-h-screen`         | `min-w-screen`         | `min-h-screen`         |
| `max-w-screen-xs … xl` | `max-h-screen-xs … xl` | `min-w-screen-xs … xl` | `min-h-screen-xs … xl` |

`max-w-*` / `max-h-*` carry the full named scale (`xs`–`xl`, mapping to the same step values as
`w-*`/`h-*`). `min-w-*` / `min-h-*` ship the structural values (`0`, `auto`, `full`, `screen`,
`screen-*`), the most common min-size needs.

```html
<article class="w-full max-w-screen-sm mx-auto">
  Fluid, capped at the sm breakpoint, centered.
</article>
```


# Spacing (/docs/foundation/utilities/spacing)



Padding and margin both draw from the **semantic gap scale** (`--gap-xs` … `--gap-xl`) and use
**logical properties** (`inline`/`block`), so spacing stays consistent and RTL-correct. Both are
built on a composition-variable system: a side utility changes only its edge, leaving the rest of
a component's spacing intact.

## Padding [#padding]

<Preview src="utilities/padding" />

| Scope                      | Classes                        | Sets                   |
| -------------------------- | ------------------------------ | ---------------------- |
| All sides                  | `p-0 p-xs p-sm p-md p-lg p-xl` | all four edges         |
| Inline axis (left + right) | `px-0 px-xs … px-xl`           | `padding-inline`       |
| Block axis (top + bottom)  | `py-0 py-xs … py-xl`           | `padding-block`        |
| Top                        | `pt-0 pt-xs … pt-xl`           | `padding-block-start`  |
| Bottom                     | `pb-0 pb-xs … pb-xl`           | `padding-block-end`    |
| Left                       | `pl-0 pl-xs … pl-xl`           | `padding-inline-start` |
| Right                      | `pr-0 pr-xs … pr-xl`           | `padding-inline-end`   |

Each size maps to its gap token (`p-md` → `var(--gap-md)`). `pt`/`pb` are block edges and
`pl`/`pr` are inline edges, so they follow writing direction.

## Margin [#margin]

Margin mirrors padding's scopes and adds &#x2A;*`auto`** (for centering and pushing) and a
**negative** scale.

| Scope       | Classes                                                 |
| ----------- | ------------------------------------------------------- |
| All sides   | `m-0 m-xs … m-xl`                                       |
| Inline axis | `mx-0 mx-xs … mx-xl`, `mx-auto`                         |
| Block axis  | `my-0 my-xs … my-xl`, `my-auto`                         |
| Per side    | `mt-* mr-* mb-* ml-*` (each `0`, `xs`–`xl`, and `auto`) |

### Auto margins [#auto-margins]

<Preview src="utilities/margin-auto" />

`mx-auto` centers a fixed-width block; `ml-auto` (or `mr-auto`) pushes a flex item to the far
edge. `auto` is a registered value of the margin composition variables, so it composes like any
other size.

### Negative margins [#negative-margins]

Pull an element past its edge, useful for full-bleed media inside padded containers.

| Scope               | Classes                               |
| ------------------- | ------------------------------------- |
| All sides           | `-m-xs … -m-xl`                       |
| Inline / block axis | `-mx-xs … -mx-xl`, `-my-xs … -my-xl`  |
| Per side            | `-mt-* -mr-* -mb-* -ml-*` (`xs`–`xl`) |

Negative margins are base classes only, with no responsive variants.

## Composition variables [#composition-variables]

Padding and margin never write the property directly. A **composing rule** reads four
`@property`-registered variables; each utility only sets the var(s) it owns. The variables are
registered with `inherits: false`, so a value on one element can't leak onto its descendants
through the shared rule.

```css
/* @property registration — non-inheriting, with a built-in default */
@property --_padding-inline-start {
  syntax: "<length-percentage>";
  inherits: false;
  initial-value: 0;
}

/* Composing rule reads the vars… */
:where(.p-0, .p-xs, .p-sm, .p-md, .p-lg, .p-xl, [class*="px-"], [class*="pl-"], [class*="pr-"]) {
  padding-inline: var(--_padding-inline-start) var(--_padding-inline-end);
}

/* …and the side utility only sets its own edge. */
:where(.pl-0) {
  --_padding-inline-start: 0;
}
```

The payoff is **independent edges**. Stacking an all-sides class with a side class overrides only
that edge. Source order makes the more specific setter win:

```html
<!-- medium padding everywhere, but a flush left edge -->
<div class="p-md pl-0">…</div>
```

<Preview src="utilities/padding-compose" />

| Variable                                            | Syntax                        | Initial | Set by                           |
| --------------------------------------------------- | ----------------------------- | ------- | -------------------------------- |
| `--_padding-inline-start` · `--_padding-inline-end` | `<length-percentage>`         | `0`     | `p-* px-* pl-* pr-*`             |
| `--_padding-block-start` · `--_padding-block-end`   | `<length-percentage>`         | `0`     | `p-* py-* pt-* pb-*`             |
| `--_margin-inline-start` · `--_margin-inline-end`   | `<length-percentage> \| auto` | `0`     | `m-* mx-* ml-* mr-* -m* mx-auto` |
| `--_margin-block-start` · `--_margin-block-end`     | `<length-percentage> \| auto` | `0`     | `m-* my-* mt-* mb-* -m* my-auto` |

The margin variables accept `auto` in their registered syntax, which is why `mx-auto` composes
exactly like a size value. The same pattern (composing rule + per-edge setter) powers
[border radius](/docs/base/utilities/borders#border-radius); see the
[overview](/docs/base/utilities#composition-variables-registered-non-inheriting) for the full model.


# Text & font (/docs/foundation/utilities/text-and-font)



These are the typographic helper utilities in `_utilities.css`: alignment, casing, font family,
and fine-grained text-flow controls. The fluid **size scale** (`text-h1`, `text-sm`, …) and
**weight** utilities live in the type system (see
[Typography in the overview](/docs/getting-started/overview#typography)), and [text color](/docs/base/utilities/text-color)
covers the color roles.

## Text align [#text-align]

| Class          | Declaration           |
| -------------- | --------------------- |
| `text-left`    | `text-align: left`    |
| `text-center`  | `text-align: center`  |
| `text-right`   | `text-align: right`   |
| `text-justify` | `text-align: justify` |

All four have responsive variants, e.g. `text-center @md:text-left`.

## Text transform [#text-transform]

| Class         | Declaration                  |
| ------------- | ---------------------------- |
| `uppercase`   | `text-transform: uppercase`  |
| `lowercase`   | `text-transform: lowercase`  |
| `capitalize`  | `text-transform: capitalize` |
| `normal-case` | `text-transform: none`       |

<Callout type="info">
  House style is **sentence case** for UI text: headings, buttons, links, labels, and nav. Reach for
  `uppercase` only when a design genuinely calls for it (the eyebrow style already handles its own
  caps).
</Callout>

## Font family [#font-family]

Three stacks, mapped to the family tokens.

| Class        | Token               |
| ------------ | ------------------- |
| `font-sans`  | `var(--font-sans)`  |
| `font-serif` | `var(--font-serif)` |
| `font-mono`  | `var(--font-mono)`  |

## Text wrapping & overflow [#text-wrapping--overflow]

Modern text-flow controls for cleaner typesetting and truncation.

| Class          | Declaration                          | Use                                     |
| -------------- | ------------------------------------ | --------------------------------------- |
| `text-balance` | `text-wrap: balance`                 | even line lengths in short headings     |
| `text-pretty`  | `text-wrap: pretty`                  | avoid orphans in body copy              |
| `leading-none` | `line-height: 1`                     | tight, single-line labels               |
| `tabular-nums` | `font-variant-numeric: tabular-nums` | aligning figures in tables and counters |

### Line clamp [#line-clamp]

Truncate to a fixed number of lines with an ellipsis. `line-clamp-1` … `line-clamp-6` set the
line count.

| Class          | Lines |
| -------------- | ----- |
| `line-clamp-1` | 1     |
| `line-clamp-2` | 2     |
| `line-clamp-3` | 3     |
| `line-clamp-4` | 4     |
| `line-clamp-5` | 5     |
| `line-clamp-6` | 6     |

```html
<h3 class="text-h3 text-balance">A headline that wraps onto evenly balanced lines</h3>
<p class="text-sm text-muted-foreground line-clamp-2">
  A two-line teaser that truncates with an ellipsis once it runs past the second line…
</p>
```


# Text color (/docs/foundation/utilities/text-color)



`text-*` color utilities read the **theme role tokens**, which resolve through `light-dark()`. Use
a role (not a literal scale step) and both light and dark modes stay correct with no extra
classes. Every value is computed as `oklch(from var(--role) l c h / calc(alpha × --_text-alpha))`,
so the [color-opacity](/docs/base/utilities/color-opacity) utilities can dim just the text channel.

## Surfaces & text [#surfaces--text]

Paired surface/`-foreground` roles. Use the foreground on top of its matching surface.

| Class                                    | Token                              |
| ---------------------------------------- | ---------------------------------- |
| `text-background`                        | `--background`                     |
| `text-foreground`                        | `--foreground`                     |
| `text-card` / `text-card-foreground`     | `--card` / `--card-foreground`     |
| `text-input` / `text-input-foreground`   | `--input` / `--input-foreground`   |
| `text-border` / `text-border-foreground` | `--border` / `--border-foreground` |

## Dim & fade [#dim--fade]

| Class                                  | Token                            | Use                                              |
| -------------------------------------- | -------------------------------- | ------------------------------------------------ |
| `text-muted` / `text-muted-foreground` | `--muted` / `--muted-foreground` | secondary, lower-emphasis text (captions, hints) |
| `text-faded` / `text-faded-foreground` | `--faded` / `--faded-foreground` | the lightest readable text                       |

`text-muted-foreground` is the everyday choice for captions and secondary copy.

## Brand [#brand]

| Class                                          | Token                                    |
| ---------------------------------------------- | ---------------------------------------- |
| `text-primary` / `text-primary-foreground`     | `--primary` / `--primary-foreground`     |
| `text-secondary` / `text-secondary-foreground` | `--secondary` / `--secondary-foreground` |
| `text-tertiary` / `text-tertiary-foreground`   | `--tertiary` / `--tertiary-foreground`   |

## Status [#status]

| Class                                              | Token                                        |
| -------------------------------------------------- | -------------------------------------------- |
| `text-info` / `text-info-foreground`               | `--info` / `--info-foreground`               |
| `text-success` / `text-success-foreground`         | `--success` / `--success-foreground`         |
| `text-warning` / `text-warning-foreground`         | `--warning` / `--warning-foreground`         |
| `text-destructive` / `text-destructive-foreground` | `--destructive` / `--destructive-foreground` |

## Absolute [#absolute]

| Class        | Token     | Note                           |
| ------------ | --------- | ------------------------------ |
| `text-white` | `--white` | does **not** flip in dark mode |
| `text-black` | `--black` | does **not** flip in dark mode |

```html
<p class="text-foreground">Primary copy.</p>
<p class="text-sm text-muted-foreground">Secondary, lower-emphasis copy.</p>
<p class="text-destructive">Something went wrong.</p>
```

## Variants [#variants]

* **Hover:** every role above has a `hover:text-*` counterpart. See [Hover states](/docs/base/utilities/hover).
* **Opacity:** dim just the text channel (not the whole element) with `text-opacity-*`. See
  [Color opacity](/docs/base/utilities/color-opacity).

<Callout type="info">
  The fluid **type scale** (`text-display`, `text-h1`–`text-h6`, `text-xl`–`text-xs`,
  `text-eyebrow`) and **font-weight** utilities live in the type system, not the utilities layer.
  See [Typography in the overview](/docs/getting-started/overview#typography). For alignment,
  transform, wrapping, and family, see [Text & font](/docs/base/utilities/text-and-font).
</Callout>