# Introduction (/docs)



Zazz is a variables-driven design framework built on native web standards: tokens, cascade layers, and browser APIs. It requires no build step, avoids framework lock-in, and eliminates selector specificity conflicts.

## Principles [#principles]

* **Tool-agnostic:** Shared tokens and structures work across Figma, HTML, and web frameworks.
* **Precision:** Spacing, color, radius, and typography resolve from CSS variables on `:root`.
* **Defaults:** Ready-to-use component styling with built-in light and dark theme support.
* **Standards-based:** Uses native HTML elements and CSS features (Popover, `<dialog>`, Invoker Commands, `@layer`, and container queries).

## Architecture [#architecture]

1. **Tokens:** Semantic variables (`--primary`, `--muted-foreground`, `--gap-md`) control the theme.
2. **Cascade layers:** Later layers (`utilities`) cleanly override earlier layers (`components`) without `!important`.
3. **Data attributes:** Variants use attributes like `data-variant="primary"` and `data-size="sm"` instead of modifier classes.
4. **Fluid scales:** Fluid `clamp()` typography and spacing scale with the viewport without breakpoint jumps.


# Accordion (/docs/components/accordion)



A `<ui-accordion>` wraps native `<details>` and `<summary>` elements. The class form `<div class="ui-accordion">` is equivalent: the tag is CSS-only without JavaScript. Expand and collapse states, keyboard interactions, and animations (via `::details-content`) run natively in the browser.

## Default [#default]

<Preview src="accordion/accordion" />

Structure each panel as a `<details class="border-b">` containing a `<summary class="font-strong hover:text-muted-foreground">` with an SVG chevron, followed by a body `<div>`. Multiple panels can open simultaneously. Give `<details>` items matching `name` attributes for mutual exclusion.

Customize using tokens: `--ui-accordion-icon-size` and `--ui-accordion-icon-transform-open`.


# Alert dialog (/docs/components/alert-dialog)



An alert dialog is a [Dialog](/docs/components/dialog) with a stricter contract: `<dialog class="ui-dialog ui-alert-dialog" role="alertdialog" closedby="none">`. There is no close button and no light dismiss; Cancel or Confirm buttons are the only ways to dismiss it. It composes standard dialog slots (`dialog-content`, `dialog-header`, `dialog-body`, `dialog-footer`) and uses a native `<dialog>` opened with Invoker Commands.

Give the dialog `aria-labelledby` pointing to the heading and `aria-describedby` pointing to the body so the prompt and its consequences are announced together.

## Default [#default]

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

## API [#api]

| Attribute    | Target             | Values                                              |
| ------------ | ------------------ | --------------------------------------------------- |
| `command`    | Trigger            | `show-modal`; `close` on the Cancel/Confirm buttons |
| `commandfor` | Trigger            | Target `<dialog>` id                                |
| `role`       | `.ui-alert-dialog` | `alertdialog`                                       |
| `closedby`   | `.ui-alert-dialog` | `none`: the alert contract                          |


# Autocomplete (/docs/components/autocomplete)



A `<ui-autocomplete>` wraps a `.ui-input` and an anchored suggestion panel (`popover="manual"`). The input holds the form value (free text allowed) and typing filters the panel options using the cmdk ranking algorithm. Arrow keys move the highlight without moving focus out of the input (`aria-activedescendant`). Pressing Enter or clicking commits a suggestion into the input. Groups hide automatically when all their options filter out, and the empty slot appears when nothing matches. Without JavaScript, the markup renders as a regular text input.

Omit the `popover` attribute on the panel for an inline, always-open list (no floating surface or dismissal; filtering unchanged).

## Default [#default]

<Preview src="autocomplete/autocomplete" />

## Groups and score ranking [#groups-and-score-ranking]

`data-sort="score"` re-ranks visible options by match quality using CSS `order` without altering the DOM tree. `data-keywords` adds extra search keywords to an option.

<Preview src="autocomplete/autocomplete-groups" />

## API [#api]

| Attribute                  | Target                             | Values                                          |
| -------------------------- | ---------------------------------- | ----------------------------------------------- |
| `data-sort`                | Root                               | `score`: rank by match (default: DOM order)     |
| `data-min-length`          | Root                               | Query length before the panel opens (default 0) |
| `data-value`               | `[data-slot="autocomplete-item"]`  | Match/commit text (default: text content)       |
| `data-keywords`            | `[data-slot="autocomplete-item"]`  | Space-separated extra match targets             |
| `data-side` / `data-align` | `[data-slot="autocomplete-panel"]` | Placement (popover matrix)                      |


# Avatar (/docs/components/avatar)



Avatars are composed with utility classes. Stack an image over fallback text using `grid grid-area-pile`, clip with `rounded-full overflow-clip`, and set dimensions with `size-*`.

Fallback text (`bg-muted`, `text-muted-foreground`) shows if the image fails to load. For text-only avatars, omit the `<img>` element.

## Default [#default]

<Preview src="avatar/avatar" />


# Badge (/docs/components/badge)



Badges use the `.ui-badge` class. Set colors with `data-variant` (default when omitted). Set `data-size="icon"` for square icon badges.

Badges can be static `<span>` elements or interactive `<button>` / `<a>` elements with hover/active states and disabled styling.

## Variants [#variants]

<Preview src="badge/badge" />

## Icon badge [#icon-badge]

Include `<span class="sr-only">` for accessible names on icon-only badges:

<Preview src="badge/badge-icon" />

## API [#api]

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

To apply status colors, override component tokens:

```html
<span
  class="ui-badge"
  style="--ui-badge-background: var(--success); --ui-badge-foreground: var(--success-foreground)"
>
  Active
</span>
```


# Breadcrumbs (/docs/components/breadcrumbs)



Breadcrumbs are composed using standard elements: a `<nav>` wrapping a `<menu>` of link buttons (`<a class="ui-button" data-variant="link">`) separated by `<span class="text-muted-foreground opacity-50">/</span>`.

The active page is rendered as a non-interactive `<div class="ui-button" data-variant="link" aria-disabled="true">`.

## Default [#default]

<Preview src="breadcrumbs/breadcrumbs" />


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



Wrap `.ui-button` elements in a `<ui-button-group>` (or the equivalent `<div class="ui-button-group">`) to combine them into a single segmented control. The container squares inner corners and collapses borders. Add `role="group"` and `aria-label` for accessibility.

## Horizontal [#horizontal]

Horizontal layout is the default:

<Preview src="button-group/button-group" />

## Vertical [#vertical]

Add `data-orientation="vertical"` to stack buttons:

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

## API [#api]

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

Outer corners adapt to child button `--ui-button-radius` tokens automatically.


# Button (/docs/components/button)



Buttons use the `.ui-button` class on `<button>` or `<a>` elements. Choose styles with `data-variant` and dimensions with `data-size`. Omitting `data-variant` applies the default style.

## Variants [#variants]

<Preview src="button/button" />

## With icons [#with-icons]

Add an inline `<svg>` inside the button. Icons are sized automatically:

<Preview src="button/button-icon" />

## Icon-only [#icon-only]

Use `data-size="icon"` or `data-size="icon-sm"` for square buttons:

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

## With keyboard shortcuts [#with-keyboard-shortcuts]

Add a `<kbd>` element inside the button for shortcut keys. Wrap a run of keys in a [`<ui-kbd-group>`](/docs/components/kbd) so their spacing stays consistent:

```html
<button class="ui-button">
  Search
  <ui-kbd-group><kbd>⌘</kbd><kbd>K</kbd></ui-kbd-group>
</button>
```

## API [#api]

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

Customize buttons globally by overriding `--ui-button-background`, `--ui-button-radius`, `--ui-button-height`, etc. on `:root`.


# Card (/docs/components/card)



Cards are composed using utility classes. Wrap `bg-card text-card-foreground` in a `rounded-md shadow-sm overflow-clip` container, then structure header, media, text, and footer elements using utilities.

## Default [#default]

<Preview src="card/card" />

## Subgrid alignment [#subgrid-alignment]

Use `grid-rows-*` and `grid-rows-subgrid` to align card headers, content, and actions across columns:

<Preview src="card/card-subgrid" />


# Carousel (/docs/components/carousel)



`<ui-carousel>` initializes an Embla carousel with markup-driven options, drag interactions, looping, keyboard navigation, and thumbnail synchronization.

## Default [#default]

<Preview src="carousel/carousel" />

## Anatomy [#anatomy]

The root is the `<ui-carousel>` element itself; interior parts are marked with `data-slot="carousel-{part}"`. Set slide widths with `basis-*` utilities:

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

| `data-slot` value                 | Purpose                                          |
| --------------------------------- | ------------------------------------------------ |
| `carousel-viewport`               | Visible window (required)                        |
| `carousel-container`              | Flex track for slides                            |
| `carousel-slide`                  | Individual slide item                            |
| `carousel-prev` / `carousel-next` | Navigation buttons (optional)                    |
| `carousel-dots` / `carousel-dot`  | Pagination container and template dot (optional) |
| `carousel-thumbs`                 | Synchronized thumbnail container (optional)      |

`data-slot` is a space-separated token list, so an element can serve two primitives at once: a lightbox slide is also a carousel slide (`data-slot="lightbox-slide carousel-slide"`). Selectors match slots with `[data-slot~="carousel-slide"]`.

## Setup [#setup]

Load `index.js` as an ES module:

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

Third-party dependencies (Embla core and plugins) resolve through the `<script type="importmap">` in `<head>`.

## Options [#options]

Configure Embla options as `data-carousel-*` attributes on `<ui-carousel>`:

| Attribute                | Purpose                           |
| ------------------------ | --------------------------------- |
| `data-carousel-loop`     | Set to `"true"` for infinite loop |
| `data-carousel-align`    | `start`, `center`, or `end`       |
| `data-carousel-keyboard` | Set to `"false"` to disable keys  |

### Plugins [#plugins]

Enable plugins with a space-separated `data-carousel-plugins` list. Configure each plugin with its option prefix; setting options alone will not load the plugin.

```html
<ui-carousel data-carousel-plugins="autoplay" data-carousel-autoplay-delay="3000">
  ...
</ui-carousel>
```

| Plugin      | Slug          | Options prefix                | Package specifier            |
| ----------- | ------------- | ----------------------------- | ---------------------------- |
| Autoplay    | `autoplay`    | `data-carousel-autoplay-*`    | `embla-carousel-autoplay`    |
| Auto Scroll | `auto-scroll` | `data-carousel-auto-scroll-*` | `embla-carousel-auto-scroll` |
| Class Names | `class-names` | `data-carousel-class-names-*` | `embla-carousel-class-names` |

## Dots pagination [#dots-pagination]

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

The script clones the template button for each slide and toggles `.is-active`.

## Thumbnail navigation [#thumbnail-navigation]

Nest a `data-slot="carousel-thumbs"` container inside `<ui-carousel>` for synchronized thumbnail strips.

## Dialog integration [#dialog-integration]

Carousels inside closed `<dialog>` elements defer initialization until the modal opens. Add `data-carousel-start="2"` to the trigger button to open at an exact slide.

## Dynamic re-initialization [#dynamic-re-initialization]

After inserting new HTML into the page:

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


# Checkbox (/docs/components/checkbox)



Checkboxes restyle native `<input type="checkbox">` elements. Bind state using standard `checked`, `name`, and `value` attributes.

## Default [#default]

<Preview src="checkbox/checkbox" />

## Indeterminate [#indeterminate]

The mixed state is always *derived* — HTML has no `indeterminate` attribute, only the JS `input.indeterminate` property, styled via native `:indeterminate`. Let a select-all group derive it (below), or set the property from your own script:

```js
input.indeterminate = true; // cleared natively when the user clicks
```

## Select-all groups [#select-all-groups]

A controller checkbox with `data-checkbox-controls="<name>"` manages every checkbox sharing that `name` in the same form (or the document when unassociated). Checking it checks or unchecks all members; member changes roll back up as checked, unchecked, or indeterminate for a subset. Members inside a table row also reflect onto the `<tr>` as `data-state="selected"`.

<Preview src="checkbox/checkbox-tasklist" />


# Combobox (/docs/components/combobox)



A `<ui-combobox>` looks like a select and filters like an autocomplete, but never submits free text. The form value lives in an authored hidden input (`data-slot="combobox-value"`), synced whenever the selection changes. Options match against their visible label and carry their machine value in `data-value`. Selected options get `aria-selected` and the shared option checkmark.

The visible input carries a **display value, not the filter**. Committing writes the option label into the input and clears the query. Reopening by clicking the control or chevron shows the full list with the committed row checked, matching [Select](/docs/components/select). Opening selects that label so the first keystroke replaces it. Focus alone does not open the panel, keeping keyboard tab navigation quiet. On blur, stray text reverts to the committed label, and cleared text clears the selection.

Omit the `popover` attribute on the panel for the **inline variant**: the list renders in flow and stays open without a floating surface, chevron, or dismissal. Filtering, highlighting, and committing work identically. This variant fits inside surfaces that already float, such as a [Menubar](/docs/components/menubar) help menu.

Without JavaScript this control remains inert. When a no-JS fallback is required, use [Select](/docs/components/select) instead.

## Default [#default]

<Preview src="combobox/combobox" />

## Multiselect [#multiselect]

Add `data-variant="multiselect"` to select a set of values. Committing toggles a row instead of replacing the selection, and the panel stays open to allow multiple picks. Each selected value renders as a removable tag inside the control while the input continues filtering beside them. Pressing Backspace on an empty input removes the last tag, and the control wraps onto extra rows as tags accumulate.

**A tag's markup is HTML, not script.** Author a `<template data-slot="combobox-tag-template">` and the combobox clones it once per selected value, filling in the label (`combobox-tag-label`), the value, and the remove button's accessible name (`combobox-tag-remove`). Changing the badge variant, adding an icon, or swapping the component requires no script changes. Omitting the template uses the default muted badge.

Options with `aria-selected="true"` are the single source of truth. Tags and hidden inputs derive from them in DOM order. The form submits repeated `name` pairs like `<select multiple>`: the authored hidden input carries the first value, and stamped siblings carry the rest. Because tags are stamped by script, server-rendered selections stay invisible without JavaScript (though values still submit). Where server-rendered initial state matters, use [`<ui-multiselect>`](/docs/components/select) instead.

<Preview src="combobox/combobox-multiselect" />

## API [#api]

| Attribute                  | Target                         | Values                                               |
| -------------------------- | ------------------------------ | ---------------------------------------------------- |
| `data-variant`             | Root                           | `multiselect`: select a set, shown as removable tags |
| `data-label-remove`        | Root                           | Tag remove-button label (default: `Remove {label}`)  |
| `data-slot`                | `<template>` in the root       | `combobox-tag-template`: tag blueprint (optional)    |
| `data-value`               | `[data-slot="combobox-item"]`  | Submitted value (label is the match text)            |
| `data-keywords`            | `[data-slot="combobox-item"]`  | Space-separated extra match targets                  |
| `aria-selected`            | `[data-slot="combobox-item"]`  | `true` seeds the selection from markup               |
| `data-sort`                | Root                           | `score`: rank by match (default: DOM order)          |
| `data-min-length`          | Root                           | Characters before typing opens the panel             |
| `name` / `value`           | `[data-slot="combobox-value"]` | The hidden input the form submits                    |
| `data-side` / `data-align` | `[data-slot="combobox-panel"]` | Placement (popover matrix)                           |


# Command (/docs/components/command)



A `<ui-command>` is a cmdk-style palette with the search input inside its panel. The panel is either a `popover="auto"` dropdown (native light dismiss with a `popovertarget` trigger) or a `<dialog class="ui-dialog">` (modal style with a `command="show-modal"` trigger). Items rank by match score, the best match auto-highlights, and Enter activates the highlighted item just like a click.

Actions use native platform attributes. Navigation items are real `<a href>` links, and action items are `<button command commandfor>` invoker buttons. Opening a dialog or popover requires no custom glue code, and custom `--commands` dispatch directly to target elements. Every activation dispatches a bubbling `zazz:command-select` event (`detail: { item, value }`) from the root. Without JavaScript, the trigger still opens the panel natively and items remain clickable; only live filtering, ranking highlights, and hotkeys are skipped.

## Popover [#popover]

<Preview src="command/command" />

## Dialog [#dialog]

<Preview src="command/command-dialog" />

## Custom actions [#custom-actions]

Simple actions need no script. For custom logic, register a `--command` handler on the invoker target, or listen for `zazz:command-select`. The loaded `command-actions.js` in this example is a template you can adapt.

<Preview src="command/command-actions" />

## API [#api]

| Attribute                      | Target                                 | Values                                                |
| ------------------------------ | -------------------------------------- | ----------------------------------------------------- |
| `data-command-hotkey`          | Root                                   | Global toggle shortcut, e.g. `mod+k`                  |
| `data-hotkey`                  | `[data-slot="command-item"]`           | Global accelerator that activates the item            |
| `data-stay-open`               | `[data-slot="command-item"]`           | Keep the panel open after activation                  |
| `data-sort`                    | Root                                   | `document`: opt out of score ranking (default: score) |
| `command` / `commandfor`       | `[data-slot="command-item"]`           | Native or custom (`--…`) invoker action               |
| `data-value` / `data-keywords` | `[data-slot="command-item"]`           | Match text / extra match targets                      |
| `data-side` / `data-align`     | `[data-slot="command-panel"][popover]` | Placement (popover form only)                         |


# Dialog (/docs/components/dialog)



Dialogs use native `<dialog class="ui-dialog">` elements. Open from buttons with `command="show-modal"` and `commandfor="<id>"`. Close with `command="close"`. Add `closedby="any"` for light-dismiss on backdrop click.

## Default [#default]

<Preview src="dialog/dialog" />

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

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

## API [#api]

| Attribute    | Target       | Values                           |
| ------------ | ------------ | -------------------------------- |
| `command`    | Trigger      | `show-modal`, `close`            |
| `commandfor` | Trigger      | Target `<dialog>` id             |
| `data-size`  | `.ui-dialog` | `article`, `container`, `screen` |
| `closedby`   | `<dialog>`   | `any`, `closerequest`, `none`    |

For a dialog that requires an explicit response before proceeding, see [Alert dialog](/docs/components/alert-dialog).


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



`.ui-input-group` wraps an `.ui-input` with `[data-slot="input-group-addon"]` elements. Position addons using `data-align`.

## Default [#default]

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

## Password group [#password-group]

Wraps inputs in `<ui-password>` to provide a password visibility toggle:

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

## API [#api]

| Attribute    | Target                            | Values                                                   |
| ------------ | --------------------------------- | -------------------------------------------------------- |
| `data-align` | `[data-slot="input-group-addon"]` | `inline-start`, `inline-end`, `block-start`, `block-end` |


# Input (/docs/components/input)



Inputs use the `.ui-input` class and share `--ui-field-*` design tokens. Validation styles trigger via `:user-invalid` on blur or submit. Wrap in `.ui-field` for label, hint, and error message layouts.

## Default [#default]

<Preview src="input/input" />

## Leading icon [#leading-icon]

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

## Trailing icon [#trailing-icon]

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


# Kbd (/docs/components/kbd)



The bare native `<kbd>` element renders as a key cap without needing an extra class. It sits in the reset layer, so component scopes restyle it by reassigning `--ui-kbd-*` tokens: keys retint inside a [Tooltip](/docs/components/tooltip) and shrink inside a [Button](/docs/components/button) without markup changes.

## Default [#default]

<Preview src="kbd/kbd" />

## Kbd group [#kbd-group]

Wrap a run of keys forming one shortcut in `<ui-kbd-group>` (or `.ui-kbd-group`). The group controls the spacing between adjacent keys through a single `--ui-kbd-group-gap` token, so shortcut hints look consistent across buttons, tooltips, command palettes, and prose instead of inheriting random parent gaps.

<Preview src="kbd/kbd-group" />

Inside a [Command](/docs/components/command) item, a lone `<kbd>` or `<ui-kbd-group>` automatically pushes to the inline end of the row.

## API [#api]

| Attribute | Target                            | Values                                                      |
| --------- | --------------------------------- | ----------------------------------------------------------- |
| Tokens    | `:root`                           | `--ui-kbd-*` (type, surface, metrics), `--ui-kbd-group-gap` |
| Icon      | `<svg>` child of `<kbd>`          | Sized by `--ui-kbd-icon-size`                               |
| Group     | `<ui-kbd-group>`, `.ui-kbd-group` | Wraps `<kbd>` children; gap = `--ui-kbd-group-gap`          |

Scoped restyling works through CSS inheritance by reassigning a token on any ancestor:

```css
.my-toolbar {
  --ui-kbd-background: var(--card);
  --ui-kbd-group-gap: var(--step-0_5);
}
```


# Lightbox (/docs/components/lightbox)



`<ui-lightbox>` coordinates an inline `<ui-carousel>` gallery with a fullscreen `<dialog>` carousel. Slides open the dialog using `command="show-modal"`. The component syncs slide indices between the inline and fullscreen carousels.

## Default [#default]

<Preview src="lightbox/lightbox" />

## Markup structure [#markup-structure]

| Markup                                                                         | Placement | Purpose                                          |
| ------------------------------------------------------------------------------ | --------- | ------------------------------------------------ |
| `<ui-lightbox>`                                                                | Root      | Coordinates gallery and modal state              |
| `<ui-carousel data-slot="lightbox-stage">`                                     | Gallery   | Inline carousel with drag and thumbnail support  |
| `<dialog class="ui-dialog" data-slot="lightbox-dialog">`                       | Root      | Fullscreen modal container                       |
| `<ui-carousel>`                                                                | Dialog    | Fullscreen carousel initialized when modal opens |
| `command="show-modal"` / `command="close"`                                     | Triggers  | Opens and closes dialog using Invoker Commands   |
| `data-slot="carousel-viewport"` / `"carousel-container"` / `"carousel-thumbs"` | Children  | Embla layout slots                               |
| `data-slot="lightbox-slide carousel-slide"`                                    | Slides    | Slide serving both primitives (see below)        |

Because `data-slot` is a space-separated token list, each slide carries two slots at once: the lightbox styles and syncs it as `lightbox-slide`, while Embla lays it out as `carousel-slide`. The same pattern applies to thumbnails (`data-slot="lightbox-thumb carousel-slide"`) and the thumbnail strip (`data-slot="lightbox-thumbs carousel-thumbs"`).


# Menu (/docs/components/menu)



A `<ui-menu>` wraps a trigger button (`popovertarget`) and its `[data-slot="menu-popover"]` panel (`popover="auto"`). The class form `<div class="ui-menu">` is equivalent and needs no JavaScript. The root names the trigger plus panel assembly, while the native `<menu>` element remains the list inside the panel. Menu items use ghost buttons. Position the panel with `data-side` and `data-align`.

When the kit script is loaded, the tag form adds arrow-key navigation: ArrowDown/ArrowUp on the closed trigger opens the panel and focuses the first or last item. Inside the panel, arrow keys navigate between items (wrapping and skipping disabled items), and Home/End jump to the ends. Escape and light dismiss remain standard Popover API behavior.

## Default [#default]

<Preview src="menu/menu" />

## Hover open [#hover-open]

Add `interestfor` alongside `popovertarget` (pointing to the same panel id) to open the menu on hover, focus, or long-press via the Interest Invokers API. Clicking still toggles, and `popover="auto"` maintains light dismiss.

<Preview src="menu/menu-interest" />

## Accessibility [#accessibility]

The menu is a disclosure pattern of links and buttons rather than an ARIA `role="menu"`. The `menu` role carries a strict menu keyboard contract (menuitem roles, typeahead, close-on-activate) meant for desktop app toolbars rather than website navigation. `popovertarget` already communicates expanded and collapsed state to assistive technology. If every item in your panel represents an application action, you can add `role="menu"` and `role="menuitem"` attributes directly.

## API [#api]

| Attribute       | Target                       | Values                                            |
| --------------- | ---------------------------- | ------------------------------------------------- |
| `popovertarget` | Trigger                      | ID of `[data-slot="menu-popover"]` (click toggle) |
| `interestfor`   | Trigger                      | Same ID: adds hover/focus open (optional)         |
| `data-side`     | `[data-slot="menu-popover"]` | `top`, `bottom`, `left`, `right`                  |
| `data-align`    | `[data-slot="menu-popover"]` | `start`, `center`, `end`                          |


# Menubar (/docs/components/menubar)



Menubars are composed from primitives: like [Toolbar](/docs/components/toolbar), there is no separate `.ui-menubar` class or stylesheet. A utility container (`inline-flex items-center gap-px bg-card rounded-md shadow-sm p-xs`) holds a row of [Menu](/docs/components/menu) primitives. Each trigger carries `popovertarget` and `interestfor` pointing at its panel so menus open on click or hover. Because only one `popover="auto"` can be open per stack, hovering an adjacent trigger closes the previous menu automatically, giving you the classic menubar glide without JavaScript.

## Default [#default]

<Preview src="menubar/menubar" />

## Help menu with search [#help-menu-with-search]

A menu panel can hold richer content than a list: here the Help menu embeds a [Combobox](/docs/components/combobox) for searching topics.

<Preview src="menubar/menubar-help-search" />

## Accessibility [#accessibility]

The container deliberately omits `role="menubar"`. That role requires a single tab stop with roving arrow-key focus across triggers, which a static composition does not provide. Instead, every trigger remains natively tabbable, and each open menu provides arrow-key navigation through the menu script. Provide an `aria-label` describing the group on the container.

## API [#api]

| Attribute                       | Target       | Values                             |
| ------------------------------- | ------------ | ---------------------------------- |
| (container)                     | any element  | Utility recipe, no component class |
| `popovertarget` + `interestfor` | Each trigger | Same panel id: click + hover glide |


# Meter (/docs/components/meter)



A native `<meter class="ui-meter">` element, styled as a visual companion to the [Progress](/docs/components/progress) bar (its geometry aliases the `--ui-progress-*` tokens). Where progress communicates completion, a meter indicates quality or capacity. The fill color is `--success` in the optimal region and shifts to `--warning` or `--destructive` as the value crosses `low` or `high` relative to `optimum`. Always include fallback text content and a label.

Engines supporting typed `attr()` paint the fill on the element itself from the meter attributes (Blink locks its shadow parts geometry). Other engines use vendor fill pseudo-elements to carry the colors.

## Default [#default]

<Preview src="meter/meter" />

## API [#api]

| Attribute                  | Target      | Values                                             |
| -------------------------- | ----------- | -------------------------------------------------- |
| `value` / `min` / `max`    | `.ui-meter` | Native meter semantics                             |
| `low` / `high` / `optimum` | `.ui-meter` | Region thresholds that drive the fill color        |
| Tokens                     | `:root`     | `--ui-meter-*`; geometry aliases `--ui-progress-*` |


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



The mobile menu combines a native `<dialog>` with nested `<details>` accordions. Trigger with `command="show-modal"` and `commandfor="<id>"`. Close with `command="close"` or backdrop light-dismiss via `closedby="any"`.

## Default [#default]

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

## Markup template [#markup-template]

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

<!-- Menu -->
<dialog
  id="mobile-menu-1"
  class="ui-dialog ui-mobile-menu"
  data-size="screen"
  data-animation="slide-right"
  closedby="any"
>
  <div data-slot="mobile-menu-viewport">
    <div data-slot="mobile-menu-header">...</div>
    <div data-slot="mobile-menu-body">
      <div class="ui-accordion">
        <details>
          <summary class="ui-button" data-variant="ghost">Section</summary>
          <div class="flex flex-col pb-sm">
            <!-- Nav links -->
          </div>
        </details>
      </div>
    </div>
    <div data-slot="mobile-menu-footer">...</div>
  </div>
</dialog>
```

## Tokens [#tokens]

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

## API [#api]

| Attribute        | Target            | Values                        |
| ---------------- | ----------------- | ----------------------------- |
| `command`        | Trigger           | `show-modal`, `close`         |
| `commandfor`     | Trigger           | Target dialog ID              |
| `data-size`      | `.ui-mobile-menu` | `screen`                      |
| `data-animation` | `.ui-mobile-menu` | `slide-right`                 |
| `closedby`       | `<dialog>`        | `any`, `closerequest`, `none` |


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



The navigation menu is rooted on a semantic `<nav class="ui-navigation-menu">` (class form only, since the native element carries the meaning) and combines button triggers (`popovertarget`) with `[data-slot="navigation-menu-popover"]` panels. `[data-slot="navigation-menu-list"]` contains items and triggers. Panels contain a `[data-slot="navigation-menu-viewport"]` grid of `[data-slot="navigation-menu-link"]` items and optional `[data-slot="navigation-menu-submenu"]` flyouts.

## Default [#default]

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

## Hover open [#hover-open]

Add `interestfor` alongside `popovertarget` (same panel id) on any trigger to open its panel on hover, focus, or long-press. This uses the Interest Invokers API. Clicking still works, and the popover auto stack closes the previous panel as the next opens.

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

## Featured panel [#featured-panel]

A common content-site layout: link rows beside a featured card, arranged with grid utilities inside the viewport.

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

## Icon grid [#icon-grid]

Tiles of icon, title, and description, each wrapped as a `navigation-menu-link` laid out with flex utilities.

<Preview src="navigation-menu/navigation-menu-icon-grid" />

## Megamenu [#megamenu]

A full-width panel using `data-size="container"` to size the popover to the whole menu bar via `anchor-size()`, holding columns of link groups with eyebrow labels.

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

## Simple menus and search [#simple-menus-and-search]

Rule of thumb: use a [Menu](/docs/components/menu) when a nav item is a flat list of links, and a navigation-menu panel when it requires grid or multi-column layout. A `<ui-menu>` works as a nav item (reset `--ui-popover-inline-size` on its panel so wide navigation sizing does not inherit into it), and a `.ui-input[type="search"]` fits at the end of the bar. For full site search palettes, see [Command](/docs/components/command).

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

## API [#api]

| Attribute        | Target                                  | Values                                    |
| ---------------- | --------------------------------------- | ----------------------------------------- |
| `popovertarget`  | Trigger                                 | ID of target panel                        |
| `interestfor`    | Trigger                                 | Same ID: adds hover/focus open (optional) |
| `data-align`     | `[data-slot="navigation-menu-popover"]` | `center`, `end`                           |
| `data-variant`   | `[data-slot="navigation-menu-popover"]` | `submenu`                                 |
| `data-size`      | `[data-slot="navigation-menu-popover"]` | `root`, `container`, `screen`             |
| `data-animation` | `[data-slot="navigation-menu-popover"]` | `slide-down`                              |


# OTP (/docs/components/otp)



A `<ui-otp>` wraps a real `<input class="ui-input ui-otp-input">` carrying standard OTP attributes: `autocomplete="one-time-code"`, `inputmode="numeric"`, `pattern`, and `maxlength`. It stamps an `aria-hidden` rail of character cells behind the input and stretches the input invisibly over the rail. The input remains the source of truth, so SMS autofill, clipboard paste, IME composition, form submission, and `:user-invalid` styling work natively while the visual cells mirror text entry. Without JavaScript, the element renders as a standard text input.

The code length comes from `maxlength`. Origin-bound SMS codes (`@example.com #123456`) autofill directly into the field.

## Default [#default]

<Preview src="otp/otp" />

## API [#api]

| Attribute              | Target             | Values                                                        |
| ---------------------- | ------------------ | ------------------------------------------------------------- |
| `maxlength`            | `.ui-otp-input`    | The code length (native)                                      |
| `data-otp-groups`      | `ui-otp`           | Separator layout, e.g. `3-3`, `2-2-2` (must sum to maxlength) |
| `data-otp-type`        | `ui-otp`           | `numeric` (default), `alpha`, `alphanumeric`, `none`          |
| `data-otp-mask`        | `ui-otp`           | Render `•` instead of characters                              |
| `data-otp-auto-submit` | `ui-otp`           | Submit the owning form once when complete                     |
| `data-otp-complete`    | `ui-otp` (stamped) | Present when every cell is filled                             |


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



`.ui-password-group` provides an input group with a trailing ghost button that toggles password visibility. Wrap with `<ui-password>` to enhance with JavaScript while remaining fully functional as a masked text input without JS.

## Default [#default]

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

## API [#api]

| Element / Attribute                   | Target          | Description                                  |
| ------------------------------------- | --------------- | -------------------------------------------- |
| `<ui-password>`                       | Wrapper         | Finds password input and toggles visibility  |
| `.ui-password-group`                  | Container       | Layout for input field and addon button      |
| `[data-slot="password-group-toggle"]` | Button          | Toggles input type between password and text |
| `data-label-show`                     | `<ui-password>` | Accessible label when password is hidden     |
| `data-label-hide`                     | `<ui-password>` | Accessible label when password is shown      |


# Progress (/docs/components/progress)



A native `<progress class="ui-progress">` element. The element box forms the themed track, and the fill comes from the browser native value rendering, recolored per engine. Always include fallback text content and either a `<label>` or `aria-label`. Omit the `value` attribute for an indeterminate bar.

## Default [#default]

<Preview src="progress/progress" />

## Indeterminate [#indeterminate]

<Preview src="progress/progress-indeterminate" />

## API [#api]

| Attribute       | Target         | Values                                         |
| --------------- | -------------- | ---------------------------------------------- |
| `value` / `max` | `.ui-progress` | Native progress semantics                      |
| *(no `value`)*  | `.ui-progress` | Indeterminate (animated stripe)                |
| Tokens          | `:root`        | `--ui-progress-*` (track, bar, height, radius) |


# Prose (/docs/components/prose)



Wrap unstyled HTML in `.ui-prose` to format headings, paragraphs, lists, tables, and blockquotes with standard spacing and typographic measure.

## Default [#default]

<Preview src="prose/prose" />


# Radio (/docs/components/radio)



Radios apply the `.ui-radio` class to native `<input type="radio">` controls. Group elements by assigning matching `name` attributes inside a `.ui-radio-group` container.

## Default [#default]

<Preview src="radio/radio" />


# Reveal (/docs/components/reveal)



Reveal triggers CSS entry transitions using `IntersectionObserver` when elements scroll into the viewport.

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

1. Add `data-reveal` or `data-reveal-each` to HTML elements.
2. The `Reveal` script observes elements and sets calculated CSS delay variables.
3. When scrolled into view, the element receives the `.in-viewport` class.
4. CSS transitions in `reveal.css` animate the element to visible.

## Setup [#setup]

Load `index.js` as an ES module and include `index.css`:

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

Reveal initializes automatically when the DOM loads.

## Single elements [#single-elements]

```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 right</div>
```

### Animation types [#animation-types]

| 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 fade                  |
| `grow`        | Scale up from smaller         |
| `shrink`      | Scale down from larger        |

## Stagger groups [#stagger-groups]

Animate child elements sequentially using `data-reveal-each`:

```html
<div data-reveal-each="fade" data-reveal-step="100">
  <div>Item 1 (first)</div>
  <div>Item 2 (100ms delay)</div>
  <div>Item 3 (200ms delay)</div>
</div>
```

Set `data-reveal-order="reversed"` to animate children in reverse order.

## Element transition isolation [#element-transition-isolation]

Reveal controls `transition-*` properties to handle delays and durations. To apply hover transitions (such as borders or background changes) without conflicting with scroll reveals, place the reveal attribute on a parent container:

```html
<div data-reveal-each="slide-up">
  <a class="bg-card border rounded-md transition hover:border-primary">Card 1</a>
  <a class="bg-card border rounded-md transition hover:border-primary">Card 2</a>
</div>
```

## Configuration attributes [#configuration-attributes]

| Attribute               | Default                       | Purpose                                           |
| ----------------------- | ----------------------------- | ------------------------------------------------- |
| `data-reveal-duration`  | `--ui-reveal-global-duration` | Animation duration                                |
| `data-reveal-wait`      | `0`                           | Base delay before starting (ms)                   |
| `data-reveal-step`      | `80`                          | Delay step between children (ms)                  |
| `data-reveal-ease`      | `--ui-reveal-global-ease`     | Timing function                                   |
| `data-reveal-distance`  | `1rem`                        | Slide translation distance                        |
| `data-reveal-scale`     | None                          | Scale value for grow/shrink                       |
| `data-reveal-margin`    | `0px`                         | Observer rootMargin                               |
| `data-reveal-threshold` | `0.2`                         | Intersection threshold (0 to 1)                   |
| `data-reveal-order`     | None                          | Set to `"reversed"` for reversed stagger sequence |

## Global tokens [#global-tokens]

```css
:root {
  --ui-reveal-global-duration: var(--default-transition-duration);
  --ui-reveal-global-ease: var(--default-transition-timing-function);
  --ui-reveal-global-wait: 0ms;
  --ui-reveal-global-distance: 1rem;
  --ui-reveal-global-grow: 0.97;
  --ui-reveal-global-shrink: 1.03;
}
```

## Dynamic updates [#dynamic-updates]

To observe newly inserted DOM elements:

```js
Reveal.getAutoInstance()?.refresh();
```


# Select (/docs/components/select)



`.ui-select` styles native `<select>` controls using `appearance: base-select`. Falls back to the standard OS dropdown where unsupported.

Requires a `<button><selectedcontent></selectedcontent></button>` as the first child of the `<select>` to serve as the trigger and mirror selection.

## Default [#default]

<Preview src="select/select" />

## Placement [#placement]

Use `data-side` and `data-align` on `.ui-select` to position the dropdown panel relative to the trigger button:

### Sides [#sides]

<Preview src="select/select-sides" />

### Alignment [#alignment]

<Preview src="select/select-align" />

## Multiple [#multiple]

`appearance: base-select` does not cover `<select multiple>` in any stable engine yet, so `<ui-multiselect>` progressively enhances a multi-select element into the same dropdown styling. The select is hidden but remains the form value carrier, while a stamped trigger and popover of checkbox rows (with the shared option checkmark) sync values both ways. The trigger displays `First selection (+N more)`. Without JavaScript, the native multi listbox renders and remains fully functional.

<Preview src="select/select-multiple" />

## API [#api]

| Attribute                  | Target           | Values                                   |
| -------------------------- | ---------------- | ---------------------------------------- |
| `data-side`                | `.ui-select`     | `top`, `bottom`, `left`, `right`         |
| `data-align`               | `.ui-select`     | `start`, `center`, `end`                 |
| `data-placeholder`         | `ui-multiselect` | Trigger text when nothing is selected    |
| `data-label-more`          | `ui-multiselect` | Overflow template, default `(+{n} more)` |
| `data-side` / `data-align` | `ui-multiselect` | Forwarded to the stamped panel           |


# Separator (/docs/components/separator)



`.ui-separator` styles the native `<hr>` element with its implicit `role="separator"` instead of rebuilding one from a div. `data-orientation="vertical"` turns it into a column rule that stretches to the row height in flex and grid layouts. Spacing uses composition: add margin utilities like `my-xs` or `mx-xs`.

Separators come in two types. A **meaningful** separator marks a content boundary that assistive tech should announce. Keep the implicit role and add `aria-orientation="vertical"` on the vertical form, because assistive tech assumes separators are horizontal by default. A **purely decorative** separator takes `role="presentation"` to stay out of the accessibility tree.

## Default [#default]

<Preview src="separator/separator" />

## API [#api]

| Attribute          | Target          | Values                                                           |
| ------------------ | --------------- | ---------------------------------------------------------------- |
| `data-orientation` | `.ui-separator` | `vertical`: column rule for flex/grid rows                       |
| `aria-orientation` | `.ui-separator` | `vertical`: pair with the above when the separator is meaningful |
| `role`             | `.ui-separator` | `presentation`: for purely decorative separators                 |
| Tokens             | `:root`         | `--ui-separator-color`, `--ui-separator-thickness`               |


# Slider (/docs/components/slider)



The slider restyles native `<input type="range">` elements. Configure with standard `min`, `max`, `step`, and `value` attributes.

## Default [#default]

<Preview src="slider/slider" />


# Switch (/docs/components/switch)



The switch restyles `<input type="checkbox" role="switch">` into a sliding toggle. Bind with `checked`, `name`, and `value`.

## Default [#default]

<Preview src="switch/switch" />


# Table (/docs/components/table)



Apply `.ui-table` to a standard `<table>` element (`<caption>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`). Rows include hover tints by default. Set `data-state="selected"` on a `<tr>` for selected styling.

Wrap wide tables in `<div class="overflow-x-auto">` for horizontal scrolling.

<Preview src="table/table" />

## Alternating rows [#alternating-rows]

Add `data-variant="alternating"` for zebra striping:

<Preview src="table/table-alternating" />

## Grid format [#grid-format]

Add `data-variant="grid"` for borders around all cells:

<Preview src="table/table-grid" />

## Compact size [#compact-size]

Add `data-size="sm"` to reduce cell padding:

<Preview src="table/table-size-sm" />

## API [#api]

| Attribute      | Values                                    |
| -------------- | ----------------------------------------- |
| `data-variant` | `alternating`, `grid` (omit = default)    |
| `data-size`    | `sm`                                      |
| `data-layout`  | `fixed` (omit = `table-layout: auto`)     |
| `data-state`   | `selected` (on a `<tr>`)                  |
| `data-side`    | `top` (on the `<caption>`; omit = bottom) |

Override styling tokens globally on `:root` or on an instance (`--ui-table-row-background--hover`, `--ui-table-alternating-background`).


# Tabs (/docs/components/tabs)



Tabs use grouped `input[type="radio"][role="tab"]` inputs to toggle panels and sliding indicators using pure CSS. Wrap in `<ui-tabs class="ui-tabs">` for keyboard navigation (arrow keys, Home/End, wrap-around). Radio button order must match tab panel order.

## Default [#default]

<Preview src="tabs/tabs" />

## API [#api]

| Attribute / Element | Placement | Values                                        |
| ------------------- | --------- | --------------------------------------------- |
| `<ui-tabs>`         | Root      | Custom element root; adds keyboard navigation |
| `data-orientation`  | Root      | `vertical` (horizontal by default)            |


# Textarea (/docs/components/textarea)



`.ui-textarea` shares `--ui-field-*` tokens and `:user-invalid` validation states with the form input family. It applies `field-sizing: content` to auto-expand with text input, clamped between `--ui-textarea-min-block-size` (`5lh`) and `--ui-textarea-max-block-size` (`12lh`).

## Default [#default]

<Preview src="textarea/textarea" />


# Toaster (/docs/components/toaster)



Toasts render inside `<ui-toaster class="ui-toaster" popover="manual">`, a custom element placed on the top layer via the Popover API.

Trigger toasts from buttons using `commandfor="<region id>"` and `command="--toast"`, or from JavaScript using `window.Toaster`.

Toasts auto-dismiss after 4 seconds (pausing on hover or when the browser tab is hidden). Place `<ui-toaster>` once per page outside `<main>`.

## Default [#default]

<Preview src="toaster/toaster" />

## API [#api]

| Attribute           | Target         | Values                                                                                        |
| ------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `command`           | Trigger        | `--toast`, `--toast-success`, `--toast-info`, `--toast-warning`, `--toast-destructive`        |
| `commandfor`        | Trigger        | ID of target `<ui-toaster>`                                                                   |
| `data-title`        | Trigger        | Toast title                                                                                   |
| `data-description`  | Trigger        | Toast body copy                                                                               |
| `data-variant`      | Trigger        | `success`, `info`, `warning`, `destructive`                                                   |
| `data-duration`     | Trigger        | Lifetime in ms (`Infinity` persists until dismissed)                                          |
| `data-close-button` | Trigger        | Set to `false` to hide close button                                                           |
| `data-position`     | `<ui-toaster>` | `top-start`, `top-center`, `top-end`, `bottom-start`, `bottom-center`, `bottom-end` (default) |
| `popover`           | `<ui-toaster>` | `manual` (required)                                                                           |

## JavaScript API [#javascript-api]

```js
// Create toast
const id = Toaster.toast({
  title: "Event created",
  description: "Monday, July 13 at 9:00 AM",
  variant: "success",
  duration: 4000,
  action: { label: "Undo", onClick: (event) => {} },
  closeButton: true,
  region: "my-toaster",
});

// Shorthands
Toaster.success("Changes saved");
Toaster.info("Update available");
Toaster.warning("Storage almost full");
Toaster.error("Something went wrong");

// Dismiss toast
Toaster.dismiss(id);
Toaster.dismiss(); // dismiss all
```


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



Wrap `.ui-toggle` elements in a `<ui-toggle-group>` (or the equivalent `<div class="ui-toggle-group">`) to combine them into a single segmented unit. Use `radio` inputs for **single-select** and `checkbox` inputs for **multi-select**. Add `role="group"` and `aria-label` for accessibility.

## Single select [#single-select]

<Preview src="toggle-group/toggle-group" />

## Multi select [#multi-select]

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

## Vertical [#vertical]

Add `data-orientation="vertical"` to stack items:

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

## API [#api]

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

Outer corners adapt to child `--ui-toggle-radius` tokens automatically.


# Toggle (/docs/components/toggle)



A toggle is a `<label class="ui-toggle">` wrapping a visually hidden `<input>` and button content. It shares styling with `.ui-button`. The checked state displays active button styles using pure CSS.

Use `checkbox` inputs for independent toggles; use `radio` inputs with matching `name` attributes for mutually exclusive choices.

## Variants [#variants]

<Preview src="toggle/toggle" />

## API [#api]

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

Tokens (`--ui-toggle-background`, `--ui-toggle-radius`, etc.) map to `--ui-button-*` tokens by default.


# Toolbar (/docs/components/toolbar)



Toolbars are composed, not shipped: a flex container of button groups, toggle groups, selects, and inputs using utility classes (`flex flex-row items-center gap-xs bg-card rounded-md shadow-sm p-xs`). Groups divide with vertical [Separators](/docs/components/separator) (`<hr class="ui-separator" data-orientation="vertical">`), and `ml-auto` pushes trailing controls to the end. There is no `.ui-toolbar` class or stylesheet.

## Default [#default]

<Preview src="toolbar/toolbar" />

## Accessibility [#accessibility]

The container deliberately omits `role="toolbar"`. That role requires a single tab stop with arrow-key roving focus between controls, which a static composition does not provide. Every control stays natively tabbable instead. Give the container an `aria-label` describing the group.


# Tooltip (/docs/components/tooltip)



A `<ui-tooltip>` wraps a trigger button and its `[data-slot="tooltip-content"]` popover (`popover="hint"`), connected via `interestfor` on the trigger. The class form `<div class="ui-tooltip">` is equivalent: the tag is CSS-only without JavaScript. Hover, focus, and long-press work automatically via the platform.

## Default [#default]

<Preview src="tooltip/tooltip" />

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

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

## Sides [#sides]

<Preview src="tooltip/tooltip-sides" />

## Disabled trigger [#disabled-trigger]

<Preview src="tooltip/tooltip-disabled" />

## API [#api]

| Attribute                | Target                          | Values                                |
| ------------------------ | ------------------------------- | ------------------------------------- |
| `interestfor`            | Trigger                         | ID of `[data-slot="tooltip-content"]` |
| `data-side`              | `[data-slot="tooltip-content"]` | `top`, `bottom`, `left`, `right`      |
| `data-align`             | `[data-slot="tooltip-content"]` | `center`                              |
| `data-use-inverted-menu` | `[data-slot="tooltip-content"]` | `false`                               |


# Utils (/docs/components/utils)



`utils.js` provides parsing utilities for component scripts. It parses HTML data-attribute strings into JavaScript values.

## Setup [#setup]

Included in `index.js`:

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

Exposes `window.Utils`.

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

Converts string attribute values to native JavaScript types:

```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 data attributes matching a prefix, converts kebab-case names to camelCase keys, and coerces values with `parseValue`:

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


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



Zazz structures color around **roles** (`primary`, `muted-foreground`, `card`) rather than static color values. Roles resolve through [`light-dark()`](/docs/core-concepts/dark-mode), making them theme-ready by default.

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

## Role reference [#role-reference]

### Surface and text pairs [#surface-and-text-pairs]

Each surface pairs with a high-contrast foreground:

| Surface      | Foreground          | Use                                |
| ------------ | ------------------- | ---------------------------------- |
| `background` | `foreground`        | Page background                    |
| `card`       | `card-foreground`   | Cards and raised containers        |
| `input`      | `input-foreground`  | Form input controls                |
| `muted`      | `muted-foreground`  | Dimmed surfaces and secondary copy |
| `faded`      | `faded-foreground`  | Faded surfaces and tertiary copy   |
| `border`     | `border-foreground` | Dividers and borders               |

The `popover` role (`--popover`, `--popover-foreground`) is consumed directly by popover and dialog components without separate `bg-` utilities.

### Brand roles [#brand-roles]

* `primary`, `primary-foreground`
* `secondary`, `secondary-foreground`
* `tertiary`, `tertiary-foreground`

### Status roles [#status-roles]

* `info`, `info-foreground`
* `success`, `success-foreground`
* `warning`, `warning-foreground`
* `destructive`, `destructive-foreground`

## Numeric scales and overlays [#numeric-scales-and-overlays]

Use numeric scales when you need a fixed color that does not switch with the theme:

* **Scales:** `--primary-50` to `--primary-950` (along with `secondary`, `tertiary`, `neutral`), `--white`, and `--black`. These exist as tokens only, without generated utility classes.
* **Overlays:** `--shade-*` (darken, derived from neutral-950) and `--tint-*` (lighten, derived from white). These include `bg-shade-*` and `bg-tint-*` utility classes for modal backdrops and image scrims.
* **Static colors:** `text-white`, `text-black`, `bg-white`, `bg-black`, `bg-transparent`.

## OKLCH color space [#oklch-color-space]

Zazz defines colors in [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch). Relative colors (`oklch(from ...)`) and `color-mix()` generate hover tints and translucent overlays with perceptual uniformity.

## Element opacity vs color opacity [#element-opacity-vs-color-opacity]

* **Element opacity (`opacity-*`):** Sets CSS `opacity` on the element and all descendants.
* **Color opacity (`bg-opacity-*`, `text-opacity-*`, `border-opacity-*`):** Sets `--_background-alpha` (or text/border alpha) without fading child elements.

```html
<!-- surface is translucent, text remains 100% opaque -->
<div class="bg-primary bg-opacity-25 text-foreground">...</div>
```

## Changing brand colors [#changing-brand-colors]

Update the `--primary` token on `:root`:

```css
:root {
  --primary: oklch(0.6 0.2 145);
}
```

See [Theme variables](/docs/foundation/variables) and [Adding custom styles](/docs/core-concepts/custom-styles).


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



Extend Zazz by loading custom styles after `index.css`:

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

## 1. Token overrides [#1-token-overrides]

Most customizations require updating variables rather than writing new rules:

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

```html
<!-- instance override -->
<div class="bg-card text-card-foreground rounded-md" style="--card: var(--muted)">...</div>
```

Token overrides preserve theme switching and layer relationships.

## 2. Custom utility classes [#2-custom-utility-classes]

Add custom utilities inside `@layer zazz.utilities`. Wrap selectors in `:where()` to maintain zero specificity:

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

## 3. Custom components [#3-custom-components]

Author new components inside `@layer zazz.components` using design tokens:

```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);
  }
}
```

Utilities will override component properties as expected.

## 4. Unlayered CSS [#4-unlayered-css]

Rules written outside of any `@layer` beat all layered rules in Zazz:

```css
.ui-button {
  border-radius: 0;
}
```

Use unlayered CSS only when intentionally bypassing the cascade layer order.

## Hierarchy of customization [#hierarchy-of-customization]

1. **Token overrides:** Best for colors, spacing, radius, and sizing.
2. **Layered rules:** Best for reusable utilities and custom components.
3. **Unlayered rules:** For absolute overrides across the system.


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



Zazz enables dark mode by default. `:root` declares `color-scheme: light dark`, and semantic role tokens resolve through `light-dark()`. Role-based styles adapt across themes without duplicated rules.

```html
<section class="bg-background text-foreground p-lg">
  <h2 class="text-h3">Works in both themes</h2>
  <p class="text-muted-foreground">Adapts automatically across light and dark modes.</p>
</section>
```

## How roles resolve [#how-roles-resolve]

Each semantic role specifies values for light and dark modes:

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

Use semantic roles (`--primary`, `--background`) to ensure theme compatibility. Use fixed scale steps (`--primary-600`) only when colors must remain static.

## Theme configuration modes [#theme-configuration-modes]

### 1. System preference (default) [#1-system-preference-default]

Include the `<meta name="color-scheme" content="light dark">` tag in `<head>` so native elements match OS preferences before styles load.

### 2. Manual toggle with `.dark` [#2-manual-toggle-with-dark]

Add the `.dark` class to `<html>` to pin dark mode:

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

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

Popovers and menus support an inverted scheme. Opt out using CSS variables or attributes:

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

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

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

Use an inline script in `<head>` to read preferences from `localStorage` and set the `.dark` class before first render:

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

## Section-level color scheme [#section-level-color-scheme]

Set `color-scheme` on a container to force a specific mode for a subtree (such as a code block):

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

## Browser support [#browser-support]

`color-scheme` is Baseline widely available. `light-dark()` is Baseline 2024 (Chrome/Edge 123, Firefox 120, Safari 17.5).


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



Zazz handles responsive design through fluid type/spacing scaling and container style query prefixes.

## Fluid sizing [#fluid-sizing]

* **Typography:** `text-*` classes use `clamp()` functions that scale with viewport width.
* **Spacing:** Spacing utilities derive from fluid interval tokens, reducing spacing on small viewports and expanding on desktop.

## Responsive prefixes [#responsive-prefixes]

Prefix layout utilities with `@xs:`, `@sm:`, `@md:`, `@lg:`, or `@xl:`. These apply style queries against centralized page breakpoint flags published by the `body` container:

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

Breakpoints activate at or above the given threshold:

| Prefix | Threshold | Token             |
| ------ | --------- | ----------------- |
| `@xs:` | >= 40rem  | `--breakpoint-xs` |
| `@sm:` | >= 48rem  | `--breakpoint-sm` |
| `@md:` | >= 64rem  | `--breakpoint-md` |
| `@lg:` | >= 80rem  | `--breakpoint-lg` |
| `@xl:` | >= 96rem  | `--breakpoint-xl` |

## Mobile-first authoring [#mobile-first-authoring]

Apply base utilities for the narrowest view, then add prefixed overrides for wider viewports:

```html
<!-- stacked on mobile, row layout from md up -->
<div class="flex flex-col @md:flex-row gap-md">...</div>
```

Supported responsive families include `container`, `display`, `grid-cols`, `grid-rows`, `flex-direction`, `text-align`, `align-items`, `justify-content`, `col-span`, `row-span`, `basis`, `table-layout`, and `caption-side`.

## Breakpoint-free responsive layouts [#breakpoint-free-responsive-layouts]

* **Auto-fit grids:** Combine `grid-flow-row` with `grid-cols-N` (where N > 1) for automatic column wrapping based on available width.
* **Gap-aware basis:** `basis-1/2`, `basis-1/3`, etc. automatically subtract gap values for wrapping flex rows.

```html
<div class="grid grid-flow-row grid-cols-3 gap-md">...</div>
```

## Browser support [#browser-support]

Zazz responsive utilities use container style queries. Supported in modern Chrome, Safari, and Firefox. Unsupported browsers fall back to the base layout.


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



Interactive states in Zazz use `hover:` utility prefixes combined with built-in framework defaults for focus rings, validation, and disabled elements.

## Hover [#hover]

Prefix utilities with `hover:` to apply styles on pointer hover:

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

<div class="bg-card rounded-md hover:opacity-75 transition">...</div>
```

Available `hover:` categories:

* **Text color:** `hover:text-primary` and all semantic roles.
* **Background:** `hover:bg-primary`, `hover:bg-transparent`, `hover:bg-none`.
* **Border:** `hover:border-primary`, `hover:border-destructive`.
* **Opacity:** `hover:opacity-0` to `hover:opacity-100`.
* **Scale:** `hover:scale-50` to `hover:scale-150`.

Pair with the `transition` utility for animated state changes.

## Focus [#focus]

Zazz configures a `:focus-visible` ring across all interactive elements in `_reset.css`:

```css
:where(:focus-visible) {
  outline: var(--outline-width) var(--outline-style) var(--ring);
}
```

To recolor the focus ring in a specific context, override `--ring-color`:

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

Add the `ring` utility to apply a persistent focus-style ring to custom elements.

## Active states [#active-states]

Define active states in component CSS with `:active` rather than markup utility classes. Built-in components include active styling by default.

## Validation states [#validation-states]

Form inputs use `:user-invalid`, styling fields only after user interaction (on blur or submit):

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

The `.ui-field` component handles label, hint, and error visibility transitions automatically.

## Disabled state [#disabled-state]

Components use `:not(:disabled)` styling guards. Add the `disabled` attribute to disable native controls:

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

## Data attributes for state [#data-attributes-for-state]

Components expose state and positioning through data attributes: `data-state`, `data-side`, and `data-align`. Transitions are handled in component stylesheets.


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



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

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

## Benefits [#benefits]

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

## Semantic tokens and escape hatches [#semantic-tokens-and-escape-hatches]

Prefer semantic tokens over arbitrary values:

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

## Common utility families [#common-utility-families]

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

Full reference: [Utilities reference](/docs/foundation/utilities).

## Shared scale [#shared-scale]

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

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

Finer steps use the `--step-0_5` to `--step-96` scale for spacing, and `50` to `950` for [colors](/docs/core-concepts/colors).

## Composable edges [#composable-edges]

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

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

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

## Utilities on components [#utilities-on-components]

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

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

## State and responsive variants [#state-and-responsive-variants]

* **Hover:** `hover:bg-primary`, `hover:scale-102`. See [States](/docs/core-concepts/states).
* **Responsive:** `@md:grid-cols-3`, `@lg:flex-row`. See [Responsive design](/docs/core-concepts/responsive-design).


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



Stylesheets in `@zazz-ui/core` follow consistent organization across base modules and components.

## Base files [#base-files]

Source files split into `base/` (core foundation) and `ui/` (co-located component stylesheets, scripts, and markup):

| File                    | Purpose                                                      | Documentation                                         |
| ----------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
| `_layers.css`           | Declares cascade layer order (loads first)                   | [Layers](/docs/foundation/layers)                     |
| `_variables.css`        | Global design tokens (colors, type, spacing, metrics)        | [Theme variables](/docs/foundation/variables)         |
| `_reset.css`            | Native element baselines and zero-specificity control resets | [Reset](/docs/foundation/reset)                       |
| `_typography.css`       | Type scale, `.ui-prose`, and typography utilities            | [Typography](/docs/foundation/typography)             |
| `_view-transitions.css` | Cross-document and SPA view transitions                      | [View transitions](/docs/foundation/view-transitions) |
| `_utilities.css`        | Atomic utility classes                                       | [Utilities](/docs/foundation/utilities)               |
| `_layout.css`           | Container bands and layout grid utilities                    | [Layout](/docs/foundation/utilities/layout)           |

## Component file structure [#component-file-structure]

Component stylesheets organize rules in top-to-bottom order:

| Step | Section                  | Layer                    | Condition                     |
| ---- | ------------------------ | ------------------------ | ----------------------------- |
| 1    | CSSDoc header            | None                     | Always                        |
| 2    | Component token hooks    | `@layer variables`       | When component exposes tokens |
| 3    | Native element baselines | `@layer reset`           | When restyling native UI      |
| 4    | Component rules          | `@layer zazz.components` | Core component rules          |
| 5    | Utility classes          | `@layer zazz.utilities`  | When shipping utilities       |

```css
/**
 * button.css: Button (.ui-button)
 *
 * @layer      variables, components
 * @requires   layers.css, _variables.css, _reset.css
 * @uses       color-mix(), oklch(from ...) (hover/active tints)
 * @tokens     --ui-button-* (@layer variables)
 */
@layer variables {
  :root {
    --ui-button-background: var(--card);
    --ui-button-height: var(--step-8);
    --ui-button-radius: var(--radius-md);
  }
}

@layer zazz.components {
  .ui-button {
    background-color: var(--ui-button-background);
    height: var(--ui-button-height);
    border-radius: var(--ui-button-radius);
  }
}
```

## CSSDoc header tags [#cssdoc-header-tags]

| Tag           | Required | Description                                       |
| ------------- | -------- | ------------------------------------------------- |
| Summary       | Yes      | First line: `file.css: Component (.ui-selector)`  |
| `@layer`      | Yes      | Cascade layers used in the file                   |
| `@requires`   | Yes      | Dependency files (set to `none` for `layers.css`) |
| `@uses`       | Optional | Modern CSS features or APIs utilized              |
| `@tokens`     | Optional | Token namespace exposed                           |
| `@consumedby` | Optional | Dependent files                                   |
| `@see`        | Optional | External references                               |
| `@example`    | Optional | HTML usage example                                |

## Token naming conventions [#token-naming-conventions]

* **Default token:** `--ui-{component}-{property}` (e.g. `--ui-button-background`, `--ui-dialog-radius`).
* **State variation:** `--ui-{component}-{property}--{state}` with double-dash (e.g. `--ui-button-background--hover`, `--ui-field-border--focus`).

## Selector conventions [#selector-conventions]

* **Roots:** a single `.ui-{component}` class (e.g. `.ui-button`, `.ui-dialog`). Primitives whose root would otherwise be a generic `<div>` also have an equivalent tag form: `<ui-tooltip>` matches the same rules as `<div class="ui-tooltip">` via `:where(ui-tooltip, .ui-tooltip)` aliasing. Classes only ever name roots.
* **Slots (interior parts):** `data-slot="{component}-{part}"` (e.g. `data-slot="dialog-header"`, `data-slot="carousel-viewport"`). The attribute is a space-separated token list like `class`, so one element can serve two primitives (`data-slot="lightbox-slide carousel-slide"`); selectors always use the token matcher `[data-slot~="carousel-slide"]`. Roots never carry `data-slot`.
* **Variants and state:** Data attributes, never modifier classes (e.g. `[data-variant="primary"]`, `[data-size="sm"]`, `[data-side]`).
* **Zero specificity:** `:where()` on reset and utility selectors.
* **Logical properties:** `inline-size`, `block-size`, `padding-inline`, `margin-block`.
* **State exclusion:** `:not(:disabled)` over order-dependent overrides.


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



`_layers.css` defines the [cascade layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) order for the framework. Layer order determines rule precedence instead of selector specificity.

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

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

`index.css` imports `_layers.css` first to establish this ordering before rules are defined.

## Layer precedence [#layer-precedence]

Later layers override earlier layers regardless of selector specificity:

```html
<!-- .ui-button sets background in @layer zazz.components.
     .bg-primary sets background in @layer zazz.utilities and overrides it cleanly. -->
<button class="ui-button bg-primary">Save</button>
```

## Layer definitions [#layer-definitions]

Priority order runs from lowest to highest:

| Layer             | Purpose                                                | File                                                                    |
| ----------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| `variables`       | Design tokens on `:root`                               | [`_variables.css`](/docs/foundation/variables) + component token blocks |
| `reset`           | Element baselines and control resets                   | [`_reset.css`](/docs/foundation/reset)                                  |
| `legacy`          | Existing pre-Zazz CSS in migrations                    | App entry stylesheet                                                    |
| `zazz.components` | Component rules                                        | `primitives/<name>/<name>.css`                                          |
| `zazz.utilities`  | Atomic utility classes                                 | [`_utilities.css`](/docs/foundation/utilities)                          |
| `migrations`      | Temporary translation shims for legacy class migration | Custom `migrations.css`                                                 |

Inside `zazz`, `utilities` follows `components`, guaranteeing utility overrides.

## Unlayered CSS [#unlayered-css]

Rules declared outside of any `@layer` override all layered rules regardless of specificity:

```css
/* Unlayered rule overrides layered components and utilities */
.ui-button {
  border-radius: 0;
}
```

To create custom overrides that remain structured, declare an app layer after Zazz instead:

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

@layer app {
  .ui-button {
    border-radius: 0;
  }
}
```

## Legacy CSS integration [#legacy-css-integration]

Import legacy stylesheets into `@layer legacy`:

```css
@import "./legacy-app.css" layer(legacy);
```

Zazz component and utility styles will override legacy styles where selectors overlap.

## Browser support [#browser-support]

Cascade layers are Baseline widely available across Chrome, Edge, Firefox, and Safari.


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



`_reset.css` normalizes browser defaults and native controls. It sits in `@layer reset`, allowing component and utility rules to override it easily.

## Zero specificity [#zero-specificity]

Reset rules wrap selectors in `:where()`, giving them `(0,0,0)` specificity:

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

## Reset scope [#reset-scope]

### Box model and container context [#box-model-and-container-context]

Resets margins, padding, and borders while setting `border-box` across elements:

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

`<body>` is configured as a flex column spanning `100svh` with `scrollbar-gutter: stable`. `<body>`, `<main>`, and section landmarks establish container query contexts.

### Theme defaults [#theme-defaults]

The reset assigns semantic tokens to baseline elements:

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

### Typography [#typography]

Headings inherit font size and weight, allowing `text-*` utility classes to govern typography:

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

Lists omit markers and padding by default; tables collapse borders; `text-wrap: pretty` is applied to body elements.

### Native controls [#native-controls]

Normalizes inline `<code>`, form inputs, search cancel buttons, and date/time pickers using token hooks (`--code-*`, `--placeholder-color`). Text selection uses primary-tinted highlights via `::selection`. The `<kbd>` baseline lives with the [Kbd](/docs/components/kbd) primitive.

### Focus and logical properties [#focus-and-logical-properties]

A global `:focus-visible` rule applies the focus ring across focusable elements. Dimensions use logical properties (`inline-size`, `block-size`, `padding-inline`) for bidirectional layout support.

## Component-level resets [#component-level-resets]

Specific native resets live alongside their respective component files: checkboxes in `_checkbox.css`, range inputs in `_slider.css`, switches in `_switch.css`, and select dropdowns in `_select.css`. These write directly into `@layer reset`.


# Typography (/docs/foundation/typography)



`_typography.css` implements the typography system from `_variables.css`, providing `.ui-prose` formatting for HTML documents and `.text-*` / `.font-*` utility classes.

## Font stacks [#font-stacks]

Zazz defines raw stacks and semantic aliases on `:root`:

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

Point `--font-family-heading` at `--font-heading` to customize heading typography. Utility classes `.font-sans`, `.font-serif`, and `.font-mono` reference the raw font stacks.

## Fluid type scale [#fluid-type-scale]

Type sizes use fluid `clamp()` calculations that scale between mobile and desktop viewport widths without breakpoint queries. Steps include `--font-size-eyebrow`, body sizes (`xs` to `xl`), heading sizes (`h6` to `h1`), and `--font-size-display`.

Each step specifies matching `--font-weight-*`, `--leading-*`, and `--tracking-*` tokens.

## Typography utility classes [#typography-utility-classes]

`.text-{step}` applies font size, line height, letter spacing, and font weight together:

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

`.font-*` sets weight directly (`.font-thin` through `.font-black`), plus semantic shortcuts (`.font-body`, `.font-heading`, `.font-strong`). See [Text and font](/docs/foundation/utilities/text-and-font) and [Text color](/docs/foundation/utilities/text-color).

## `.ui-prose` container [#ui-prose-container]

Wrap unclassed HTML (such as Markdown or CMS output) in `.ui-prose` to format headings, paragraphs, lists, blockquotes, and figures automatically:

```html
<article class="ui-prose">
  <h1>Page title</h1>
  <p>Body copy with standard typographic rhythm and measures.</p>
</article>
```

### Prose configuration tokens [#prose-configuration-tokens]

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

Vertical block rhythm is controlled by `--paragraph-spacing-*` tokens.


# Theme variables (/docs/foundation/variables)



Values in Zazz are CSS custom properties on `:root`. Components consume `var(--token)` without hardcoded values.

```css
/* Update global brand color */
:root {
  --primary: oklch(0.6 0.2 145);
}
```

## Token tiers [#token-tiers]

| Tier                   | Description                 | Examples                                                                                         |
| ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| Brand & literal scales | Fixed color ramps           | `--primary-50` to `--primary-950`, `--neutral-*`, `--shade-*`, `--tint-*`                        |
| Semantic roles         | Theme-aware colors          | `--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--destructive`              |
| Metrics & systems      | Spacing, typography, shapes | `--gap-*`, `--step-*`, `--font-size-*`, `--radius-*`, `--shadow-*`, `--breakpoint-*`, `--ring-*` |
| Component tokens       | Component-specific hooks    | `--ui-button-background`, `--ui-field-border`, `--ui-dialog-radius`                              |

Roles resolve through [`light-dark()`](/docs/core-concepts/dark-mode). Component tokens default to global semantic tokens.

## Override scopes [#override-scopes]

### Global override [#global-override]

Update tokens on `:root` to apply system-wide:

```css
:root {
  --radius-md: 0;
  --primary: oklch(0.55 0.18 264);
}
```

### Component default override [#component-default-override]

Reassign component tokens on `:root` to update all instances of a component:

```css
:root {
  --ui-button-radius: var(--radius-full);
}
```

### Instance override [#instance-override]

Set tokens inline on a single element:

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

## Token families [#token-families]

* **Spacing:** Semantic `--gap-xs` to `--gap-xl` and fluid step scale `--step-0_5` to `--step-96`.
* **Typography:** `--font-size-*`, `--font-weight-*`, `--leading-*`, and `--tracking-*`.
* **Color:** Semantic roles and literal scales. See [Colors](/docs/core-concepts/colors).
* **Radius:** `--radius-none` to `--radius-full`, scaled by `--radius-multiplier`.
* **Shadow:** `--shadow-xs` to `--shadow-xl`.
* **Layout:** `--breakpoint-xs` to `--breakpoint-xl`, `--gutters`, and reading measures `--article-xs` to `--article-xl`.
* **Motion:** `--spring-easing`, `--spring-duration`, and `--default-transition-*`. Zeroed automatically when `prefers-reduced-motion` is active.

## Token source files [#token-source-files]

Global tokens are defined in `src/base/_variables.css`. Component tokens are declared in each component's stylesheet under `@layer variables`.


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



Zazz provides multi-page view transitions without client framework requirements. When navigating same-origin links, `<main>` content updates with animated transitions while persistent chrome (header and footer) remains stationary.

## Architecture [#architecture]

1. **Navigation API:** Intercepts same-origin link clicks and swaps `<main>` content via `fetch()`.
2. **View Transitions API:** Wraps the DOM update in animation curves.

## Setup [#setup]

Include the stylesheet and `index.js` (which bundles `navigation.js`):

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

Add transition attributes to header and footer elements (`<main>` receives transition properties automatically):

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

## Transition tokens [#transition-tokens]

Animation duration defaults to `0ms`. Set `--view-transition-duration` on `:root` to activate:

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

| Token                              | Default                | Description                              |
| ---------------------------------- | ---------------------- | ---------------------------------------- |
| `--view-transition-duration`       | `0ms`                  | Animation duration (set > 0ms to enable) |
| `--view-transition-ease`           | `var(--bezier-easing)` | Easing curve                             |
| `--view-transition-wait`           | `0ms`                  | Delay before incoming animation          |
| `--view-transition-origin`         | `center top`           | Transform origin                         |
| `--view-transition-scale--old`     | `1`                    | Scale of outgoing content                |
| `--view-transition-scale--new`     | `1`                    | Scale of incoming content                |
| `--view-transition-translate--old` | `0, 0, 0`              | `translate3d` of outgoing content        |
| `--view-transition-translate--new` | `0, 0, 0`              | `translate3d` of incoming content        |
| `--view-transition-opacity--old`   | `0`                    | Final opacity of outgoing content        |
| `--view-transition-opacity--new`   | `0`                    | Starting opacity of incoming content     |

## Transition behavior [#transition-behavior]

| Layer name      | Transition mode                                         |
| --------------- | ------------------------------------------------------- |
| `main-content`  | Animated: outgoing content fades out, incoming fades in |
| `global-header` | Static: retained across navigations                     |
| `global-footer` | Static: retained across navigations                     |

## Navigation script lifecycle [#navigation-script-lifecycle]

`navigation.js` handles qualifying same-origin link clicks:

1. Intercepts `navigate` events.
2. Fetches destination HTML and extracts `<main>`.
3. Calls `document.startViewTransition()` to swap DOM nodes.
4. Updates `document.title`, restores scroll position, triggers `Reveal.refresh()`, re-initializes carousels, and focuses the new `<h1>`.

## Fallback behavior [#fallback-behavior]

* **No Navigation API:** Performs standard full-page load.
* **No View Transitions API:** Swaps content immediately without animation.
* **`prefers-reduced-motion`:** Content swaps instantly without transforms.


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



Zazz uses standard HTML document conventions for style loading, script initialization, and view transitions.

## Minimal head [#minimal-head]

Style-only pages require color-scheme declaration and one stylesheet link:

<HeadSnippet scripts="false" fontDisplay="false" theme="false" />

### Color scheme declaration [#color-scheme-declaration]

The `<meta name="color-scheme" content="light dark">` tag tells the browser to render native UI (canvas background, scrollbars, inputs) in the correct theme before CSS loads.

<Callout type="warn">
  Keep the meta tag and CSS `:root { color-scheme: light dark; }` in sync. The meta tag prevents initial paint flashes; the CSS property controls [`light-dark()`](/docs/core-concepts/dark-mode).
</Callout>

### Stylesheet link [#stylesheet-link]

Point one `<link>` at `index.css`:

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

<Callout>
  A `<link rel="preload" as="style">` for `index.css` is unnecessary. Same-document stylesheet links in `<head>` already block render at highest network priority.
</Callout>

### Override stylesheet [#override-stylesheet]

Load custom overrides after `index.css`:

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

### Loading Geist font [#loading-geist-font]

Zazz defaults to Geist via `--font-family-body` and `--font-family-heading`:

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

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

If persisting user theme selections (see [Dark mode](/docs/core-concepts/dark-mode)), place an inline script in `<head>` without `defer` or `type="module"`. It toggles `.dark` on `<html>` before first paint.

## Full head template [#full-head-template]

Complete head configuration including import map, polyfills, module entry, and theme script:

<HeadSnippet />

### Landmark markup [#landmark-markup]

```html
<body>
  <header data-transition-layer="global-header">
    <!-- Navigation -->
  </header>

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

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

`_reset.css` applies container and layout contexts to `<body>`, `<main>`, and section landmarks.

## Third-party modules and import map [#third-party-modules-and-import-map]

Zazz scripts import dependencies (TC39 signals polyfill and Embla Carousel) using bare specifiers:

```js
import { Signal } from "signal-polyfill";
import EmblaCarousel from "embla-carousel";
```

The browser resolves specifiers through `<script type="importmap">`:

1. **Host:** jsDelivr CDN URLs.
2. **Versions:** Pinned exact versions.
3. **Integrity:** SRI hashes on all entries.

Place the import map before `index.js`. To remove external network calls, vendor files locally and update import map paths.

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

`index.js` imports component behaviors in dependency order:

1. **Import map:** Parsed before module execution.
2. **Polyfills (optional):** Popover API (`@oddbird/popover-polyfill`), Invoker Commands.
3. **`index.js` (`<script type="module">`):** Deferred by default; runs before `DOMContentLoaded`.
4. **Inline theme script:** Executed synchronously before paint.

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

For cross-document or SPA transitions via `navigation.js`, label persistent regions:

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

`<main>` receives transition animation automatically while header and footer remain static.


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



Zazz runs on CSS and standard browser APIs without required bundlers or frameworks.

Choose an installation method:

* **npm:** For projects with a `package.json` needing versioned package updates.
* **CDN:** Load two tags in HTML without installing dependencies.
* **Copy files:** Keep component source directly in your project.

## npm [#npm]

```bash
pnpm add @zazz-ui/core
# or: npm install @zazz-ui/core
```

Import the stylesheet and optional component scripts:

```js
import "@zazz-ui/core/index.css";
import "@zazz-ui/core"; // component scripts
```

Pre-flattened bundles are available at `@zazz-ui/core/zazz.css` and `@zazz-ui/core/zazz.js`.

## CDN [#cdn]

Load pre-bundled files via jsDelivr:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zazz-ui/core/dist/zazz.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@zazz-ui/core/dist/zazz.js"></script>
```

You can also load individual stylesheets:

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@zazz-ui/core/src/primitives/dialog/dialog.css"
/>
```

<Callout type="warn">
  Pin an explicit version in production (`@zazz-ui/core@0.x.y`) to avoid unexpected changes.
</Callout>

## Copy source files [#copy-source-files]

Components live in `src/primitives/<name>/` with their stylesheets, scripts, and markup examples. Base layers live in `src/base/`.

Copy using degit:

```bash
# entire source directory
pnpm dlx degit dereknelsen/zazz-ui/packages/core/src ./zazz

# single component folder
pnpm dlx degit dereknelsen/zazz-ui/packages/core/src/primitives/dialog ./zazz/primitives/dialog
```

<Callout type="warn">
  Repo component scripts are TypeScript. For compiled JS without a TS build step, extract `.js`
  files from the published npm package or CDN URLs.
</Callout>

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

Reference `index.css` in your HTML:

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

Enable gzip or Brotli on your server for production compression.

## Verification [#verification]

```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" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zazz-ui/core/dist/zazz.css" />
    <title>Zazz Test</title>
  </head>
  <body>
    <button class="ui-button" data-variant="primary">It works</button>
  </body>
</html>
```

## Package structure [#package-structure]

```
@zazz-ui/core/
├── src/
│   ├── index.css                   (stylesheet entry)
│   ├── index.js                    (script entry)
│   ├── base/
│   │   ├── _layers.css             (cascade layers)
│   │   ├── _variables.css          (design tokens)
│   │   ├── _reset.css              (element baselines)
│   │   ├── _typography.css         (type scale and .ui-prose)
│   │   ├── _view-transitions.css   (page transitions)
│   │   ├── _utilities.css          (utility classes)
│   │   ├── _layout.css             (container and layout utilities)
│   │   └── utils.js, reveal.js...  (shared runtime)
│   └── primitives/
│       ├── button/
│       │   ├── button.css
│       │   └── button.html
│       └── ...
└── dist/
    ├── zazz.css                    (standalone CSS bundle)
    └── zazz.js                     (standalone JS bundle)
```

## Customization [#customization]

Override variables in your own stylesheet loaded after Zazz:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zazz-ui/core/dist/zazz.css" />
<link rel="stylesheet" href="./your-styles.css" />
```

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


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



Zazz includes structured agent skills and reference docs for AI coding assistants. These files define the token system, CSS APIs, and component authoring patterns.

## Available skills [#available-skills]

The `zazz` skill lives at [`.claude/skills/zazz/`](https://github.com/dereknelsen/zazz-ui/tree/main/.claude/skills/zazz):

| File                       | Purpose                                         |
| -------------------------- | ----------------------------------------------- |
| `SKILL.md`                 | Entry instructions and system trigger rules     |
| `DESIGN.md`                | Design system principles and token architecture |
| `PATTERNS.md`              | Component authoring patterns and conventions    |
| `references/tokens.md`     | Token reference (scales, roles, metrics)        |
| `references/components.md` | Component markup and variant API reference      |
| `references/apis.md`       | Modern CSS APIs used across the system          |

## AI assistant setup [#ai-assistant-setup]

### Claude [#claude]

The skill is pre-configured. Claude tools reading `.claude/skills/` load Zazz conventions automatically.

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

Provide key reference files as context:

1. **`SKILL.md`:** Instructions for using Zazz.
2. **`references/tokens.md`:** Valid token names and semantic roles.
3. **`references/components.md`:** HTML markup patterns for components.

### Plain-text endpoints [#plain-text-endpoints]

* [`/llms.txt`](/llms.txt): Condensed site documentation.
* [`/llms-full.txt`](/llms-full.txt): Complete documentation in plain text.

## Core rules in the skill [#core-rules-in-the-skill]

* Use the four-layer cascade (`variables`, `reset`, `components`, `utilities`).
* Use semantic tokens (`--primary`, `--gap-md`) over hardcoded pixel/hex values.
* Apply variants through `data-*` attributes.
* Use `light-dark()` for theme-aware colors.
* Follow token naming conventions (`--{component}-{property}--{state}`).
* Match existing component file structure.

## Repository [#repository]

Source code and skill files:
[github.com/dereknelsen/zazz-ui](https://github.com/dereknelsen/zazz-ui)


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



Zazz uses cascade layers and zero-specificity resets, allowing incremental adoption on existing codebases without full rewrites or `!important` overrides.

## The cascade rule: unlayered rules beat layered rules [#the-cascade-rule-unlayered-rules-beat-layered-rules]

Unlayered CSS rules beat all layered CSS rules regardless of selector specificity. Existing unlayered project CSS will override Zazz layers unless wrapped in its own lower layer.

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

Declare layer order in your entry stylesheet and assign legacy rules to `legacy`:

```css
/* entry.css */
@layer variables, reset, legacy, zazz, migrations;

@import "./legacy/app.css" layer(legacy);
@import "./zazz/index.css";
```

Because `legacy` is ordered below `zazz`, Zazz component and utility rules take precedence where they overlap, while unstyled legacy components continue working.

<Callout>
  The `migrations` layer sits above `zazz.utilities`. Shims in this layer override native Zazz rules
  during refactoring.
</Callout>

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

Use `@scope` to isolate converted and unconverted DOM subtrees:

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

Use `all: revert-layer` inside `@layer legacy` to strip old styles from converted sections while retaining Zazz styles.

## Step 3: Reset regions with `all: revert` [#step-3-reset-regions-with-all-revert]

To reset an element tree back to browser default styles:

```css
@scope (.takeover) to (.legacy-widget) {
  :scope,
  :scope * {
    all: revert;
  }
}
```

Use `all: revert-layer` to drop to the previous cascade layer without stripping Zazz rules.

## Step 4: Translate legacy classes in `migrations` [#step-4-translate-legacy-classes-in-migrations]

Bridge legacy HTML before markup updates using translation shims in `@layer migrations`:

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

Delete each translation rule once markup is converted to native Zazz classes.

## Migration workflow [#migration-workflow]

1. **Layer:** Place existing CSS in `@layer legacy`.
2. **Isolate:** Apply `@scope` boundaries between converted and legacy trees.
3. **Reset:** Apply `all: revert-layer` on converted sections to remove legacy styles.
4. **Translate and convert:** Add temporary shims in `migrations.css`, update markup to Zazz classes, then remove shims.

## Browser support [#browser-support]

`@layer`, `all: revert`, and `revert-layer` are Baseline widely available. `@scope` is Baseline 2024 (Chrome/Edge 118, Safari 17.4, Firefox 128).


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



Zazz structures styles with CSS cascade layers and semantic tokens. You can extend and customize components without specificity overrides.

## Cascade layers [#cascade-layers]

Zazz defines layer 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:

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

Utilities in `zazz.utilities` override `.ui-button` in `zazz.components` without `!important`. See [Layers](/docs/foundation/layers).

## Base files [#base-files]

Four core stylesheets form the system:

* [`_layers.css`](/docs/foundation/layers): Declares cascade layer order (loads first).
* [`_variables.css`](/docs/foundation/variables): Global tokens for color scales, semantic roles, spacing, typography, radius, and shadows.
* [`_reset.css`](/docs/foundation/reset): Element defaults wrapped in `:where()` for zero specificity.
* [`_utilities.css`](/docs/foundation/utilities): Atomic utility classes wrapped in `:where()`.

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

Components read `var(--token)`. Restyle UI by updating variables:

```css
:root {
  --primary: oklch(0.6 0.2 145); /* global brand override */
  --ui-button-radius: var(--radius-full); /* component-level override */
}
```

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

See [Theme variables](/docs/foundation/variables).

## Typography [#typography]

Zazz uses fluid `clamp()` sizing. A single `text-*` utility sets font size, line height, letter spacing, and weight. The `.ui-prose` class formats author-controlled HTML.

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

See [Text and font](/docs/foundation/utilities/text-and-font) and [Prose](/docs/components/prose).

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

Components expose styling through `data-*` attributes. Omitting the attribute renders the default variant:

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

## Dark mode [#dark-mode]

`:root` declares `color-scheme: light dark`. Role tokens use `light-dark()` to resolve values automatically based on system preference or a `.dark` class. See [Dark mode](/docs/core-concepts/dark-mode).


# Scripting (/docs/scripts/scripting)



Scripts in `@zazz-ui/core` live alongside their components: shared runtime in `src/base/` and component logic in `src/primitives/<name>/`. Authored in TypeScript, they compile to readable `.js` files that run as native ES modules in modern browsers without a required bundler.

`index.js` imports all component scripts so pages can load behaviors with a single `<script type="module" src="./zazz/index.js">` tag.

## Principles [#principles]

* **Vanilla JS:** Shipped `.js` files are standard ES modules. External dependencies (signals polyfill, Embla) resolve through the page's import map.
* **HTML-driven:** Components read configuration from data attributes (`data-carousel-*`, `data-reveal-*`). Custom element props are `data-*` attributes too (e.g. `data-label-show` / `data-label-hide` on `<ui-password>`), not bare attributes.
* **Progressive enhancement:** Components fall back to native HTML behaviors if JavaScript is disabled.

## File template [#file-template]

```js
"use strict";

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

import { Dependency } from "./dependency.js";

// Implementation

if (typeof window !== "undefined" && typeof document !== "undefined") {
  // Auto-init
}

if (typeof window !== "undefined") {
  window.MyExport = MyExport;
}

export { MyExport };
```

## Module exports [#module-exports]

Scripts expose an API on `window` and provide named exports for ES module consumers:

| File                  | Global             | Exports                                                            |
| --------------------- | ------------------ | ------------------------------------------------------------------ |
| `utils.js`            | `window.Utils`     | `{ parseValue, parseDataAttributes }`                              |
| `signals.js`          | `window.Signals`   | `{ state, computed, effect }`                                      |
| `reveal.js`           | `window.Reveal`    | `Reveal` class                                                     |
| `zazz-element.js`     | *(none)*           | `ZazzElement` base, `defineZazzElement`, refresh registry          |
| `dialog-lifecycle.js` | *(none)*           | Emits `zazz:dialog-open` / `zazz:dialog-close` on every `<dialog>` |
| `embla.js`            | `window.EmblaInit` | `{ init, initRoot, addDotBtnsAndClickHandlers }`                   |
| `toaster.js`          | `window.Toaster`   | `Toaster` imperative API                                           |
| `navigation.js`       | None               | Side-effect only                                                   |

Web component scripts (`carousel.js`, `lightbox.js`, `password-group.js`, `tabs.js`, `toaster.js`) register custom elements automatically.

## Auto-initialization [#auto-initialization]

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

Initializers are idempotent and check element state (e.g. `data-carousel-init`) before binding.

## Dependencies [#dependencies]

The module graph resolves loading order automatically via `index.js`:

| Script                | Imports                    | Notes                                            |
| --------------------- | -------------------------- | ------------------------------------------------ |
| `utils.js`            | None                       | Exposes `window.Utils`                           |
| `signals.js`          | `signal-polyfill`          | Reactive state (`window.Signals`)                |
| `reveal.js`           | None                       | Standalone viewport observer                     |
| `dialog-lifecycle.js` | None                       | Owns `<dialog>` visibility; components subscribe |
| `embla.js`            | `utils.js`, Embla packages | Embla packages resolve through the import map    |
| `carousel.js`         | `embla.js`                 | `<ui-carousel>` custom element                   |
| `lightbox.js`         | `carousel.js`              | `<ui-lightbox>` custom element                   |
| `password-group.js`   | `signals.js`               | `<ui-password>` custom element                   |
| `tabs.js`             | None                       | `<ui-tabs>` custom element                       |
| `toaster.js`          | `signals.js`               | `<ui-toaster>` custom element                    |
| `navigation.js`       | `zazz-element.js`          | Page transitions; refreshes swapped-in content   |

Ensure the import map appears in the DOM before `index.js`.


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



`bg-*` utilities set `background-color` using semantic role tokens that resolve through `light-dark()`.

## Surfaces and roles [#surfaces-and-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 and status [#brand-and-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` (static across light/dark)      |
| `bg-black`       | `--black` (static across light/dark)      |
| `bg-transparent` | `background-color: transparent`           |
| `bg-none`        | `background: none` (clears image + color) |

## Overlay ramps [#overlay-ramps]

Alpha-based overlays for modal backdrops, scrims, and frosted effects:

| Scale              | Classes                                                           | Derived from                     | Typical use             |
| ------------------ | ----------------------------------------------------------------- | -------------------------------- | ----------------------- |
| **Shade** (darken) | `bg-shade-none`, `bg-shade-50` to `bg-shade-950`, `bg-shade-full` | `--shade-*` (from `neutral-950`) | Scrims, modal backdrops |
| **Tint** (lighten) | `bg-tint-none`, `bg-tint-50` to `bg-tint-950`, `bg-tint-full`     | `--tint-*` (from white)          | Highlights over media   |

```html
<div class="grid grid-area-pile">
  <img src="/image.jpg" alt="" class="size-full object-cover" />
  <div class="bg-shade-700"></div>
  <h2 class="text-white self-end p-md">Text overlay</h2>
</div>
```

## Variants [#variants]

* **Hover:** All roles have `hover:bg-*` counterparts. See [Hover states](/docs/foundation/utilities/hover).
* **Opacity:** Dim background channels using `bg-opacity-*`. See [Color opacity](/docs/foundation/utilities/color-opacity).


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



Border utilities handle border lines, styles, and per-corner border radius.

## Borders [#borders]

### Edges [#edges]

| Class                                                              | Result                 |
| ------------------------------------------------------------------ | ---------------------- |
| `border`                                                           | 1px solid on all sides |
| `border-t`, `border-r`, `border-b`, `border-l`                     | 1px solid on that edge |
| `border-none`                                                      | Removes all borders    |
| `border-t-none`, `border-r-none`, `border-b-none`, `border-l-none` | Removes that edge      |

### Color [#color]

Color classes update `--_border-color` (default: `--border`):

| Class                                                                   | Role         |
| ----------------------------------------------------------------------- | ------------ |
| `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 border.</div>
```

## Border radius [#border-radius]

Uses the radius scale (`--radius-xs` to `--radius-full`, scaled by `--radius-multiplier`):

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

### Edges and corners [#edges-and-corners]

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

Radius utilities set four `@property`-registered variables with `inherits: false`:

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

:where(.rounded-b-0) {
  --_radius-bottom-left: 0px;
  --_radius-bottom-right: 0px;
}
```

```html
<!-- keep top corners rounded, flatten bottom edge -->
<div class="rounded-lg rounded-b-0">...</div>
```

| Variable                 | Syntax                | Initial | Managed 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-*` |


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



Color opacity utilities adjust single-channel alpha without fading child elements.

## Opacity modes [#opacity-modes]

| Mode                | Target                        | Classes                                                                      |
| ------------------- | ----------------------------- | ---------------------------------------------------------------------------- |
| **Element opacity** | Whole element and descendants | `opacity-0` to `opacity-100` ([Effects](/docs/foundation/utilities/effects)) |
| **Channel alpha**   | Named color channel only      | `text-opacity-*`, `bg-opacity-*`, `border-opacity-*`                         |

Scale steps: `0`, `25`, `50`, `75`, `100`.

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

Combine with role color classes:

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

```html
<span class="bg-primary bg-opacity-50 text-primary-foreground rounded-sm px-sm">
  50% background alpha
</span>
<p class="text-foreground text-opacity-75">75% text alpha.</p>
```

## Implementation [#implementation]

Color utilities compute alpha via `calc(alpha * var(--_background-alpha, 1))`. Alpha variables use `@property` with `inherits: false`, preventing values from bleeding into child elements.

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


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



Effect utilities configure elevation, element opacity, scale transforms, and transitions.

## Box shadow [#box-shadow]

| 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 element-level `opacity` (fading all children):

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

Supports `hover:` prefixes (e.g. `hover:opacity-75`). To fade only colors without children, see [Color opacity](/docs/foundation/utilities/color-opacity).

## Scale [#scale]

| Class                                              | Value                 |
| -------------------------------------------------- | --------------------- |
| `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)` |

All scale utilities support `hover:scale-*`.

## Transitions [#transitions]

Transitions map to system tokens (`--default-transition-*`):

| Class                  | Property             |
| ---------------------- | -------------------- |
| `transition`           | Default property set |
| `transition-all`       | `all`                |
| `transition-opacity`   | `opacity`            |
| `transition-transform` | `transform`          |

```html
<img class="rounded-md transition hover:scale-102 hover:opacity-75" src="/thumb.jpg" alt="" />
```

<Callout type="info">
  When `prefers-reduced-motion: reduce` is active, transition duration defaults to `0ms`.
</Callout>


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



Flexbox utilities control container layout, item flex factors, and alignment across axes.

## 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` support responsive prefixes (e.g. `flex-col @md:flex-row`).

## Flex grow & shrink [#flex-grow--shrink]

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

| Class          | Declaration     | Description                          |
| -------------- | --------------- | ------------------------------------ |
| `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 do not grow               |
| `flex-none`    | `flex: none`    | Prevent growing or shrinking         |

## Alignment and distribution [#alignment-and-distribution]

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

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

### Item self-alignment [#item-self-alignment]

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

Grid item self-justification classes are also available: `justify-self-auto`, `justify-self-start`, `justify-self-center`, `justify-self-end`, and `justify-self-stretch`.


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



`gap-*` controls spacing in flex and grid containers. `basis-*` sets flex basis fractions that automatically account for container gaps.

## Gap utilities [#gap-utilities]

<Preview src="utilities/gap" />

| 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-specific gaps [#axis-specific-gaps]

Use `gap-x-*` for `column-gap` and `gap-y-*` for `row-gap`:

```html
<div class="grid grid-cols-3 gap-x-lg gap-y-sm">...</div>
```

## Flex basis fractions [#flex-basis-fractions]

<Preview src="utilities/basis" />

Fraction utilities subtract gap values so child elements fit on a single line:

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

<Callout type="info">
  Set a `gap-*` class on the flex container to pass the gap value into `--_gap`. With no gap class,
  `--_gap` defaults to `0px`.
</Callout>

## Gap coordination variables [#gap-coordination-variables]

| Variable   | Default | Set by    | Consumed by                                |
| ---------- | ------- | --------- | ------------------------------------------ |
| `--_gap`   | `0px`   | `gap-*`   | `basis-1/2` to `basis-1/6`, auto-fill grid |
| `--_gap-x` | None    | `gap-x-*` | `column-gap`                               |
| `--_gap-y` | None    | `gap-y-*` | `row-gap`                                  |


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



CSS Grid utilities define container tracks, item spans, subgrid alignment, and responsive auto-filling columns.

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

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

| Class                           | Declaration                                               |
| ------------------------------- | --------------------------------------------------------- |
| `grid`                          | `display: grid` (sets `--_grid-col-min: min(100%, 25ch)`) |
| `grid-cols-1` to `grid-cols-12` | `grid-template-columns: repeat(N, minmax(0, 1fr))`        |
| `grid-rows-1` to `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` update `--_grid-cols` and `--_grid-rows` coordination variables.

## Spanning [#spanning]

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

Spans clamp to the declared track count via `span min(N, var(--_grid-cols))`:

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

## Subgrid [#subgrid]

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

## Stacking with `grid-area-pile` [#stacking-with-grid-area-pile]

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

`grid-area-pile` stacks direct children into a single cell with `place-items: center`. Useful for media overlays and avatar fallbacks.

## Place items [#place-items]

| 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" />

Combining `grid-flow-row` with `grid-cols-N` (N > 1) activates a gap-aware `auto-fill` formula. Columns wrap automatically as the container narrows without breakpoint queries.

```html
<div class="grid grid-flow-row grid-cols-4 gap-md">
  <!-- up to 4 columns, wrapping automatically -->
</div>
```

## Coordination variables [#coordination-variables]

| Variable          | Set by        | Default           | Consumed by                                   |
| ----------------- | ------------- | ----------------- | --------------------------------------------- |
| `--_grid-cols`    | `grid-cols-N` | `1`               | `col-span-*` clamping, auto-fill grid         |
| `--_grid-rows`    | `grid-rows-N` | `1`               | `row-span-*` clamping                         |
| `--_grid-col-min` | `.grid`       | `min(100%, 25ch)` | `grid-flow-row` auto-fill minimum track floor |


# Hover states (/docs/foundation/utilities/hover)



`hover:` variants apply styles on `:hover` without JavaScript. Combine with `transition` for smooth animations.

```html
<a href="#" class="text-muted-foreground hover:text-primary transition">Hover link</a>
<img class="rounded-md transition hover:scale-102 hover:opacity-75" src="/thumb.jpg" alt="" />
```

<Callout type="info">
  In HTML markup, write `class="hover:bg-primary"`. The selector is escaped internally as
  `.hover\:bg-primary`.
</Callout>

## Text color [#text-color]

`hover:text-{role}` for all semantic roles (`primary`, `muted`, `card`, `destructive`, etc.).

## Background [#background]

`hover:bg-{role}` for all background roles, plus `hover:bg-transparent` and `hover:bg-none`.

## Border [#border]

`hover:border-{color}` for all color roles. Pair with a `border` class:

```html
<div class="border hover:border-primary rounded-md p-md transition">Card</div>
```

## Opacity & scale [#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-102`, `hover:scale-110`, `hover:scale-125`, `hover:scale-150` |

## Shadow [#shadow]

`hover:shadow-{size}` (`shadow-none`, `shadow-xs` to `shadow-xl`):

```html
<div class="shadow-sm hover:shadow-lg rounded-md p-md transition">Lifts on hover</div>
```

<Callout type="warn">
  Active (pressed) states should be styled in component CSS with `:active` rather than utility
  classes.
</Callout>


# Utilities (/docs/foundation/utilities)



Utilities in Zazz are atomic classes declared in `@layer zazz.utilities`. They override component styles by layer position and are wrapped in `:where()` for zero specificity.

<Preview src="utilities/compose" />

## Rules [#rules]

1. **Layer precedence:** Layer order is `variables`, `reset`, `legacy`, `zazz.components`, `zazz.utilities`, `migrations`. Utilities override component styles without `!important`.
2. **Zero specificity:** Each rule uses `:where(.utility) { ... }` with `(0,0,0)` specificity so custom selectors can override them easily.

## Utility families [#utility-families]

| Group                                                                                                                                           | Coverage                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Layout](/docs/foundation/utilities/layout)                                                                                                     | display, position, overflow, z-index, aspect-ratio, object-fit, order, container bands |
| [Flexbox](/docs/foundation/utilities/flexbox), [Grid](/docs/foundation/utilities/grid), [Gap & basis](/docs/foundation/utilities/gap-and-basis) | containers, alignment, spans, subgrid, gaps, basis fractions                           |
| [Spacing](/docs/foundation/utilities/spacing), [Sizing](/docs/foundation/utilities/sizing)                                                      | padding, margin, negative margins, width, height, size, min/max constraints            |
| [Text color](/docs/foundation/utilities/text-color), [Text & font](/docs/foundation/utilities/text-and-font)                                    | role colors, text alignment, transform, wrap, clamp, font families                     |
| [Backgrounds](/docs/foundation/utilities/backgrounds), [Borders](/docs/foundation/utilities/borders)                                            | surface colors, overlays, borders, border-radius                                       |
| [Effects](/docs/foundation/utilities/effects), [Color opacity](/docs/foundation/utilities/color-opacity)                                        | shadows, opacity, scale, transitions, channel-specific alpha                           |
| [Interactivity](/docs/foundation/utilities/interactivity), [Hover states](/docs/foundation/utilities/hover)                                     | cursor, focus ring, screen readers, `hover:` variant prefixes                          |
| [Responsive design](/docs/foundation/utilities/responsive-design)                                                                               | `@xs:`, `@sm:`, `@md:`, `@lg:`, `@xl:` container query prefixes                        |

## Internal composition and coordination variables [#internal-composition-and-coordination-variables]

### Non-inheriting composition variables [#non-inheriting-composition-variables]

Padding, margin, radius, and color-alpha utilities use `@property`-registered variables with `inherits: false`. Setting an edge or channel on an element does not leak into child elements:

```css
/* Shared composing rule */
: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);
}

/* Side utility sets only its target variable */
:where(.pl-0) {
  --_padding-inline-start: 0;
}
```

| Variable                                                  | Syntax                        | Initial | Managed by                                            |
| --------------------------------------------------------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `--_padding-{inline,block}-{start,end}`                   | `<length-percentage>`         | `0`     | `p-*`, `px-*`, `py-*`, `pt-*`, `pr-*`, `pb-*`, `pl-*` |
| `--_margin-{inline,block}-{start,end}`                    | `<length-percentage> \| auto` | `0`     | `m-*`, `mx-*`, `my-*`, `mt-*`, `-m-*`, `mx-auto`      |
| `--_radius-{top-left,top-right,bottom-right,bottom-left}` | `<length-percentage>`         | `0`     | `rounded-*`, `rounded-t-*`, `rounded-tl-*`            |
| `--_text-alpha`, `--_background-alpha`, `--_border-alpha` | `<number>`                    | `1`     | `text-opacity-*`, `bg-opacity-*`, `border-opacity-*`  |

### Inheriting coordination variables [#inheriting-coordination-variables]

Unregistered variables that pass layout settings from container to children:

| Variable                       | Default           | Set by                       | Consumed by                                |
| ------------------------------ | ----------------- | ---------------------------- | ------------------------------------------ |
| `--_gap`                       | `0px`             | `gap-*`                      | `basis-1/2` to `basis-1/6`, auto-fill grid |
| `--_gap-x`, `--_gap-y`         | None              | `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 |
| `--_grid-col-min`              | `min(100%, 25ch)` | `.grid`                      | `grid-flow-row` auto-fill floor            |

## Responsive and state prefixes [#responsive-and-state-prefixes]

Layout utilities support `@xs:` to `@xl:` container query prefixes. Color, opacity, and scale utilities support `hover:` prefixes.

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


# Interactivity (/docs/foundation/utilities/interactivity)



Interactivity utilities control pointer events, manual focus rings, and screen-reader content visibility.

## Pointer and cursor [#pointer-and-cursor]

| Class                 | Declaration            | Purpose                                  |
| --------------------- | ---------------------- | ---------------------------------------- |
| `pointer-events-none` | `pointer-events: none` | Makes element transparent to clicks      |
| `pointer-cursor`      | `cursor: pointer`      | Adds hand pointer to non-button elements |
| `pointer-default`     | `cursor: default`      | Restores standard arrow cursor           |

## Focus ring [#focus-ring]

`ring` applies the system focus ring to custom elements. It uses box-shadow offsets and activates on `:focus-visible`:

```html
<a href="#" class="ring rounded-md">Keyboard-focusable link</a>
```

* Inactive when unfocused: `--_ring-width` and `--_ring-offset-width` sit at `0`.
* Ring color defaults to `--primary`; offset uses `--ring-offset-color` (page background).
* A matching transparent `outline` ensures visibility in forced-colors mode.

## Screen-reader only [#screen-reader-only]

`sr-only` visually hides content while keeping it accessible to screen readers:

```html
<button class="ui-button" data-size="icon">
  <svg aria-hidden="true"><!-- icon --></svg>
  <span class="sr-only">Close dialog</span>
</button>
```


# Layout (/docs/foundation/utilities/layout)



Layout utilities control display mode, positioning, overflow, stacking, and page-level container bands.

## Containers [#containers]

Apply `.container` to `main`, `section`, `header`, `footer`, or `article` to create a centered layout grid with gutters:

```html
<section class="container">
  <h1>Large band title with gutters</h1>
  <p>Body copy aligned to the container band.</p>
</section>
```

### Container bands [#container-bands]

| Band           | Max width                  | Use                                      |
| -------------- | -------------------------- | ---------------------------------------- |
| `xs`           | `--breakpoint-xs` (40rem)  | Narrow column                            |
| `sm`           | `--breakpoint-sm` (48rem)  | Forms, card layouts                      |
| `md` (default) | `--breakpoint-md` (64rem)  | Standard content width                   |
| `lg`           | `--breakpoint-lg` (80rem)  | Wide sections                            |
| `xl`           | `--breakpoint-xl` (96rem)  | Dashboards and galleries                 |
| `full`         | Region width minus gutters | Edge-aligned rows retaining page gutters |
| `bleed`        | 100% viewport/region width | Full-bleed media and color bands         |

### Default band [#default-band]

```html
<section class="container" data-container="md">
  <h2>Medium width section</h2>
  <p>Children align to the md band.</p>
</section>
```

### Child band overrides [#child-band-overrides]

```html
<section class="container">
  <h1>Title in default band</h1>
  <figure data-container="bleed">
    <img src="/wide.jpg" alt="" />
  </figure>
</section>
```

### Article reading measure [#article-reading-measure]

Add `data-variant="article"` to center content constrained by `ch` units:

```html
<article class="container" data-variant="article" data-container="md">
  <h1>Reading column</h1>
  <p>Constrained to 65ch line length with gutters.</p>
</article>
```

| Value          | Measure |
| -------------- | ------- |
| `xs`           | 45ch    |
| `sm`           | 50ch    |
| `md`           | 65ch    |
| `lg` (default) | 70ch    |
| `xl`           | 75ch    |

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

### Visibility [#visibility]

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

### Insets and offsets [#insets-and-offsets]

| Class                      | Declaration                          |
| -------------------------- | ------------------------------------ |
| `inset-0`                  | `top/right/bottom/left: 0`           |
| `inset-xs` to `inset-xl`   | all four edges = `var(--gap-{size})` |
| `top-xs` to `top-xl`       | `top: var(--gap-{size})`             |
| `right-xs` to `right-xl`   | `right: var(--gap-{size})`           |
| `bottom-xs` to `bottom-xl` | `bottom: var(--gap-{size})`          |
| `left-xs` to `left-xl`     | `left: var(--gap-{size})`            |

```html
<div class="relative">
  <span class="absolute top-sm right-sm ui-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 scrollbar display while keeping scrollable functionality |

## Stacking (z-index) [#stacking-z-index]

| 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" />

| Class               | Ratio      | Typical 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`    | Editorial media     |
| `aspect-anamorphic` | `2.39 / 1` | Cinematic video     |

## Object fit [#object-fit]

<Preview src="utilities/object-fit" />

| Class               | Declaration              |
| ------------------- | ------------------------ |
| `object-contain`    | `object-fit: contain`    |
| `object-cover`      | `object-fit: cover`      |
| `object-fill`       | `object-fit: fill`       |
| `object-none`       | `object-fit: none`       |
| `object-scale-down` | `object-fit: scale-down` |

## Order [#order]

<Preview src="utilities/order" />

| Class         | Declaration    |
| ------------- | -------------- |
| `order-first` | `order: -9999` |
| `order-last`  | `order: 9999`  |
| `order-none`  | `order: 0`     |


# Responsive design (/docs/foundation/utilities/responsive-design)



Responsive utilities use container style queries with `@` prefixes: `@xs:`, `@sm:`, `@md:`, `@lg:`, `@xl:`.

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

## Prefixes [#prefixes]

Each prefix applies min-width style rules at or above the threshold:

| Prefix | Threshold | Token             |
| ------ | --------- | ----------------- |
| (none) | Base view | None              |
| `@xs:` | 40rem     | `--breakpoint-xs` |
| `@sm:` | 48rem     | `--breakpoint-sm` |
| `@md:` | 64rem     | `--breakpoint-md` |
| `@lg:` | 80rem     | `--breakpoint-lg` |
| `@xl:` | 96rem     | `--breakpoint-xl` |

```html
<div class="grid grid-cols-1 @xs:grid-cols-2 @sm:grid-cols-3 @lg:grid-cols-4 gap-md">...</div>
```

## How breakpoints work [#how-breakpoints-work]

1. `_variables.css` defines `--breakpoint-*` length tokens.
2. The `body` element acts as a container (`container-name: body`). Container size queries set boolean flags (`--is-breakpoint-md: true`) when width thresholds are reached.
3. Responsive classes evaluate `@container style(--is-breakpoint-md: true)`.

## Supported responsive families [#supported-responsive-families]

* **Container:** `container` (and `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`

## Base-only families [#base-only-families]

To keep CSS size compact, the following families do not generate responsive prefixes:

* Self alignment (`self-*`, `justify-self-*`, `place-items-*`)
* Spacing (`p-*`, `m-*`, `gap-*`), sizing (`w-*`, `h-*`, `size-*`), and negative margins
* Color, borders, radius, shadow, opacity, and scale

Change layout structure at breakpoints (e.g. `@md:flex-row`) to adapt spacing instead of using per-breakpoint spacing classes.

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


# Sizing (/docs/foundation/utilities/sizing)



Sizing utilities use logical properties (`inline-size`, `block-size`) to match document writing mode.

## Width & height [#width--height]

<Preview src="utilities/width" />

| 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`                                          |
| `h-screen`                     | `100svh`                                         |
| `w-screen-xs` to `w-screen-xl` | `var(--breakpoint-xs)` to `var(--breakpoint-xl)` |
| `h-screen-xs` to `h-screen-xl` | `var(--breakpoint-xs)` to `var(--breakpoint-xl)` |

## Square size shorthand [#square-size-shorthand]

<Preview src="utilities/size" />

`size-*` sets `inline-size` and `block-size` simultaneously:

| 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` x `100svh`              |
| `size-screen-xs` to `size-screen-xl` | `var(--breakpoint-*)` both axes |

## Min and max constraints [#min-and-max-constraints]

| 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` to `max-w-xl`  | `max-h-xs` to `max-h-xl`  | None                      | None                      |
| `max-w-screen`            | `max-h-screen`            | `min-w-screen`            | `min-h-screen`            |
| `max-w-screen-xs` to `xl` | `max-h-screen-xs` to `xl` | `min-w-screen-xs` to `xl` | `min-h-screen-xs` to `xl` |

```html
<article class="w-full max-w-screen-sm mx-auto">
  Fluid width constrained to sm breakpoint and centered.
</article>
```


# Spacing (/docs/foundation/utilities/spacing)



Spacing utilities use semantic gap tokens (`--gap-xs` to `--gap-xl`) and logical properties (`inline`, `block`).

## Padding [#padding]

<Preview src="utilities/padding" />

| Scope                      | Classes                    | Sets                   |
| -------------------------- | -------------------------- | ---------------------- |
| All sides                  | `p-0`, `p-xs` to `p-xl`    | All four edges         |
| Inline axis (left + right) | `px-0`, `px-xs` to `px-xl` | `padding-inline`       |
| Block axis (top + bottom)  | `py-0`, `py-xs` to `py-xl` | `padding-block`        |
| Top (block-start)          | `pt-0`, `pt-xs` to `pt-xl` | `padding-block-start`  |
| Bottom (block-end)         | `pb-0`, `pb-xs` to `pb-xl` | `padding-block-end`    |
| Left (inline-start)        | `pl-0`, `pl-xs` to `pl-xl` | `padding-inline-start` |
| Right (inline-end)         | `pr-0`, `pr-xs` to `pr-xl` | `padding-inline-end`   |

## Margin [#margin]

| Scope       | Classes                                                        |
| ----------- | -------------------------------------------------------------- |
| All sides   | `m-0`, `m-xs` to `m-xl`                                        |
| Inline axis | `mx-0`, `mx-xs` to `mx-xl`, `mx-auto`                          |
| Block axis  | `my-0`, `my-xs` to `my-xl`, `my-auto`                          |
| Per side    | `mt-*`, `mr-*`, `mb-*`, `ml-*` (`0`, `xs` to `xl`, and `auto`) |

### Auto margins [#auto-margins]

<Preview src="utilities/margin-auto" />

* `mx-auto`: Centers a fixed-width block.
* `ml-auto` / `mr-auto`: Pushes a flex child to the opposite edge.

### Negative margins [#negative-margins]

| Scope               | Classes                                           |
| ------------------- | ------------------------------------------------- |
| All sides           | `-m-xs` to `-m-xl`                                |
| Inline / block axis | `-mx-xs` to `-mx-xl`, `-my-xs` to `-my-xl`        |
| Per side            | `-mt-*`, `-mr-*`, `-mb-*`, `-ml-*` (`xs` to `xl`) |

## Composition variables [#composition-variables]

Spacing utilities set `@property`-registered variables with `inherits: false`. You can combine an all-sides utility with a single-edge utility:

```html
<!-- md padding on top, bottom, and right; zero on left -->
<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` |


# Text & font (/docs/foundation/utilities/text-and-font)



Typographic utility classes in `_utilities.css` handle text alignment, casing, font family, and line wrapping.

## 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 classes support responsive prefixes (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`       |

## Font family [#font-family]

| Class        | Token                     |
| ------------ | ------------------------- |
| `font-sans`  | `var(--font-body)`        |
| `font-serif` | `var(--font-heading)`     |
| `font-mono`  | `var(--font-family-mono)` |

## Text wrapping and overflow [#text-wrapping-and-overflow]

| Class          | Declaration                          | Purpose                                |
| -------------- | ------------------------------------ | -------------------------------------- |
| `text-balance` | `text-wrap: balance`                 | Balanced line breaks in short headings |
| `text-pretty`  | `text-wrap: pretty`                  | Prevent orphan words in body text      |
| `leading-none` | `line-height: 1`                     | Single-line labels                     |
| `tabular-nums` | `font-variant-numeric: tabular-nums` | Align numeric columns in tables/data   |

### Line clamp [#line-clamp]

| 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">Balanced headline wrapping</h3>
<p class="text-sm text-muted-foreground line-clamp-2">
  Summary truncated with an ellipsis after two lines...
</p>
```


# Text color (/docs/foundation/utilities/text-color)



`text-*` utilities set text colors using semantic role tokens that resolve through `light-dark()`.

## Surfaces and foregrounds [#surfaces-and-foregrounds]

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

## Secondary and muted text [#secondary-and-muted-text]

| Class                                  | Token                            | Use                             |
| -------------------------------------- | -------------------------------- | ------------------------------- |
| `text-muted` / `text-muted-foreground` | `--muted` / `--muted-foreground` | Secondary copy, captions, hints |
| `text-faded` / `text-faded-foreground` | `--faded` / `--faded-foreground` | Tertiary, lower-emphasis text   |

## Brand roles [#brand-roles]

| 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 roles [#status-roles]

| 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 colors [#absolute-colors]

| Class        | Token     | Note                           |
| ------------ | --------- | ------------------------------ |
| `text-white` | `--white` | Static across light/dark modes |
| `text-black` | `--black` | Static across light/dark modes |

```html
<p class="text-foreground">Primary copy.</p>
<p class="text-sm text-muted-foreground">Secondary caption copy.</p>
<p class="text-destructive">Error state.</p>
```

## Variants [#variants]

* **Hover:** All roles have `hover:text-*` counterparts. See [Hover states](/docs/foundation/utilities/hover).
* **Opacity:** Dim text channels using `text-opacity-*`. See [Color opacity](/docs/foundation/utilities/color-opacity).