# @hyzer-labs/ui — full component reference

> Every component's props, styling hooks, and accessibility notes in one file.
> Generated from the same data that renders the documentation site.

Index of every documentation page: https://design.hyzer.sh/llms.txt
Conventions for coding agents: https://design.hyzer.sh/agents.md

## Imports

```ts
import { Button, Modal, Combobox } from '@hyzer-labs/ui';   // components
import { defineConfig } from '@hyzer-labs/ui/config';        // token engine
import { reveal, fade } from '@hyzer-labs/ui/motion';        // motion
import { intersect } from '@hyzer-labs/ui/observers';        // observers
import IconSearch from '@hyzer-labs/ui/icons/search';        // one glyph at a time
import { contrastRatio } from '@hyzer-labs/ui/utils';        // utilities
import type { Intent } from '@hyzer-labs/ui/types';          // types

import '@hyzer-labs/ui/tokens.css';    // required
import '@hyzer-labs/ui/theme';         // optional reference theme
import '@hyzer-labs/ui/reset.css';     // optional structural reset
```

## Content

### Accordion

A disclosure component using native <details>/<summary> elements, supporting single and multiple open modes with keyboard navigation. Item titles accept plain strings or snippets.

Docs: https://design.hyzer.sh/docs/components/accordion

```ts
import { Accordion } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `AccordionItem[]` | `—` | Required. See AccordionItem below. |
| `type` | `'single' \| 'multiple'` | `'single'` |  |
| `defaultOpen` | `string \| string[]` | `[]` |  |
| `collapsible` | `boolean` | `true` | false keeps one panel open in single mode. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` |  |
| `panel` | `Snippet<[AccordionItem]>` | `—` | Required. Renders each panel. |
| `icon` | `Snippet` | `—` | Replaces the default chevron. |
| `onToggle` | `(openIds: string[]) => void` | `—` |  |
| `class` | `string` | `—` | Merged after the hz-accordion class. |

#### AccordionItem

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | `—` | Required. Must be unique. |
| `title` | `string \| Snippet` | `—` | Required. String for plain text; snippet for inner markup. |
| `disabled` | `boolean` | `false` |  |

#### Styling

Root class: `hz-accordion`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'open' \| 'closed'` | On .hz-accordion-item; rotates the icon. |
| `data-type` | `'single' \| 'multiple'` | Mirrors the prop. The behaviour is native <details> grouping, not CSS, so nothing in the theme reads this — it is yours. |
| `[aria-disabled]` | `'true'` | Disabled styling hangs off aria-disabled on .hz-accordion-trigger — not off the data-disabled that also appears on the item. Tabs does the opposite; match the component you are styling. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-accordion-item` | `child element` | The <details> element. |
| `.hz-accordion-trigger` | `child element` | The <summary>. |
| `.hz-accordion-heading` | `child element` | The heading inside the summary, at your headingLevel. |
| `.hz-accordion-icon` | `child element` | The disclosure chevron. |
| `.hz-accordion-panel` | `child element` | The content. The component ships no display/height/overflow on it on purpose, so it is free for you to animate. |

#### Accessibility

Built on native `<details>`, so no ARIA is needed for disclosure semantics. Arrow keys move between summaries, and Home/End jump to the first and last.

Disabled items have `aria-disabled='true'` and block interaction. Summaries wrap a real heading (`headingLevel`) so panels join the document outline.

### Blockquote

A semantic quote: a figure wrapping a blockquote, with an optional visible attribution and an optional machine-readable source URL.

Docs: https://design.hyzer.sh/docs/components/blockquote

```ts
import { Blockquote } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `Snippet` | `—` | Required. The quoted content. |
| `cite` | `string \| Snippet` | `—` | Visible attribution, rendered in a <cite> outside the quote. |
| `citeUrl` | `string` | `—` | Source URL — sets the blockquote cite attribute; never rendered as text. |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Aligns the attribution row under the quote; the quote body is untouched. |
| `intent` | `Intent` | `—` | See Foundation → Colors & Intent. |
| `intentScope` | `'line' \| 'full'` | `'line'` | Only relevant with intent set. line colors just the accent line; full also colors the quote text. Attribution stays muted either way. |
| `class` | `string` | `—` | Merged after the hz-blockquote class. |

#### Styling

Root class: `hz-blockquote`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-align` | `'start' \| 'center' \| 'end'` | Aligns the attribution row only — the quote body is deliberately left alone. Default start. |
| `data-intent` | `any registered intent` | Present only when intent is set. Colors only the accent line (border-inline-start) — no intent leaves the accent line at its default border color. |
| `data-intent-scope` | `'line' \| 'full'` | Present only when intent is set (mirrors data-intent — meaningless without an intent to scope). line (default) matches data-intent alone; full also colors the quote text. The attribution row is never affected. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-blockquote-border-width` | `<length> — default var(--hz-border-width-heavy)` | Thickness of the inline-start accent line. Defaults to the heaviest border-width token; override with any length or a lighter token. The attribution row indent tracks it automatically. |
| `--hz-blockquote-font-size` | `<length> — default var(--hz-font-size-xl)` | Font size of the quote body. Read, never declared, so it can be set per instance or inherited from any ancestor — the docs site tunes it down to body size for its doctrine notes. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-blockquote-quote` | `child element` | The quote itself, carrying the accent bar. |
| `.hz-blockquote-attribution` | `child element` | The attribution line. |
| `.hz-blockquote-cite` | `child element` | The cite element. |

#### Accessibility

The root is always a `<figure>` wrapping a `<blockquote>`. When `cite` is provided, the attribution renders in a `<figcaption><cite>` outside the quote, so screen readers do not announce it as part of the quotation itself.

No ARIA is added: the native `figure`/`blockquote`/`figcaption`/`cite` elements carry all the semantics.

The decorative em-dash before the attribution is a theme `::before` pseudo-element, so it never enters the accessible name.

### Button

A button with solid, outline, ghost, and soft variants, plus intent colors, sizes, a loading state, and icon slots.

Docs: https://design.hyzer.sh/docs/components/button

```ts
import { Button } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `variant` | `'solid' \| 'outline' \| 'ghost' \| 'soft'` | `'solid'` |  |
| `intent` | `Intent` | `'primary'` | The full intent registry, not a hand-picked subset — see Foundation → Colors & Intent. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | full fills its container at the md height/padding; not combinable with sm/lg. |
| `disabled` | `boolean` | `false` |  |
| `loading` | `boolean` | `false` |  |
| `loadingLabel` | `string` | `'Loading'` | Screen-reader-only text announced while loading; not rendered visually. |
| `href` | `string` | `—` | Renders as a plain <a> (no role="button") when set — it genuinely navigates. |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` |  |
| `ariaLabel` | `string` | `—` | Required for icon-only buttons. |
| `onclick` | `(e: MouseEvent) => void` | `—` | Swallowed while disabled or loading. |
| `class` | `string` | `—` | Merged after the hz-button class. |
| `children` | `Snippet` | `—` |  |
| `iconStart` | `Snippet` | `—` | An icon snippet with no children renders the compact circular icon-only form. |
| `iconEnd` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-button`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-variant` | `'solid' \| 'outline' \| 'ghost' \| 'soft'` | Default solid. |
| `data-intent` | `'neutral' \| any registered intent` | The full vocabulary, not a hand-picked subset — register an intent and Button stamps it. Sets --hz-button-accent. |
| `data-size` | `'sm' \| 'md' \| 'lg' \| 'full'` | Default md. full fills its container at the md height/padding — not combinable with sm/lg. |
| `data-state` | `'disabled' \| 'loading' \| absent` | Absent when interactive — every hover and active rule is gated on :not([data-state]), so styling a state cannot be undone by a hover. disabled wins over loading. |
| `data-icon-only` | `present when icon-only` | Derived: an icon with no children. Renders the circle form. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-button-accent` | `<color> — default var(--hz-intent-primary)` | The accent every variant derives from. Override it to restyle solid, outline, ghost, and soft at once — and it is how you wire up an intent you registered yourself. |
| `--hz-button-on-accent` | `<color> — default var(--hz-color-surface)` | Text colour on a solid fill. The surface role rather than white, so it flips with the mode and keeps solid text ≥ 4.5:1 in both. |
| `--hz-button-tint` | `<percentage> — 14% light, 28% dark` | Soft-variant background tint strength — the same recipe and hook pattern as --hz-badge-tint. |

#### Accessibility

Use `ariaLabel` for icon-only buttons (no visible text). The loading state sets `aria-busy="true"` and renders a screen-reader-only "Loading" label. Disabled state sets `aria-disabled="true"`.

### Card

A content container with optional media, actions, horizontal layout, and clickable-overlay support.

Docs: https://design.hyzer.sh/docs/components/card

```ts
import { Card } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Set 'none' to opt out and control padding entirely from your own class. |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` |  |
| `href` | `string` | `—` | Makes the whole card clickable. |
| `ariaLabel` | `string` | `—` | Required when href is set. |
| `horizontal` | `boolean` | `false` |  |
| `mediaPosition` | `'start' \| 'end'` | `'start'` |  |
| `class` | `string` | `—` | Merged after the hz-card class. |
| `media` | `Snippet` | `—` |  |
| `children` | `Snippet` | `—` |  |
| `actions` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-card`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | Lands on .hz-card-content, not the root — which is how media bleeds edge-to-edge while text stays inset. Default md. |
| `data-rounded` | `'none' \| 'sm' \| 'md' \| 'lg'` | No full rung, unlike the shared Rounded scale. Default md. |
| `data-horizontal` | `present when horizontal` | Media beside content above 640px. |
| `data-clickable` | `present when href is set` | The whole card becomes a target; the theme hangs its hover affordances off this together with a treatment class. |
| `data-media-position` | `'start' \| 'end'` | Mirrors the prop. The effect is DOM order, not CSS order — so reading order and visual order cannot disagree. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-card-media-size` | `<length\|percentage> — default 40%` | The media track in horizontal mode; media fills it. Never declared, so set it yourself on .hz-card or an ancestor. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-card--outlined` | `opt-in class` | A theme treatment, not a prop: pass it via class. Card ships no variant prop because the look is the theme’s call, not the API’s. |
| `.hz-card--elevated` | `opt-in class` | The shadow treatment. Same deal. |
| `.hz-card-title` | `opt-in class` | Card never emits this — you bring the heading element at whatever level the page needs, and the class only styles it. Headings aren’t load-bearing for Card the way they are for Modal or Accordion, so this never became API. |
| `.hz-card-media` | `child element` | The media wrapper. |
| `.hz-card-content` | `child element` | The padded region. |
| `.hz-card-body` | `child element` | The default slot wrapper. |
| `.hz-card-actions` | `child element` | The actions row. |
| `.hz-card-link` | `child element` | The overlay anchor, present only when clickable. Its own focus ring would be clipped on rounded cards, so the theme draws the ring on .hz-card itself while this anchor holds focus. |

#### Accessibility

When `href` is set, the entire card is wrapped in a link, so supply `ariaLabel` with a descriptive name. Inner interactive elements remain clickable above the overlay via z-index.

### Carousel

An accessible, manually rotated carousel: a draggable slide track, labeled slides, previous and next controls, arrow-key steering, and a live region announcing changes. It does not auto-rotate, by design.

Docs: https://design.hyzer.sh/docs/components/carousel

```ts
import { Carousel } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `T[]` | `—` | Required. Generic — each item renders via the slide snippet. |
| `ariaLabel` | `string` | `—` | Required. Names the carousel region. |
| `index` | `number (bindable)` | `0` |  |
| `loop` | `boolean` | `false` | Wrap from the last slide to the first and back. |
| `draggable` | `boolean` | `true` | Pointer drag to slide (drag wraps when loop is set — seamlessly, when seamless is also set). Off leaves keyboard, buttons, and dots working. |
| `controls` | `'visible' \| 'focus'` | `'visible'` | focus keeps the prev/next buttons and indicator in the DOM and fully operable, hidden only visually until :hover/:focus-within reveals the whole row together — the WCAG 2.5.7 non-dragging alternative, always reachable. |
| `seamless` | `boolean` | `false` | Opt-in continuous boundary wrap: every ±1 loop step — drag, buttons, dots, arrow keys — settles through a hidden clone instead of sweeping back through the row. Only meaningful with loop; an inert no-op without it. |
| `indicator` | `'counter' \| 'dots'` | `'counter'` | The "1 / 3" counter, or clickable slide-picker dots. |
| `prevLabel` | `string` | `'Previous slide'` |  |
| `nextLabel` | `string` | `'Next slide'` |  |
| `slideLabel` | `(item, index) => string` | `—` | Accessible name per slide; defaults to "{n} of {total}". |
| `dotLabel` | `(index, count) => string` | `—` | Accessible name per dot; defaults to "Go to slide {n} of {total}". |
| `onchange` | `(index: number) => void` | `—` |  |
| `slide` | `Snippet<[T, number]>` | `—` | Required. Renders one slide. |
| `class` | `string` | `—` | Merged after the hz-carousel class. |

#### Styling

Root class: `hz-carousel`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-active` | `present on the active slide and dot` | On .hz-carousel-slide and .hz-carousel-dot. Off-screen slides carry inert instead — they are clipped by the viewport, not hidden — so target :not([inert]) for the visible one. |
| `data-dragging` | `present while a drag is underway` | On .hz-carousel-track. The settle transition is suppressed while it is present so the track follows the pointer 1:1; a grab/grabbing cursor pairs with it. |
| `data-controls` | `'visible' \| 'focus'` | On the root, always stamped, both values. Presentation only: the controls markup is identical either way. focus visually hides the whole control row until :hover/:focus-within reveals it together — the row stays in the DOM, in the a11y tree, and fully operable throughout (the WCAG 2.5.7 non-dragging alternative to drag). Default 'visible'. |
| `data-seamless` | `present only when seamless && loop` | On the root. Absent when seamless is set without loop — an inert no-op — so the hook reflects effective behavior, never advertising a wrap that cannot happen. |
| `data-clone` | `present on a wrap-settle clone slide` | On .hz-carousel-slide. Rendered only mid-wrap, seamless loop, a distance-1 boundary crossing (drag, buttons, an adjacent-wrap dot, or arrow keys) — an inert, aria-hidden copy of the opposite-end slide the track settles into before silently resetting to the real target. Never counted in count, "{n} of {total}", or the dot rail; never focusable. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-carousel-dot-size` | `<length> — default 0.5rem` | Dot diameter (the painted size; the tap target is larger). Declared on .hz-carousel-dot itself, so set it there — declaring it on .hz-carousel will not reach, since the local declaration beats your inherited value. |
| `--hz-carousel-focus-min-height` | `<length> — default 12rem` | Minimum height of .hz-carousel-viewport, data-controls='focus' only. The revealed control row is an absolutely positioned overlay with no reserved layout space, so on a short carousel it can cover most of the slide — this keeps slide content clear of the row regardless of the slide's own height. data-controls='visible' needs no reserved space (its row sits in normal flow below the viewport) and is unaffected. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-carousel-viewport` | `child element` | The clip window and live region. |
| `.hz-carousel-track` | `child element` | The sliding row of slides. Its transform is an inline style; the transition and the drag cursor live here. |
| `.hz-carousel-slide` | `child element` | One slide; off-screen ones are inert. |
| `.hz-carousel-controls` | `child element` | The control row. |
| `.hz-carousel-prev` | `on a Button` | Previous control; also a .hz-button. Its ::before carries the 44px touch target. |
| `.hz-carousel-next` | `on a Button` | Next control; also a .hz-button. Its ::before carries the 44px touch target. |
| `.hz-carousel-dots` | `child element` | The dot rail. |
| `.hz-carousel-dot` | `child element` | One dot. Its ::before is a transparent tap target larger than the painted dot. |
| `.hz-carousel-status` | `child element` | The "1 / 3" counter. |

#### Accessibility

Built on the APG carousel pattern. The region and each slide carry `aria-roledescription`, and slides are named ('2 of 5'-style by default, or set your own with `slideLabel`).

There is no auto-rotation, so the viewport is an `aria-live="polite"` region and slide changes announce themselves. Arrow keys, Home, and End move between slides while focus is inside the carousel.

`controls="focus"` hides the control row visually only. It never uses `display`, `visibility`, `aria-hidden`, or `inert`, so the row stays reachable by Tab and appears on hover. That is the WCAG 2.5.7 alternative to the drag gesture.

### CodeBlock

A headless, read-only code viewer with a copy button, an opt-in title and language header, decorative line numbers, and a Show-more collapse for long listings. It ships no syntax highlighter, so bring your own through the language class hook (client autoloaders) or the children escape hatch (build-time highlighters like Shiki).

Docs: https://design.hyzer.sh/docs/components/code-block

```ts
import { CodeBlock } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `code` | `string` | `—` | Required. The source text. Copy, the line count, and the gutter always read from this, never from `children` or highlighter-injected markup. |
| `children` | `Snippet` | `—` | Escape hatch for pre-highlighted content, usually a build-time highlighter's own `<pre>` via `{@html}` (Shiki, for example). Replaces the default `<pre><code>` entirely; `code` is still required. |
| `title` | `string` | `—` | A filename or label. Renders the header bar, together with `language`. |
| `language` | `string` | `—` | Stamps `class="language-<language>"` on the default code (the hook browser-side highlighters look for) and shows a visible, non-interactive tag in the header. |
| `lineNumbers` | `boolean` | `false` | Opt-in decorative line-number gutter. Never part of copy or selection. |
| `copyable` | `boolean` | `true` | Whether the built-in copy button renders. |
| `collapsible` | `boolean` | `false` | Clamp tall listings behind a Show-more/less toggle. |
| `collapsedLines` | `number` | `16` | Rows shown while collapsed. The toggle appears only when the listing is longer than this. |
| `class` | `string` | `—` | Merged after the hz-code-block class. |

#### Styling

Root class: `hz-code-block`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-language` | `<string> — present when language is set` | Mirrors the language prop; the default code also carries language-<value> for client autoloaders, and the header shows a matching tag. |
| `data-has-title` | `present when title is set` | Marks the titled form. Independent of data-language — the header can render from either. |
| `data-highlighted` | `present when the children escape hatch is used` | Marks a block whose code node is consumer-supplied pre-highlighted markup. Target it to drop the default code-surface fill and let a build-time highlighter's own background sit cleanly. |
| `data-collapsible` | `present when the listing exceeds collapsedLines` | Reflects effective behaviour, not the raw prop — a short listing never gets the toggle, so this is absent for it. |
| `data-line-numbers` | `present when lineNumbers is on` | Marks the gutter form. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-code-block-bg` | `<color> — default var(--hz-color-surface-muted)` | The code surface fill; the collapse fade fades into it. Suppressed under data-highlighted so a build-time highlighter's own background shows. |
| `--hz-code-block-padding` | `<length> — default 1rem` | Padding inside the code region (pre) — reaches a consumer-supplied pre too. |
| `--hz-code-block-fade-height` | `<length> — default 3rem` | Height of the collapse fade over the clamped edge. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-code-block-header` | `child element` | The header bar; present when title or language is set. |
| `.hz-code-block-title` | `child element` | The filename/label text. |
| `.hz-code-block-lang` | `child element` | The non-interactive language tag; present only when language is set. |
| `.hz-code-block-clip` | `child element` | The code region — the collapsible viewport, focusable when it renders the default code node. |
| `.hz-code-block-gutter` | `child element` | The aria-hidden, non-selectable line-number column; present only with lineNumbers. |
| `.hz-code-block-copy` | `on a Button` | Rides through Button’s class prop, so it also carries .hz-button and its data-attrs. |
| `.hz-code-block-expand` | `on a Button` | The Show-more/less toggle; also a .hz-button. |
| `code.language-<language>` | `on the default inner code` | The class a client autoloader targets; present only when language is set and the children escape hatch is not used. Not an hz-owned class. |

#### Accessibility

The copy button is a real labeled `<button>`. Its "Copied" state lasts about 2 seconds and is announced once through a polite live region. If the clipboard is denied or unavailable, nothing happens and nothing is announced, so you never get a false "copied" (WCAG 4.1.3).

In its default rendering the code region is a focusable, named `role="group"`, so you can scroll an overflowing listing with the arrow keys (WCAG 2.1.1). When `children` supplies pre-highlighted markup, the region gives up its own tab stop to your focusable `<pre>` (Shiki's carries `tabindex="0"`) rather than creating a second one.

The language tag is plain visible text with no interactive role. It is never the region's accessible name, so nothing is announced twice. The line-number gutter is `aria-hidden` and left out of selection, so a screen-reader user and a mouse copy both get clean source.

If you supply a highlighter's markup through `children`, its token colors (a Shiki theme, say) are yours to check for contrast. CodeBlock adds no color to that markup.

### Divider

A thematic separator: a native hr when bare, and a labeled role=separator element when it wraps a centered text label.

Docs: https://design.hyzer.sh/docs/components/divider

```ts
import { Divider } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `Snippet` | `— (label)` | Optional. Absent → bare <hr>; present → the labeled form. |
| `variant` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` |  |
| `spacing` | `LayoutPadding` | `'md'` | Block margin: 'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away' — the shared layout scale; near/away tighten inside data-density-shift regions. |
| `lineWidth` | `'thin' \| 'thick'` | `'thin'` | Maps 1:1 to the --hz-border-width-thin/-thick tokens. |
| `class` | `string` | `—` | Merged after the hz-divider class. |

#### Styling

Root class: `hz-divider`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-variant` | `'solid' \| 'dashed' \| 'dotted'` | Line style. Default solid. |
| `data-spacing` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Block margin from the space scale. near and away are the density distances, so dividers respond to a density shift like the layout family. Default md. |
| `data-line-width` | `'thin' \| 'thick'` | 1:1 with --hz-border-width-thin/-thick. |
| `data-labeled` | `present on the labeled form` | The labeled form is a div with rules; the plain form is a bare hr. The theme tells them apart by element (hr.hz-divider vs div.hz-divider), so match that if you restyle. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-divider-label` | `child element` | The label. Its flanking lines are ::before/::after, so they are not separately targetable. |

#### Accessibility

The bare form is a native `<hr>`: implicit `role="separator"`, horizontal, non-focusable, and needing no ARIA.

The labeled form keeps `role="separator"` on the wrapping `<div>`, so the thematic break survives the switch away from `<hr>`. The label text is the separator's accessible name and stays in the tree, so screen readers announce a separator followed by its label, though the exact wording varies by reader.

The flanking rules are decorative `::before`/`::after` pseudo-elements, never part of the accessibility tree.

### Hero

A section component for page heroes supporting center, split, and overlay layouts. Text slots accept plain strings or snippets; in the overlay layout, media becomes the full-bleed background.

Docs: https://design.hyzer.sh/docs/components/hero

```ts
import { Hero } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `layout` | `'center' \| 'split' \| 'overlay'` | `'center'` |  |
| `height` | `'auto' \| 'screen' \| 'half'` | `'auto'` |  |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` |  |
| `reverseOnMobile` | `boolean` | `false` | Split layout only: media renders above content while the split is stacked. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |  |
| `ariaLabel` | `string` | `—` | Accessible name when no title is provided. |
| `class` | `string` | `—` | Merged after the hz-hero class. |
| `eyebrow` | `string \| Snippet` | `—` | String for plain text; snippet for inner markup. |
| `title` | `string \| Snippet` | `—` |  |
| `subtitle` | `string \| Snippet` | `—` |  |
| `actions` | `Snippet` | `—` |  |
| `media` | `Snippet` | `—` | Beside/below content in center/split; becomes the background in overlay. |

#### Styling

Root class: `hz-hero`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-layout` | `'center' \| 'split' \| 'overlay'` | In overlay the media becomes the background. split composes Split underneath, so .hz-split-layout is in reach. Default center. |
| `data-height` | `'auto' \| 'screen' \| 'half'` | Uses dvh where supported. Default auto. |
| `data-align` | `'start' \| 'center' \| 'end'` | Default center. |
| `data-reverse-on-mobile` | `present when reversed` | Split layout only: wraps the media above the content on narrow screens. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-hero-background` | `child element` | The full-bleed media, overlay layout only. |
| `.hz-hero-content` | `child element` | The text column. |
| `.hz-hero-eyebrow` | `child element` | The eyebrow line. |
| `.hz-hero-title` | `child element` | The heading, at your headingLevel. |
| `.hz-hero-subtitle` | `child element` | The subtitle, capped at 60ch. |
| `.hz-hero-actions` | `child element` | The actions row. |
| `.hz-hero-media` | `child element` | The media wrapper in center and split layouts. |

#### Accessibility

Hero renders a `<section>` with `aria-labelledby` pointing at the title element, or `aria-label` when there is no title. Use `headingLevel` to keep your page's heading hierarchy correct. If the page already has an h1, hero titles inside it are usually level 2.

### Icons

The full Lucide icon set (ISC) ships as generated per-icon Svelte components, loaded one glyph at a time. Each icon is decorative by default and labeled when you pass ariaLabel.

Docs: https://design.hyzer.sh/docs/components/icons

```ts
import IconSearch from "@hyzer-labs/ui/icons/search"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `size` | `number` | `24` | Width and height in px. |
| `strokeWidth` | `number` | `2` |  |
| `intent` | `Intent` | `—` | Colors the glyph from the shared intent vocabulary. |
| `ariaLabel` | `string` | `—` | Absent or empty means decorative, so the icon gets aria-hidden="true". |
| `class` | `string` | `—` | Merged after the hz-icon class. |

#### Styling

Root class: `hz-icon`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-intent` | `any registered intent` | Present only when the intent prop is set; the glyph inherits currentColor otherwise. |

### Link

An accessible anchor component with variant styles, external link support, and icon slots. Links inherit the surrounding text size.

Docs: https://design.hyzer.sh/docs/components/link

```ts
import { Link } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `href` | `string` | `—` | Required. |
| `external` | `boolean` | `false` |  |
| `externalIcon` | `boolean` | `true` | Auto external glyph; iconEnd replaces it, false suppresses it. |
| `variant` | `'default' \| 'subtle' \| 'nav'` | `'default'` |  |
| `ariaCurrent` | `'page' \| 'step' \| 'true'` | `—` |  |
| `ariaLabel` | `string` | `—` |  |
| `onclick` | `(e: MouseEvent) => void` | `—` |  |
| `class` | `string` | `—` | Merged after the hz-link class. |
| `children` | `Snippet` | `—` |  |
| `iconStart` | `Snippet` | `—` |  |
| `iconEnd` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-link`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-variant` | `'default' \| 'subtle' \| 'nav'` | Its own union, not the shared Variant. subtle inherits colour; nav is quiet until hover or aria-current. No size hook by design — a link inherits its surrounding text size. |
| `[aria-current]` | `'page' \| 'step' \| 'true'` | Load-bearing for styling, not just semantics: the active nav-link rule is [data-variant="nav"][aria-current]. |
| `data-external` | `present on external links` | Accompanies target="_blank" and the visually-hidden "opens in new tab" hint. The reference theme styles the glyph instead, so this one is yours. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-link-external-icon` | `child element` | The auto-rendered external glyph. Absent when you supply your own iconEnd. |

#### Accessibility

External links automatically add `target="_blank"`, `rel="noopener noreferrer"`, a decorative external glyph, and a visually-hidden "(opens in new tab)" string. `ariaCurrent` sets `aria-current` on the anchor for nav links.

### Metatags

The head tags one page needs for search results and link previews: title, description, canonical, Open Graph, and an X card. Site-level values are props too, so a small wrapper of your own holds them while each page passes only what changes.

Docs: https://design.hyzer.sh/docs/components/metatags

```ts
import { Metatags } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `siteUrl` | `string` | `—` | Absolute site origin, such as "https://example.com". Any relative url, canonical, or image needs it to resolve to the absolute URL Open Graph requires. |
| `url` | `string` | `—` | This page: a root-relative path ("/pricing") or an absolute URL. In SvelteKit this is page.url.pathname, passed by your own wrapper — see the "Per-site wrapper" demo above. |
| `title` | `string` | `—` | The page title. Composed with siteName into one string shared by <title>, og:title, and twitter:title. |
| `siteName` | `string` | `—` | The site's name. Emits og:site_name and is the title suffix. |
| `titleSeparator` | `string` | `' \| '` | Sits between title and siteName. |
| `description` | `string` | `—` | Sets the description meta tag plus og:description and twitter:description. An empty string counts as unset. |
| `image` | `string` | `—` | Preview image, a path or an absolute URL, resolved the same way as url. |
| `imageAlt` | `string` | `—` | Alt text for the preview image. Setting image without it prints a console warning in development. |
| `type` | `string` | `'website'` | Sets og:type, emitted as given with no validation. The Open Graph protocol's type list is the reference; 'article' is the other common one. |
| `canonical` | `string` | `url` | Canonical override for a page reachable at more than one address, path or absolute. |
| `twitterCard` | `'summary' \| 'summary_large_image'` | `derived from image` | summary_large_image once an image resolves, summary otherwise. |
| `children` | `Snippet` | `—` | Rendered last, inside the same head block — for tags this component does not manage (twitter:site, robots, JSON-LD, and the rest), not for overriding the ones it does. |

#### Accessibility

This component has no ARIA, no roles, and no focus behavior. Nothing here is interactive, but two accessibility duties still apply. `<title>` is the page's accessible name, both in the browser tab and in a screen reader's window list, so this component never emits an empty or invented one: give it a `title`, a `siteName`, or both. `og:image:alt` and `twitter:image:alt` give the preview image a text alternative in every client that shows one, so setting `image` without `imageAlt` prints a development-only warning.

Set a page's title once, either through this component or through the page's own `<svelte:head>`, never both.

### Table

A data table with client sorting, row selection, a sticky header, built-in empty and loading states, and an opt-in stacked mode for narrow widths. Real <table> semantics throughout.

Docs: https://design.hyzer.sh/docs/components/table

```ts
import { Table } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `T[]` | `—` | Required. |
| `columns` | `TableColumn<T>[]` | `—` | Required. Each column's `key` is a property name on T — the default cell reads `row[key]`. See TableColumn below. |
| `caption` | `string \| Snippet` | `—` | Visible caption. `caption` or `ariaLabel` is required — logs a warning in development if neither is set. Caption wins if both are given (no aria-label). |
| `ariaLabel` | `string` | `—` | See `caption`. |
| `sort` | `TableSort \| null` | `null` | Bindable. See TableSort below. |
| `clientSort` | `boolean` | `true` | false: Table renders `items` as given and only reports/marks sort state — you reorder `items` yourself. |
| `selectable` | `boolean` | `false` | Prepends a checkbox column. |
| `selected` | `SvelteSet<string>` | `new SvelteSet()` | Bindable — row ids (via getRowId) currently selected. |
| `getRowId` | `(row: T, index: number) => string` | `stringified index` | Row identity for selection. Supply a real id so selection survives re-sorting. |
| `rowLabel` | `(row: T) => string` | `—` | Accessible name for a row's checkbox; falls back to the first column's cell text. |
| `stickyHeader` | `boolean` | `false` |  |
| `bordered` | `boolean` | `true` | Frame and row rules. Set false inside a card or panel that already draws the edges; the divider under the header stays either way. |
| `loading` | `boolean` | `false` |  |
| `loadingRows` | `number` | `3` |  |
| `stack` | `'sm' \| 'md' \| 'lg'` | `—` | Stacks below the named width. Off by default (scroll wrap only); 'sm' (640px) suits most tables — reserve md/lg for wide or many-column tables that need to shed the table layout earlier. |
| `cell` | `Snippet<[T, TableColumn<T>]>` | `—` | Default is `String(row[column.key])`. |
| `empty` | `Snippet` | `—` | Default is "No rows". |
| `class` | `string` | `—` | Merged after hz-table-wrap. |

#### TableColumn<T>

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `key` | `string` | `—` | Required. A property name on a row of T (the default cell renders `row[key]`) and the column id (sort target, stacked-mode data-label). |
| `header` | `string` | `—` | Required. Header cell text (also the stacked-mode label). |
| `sortable` | `boolean` | `false` |  |
| `sortBy` | `(row: T) => string \| number` | `row[key]` | The escape hatch for mixed-type or computed sort values. |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Logical — flips under RTL. |
| `width` | `string` | `—` | CSS width for the column's <col>. |

#### TableSort

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `key` | `string` | `—` |  |
| `direction` | `'asc' \| 'desc'` | `—` |  |

#### Styling

Root class: `hz-table hz-table-wrap`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-bordered` | `present unless bordered={false}` | On .hz-table-wrap. The reference theme keys the frame and the row rules off it, so `bordered={false}` leaves an edgeless table for a card or panel that draws its own edges. The heavier divider under the header stays either way, since a borderless table still needs its header separated from its body. |
| `data-sticky` | `present when stickyHeader` | On .hz-table-wrap. Pins thead against the wrap’s own scroll — cap the wrap’s max-height (e.g. via your own class through Table’s `class` prop, which lands on the wrap) to see it scroll. |
| `data-stack` | `'sm' \| 'md' \| 'lg'` | On .hz-table-wrap. Mirrors the stack prop — stacked below the named --hz-width-* threshold, a real table at/above it. Absent (default): never stacks. 'sm' (640px) is the recommended default — genuinely narrow viewports only. |
| `data-selected` | `present on a selected row` | On tbody tr. Pairs with aria-selected="true" — both present only when selected. |
| `data-align` | `'start' \| 'center' \| 'end'` | On th/td, mirroring a column’s align. Logical values, so start/end flip under RTL with no extra rule. |
| `aria-sort` | `'ascending' \| 'descending'` | Not a data-* hook, but load-bearing for styling the active-column indicator: present only on the sorted column’s th, never on the others. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-table-sort` | `child element` | The sort trigger — a real button wrapping a sortable column’s header text, with the active-column chevron alongside it. |
| `.hz-table-empty` | `child element` | The full-width cell rendered when items is empty and not loading. |
| `.hz-table-skeleton` | `child element` | A loading placeholder row — on tbody tr; aria-hidden, so it never reaches assistive tech. |
| `.hz-table--striped` | `opt-in class` | Zebra striping. Pass it via class — like Card’s treatment classes, this is a theme look, not a prop. |

#### Accessibility

This is a static data table, not an APG grid pattern. Sort buttons and checkboxes are ordinary native controls in the natural tab order, so there is no roving grid navigation.

`aria-sort` (`ascending`/`descending`) sits only on the sorted column's `th`, never on the others. Select-all announces the partial state through the native `indeterminate` property, not an ARIA attribute.

Loading skeleton rows carry `aria-hidden`, so they never reach assistive tech.

Real `role`/`scope` semantics are stamped explicitly (`table`/`row`/`columnheader`/`cell`, plus `scope`), so they survive the stacked mode's CSS display overrides.

### Tabs

An accessible tab interface with roving tabindex, arrow-key navigation, and horizontal or vertical orientation. Tab labels accept plain strings or snippets.

Docs: https://design.hyzer.sh/docs/components/tabs

```ts
import { Tabs } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `TabItem[]` | `—` | Required. See TabItem below. |
| `ariaLabel` | `string` | `—` | Required. Labels the tablist. |
| `defaultTab` | `string` | `—` | ID of the initially active tab. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
| `activation` | `'auto' \| 'manual'` | `'auto'` | auto activates on arrow-key focus; manual waits for Enter/Space. |
| `panel` | `Snippet<[TabItem]>` | `—` | Required. Renders each panel. |
| `onChange` | `(activeId: string) => void` | `—` |  |
| `class` | `string` | `—` | Merged after the hz-tabs class. |

#### TabItem

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | `—` | Required. Must be unique. |
| `label` | `string \| Snippet` | `—` | Required. String for plain text; snippet for inner markup. |
| `disabled` | `boolean` | `false` |  |

#### Styling

Root class: `hz-tabs`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-orientation` | `'horizontal' \| 'vertical'` | Vertical moves the list border and the active indicator to the inline edge. Default horizontal. |
| `data-state` | `'active' \| 'inactive'` | On .hz-tabs-trigger. The panel carries it too, but its visibility runs off the native hidden attribute. |
| `data-disabled` | `present on disabled tabs` | On .hz-tabs-trigger. Disabled tabs stay focusable (aria-disabled, not the native attribute). |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-tabs-list` | `child element` | The tablist. Scrolls horizontally. |
| `.hz-tabs-trigger` | `child element` | One tab. The theme owns the whole button reset here, so an unthemed Tabs renders native buttons. The active indicator is an inset box-shadow, deliberately: the list scrolls, and any overlap trick that adds layout size produces a phantom scrollbar. Keep that property if you restyle it. |
| `.hz-tabs-panel` | `child element` | One panel. |

#### Accessibility

Implements the WAI-ARIA tabs pattern: `role='tablist'/'tab'/'tabpanel'`, `aria-selected`, and roving `tabindex`. Tab is one stop for the whole tablist, and arrow keys move between triggers, with Home/End jumping to the first/last.

Panels are only their own tab stop when they contain no focusable content. `ariaLabel` is required to name the tablist.

Disabled tabs stay focusable via arrows but carry `aria-disabled='true'` and never activate.

## Feedback & Status

### Alert

An inline feedback banner on the shared intent scale, with an optional heading and dismiss button. Announcement semantics are opt-in, and the Form error summary is built from one.

Docs: https://design.hyzer.sh/docs/components/alert

```ts
import { Alert } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `Snippet` | `—` | Required. The alert body. |
| `title` | `string \| Snippet` | `—` | Optional heading; labels the alert via aria-labelledby. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | An alert is nearly always a callout inside a section rather than a section of its own, so the default keeps it below your page headings. Raise or lower it to match the surrounding document. |
| `intent` | `Intent` | `'neutral'` | See Foundation → Colors & Intent. |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | The shared Rounded scale — 1:1 with the --hz-radius-* tokens. |
| `icon` | `Snippet` | `—` | Decorative; rendered aria-hidden. |
| `onDismiss` | `() => void` | `—` | Renders the dismiss button. Visibility is your state — the Alert never hides itself. |
| `dismissLabel` | `string` | `'Dismiss'` |  |
| `class` | `string` | `—` | Merged after the hz-alert class. |

#### Styling

Root class: `hz-alert`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-intent` | `'neutral' \| any registered intent` | Drives the accent bar, tint, and title colour. Spans the intent registry, so an intent you register lands here too. |
| `data-rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | 1:1 with the --hz-radius-* scale. Default md. |
| `data-dismissible` | `present when dismissible` | Marks the dismissible form. Always stamped so you can target it, though the reference theme ships no rule for it. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-alert-tint` | `<percentage> — 10% light, 22% dark` | How strongly the intent colour mixes into the surface. Retuning it means re-checking the soft pairings on Contrast & Accessibility. |
| `--hz-alert-border-width` | `<length> — default var(--hz-border-width-heavy)` | Thickness of the inline-start accent bar. Defaults to the heaviest border-width token; override with any length or a lighter token. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-alert-icon` | `child element` | The intent icon. |
| `.hz-alert-body` | `child element` | Title and content wrapper. |
| `.hz-alert-title` | `child element` | The heading, at your headingLevel. |
| `.hz-alert-content` | `child element` | The message body. |
| `.hz-alert-dismiss` | `child element` | The dismiss button. |

#### Accessibility

A statically rendered Alert is plain content: no role, no live region. The optional `title` names it via `aria-labelledby`.

For alerts inserted after load, pass `role="status"` (polite) or `role="alert"` (assertive, use sparingly) via the rest props. A live role on static content is dead weight, so it's never a default.

The dismiss button is a real labeled `<button>`. Dismissal is your state change, so consider where focus should land.

There is deliberately no Toast component. A timed self-dismissing overlay is hard to make accessible. Under WCAG 2.2.1 the timing has to be adjustable, extendable, or pausable. A message that vanishes on its own often goes unannounced as well. The library prefers dismissal the reader chooses, so content never disappears out from under them. An inline Alert with `role="status"` covers the need accessibly.

### Badge

A small inline status chip with intent coloring, soft, solid, and outline variants, the shared rounded scale, and an optional dismiss button. It is the building block for selected-option chips.

Docs: https://design.hyzer.sh/docs/components/badge

```ts
import { Badge } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `Snippet` | `—` | Required. The badge content. |
| `intent` | `Intent` | `'neutral'` | See Foundation → Colors & Intent. |
| `variant` | `'soft' \| 'solid' \| 'outline'` | `'soft'` |  |
| `size` | `'sm' \| 'md'` | `'md'` |  |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` | The shared Rounded scale — 1:1 with the --hz-radius-* tokens. |
| `onDismiss` | `() => void` | `—` | Renders the trailing remove button (the chip form). |
| `dismissLabel` | `string` | `'Remove'` | In lists, pass a per-item label — "Remove" alone is ambiguous. |
| `class` | `string` | `—` | Merged after the hz-badge class. |

#### Styling

Root class: `hz-badge`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-intent` | `'neutral' \| any registered intent` | Spans the intent registry. |
| `data-variant` | `'soft' \| 'solid' \| 'outline'` | Default soft. |
| `data-size` | `'sm' \| 'md'` | Two rungs only, unlike Button. Default md. |
| `data-rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | Default full — the pill. |
| `data-dismissible` | `present when dismissible` | Marks the chip form. Always stamped so you can target it. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-badge-tint` | `<percentage> — 14% light, 28% dark` | Soft-variant background tint strength. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-badge-dismiss` | `child element` | The remove button. |

#### Accessibility

A badge is plain inline text with no role and no label, so it announces as part of the surrounding content. Never let the intent color be the only signal; the text itself carries the meaning.

The dismiss button is a real `<button>` named by `dismissLabel`, with a decorative icon. When rendering several chips, give each a per-item label like `Remove Destroyer`.

### Banner

A full-width, solid-intent announcement bar with an optional dismiss button and top or bottom pinning. Made for page-level messages: maintenance notices, promos, and outage warnings.

Docs: https://design.hyzer.sh/docs/components/banner

```ts
import { Banner } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `Snippet` | `—` | Required. The banner body. |
| `intent` | `Intent` | `'neutral'` | See Foundation → Colors & Intent. |
| `pin` | `'top' \| 'bottom'` | `—` | Sticks the bar to that edge, in flow (position: sticky). Static by default. |
| `icon` | `Snippet` | `—` | Decorative; rendered aria-hidden. |
| `actions` | `Snippet` | `—` | Trailing slot — a Link or Button, e.g. "Learn more". |
| `onDismiss` | `() => void` | `—` | Renders the dismiss button. Visibility is your state — the Banner never hides itself. |
| `dismissLabel` | `string` | `'Dismiss'` |  |
| `as` | `string` | `'div'` | Polymorphic root — e.g. section or aside for landmark semantics. |
| `class` | `string` | `—` | Merged after the hz-banner class. |

#### Styling

Root class: `hz-banner`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-intent` | `'neutral' \| any registered intent` | Drives the solid fill via --hz-banner-bg; spans the intent registry. |
| `data-pin` | `'top' \| 'bottom'` | Present only when pinned; sticks the bar to that edge via position: sticky. |
| `data-dismissible` | `present when dismissible` | Present only when onDismiss is set — target it to style the dismissible form. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-banner-bg` | `<color> — default var(--hz-intent-neutral)` | The solid fill, switched per intent — override to restyle every intent's bar. |
| `--hz-banner-fg` | `<color> — default var(--hz-color-surface)` | On-fill text colour, the surface role so it flips with the mode and keeps text ≥ 4.5:1 in both. |
| `--hz-banner-padding-block` | `<length> — default 1.5rem` | Vertical padding of the bar. |
| `--hz-banner-padding-inline` | `<length> — default 2.5rem` | Horizontal padding of the bar. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-banner-icon` | `child element` | The decorative leading icon. |
| `.hz-banner-content` | `child element` | The message body. |
| `.hz-banner-actions` | `child element` | The trailing actions slot. |
| `.hz-banner-dismiss` | `child element` | The dismiss button. |
| `.hz-banner-title` | `opt-in class` | Banner never emits this — put it on your own lead element (strong, a heading) and it goes block-level semibold, stacking over the body copy. The .hz-card-title convention. |

#### Accessibility

A statically rendered Banner is plain content: no role, no live region. For a Banner inserted after load, pass `role="status"` (polite) or `role="alert"` (assertive, use sparingly) via the rest props.

The icon slot is decorative (`aria-hidden`). Links inside are underlined, and color is never the only signal. The dismiss button is a real labeled `<button>`, and dismissal is your state change.

A pinned Banner can cover a focused element that scrolls under it. Keep pinned banners short, one line where possible. Give in-page anchor targets `scroll-margin-block-start`/`-end` equal to the banner height so they clear it. The Banner itself sets no `scroll-margin`.

There is deliberately no Toast component. A timed self-dismissing overlay is hard to make accessible. Under WCAG 2.2.1 the timing has to be adjustable, extendable, or pausable. A message that vanishes on its own often goes unannounced as well. The library prefers dismissal the reader chooses, so content never disappears out from under them. Banner is the supported pattern for a pinned or site-wide message instead, with opt-in `role="status"` and dismissal you own.

### Loading

An accessible loading indicator in four variants: spinner, ring, dots, and bar. All four are indeterminate on their own; pass a value and bar becomes a linear progress bar while ring becomes a circular arc with a centered readout, and spinner and dots stay indeterminate.

Docs: https://design.hyzer.sh/docs/components/loading

```ts
import { Loading } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `number` | `— (indeterminate)` | Omitted, undefined, or NaN ⇒ indeterminate. There is no separate `indeterminate` boolean: the mode follows `value`, the same way a native `<progress>` does. |
| `max` | `number` | `100` |  |
| `intent` | `Intent` | `'primary'` | Defaults to primary, unlike Badge and Banner, since a fill reads as an accent. See Foundation → Colors & Intent. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
| `variant` | `'bar' \| 'spinner' \| 'ring' \| 'dots'` | `'bar'` | A value on `bar` renders a determinate linear progress bar; a value on `ring` renders a determinate circular arc with a centered readout. `spinner` and `dots` are indeterminate only, so a value passed to either is ignored (with a warning in development). With no value, `ring` rotates continuously while its arc grows and shrinks. |
| `label` | `string` | `—` | The accessible name. Required: a bare progressbar has a role but no name, and a missing name logs a warning in development. You can pass aria-label or aria-labelledby through rest instead. |
| `showValue` | `boolean` | `false` | Renders a formatted readout beside the bar, or centered inside a determinate ring. Determinate only: ignored (with a warning in development) on any indeterminate presentation (including the indeterminate ring) and on spinner/dots. At sm/md the centered ring readout gets tight, so prefer lg or a larger --hz-loading-size. |
| `format` | `(value: number, max: number) => string` | `(v, max) => `${Math.round((v / max) * 100)}%`` | Feeds both the visible readout and aria-valuetext, so what you see and what is announced never differ. Applies to both the bar and the determinate ring. |
| `class` | `string` | `—` | Merged after the hz-loading class. |

#### Styling

Root class: `hz-loading`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-intent` | `'primary' \| any registered intent` | Drives the fill via --hz-loading-fill for every variant/mode (bar, ring, spinner, dots). Spans the intent registry. Default primary — a fill is an accent by nature, unlike Badge/Banner’s neutral default. |
| `data-size` | `'sm' \| 'md' \| 'lg'` | Bar thickness, spinner/ring diameter, and dot size. Default md. |
| `data-variant` | `'bar' \| 'spinner' \| 'ring' \| 'dots'` | Default bar. spinner and dots are indeterminate-only — a value passed to either is ignored (with a warning in development). ring is the sole home of circular progress: determinate with a value (a static arc), indeterminate without one (a rotating, arc-length-pulsing loader). |
| `data-indeterminate` | `present when there is no value` | Present whenever value is absent/NaN on bar or ring, and always for spinner and dots (both indeterminate-only by construction). :not([data-indeterminate]) selects a determinate form — the linear bar or the (value-bearing) circular ring. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-loading-fill` | `<color> — default var(--hz-intent-primary)` | The filled portion — the bar fill, the ring arc, the spinner stroke, and the dot color — switched per intent. |
| `--hz-loading-track` | `<color>` | The unfilled track / unfilled ring. |
| `--hz-loading-size` | `<length> — defaulted per data-size` | Bar thickness for the bar; spinner-glyph / ring diameter for the spinner and ring; dot diameter for dots — each defaulted per data-size. |
| `--hz-loading-ring-width` | `<length> — default calc(var(--hz-loading-size) / 8)` | The ring’s stroke width (both the determinate static arc and the indeterminate rotating/pulsing arc), scaled off --hz-loading-size so it stays proportional to the ring diameter. Applied with vector-effect: non-scaling-stroke so it stays a true length under the SVG viewBox scale. |
| `--hz-loading-speed` | `<time> — default calc(var(--hz-duration-base) * 6) ≈ 2.4s` | Base duration of the indeterminate animations: the spinner rotation, the dots cycle, and the indeterminate ring’s rotation + arc-length pulse all run at exactly this; the bar sweep runs at 1.6x it. Anchored to the --hz-duration-* scale rather than a bare token, since that scale is tuned for one-shot transitions, not continuous loops. Under reduced motion the effective duration is slowed (≈2x, ≈4.8s), never zeroed — indeterminate Loading keeps animating (the deliberate exception; contrast Skeleton). The determinate bar/ring are static, so this hook is moot for them. |
| `--hz-loading-ease` | `<timing-function> — default var(--hz-ease-standard)` | Easing of the dots cycle and the indeterminate ring’s arc-length pulse — both reverse in place rather than travel, so an ease reads cleanly. The spinner spin, the ring’s rotation, and the bar sweep are always linear, independent of this hook — an eased rotation or looping sweep reads as stuttering (it slows to a stop and restarts each cycle). |
| `--hz-loading-pulse-width` | `<percentage> — default 150%` | Width of the indeterminate bar's moving highlight (its “pulse”) as a percentage of the bar's own width. Wider reads softer and more ambient — the peak stays a point at the band center, so a wide value fades gently over a long distance. Values up to ~200% keep the loop seamless. Affects the indeterminate bar only (unrelated to the ring's own arc-length pulse). |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-loading-bar` | `the native <progress>` | The bar variant’s real progressbar. |
| `.hz-loading-value` | `child element` | The formatted readout, present only with showValue on a determinate form (the bar, inline; the ring, centered). Never present on the indeterminate ring. |
| `.hz-loading-spinner` | `child element` | The spinner-variant wrapper — role="progressbar" aria-busy="true". Wraps the indeterminate IconLoader glyph. spinner is indeterminate-only; see ring for determinate circular progress. |
| `.hz-loading-ring-wrapper` | `child element` | The ring-variant wrapper — role="progressbar". Carries aria-busy="true" around the indeterminate rotating/pulsing arc, or aria-valuemin/max/now (no aria-busy) around the determinate static arc. |
| `.hz-loading-ring` | `child element` | The ring’s SVG — a static arc when determinate, a continuously rotating arc-length-pulsing loop when indeterminate. role="img" aria-hidden="true" (the wrapper carries the ARIA). |
| `.hz-loading-ring-track` | `child element` | The ring’s unfilled circle. |
| `.hz-loading-ring-fill` | `child element` | The ring’s arc circle. stroke-dasharray is a theme hook; for a determinate ring the live stroke-dashoffset fraction is written inline by the component (the Slider-fill precedent), not a documented hook. An indeterminate ring instead animates this circle’s rotation and dash length entirely in the theme. |
| `.hz-loading-dots` | `child element` | The ellipsis-loader wrapper — role="progressbar" aria-busy="true". Adds no new custom-property hooks: reuses --hz-loading-fill, --hz-loading-size, --hz-loading-speed, and --hz-loading-ease. |
| `.hz-loading-dot` | `child element` | One of the dots’ three spans. |

#### Accessibility

A determinate bar (what a `value` gives you) is a native `<progress>`. It carries `role="progressbar"` plus `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` for free, so the component stamps none of them by hand. A determinate ring (`variant="ring"` with a `value`) renders a static circular arc instead. That arc is a decorative SVG, so the same ARIA (`role="progressbar"`, `aria-valuemin`/`aria-valuemax`/`aria-valuenow`) is stamped on its wrapping span. Neither determinate form sets `aria-busy`, because the progress is known.

The indeterminate presentations are a bare bar with no `value`, the spinning glyph, an indeterminate ring, and the dots. None expose `aria-valuenow`, since the progress is unknown; each wraps in `role="progressbar" aria-busy="true"` instead. The glyph, the ring SVG, and the dots are all `aria-hidden` decoration, so the accessible name carries the meaning.

A name is required: pass `label` (applied as `aria-label` on the progressbar element), or an `aria-label`/`aria-labelledby` via rest. A missing name logs a warning in development, citing WCAG 4.1.2.

For non-percentage units, pass a custom `format`. Its output becomes `aria-valuetext` as well as the visible readout (bar or determinate ring), so what a sighted user reads and what a screen reader announces always match.

Reduced motion is a deliberate exception here. The rest of the library reduces animation to zero under `prefers-reduced-motion: reduce`. An indeterminate Loading keeps animating, because a frozen loader reads as stalled or broken, which is worse for every user. It runs a calmer version at roughly half speed instead (about 4.8s per cycle at the default speed): the spinner keeps spinning, the dots keep cycling, and the indeterminate ring keeps rotating and pulsing, just more slowly. The bar softens from a traveling sweep to a gentle low-amplitude pulse. The determinate forms, the linear bar and the circular ring whenever a `value` is present, are static either way, so reduced motion changes nothing for them. Skeleton is the opposite of the indeterminate case: its shimmer/pulse goes fully still under reduced motion, because the placeholder shape is itself the "loading" cue and needs no motion.

### Skeleton

A decorative placeholder for content that has not loaded yet. Its shape variants (text lines, circle, rectangle, and fill-the-box) combine into any card-like placeholder, with free width, height, and radius overrides and a shimmer animation that goes still under reduced motion.

Docs: https://design.hyzer.sh/docs/components/skeleton

```ts
import { Skeleton } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `variant` | `'text' \| 'circle' \| 'rect' \| 'block'` | `'text'` | Picks a shape and its default dimensions. For a card-like placeholder, compose several Skeletons in your own Stack/Cluster/Card layout; there is no preset prop for it. |
| `width` | `string \| number` | `variant default` | A number is emitted as px; a string is used as written (any CSS length or percentage). This is a per-instance style rather than a theme hook, like Grid's --hz-grid-cols*. |
| `height` | `string \| number` | `variant default` | See width. |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `variant default` | The shared Rounded scale. circle always forces full, whatever you pass here. |
| `lines` | `number` | `1` | text only. > 1 renders that many stacked bars; a value ≤ 0 clamps to 1 (with a warning in development). Ignored on other variants. |
| `lastLineWidth` | `string \| number` | `'60%'` | text only, lines > 1. The final line is shortened so the block reads like a real paragraph. |
| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Every mode collapses to a static muted block under prefers-reduced-motion: reduce. |
| `class` | `string` | `—` | Merged after the hz-skeleton class. |

#### Styling

Root class: `hz-skeleton`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-variant` | `'text' \| 'circle' \| 'rect' \| 'block'` | Default text. |
| `data-animation` | `'shimmer' \| 'pulse' \| 'none'` | Default shimmer. Collapses to a static block (same as none) under prefers-reduced-motion: reduce. |
| `data-rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | 1:1 with the --hz-radius-* scale. circle forces full regardless of the rounded prop. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-skeleton-color` | `<color>` | The base block color. Strengthened in dark (the Badge --hz-badge-tint precedent). |
| `--hz-skeleton-highlight` | `<color>` | The shimmer sweep color. |
| `--hz-skeleton-speed` | `<time> — default 1.4s` | The shimmer/pulse animation cycle. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-skeleton-line` | `child element` | One bar in a multi-line text skeleton (variant="text", lines > 1). |

#### Accessibility

Skeleton stamps `aria-hidden="true"` by default. It is decorative scaffolding with no role, no live region, and no label, so it cannot announce loading on its own. In the rare case you want it exposed, you can override `aria-hidden` through the rest props.

That is the deliberate split: Loading announces, Skeleton decorates. Wrap the loading region in `aria-busy="true"` and pair it with either a labeled indeterminate `Loading` or a polite `aria-live` "Loading…" message, so screen-reader users are told content is coming, then told when it arrives. See the paired loading pattern demo below.

Reduced motion works the other way round here from Loading, on purpose. Skeleton's shimmer and pulse go fully still under `prefers-reduced-motion: reduce`, because the placeholder shape already carries the "content loading here" cue, so no motion is needed. `Loading` (and Button's loading spinner) keep animating instead, much more slowly, because for them the motion is the cue.

## Overlays

### Dropdown

A generic action menu built on the WAI-ARIA APG menu button pattern, with real roving-tabindex keyboard focus.

Docs: https://design.hyzer.sh/docs/components/dropdown

```ts
import { Dropdown } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `DropdownEntry[]` | `—` | Required. A DropdownEntry is either a DropdownItem or a DropdownSeparator, both below. |
| `label` | `string` | `—` | Visible trigger text (and the accessible name, unless triggerLabel overrides it). |
| `triggerLabel` | `string` | `—` | Accessible-name override; required for an icon-only trigger (no label). |
| `triggerProps` | `DropdownTriggerProps` | `{}` | Trigger appearance pass-through. Resolves to variant: 'outline', intent: 'neutral'. |
| `triggerIcon` | `Snippet` | `— (⇒ IconChevronDown)` | Decorative; the labeled trigger renders it trailing, the icon-only trigger renders it alone. |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` |  |
| `onselect` | `(id: string, item: DropdownItem) => void` | `—` | Fires on every activation, after the item's own onselect. |
| `disabled` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-dropdown class. |

#### DropdownItem

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | `—` | Required. Stable identity — keys the item, its DOM id, and the onselect callback. |
| `label` | `string` | `—` | Required. |
| `disabled` | `boolean` | `—` | Stays focusable — reachable by Arrow / Home / End / typeahead — but inert on activation. |
| `danger` | `boolean` | `—` | Destructive action — surfaces the data-danger styling hook. |
| `icon` | `Snippet` | `—` | Decorative leading glyph; the label owns the accessible name. |
| `onselect` | `() => void` | `—` | Per-item action, fired before the component's onselect. |

#### DropdownSeparator

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `separator` | `true` | `—` | A non-interactive divider — discriminates it from an actionable item. |

#### Styling

Root class: `hz-dropdown`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-open` | `present while open` | Hides the closed menu and rotates the chevron. |
| `data-side` | `'bottom' \| 'top'` | On .hz-dropdown-menu — the resolved side, bottom unless flipped for lack of room below. See Positioning for the caret recipe. |
| `data-align` | `'start' \| 'center' \| 'end'` | On .hz-dropdown-menu — which edge the menu hangs from (or centered), RTL-aware. |
| `data-danger` | `present on danger items` | Per-item. The label text carries the meaning too — colour alone never does. |
| `data-disabled` | `present on disabled items` | Per-item. Items stay focusable (aria-disabled, not the native attribute), so the disabled state is still discoverable. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-dropdown-trigger` | `on a Button` | Merged onto the composed Button, so the trigger carries .hz-button and its full data-attr set as well. |
| `.hz-dropdown-menu` | `child element` | The menu surface. |
| `.hz-dropdown-item` | `child element` | One item. There is no data-active — the active item is real DOM focus, so style :focus / :focus-visible. |
| `.hz-dropdown-item-icon` | `child element` | An item’s icon slot. |
| `.hz-dropdown-separator` | `child element` | A separator row. |

#### Accessibility

The trigger is a real button (the library's own Button) with `aria-haspopup=menu`, `aria-expanded`, and `aria-controls`. It opens a `role=menu` popup of `role=menuitem` buttons, named by the trigger via `aria-labelledby`.

Unlike `Combobox`, which keeps DOM focus on its text input and tracks a virtually-focused option with `aria-activedescendant`, Dropdown moves real DOM focus into the menu. Opening it lands focus on the first menuitem (the last, on `ArrowUp`). A roving `tabindex` (`0` on the focused item, `-1` on the rest) keeps the menu a single tab stop, so the active item is styled with native `:focus` rather than a `data-active` hook.

Keyboard: `ArrowDown`/`ArrowUp` move focus and wrap, including over disabled items. `Home`/`End` jump to the first and last item. Typing a character cycles focus to the next item whose label starts with it. `Enter`/`Space` activate the focused item through its own native button click, with no separate handling. `Escape` closes the menu and returns focus to the trigger. `Tab`/`Shift+Tab` close the menu and let focus move on, since there is no focus trap.

A disabled item keeps `aria-disabled=true` rather than the native `disabled` attribute, so it stays focusable and screen-reader users can discover it. Activating it does nothing.

### Modal

An accessible dialog built on the native <dialog> element with focus trap, Esc-to-close, scroll lock, and configurable sizes.

Docs: https://design.hyzer.sh/docs/components/modal

```ts
import { Modal } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `title` | `string` | `—` | Required for accessibility. |
| `open` | `boolean` | `false` | $bindable. |
| `description` | `string` | `—` |  |
| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` |  |
| `closeOnOverlay` | `boolean` | `true` | Esc always closes regardless — the dialog pattern requires it. |
| `showClose` | `boolean` | `true` |  |
| `preventScroll` | `boolean` | `true` |  |
| `closeLabel` | `string` | `'Close dialog'` |  |
| `onclose` | `() => void` | `—` |  |
| `class` | `string` | `—` | Merged after the hz-modal class. |
| `children` | `Snippet` | `—` |  |
| `actions` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-modal`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-size` | `'sm' \| 'md' \| 'lg' \| 'full'` | full goes edge-to-edge and drops the radius. Default md. |
| `data-state` | `'open' \| 'closed'` | Mirrors the open prop. Visibility itself runs off the native [open] attribute that showModal() sets — this is the hook to animate against. |
| `data-modal-close` | `present on the close button` | Load-bearing beyond styling: focus management queries it to keep the close button out of the first-focus candidates. Renaming it breaks focus order, not just looks. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-modal-width` | `<length> — 30/40/52rem by size` | One name across all three sizes: it overrides whichever size is active. data-size="full" ignores it. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-modal-header` | `child element` | Always rendered. |
| `.hz-modal-title` | `child element` | Always an h2 — Modal has no headingLevel prop, because the dialog is its own document section. |
| `.hz-modal-description` | `child element` | The optional description. |
| `.hz-modal-body` | `child element` | Always rendered, so the scroll region stays stable even when empty. |
| `.hz-modal-footer` | `child element` | Present only with actions. |
| `::backdrop` | `pseudo-element` | The native dialog backdrop. |

#### Accessibility

Modal uses `showModal()` for native top-layer focus trapping and backdrop. `aria-modal`, `aria-labelledby`, and optional `aria-describedby` are set automatically. Focus returns to the trigger on close. The built-in close button's accessible name comes from `closeLabel`.

### Popover

A click-triggered disclosure panel for rich or interactive content, such as a filter form, a settings menu, or extra detail. It is non-modal, with no focus trap and no backdrop: reach for Modal when you need a focus-trapped dialog, or Dropdown when you need a menu of actions.

Docs: https://design.hyzer.sh/docs/components/popover

```ts
import { Popover } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | $bindable. |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| '<side>-start' \| '<side>-end'` | `'bottom-start'` | A bare side centers on the trigger; -start/-end add alignment. left/right follow the trigger's writing direction, so RTL flips the physical side. See Positioning for how a placement resolves. |
| `offset` | `number` | `8` | Gap from the trigger, in px. |
| `autoFocus` | `boolean` | `false` | true moves focus to the panel's first focusable element when it opens. Off by default, because a disclosure should not steal focus. |
| `dismissible` | `boolean` | `true` | false turns off closing on an outside click. Escape still closes the panel either way; there is no opt-out. |
| `label` | `string` | `—` | The panel's accessible name, used when it has no visible heading of its own. |
| `onopen` | `() => void` | `—` |  |
| `onclose` | `() => void` | `—` |  |
| `triggerLabel` | `string` | `—` | Visible label for the default composed-Button trigger. Ignored when `trigger` is provided. |
| `triggerProps` | `PopoverTriggerProps` | `{}` | Trigger appearance pass-through. Resolves to variant: 'outline', intent: 'neutral'. |
| `triggerIcon` | `Snippet` | `—` | Icon for the default Button trigger. |
| `trigger` | `Snippet<[TriggerAttrs]>` | `—` | Escape hatch. Wins over triggerLabel/triggerProps/triggerIcon. Receives an attrs bag (id, aria-expanded, aria-controls, popovertarget, onclick) to spread onto your own element: a link, an avatar, a custom control. |
| `children` | `Snippet` | `—` | Required. The panel content. Interactive controls are supported. |
| `class` | `string` | `—` | Merged after the hz-popover class. |

#### Styling

Root class: `hz-popover`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-open` | `present while open` | On the root — the Dropdown parity hook. |
| `data-state (panel)` | `'open' \| 'closed'` | On .hz-popover-panel — mirrors the open prop; the hook to animate the entrance against. |
| `data-placement` | `Placement` | On .hz-popover-panel — the requested placement string, e.g. "bottom-start". |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | On .hz-popover-panel — the resolved, physical side. See Positioning for the caret recipe. |
| `data-align` | `'start' \| 'center' \| 'end'` | On .hz-popover-panel — the resolved cross-axis alignment (RTL-aware for a top/bottom placement). |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-z-popover` | `<number> — default 200` | Matters mainly on the non-top-layer fallback path (older browsers) — a real top-layer panel stacks above everything regardless of z-index. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-popover-trigger` | `on a Button` | Merged onto the default composed Button trigger — absent when the `trigger` snippet escape hatch is used instead, since that renders your own element. |
| `.hz-popover-panel` | `child element` | The disclosure panel surface. |
| `.hz-popover-content` | `child element` | The scroll container inside the panel — the panel itself stays overflow-visible so a caret you draw can protrude. See Positioning for the recipe. |

#### Accessibility

The trigger carries `aria-expanded` and `aria-controls` pointing at the panel. That is the APG Disclosure pattern, not a dialog. The panel itself is a plain region by default, or a labeled `role="group"` when you pass `label` (for a panel with no visible heading). It is never `aria-modal`, never traps focus, and never renders a backdrop. Interactive content inside flows through the normal tab order and back out.

Escape always closes the panel and returns focus to the trigger, even with `dismissible: false`. There is no opt-out, the same rule Modal follows for its own Escape handling. Clicking outside the panel closes it too, unless `dismissible: false`. Unlike Escape, an outside click leaves focus wherever the click landed rather than pulling it back.

By default (`autoFocus: false`) opening the panel does not move focus at all, because a disclosure should not take focus uninvited. Set `autoFocus` when the panel's first control really is the next thing someone wants, such as a search field.

### Tooltip

An accessible hover and focus description for an element you already have, such as an icon button, a link, or an abbreviation. It holds non-interactive text only; for a click-triggered panel with rich content, use Popover.

Docs: https://design.hyzer.sh/docs/components/tooltip

```ts
import { tooltip } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `text` | `string` | `—` | Required. The tooltip text. `tooltip('Save changes')` is shorthand for `tooltip({ text: 'Save changes' })`. |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| '<side>-start' \| '<side>-end'` | `'top'` | 'top' == 'top-center'; -start/-end add alignment. left/right follow the trigger's writing direction, so RTL flips the physical side. |
| `offset` | `number` | `8` | Gap from the trigger, in px. |
| `openDelay` | `number` | `400` | A hover-intent filter, in ms. A pointer that only passes over the trigger never opens it. Keyboard focus shows the tooltip right away, with no delay. |
| `closeDelay` | `number` | `150` | The hoverable bridge, in ms. It gives the pointer time to travel from the trigger onto the tooltip itself without the tooltip disappearing. |
| `class` | `string` | `—` | Merged after the hz-tooltip class. |

#### Styling

Root class: `hz-tooltip`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'open' \| 'closed'` | Drives visibility (inline display, not the theme) — the hook to animate the entrance/exit against. |
| `data-placement` | `Placement` | The requested placement string, e.g. "top" or "bottom-start" — mirrors the placement option verbatim. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | The resolved, physical side — after any overflow flip and RTL resolution. See Positioning for the caret recipe. |
| `data-align` | `'start' \| 'center' \| 'end'` | The resolved cross-axis alignment (RTL-aware for a top/bottom placement). |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-z-tooltip` | `<number> — default 150` | Matters mainly on the non-top-layer fallback path (older browsers) — a real top-layer tooltip stacks above everything regardless of z-index. |

#### Accessibility

The trigger gains `aria-describedby` pointing at the tooltip's `role="tooltip"` node. Any existing `aria-describedby` is kept, with the tooltip appended to it, and restored on teardown. The tooltip shows on hover, after `openDelay` filters out incidental passes, and on keyboard focus, immediately and with no delay. The APG Tooltip pattern requires both, not just one.

WCAG 2.2 SC 1.4.13 (Content on Hover or Focus) is satisfied. Dismissible: Escape hides the tooltip without moving focus or the pointer, and it will not re-open until you leave and re-enter or re-focus the trigger. Hoverable: the pointer can travel from the trigger onto the tooltip itself, across the `offset` gap, without it disappearing, because `closeDelay` bridges the gap. Persistent: it stays visible until you dismiss it, blur the trigger, or leave both the trigger and the tooltip. It never times out on its own.

`tooltip` never adds `tabindex`. It enhances a control that is already focusable. Attach it to a non-focusable element (a plain `<span>`, say) and it still shows on hover, but keyboard users cannot reach it. That case logs a warning in development.

There is no hover on touch. With a touch or coarse pointer, a tap activates the control underneath rather than revealing the tooltip, though `aria-describedby` still exposes the text to assistive tech. For content revealed by a tap, use Popover.

## Layout

### Container

Centers content horizontally with a configurable max-width and padding. Container decides how wide a region is, so pair it with Stack, Cluster, Grid, or Split to arrange the content inside.

Docs: https://design.hyzer.sh/docs/components/container

```ts
import { Container } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `max` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'lg'` |  |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'md'` | Both axes. Shared LayoutPadding scale — near/away tighten inside data-density-shift regions. |
| `paddingInline` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the inline axis. Same LayoutPadding scale. |
| `paddingBlock` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the block axis. Same LayoutPadding scale. |
| `center` | `boolean` | `true` |  |
| `breakout` | `boolean` | `false` | Escapes the parent column to span the nearest inline-size container (viewport when none). Overrides max. |
| `as` | `string` | `'div'` |  |
| `class` | `string` | `—` | Merged after the hz-container class. |
| `children` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-container`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-max` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | Selects which --hz-width-* token caps the column. Default lg. |
| `data-padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Padding on both axes. Default md. |
| `data-center` | `present when centered` | Applies margin-inline: auto. Present by default. |
| `data-breakout` | `present when breaking out` | Escapes the column to span the nearest inline-size container. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-breakout-shift` | `<length> — default calc(50% - 50cqw)` | Breakout alignment offset. The default assumes a centered column; set it to 0 in a start-aligned layout so the bleed only grows rightward. |

#### Accessibility

Container is a layout primitive with no ARIA semantics. Use the `as` prop to render a meaningful landmark element (e.g. as='main') where that fits.

### Stack

Lays children out in a vertical column with consistent spacing between items. Stack arranges content; pair it with a Container when the column also needs a max-width or page gutters.

Docs: https://design.hyzer.sh/docs/components/stack

```ts
import { Stack } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'near' \| 'away'` | `'md'` | near/away are the density distances — they tighten inside data-density-shift regions. |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Shared LayoutAlign scale (Stack/Cluster/Grid). |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'none'` | Both axes. Shared LayoutPadding scale — near/away tighten inside data-density-shift regions. |
| `paddingInline` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the inline axis. Same LayoutPadding scale. |
| `paddingBlock` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the block axis. Same LayoutPadding scale. |
| `as` | `string` | `'div'` |  |
| `class` | `string` | `—` | Merged after the hz-stack class. |
| `children` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-stack`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'near' \| 'away'` | Row gap. Default md. The only layout gap scale with an xl rung. |
| `data-align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | align-items. Default stretch. |
| `data-padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Padding on both axes. Default none. |

#### Accessibility

Stack is a layout primitive with no ARIA semantics. The reading and focus order follow the DOM order of children.

### Cluster

Lays children out in a horizontal row that wraps to new lines as needed.

Docs: https://design.hyzer.sh/docs/components/cluster

```ts
import { Cluster } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'sm'` | near/away are the density distances — they tighten inside data-density-shift regions. |
| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | `'start'` |  |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'center'` | Shared LayoutAlign scale (Stack/Cluster/Grid). |
| `wrap` | `boolean` | `true` |  |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'none'` | Both axes. Shared LayoutPadding scale — near/away tighten inside data-density-shift regions. |
| `paddingInline` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the inline axis. Same LayoutPadding scale. |
| `paddingBlock` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the block axis. Same LayoutPadding scale. |
| `as` | `string` | `'div'` |  |
| `class` | `string` | `—` | Merged after the hz-cluster class. |
| `children` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-cluster`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Gap between items. Default sm. |
| `data-justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | justify-content. Default start. |
| `data-align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | align-items. Default center. |
| `data-wrap` | `present when wrapping` | Present by default; its absence is styled too (:not([data-wrap]) sets nowrap). |
| `data-padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Padding on both axes. Default none. |

#### Accessibility

Cluster is a layout primitive with no ARIA semantics. Reading and focus order follow DOM order.

### Grid

Responsive CSS grid that adapts its column count to its own width via container queries.

Docs: https://design.hyzer.sh/docs/components/grid

```ts
import { Grid } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `columns` | `number \| { sm?: number; md?: number; lg?: number; xl?: number } \| { min: string }` | `{ sm: 1, md: 2, lg: 3 }` | Band keys name the band ending at their width token: sm below 640px, md to 968px, lg to 1200px, xl beyond — fixed system constants, because queries cannot read tokens. { min } is the fluid, fully var-driven mode. |
| `gap` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'md'` | near/away are the density distances — they tighten inside data-density-shift regions. |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Shared LayoutAlign scale (Stack/Cluster/Grid). |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'none'` | Both axes, on the grid root — the column breakpoints measure the padded-down width. Shared LayoutPadding scale. |
| `paddingInline` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the inline axis. Same LayoutPadding scale. |
| `paddingBlock` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the block axis. Same LayoutPadding scale. |
| `as` | `string` | `'div'` |  |
| `class` | `string` | `—` | Merged after the hz-grid class. |
| `children` | `Snippet` | `—` |  |

#### Styling

Root class: `hz-grid`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-gap` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Track gap. Default md. |
| `data-align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | align-items. Default stretch. |
| `data-padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Padding, applied to the root so container queries measure the space the tracks actually get. Default none. |
| `data-fluid` | `present in fluid mode` | Read-only: present when columns is {min}. Target it to style fluid grids apart from banded ones — the mode is set by the prop, not the attribute. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-grid-layout` | `child element` | The real grid. The root is a size container only (an element cannot container-query itself), so track and gap rules live here. |

#### Accessibility

Grid is a layout primitive with no ARIA semantics. Reading and focus order follow DOM order.

### Split

Two-column layout with configurable proportions that stacks to a single column when its own width gets narrow.

Docs: https://design.hyzer.sh/docs/components/split

```ts
import { Split } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `fraction` | `'1/4' \| '1/3' \| '1/2' \| '2/3' \| '3/4' \| 'auto'` | `'1/2'` |  |
| `gap` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'md'` | near/away are the density distances — they tighten inside data-density-shift regions. |
| `reverse` | `boolean` | `false` |  |
| `stackBelow` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Stacks under the --hz-width-sm/md/lg token (640/968/1200px) of the Split's own width. Resolves via var() — overriding the token retunes the threshold. |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `'none'` | Both axes, on the split root — stackBelow measures the padded-down width. Shared LayoutPadding scale. |
| `paddingInline` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the inline axis. Same LayoutPadding scale. |
| `paddingBlock` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | `—` | Per-axis override — wins over padding on the block axis. Same LayoutPadding scale. |
| `as` | `string` | `'div'` |  |
| `class` | `string` | `—` | Merged after the hz-split class. |
| `children` | `Snippet` | `—` | Two direct children become the columns. |

#### Styling

Root class: `hz-split`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-fraction` | `'1/4' \| '1/3' \| '1/2' \| '2/3' \| '3/4' \| 'auto'` | Ratio of the two columns above the stack threshold. Default 1/2. |
| `data-gap` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Gap between the columns. Default md. |
| `data-reverse` | `present when reversed` | Visual-only swap via order — DOM and focus order are preserved. |
| `data-stack-below` | `'sm' \| 'md' \| 'lg'` | Picks which --hz-width-* token the stack threshold resolves through, so overriding that token retunes when the split stacks. Default sm. |
| `data-padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'near' \| 'away'` | Padding, applied to the root. Default none. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-split-layout` | `child element` | The flex row. Carries the gap; the fraction and order rules reach your two children through it. |

#### Accessibility

Split is a layout primitive with no ARIA semantics. DOM order determines reading and focus order regardless of visual arrangement.

### Virtualizer

A headless windowing primitive that renders only the visible slice of a huge items array. Row heights can be uniform, known-variable, or measured at runtime.

Docs: https://design.hyzer.sh/docs/components/virtualizer

```ts
import { Virtualizer } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `T[]` | `—` | Required. |
| `itemHeight` | `number \| ((item: T, index: number) => number)` | `—` | Required. A fixed px height (uniform), or a per-item height function (known-variable). The estimate/seed when measure is true. |
| `height` | `number` | `—` | Optional — omit for fluid. Viewport extent in px for fixed, SSR-exact windowing. Omitted, the viewport is fluid: CSS-size it and the component measures its own box at runtime. |
| `measure` | `boolean` | `false` | Runtime-measures each rendered row via ResizeObserver; itemHeight becomes the seed estimate for unmeasured rows. |
| `overscan` | `number` | `3` | Extra rows rendered above/below the visible span. |
| `row` | `Snippet<[T, number]>` | `—` | Required. Renders one row — see the row snippet signature below. |
| `class` | `string` | `—` | Merged after the hz-virtualizer class. |

#### itemHeight (union)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `number` | `number` | `—` | Uniform row height in px — the O(1) fast path (no measure). |
| `(item, index) => number` | `(item: T, index: number) => number` | `—` | Known-variable — a per-row height resolved from the item/index. |

#### row snippet — Snippet<[item, index]>

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `item` | `T` | `—` | The array element rendered by this row. |
| `index` | `number` | `—` | The item's absolute index in items — not the window-local render position — so keys, striping, and aria-posinset stay correct despite windowing. |

#### Styling

Root class: `hz-virtualizer`

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-virtualizer-sizer` | `child element` | Full-height spacer that gives the scroller its scroll range. |
| `.hz-virtualizer-window` | `child element` | The translated window holding the rendered rows. |
| `.hz-virtualizer-row` | `child element` | Per-row wrapper. Also load-bearing at runtime — measured mode queries it — so it is stable by contract, not just by convention. |

#### Accessibility

Virtualizer is role-neutral by design. It applies no `role`, `aria-*`, or `tabindex` of its own. It is a rendering optimization rather than a widget, so all semantics come from the `row` snippet and `...rest` on the viewport.

Windowing removes off-screen rows from the DOM, so any count-dependent semantics must be supplied explicitly. Set `aria-setsize` to the total item count and `aria-posinset` to the row's absolute index plus one, using the absolute index the snippet receives. That way assistive tech announces 'item N of total' correctly despite the elided DOM. See the List semantics demo below.

A keyboard-scrollable viewport is opt-in: add a `tabindex` of 0 (plus a `role`/label) through `...rest`. The component adds no key handling of its own.

Virtualization can scroll a focused row out of the DOM, a known windowing hazard. Patterns that need a persistently focused off-screen row (for example, `aria-activedescendant` listboxes) should keep the active row rendered rather than reaching for the raw Virtualizer.

## Navigation

### Nav

A horizontal row of links with dropdown menus, or a vertical sidebar column with nested, multi-open disclosure sections. It stays a semantically correct navigation landmark in any context: standalone, in a sidebar, or composed by Header into a full top bar.

Docs: https://design.hyzer.sh/docs/components/nav

```ts
import { Nav } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `NavItem[]` | `—` | Required. See NavItem below. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | horizontal: a row of links with dropdown menus. vertical: a sidebar column with inline, nested, multi-open disclosure sections. |
| `ariaLabel` | `string` | `'Main navigation'` |  |
| `chevronIcon` | `Snippet` | `—` | Replaces the dropdown chevron. |
| `class` | `string` | `—` | Merged after the hz-nav class. |

#### NavItem

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `string` | `—` | Required. |
| `href` | `string` | `—` | Omit (with children present) for a trigger-only dropdown / section parent. |
| `children` | `NavChild[]` | `—` | Makes the item a dropdown (horizontal) or a nested disclosure section (vertical). May contain items or { heading } group labels. |
| `external` | `boolean` | `—` | Adds the external-link treatment. |
| `ariaCurrent` | `'page' \| 'step' \| 'true'` | `—` | Set on the active item. |
| `defaultOpen` | `boolean` | `—` | Vertical only: the section starts open, and re-opens when items is rebuilt (e.g. on navigation). |

#### Styling

Root class: `hz-nav`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-orientation` | `'horizontal' \| 'vertical'` | Selects the layout mode — a horizontal row with popover dropdown panels, or a sidebar column with inline nested disclosure sections. Default horizontal. |
| `data-state` | `'open' \| 'closed'` | On .hz-nav-panel — the dropdown/disclosure open/closed vocabulary to animate against. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-nav-links` | `child element` | The link list — a row (horizontal) or a column (vertical). |
| `.hz-nav-dropdown` | `child element` | The list item wrapping a submenu. |
| `.hz-nav-trigger` | `child element` | The label-only section toggle (no href). |
| `.hz-nav-chevron` | `child element` | The separate chevron button when the item is both a link and a toggle. |
| `.hz-nav-panel` | `child element` | The submenu list — a popover when horizontal, an inline section when vertical. |
| `.hz-nav-heading` | `child element` | A group label inside a panel: static text, no focus stop. |

#### Accessibility

Horizontal dropdowns follow the APG menu-button pattern. The trigger carries `aria-haspopup`/`aria-expanded`, the panel is a `role=menu` with roving arrow-key focus, and `Escape` closes it and returns focus to the trigger.

Vertical sections are plain disclosure (`aria-expanded` on each `<button>`), not menus, with native keyboard traversal.

A `heading` entry is static, non-focusable text read in sequence before the links it labels.

### Header

A site header bar with branding, navigation, actions, and a responsive hamburger and drawer built in. It composes Nav horizontally in the bar and vertically in the drawer, so one item set drives both.

Docs: https://design.hyzer.sh/docs/components/header

```ts
import { Header } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `NavItem[]` | `—` | Navigation — rendered horizontally in the bar and vertically in the drawer. See Nav. |
| `logo` | `Snippet` | `—` | Logo region at the start. |
| `actions` | `Snippet` | `—` | End of the bar; repeated inside the drawer. |
| `sticky` | `boolean` | `false` | position: sticky at the top of the nearest scroll container. |
| `variant` | `'default' \| 'transparent'` | `'default'` |  |
| `bordered` | `boolean` | `false` | Bottom hairline — composes with any variant. |
| `mobileBreakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Collapse threshold (640/968/1200px), a container query against the header width. none never collapses. |
| `ariaLabel` | `string` | `'Main navigation'` | Names the navigation. |
| `menuIcon` | `Snippet` | `—` | Replaces the hamburger icon. |
| `chevronIcon` | `Snippet` | `—` | Forwarded to the Nav. |
| `class` | `string` | `—` | Merged after the hz-header class. |

#### Styling

Root class: `hz-header`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-variant` | `'default' \| 'transparent'` | Bar surface treatment. Default default. |
| `data-bordered` | `present when bordered` | Bottom hairline. Composes with any variant. |
| `data-sticky` | `present when sticky` | Sticks the bar to the top. |
| `data-mobile-breakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | Which width collapses the bar into the drawer. none never collapses. Default md. |
| `data-state` | `'open' \| 'closed'` | On .hz-header-drawer — the drawer open/closed vocabulary to animate against. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-header-inner` | `child element` | The flex bar; owns its padding. |
| `.hz-header-logo` | `child element` | Wrapper for the logo snippet. |
| `.hz-header-actions` | `child element` | Wrapper for the actions snippet (in the bar). Below the mobile breakpoint, an auto inline-start margin pins it to the end, next to the hamburger — override margin-inline-start on this class (e.g. via a descendant selector off your own class prop) for centering or any other placement. |
| `.hz-header-toggle` | `child element` | The hamburger button. |
| `.hz-header-drawer` | `child element` | The mobile drawer. |
| `.hz-header-drawer-actions` | `child element` | The actions repeated inside the drawer. |

#### Accessibility

The header is a `banner` landmark. Its bar and drawer each render a `Nav` landmark with distinct accessible names (`ariaLabel` and `ariaLabel (menu)`), so they do not collide.

The hamburger carries `aria-expanded` and `aria-controls`. The open drawer traps focus. `Escape` closes it and returns focus to the toggle.

At narrow widths, the drawer keeps every link reachable.

### Footer

Site footer with auto-fitting multi-column link groups, optional logo, social links, and a bottom bar.

Docs: https://design.hyzer.sh/docs/components/footer

```ts
import { Footer } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `columns` | `FooterColumn[]` | `—` | Required. See FooterColumn below. |
| `variant` | `'default' \| 'minimal'` | `'default'` |  |
| `bordered` | `boolean` | `false` | Top hairline — composes with any variant. |
| `linkVariant` | `'default' \| 'subtle' \| 'nav'` | `'subtle'` | Passed through to every column Link. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading element for column titles — match your page hierarchy. |
| `logo` | `Snippet` | `—` | Rendered above the columns. |
| `social` | `Snippet` | `—` | Icon-link row rendered under the columns. |
| `bottom` | `Snippet` | `—` | Bottom bar with a top hairline — copyright, legal links. |
| `class` | `string` | `—` | Merged after the hz-footer class. |

#### FooterColumn

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `title` | `string` | `—` | Required. Labels the column’s nav landmark. |
| `links` | `NavItem[]` | `—` | Required. label/href/external/ariaCurrent apply — see NavItem on the Nav page. |

#### Styling

Root class: `hz-footer`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-variant` | `'default' \| 'minimal'` | minimal drops the padding and goes transparent. Default default. |
| `data-bordered` | `present when bordered` | Top hairline. A prop, not a variant — it composes with either surface. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-footer-col-min` | `<length> — default 12rem` | Minimum column width for the auto-fit link grid: how narrow a column may get before the row reflows. No media queries involved — this is the whole knob. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-footer-logo` | `child element` | Wrapper for the logo snippet. |
| `.hz-footer-columns` | `on a Grid` | Rides through Grid’s class prop. The auto-fit override hangs off it — and lands on .hz-grid-layout, since that is where Grid does its layout. |
| `.hz-footer-column` | `child element` | One column’s nav landmark. |
| `.hz-footer-heading` | `child element` | A column heading. |
| `.hz-footer-social` | `child element` | Wrapper for the social snippet. |
| `.hz-footer-bottom` | `child element` | The bottom bar. |

#### Accessibility

Each column is a `<nav>` landmark whose `aria-label` is its title. The visible heading repeats that text, but the heading is not what names the landmark. Set `headingLevel` to match your page hierarchy. Links use the Link component, and icon-only social links need an `ariaLabel`.

### Breadcrumbs

A wrapping breadcrumb trail of navigation links with chevron separators and automatic current-page semantics.

Docs: https://design.hyzer.sh/docs/components/breadcrumbs

```ts
import { Breadcrumbs } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `BreadcrumbItem[]` | `—` | Required. See BreadcrumbItem below. |
| `ariaLabel` | `string` | `'Breadcrumb'` |  |
| `separator` | `Snippet` | `—` | Replaces the chevron between items; rendered aria-hidden. |
| `class` | `string` | `—` | Merged after the hz-breadcrumbs class. |

#### BreadcrumbItem

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `string` | `—` | Required. |
| `href` | `string` | `—` | Omit on the last item to render the current page as plain text. |
| `external` | `boolean` | `—` | Adds the external-link treatment. |
| `ariaCurrent` | `'page' \| 'step' \| 'true'` | `—` | The last item gets aria-current="page" automatically; set this to override. |

#### Styling

Root class: `hz-breadcrumbs`

| Attribute | Values | Notes |
| --- | --- | --- |
| `[aria-current]` | `'page'` | Not a data hook — Breadcrumbs stamps no data-*. The last crumb carries aria-current, and that is the only state selector on offer. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-breadcrumbs-current` | `child element` | The final crumb when it has no href (plain text rather than a link). |
| `.hz-breadcrumbs-separator` | `child element` | The aria-hidden separator wrapper; sizes its icon to 1em. |

#### Accessibility

Breadcrumbs renders a `<nav aria-label="Breadcrumb">` landmark wrapping an ordered list. The last item is the current page: it gets `aria-current="page"` automatically, and renders as plain text when it has no `href`. Separators are decorative and `aria-hidden`.

### Pagination

A navigation landmark of page controls: previous and next, boundary and sibling windows with ellipsis truncation, and button or real-link modes.

Docs: https://design.hyzer.sh/docs/components/pagination

```ts
import { Pagination } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `count` | `number` | `—` | Required. Total pages. |
| `page` | `number` | `1` | Bindable. 1-based. |
| `siblings` | `number` | `1` | Pages shown on each side of the current page. |
| `boundaries` | `number` | `1` | Pages pinned at each end. |
| `href` | `(page: number) => string` | `—` | Link mode: items render as real anchors; omit for button mode. |
| `onchange` | `(page: number) => void` | `—` |  |
| `ariaLabel` | `string` | `'Pagination'` | Names the landmark. |
| `prevLabel` | `string` | `'Previous page'` |  |
| `nextLabel` | `string` | `'Next page'` |  |
| `pageLabel` | `(page: number) => string` | ``Page ${page}`` | Accessible name per page item. |
| `class` | `string` | `—` | Merged after the hz-pagination class. |

#### Styling

Root class: `hz-pagination`

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-pagination-list` | `child element` | The row of page controls. |
| `.hz-pagination-page` | `on a Button` | Rides through Button’s class prop, so it lands on a .hz-button — target it accordingly. Tabular numerals and a min-width keep the row from jittering. |
| `.hz-pagination-prev` | `on a Button` | Previous control. Also a .hz-button. |
| `.hz-pagination-next` | `on a Button` | Next control. Also a .hz-button. |
| `.hz-pagination-ellipsis` | `child element` | The aria-hidden gap marker. |

#### Accessibility

Pagination renders a `<nav>` landmark named by `ariaLabel`. Give it a distinct name when a page hosts several.

Every control is a `Button`. The current item carries `aria-current="page"`, and page items get full accessible names via `pageLabel` ("Page 7", not a bare number). Ellipses are decorative.

In link mode, everything is a real `<a>`. At the ends, the previous and next controls render as disabled Buttons with no `href`, because a link cannot be disabled and a dead link that announces itself helps no one.

Tab order is native. There are no roving-focus tricks.

### Toc

A table-of-contents rail with automatic heading collection, nested levels, scroll-spy, smooth scroll, and an optional mobile collapse. It is the docs site's own 'On this page' rail, generalized behind props.

Docs: https://design.hyzer.sh/docs/components/toc

```ts
import { Toc } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `container` | `string \| HTMLElement` | `'main'` | Selector or element to collect headings from. |
| `levels` | `number[]` | `[2]` | Heading levels to collect — 2 for h2, 3 for h3, and so on. |
| `exclude` | `string \| string[]` | `—` | Headings inside a match are skipped (e.g. demo/example regions). Pass an array to combine several selectors. |
| `minEntries` | `number` | `2` | Renders nothing below this many entries — a single link is not navigation. |
| `title` | `string` | `'On this page'` | '' hides it. |
| `ariaLabel` | `string` | `— (defaults to title)` | Names the nav landmark. |
| `autoId` | `boolean` | `true` | Slugify id-less headings (kebab, deduped with -2, -3 …). false skips them instead. |
| `watch` | `boolean` | `true` | Re-collects on DOM mutation (a MutationObserver on container, debounced). No framework coupling — no $app/* import, so it works the same in any SvelteKit or plain-Svelte app. |
| `smoothScroll` | `boolean` | `true` | Instant under prefers-reduced-motion regardless. |
| `breakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'none'` | Collapses into a disclosure below this width (640/968/1200px). none never collapses. |
| `active` | `string` | `''` | Bindable id of the current heading (scroll-spy — or the last clicked link). |
| `onActive` | `(id: string) => void` | `—` | Fires when the active heading changes — not on every scroll frame. |
| `class` | `string` | `—` | Merged after the hz-toc class. |

#### TocEntry

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | `—` | The heading's id — its own, or an autoId slug. |
| `label` | `string` | `—` | The heading's trimmed text content. |
| `level` | `number` | `—` | The collected heading level (2, 3, …). |

#### Styling

Root class: `hz-toc`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-breakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | Which width the rail collapses below into a disclosure. none (default) never collapses. A real @media breakpoint, not a container query — the rail’s own box is typically narrow regardless of page width. |
| `data-collapsed` | `present while the mobile disclosure is closed` | Only stamped when data-breakpoint is not none. Absent once the panel opens, and inert above the breakpoint, where the panel is always shown. |
| `[aria-current]` | `'location'` | On .hz-toc-link — the scroll-spy’s active entry. Not a data-* hook. |
| `data-level (on .hz-toc-link)` | `<number> — the collected heading level (2, 3, …)` | Per-entry, not root-level — drives the indent. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-toc-title` | `child element` | The plain (non-heading) title. |
| `.hz-toc-trigger` | `child element` | The mobile disclosure button (title + chevron). Always rendered, shown only below the breakpoint — the theme swaps it in for .hz-toc-title by data-breakpoint and the viewport, the Header toggle precedent. |
| `.hz-toc-panel` | `child element` | Wraps the list; what the trigger shows/hides below the breakpoint. |
| `.hz-toc-list` | `child element` | A nested <ul>, one per level below the top. |
| `.hz-toc-link` | `child element` | One entry. |

#### Accessibility

The root is a `nav` landmark named by `ariaLabel` (which defaults to `title`). Give every Toc on a page a distinct name if there's more than one.

The active entry carries `aria-current="location"`, updated by the scroll-spy and by clicking a link.

In collapse mode, the trigger is a real disclosure button (`aria-expanded`/`aria-controls`). `Escape` closes it and returns focus to the trigger, and an outside click closes it without stealing focus from wherever the click landed.

Motion respects `prefers-reduced-motion`: `smoothScroll` degrades to an instant jump automatically.

## Media

### Image

Responsive image with aspect-ratio, object-fit, rounded corners, color and blur placeholder states, and a picture mode for art direction.

Docs: https://design.hyzer.sh/docs/components/image

```ts
import { Image } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `src` | `string` | `—` | Required. Fallback in picture mode. |
| `alt` | `string` | `—` | Required. Empty string for decorative. |
| `sources` | `ImageSource[]` | `—` | Renders a <picture>: candidates in priority order — see ImageSource below. src remains the fallback and drives the load state. |
| `width` | `number` | `—` |  |
| `height` | `number` | `—` |  |
| `loading` | `'lazy' \| 'eager'` | `'lazy'` |  |
| `aspectRatio` | `'auto' \| '1/1' \| '4/3' \| '16/9' \| '21/9' \| string` | `'auto'` |  |
| `fit` | `'cover' \| 'contain' \| 'fill' \| 'none'` | `'cover'` |  |
| `rounded` | `boolean \| 'sm' \| 'md' \| 'lg' \| 'full'` | `false` | true is shorthand for md. |
| `placeholder` | `'blur' \| 'color' \| 'none'` | `'none'` |  |
| `placeholderSrc` | `string` | `—` | Low-res image for placeholder="blur"; required in that mode. |
| `placeholderColor` | `string` | `'var(--hz-color-border)'` |  |
| `class` | `string` | `—` | Merged after the hz-image class. |

#### ImageSource

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `srcset` | `string` | `—` | Required. Candidate URL(s) for this source. |
| `type` | `string` | `—` | MIME type for format negotiation, e.g. 'image/avif'. |
| `media` | `string` | `—` | Viewport media query for art direction, e.g. (min-width: 968px). |
| `sizes` | `string` | `—` |  |

#### Styling

Root class: `hz-image`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'loading' \| 'loaded' \| 'error'` | The load lifecycle. Read-only — the component owns it. Drives the placeholder crossfade and the error surface. |
| `data-fit` | `'cover' \| 'contain' \| 'fill' \| 'none'` | object-fit on the inner img. Default cover. |
| `data-rounded` | `present \| 'sm' \| 'md' \| 'lg' \| 'full'` | Corner radius. Bare presence (from rounded={true}) means md. |
| `data-aspect-ratio` | `'auto' \| '1/1' \| '4/3' \| '16/9' \| '21/9' \| any ratio` | Mirrors the prop; the ratio itself lands as an inline style. The union is open — the listed values are documentation, not a limit. |
| `data-placeholder` | `'blur' \| 'color'` | Absent when there is no placeholder — you cannot select [data-placeholder='none']. blur without placeholderSrc degrades to none. |
| `data-loading` | `'lazy' \| 'eager'` | Mirrors the loading prop. |
| `data-picture` | `present in picture mode` | Present when sources are supplied. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-image-placeholder-blur` | `<length> — default 20px` | Blur radius on the low-res placeholder. |
| `--hz-image-fade-duration` | `<time> — default 0.3s` | Placeholder crossfade duration. Read at both ends of the fade, so the two stay locked together. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-image__img` | `child element` | The real img. Note the BEM double underscore — Image and Video use it; the rest of the library uses a single dash. |
| `.hz-image__placeholder` | `child element` | The decorative low-res image that fades out. |
| `.hz-image__picture` | `child element` | The <picture> element. display: contents, so it adds no box. |

#### Accessibility

Pass descriptive alt text for informative images. Pass `alt=''` for decorative images: the component then sets `role='presentation'` for you.

### Lightbox

A click-to-enlarge media viewer: a thumbnail strip whose items open in an accessible, focus-trapped dialog. Multiple images and videos page through an embedded Carousel.

Docs: https://design.hyzer.sh/docs/components/lightbox

```ts
import { Lightbox } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `LightboxItem[]` | `—` | Media entries (images and videos) — see LightboxItem below. Renders one thumbnail trigger per item; the viewer pages through them with a Carousel. |
| `src / alt / thumbSrc / caption` | `string` | `—` | Single-image sugar — equivalent to a one-item items array. |
| `open` | `boolean (bindable)` | `false` |  |
| `dialogLabel` | `string` | `'Media viewer'` | Dialog name in multi-item mode (single items are labeled by their own name). |
| `triggerLabel` | `string` | `'View larger: {name}'` | Single trigger only. |
| `closeLabel` | `string` | `'Close media viewer'` |  |
| `prevLabel` | `string` | `'Previous item'` |  |
| `nextLabel` | `string` | `'Next item'` |  |
| `onclose` | `() => void` | `—` | Fires once per dismissal. |
| `children` | `Snippet` | `—` | Custom trigger content — replaces the thumbnail strip; opens the first item. |
| `trigger` | `Snippet<[LightboxItem, number]>` | `—` | Per-item trigger face, e.g. an Image — replaces the default thumb/badge for every item. Ignored (with a DEV warning) when children is also passed. |
| `class` | `string` | `—` | Merged after the hz-lightbox-triggers class (the inline strip). |

#### LightboxItem (image)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `type` | `'image'` | `'image'` | Optional — image is the default. |
| `src` | `string` | `—` | Required. Full-size image. |
| `alt` | `string` | `—` | Required. |
| `thumbSrc` | `string` | `—` | Strip thumbnail; defaults to src. |
| `caption` | `string` | `—` |  |

#### LightboxItem (video)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `type` | `'video'` | `—` | Required for videos. |
| `src` | `string` | `—` | Required. Native file or YouTube/Vimeo URL — plays via the Video component. |
| `label` | `string` | `—` | Required. Accessible name (the Video title). |
| `poster` | `string` | `—` |  |
| `thumbSrc` | `string` | `—` | Strip thumbnail; defaults to poster. |
| `caption` | `string` | `—` |  |

#### Styling

Root class: `hz-lightbox-triggers`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'open' \| 'closed'` | On the viewer dialog, mirroring the bindable open prop. Visibility itself runs off the native [open] attribute — this is the hook to animate against. |
| `data-gallery` | `present with more than one item` | On the viewer dialog. Drives the fixed gallery stage sizing that a single item skips (it hugs its media instead). |
| `data-lightbox-trigger` | `present on a grouped trigger` | Set by the lightboxGroup attachment rather than the component. Its only styling is a zoom-in cursor. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-lightbox-trigger` | `child element` | A thumbnail button. Also the root class when you supply your own children. |
| `.hz-lightbox-thumb` | `child element` | The thumbnail image. |
| `.hz-lightbox-thumb-label` | `child element` | Fallback chip when no thumbnail resolves. |
| `.hz-lightbox-badge` | `child element` | The play marker on video items. |
| `.hz-lightbox` | `the viewer dialog` | The overlay itself. It takes no class prop, so this name is unconditionally stable. |
| `.hz-lightbox-close` | `child element` | The close control. |
| `.hz-lightbox-carousel` | `on the embedded Carousel` | Multi-item viewers only — see Carousel for its own parts underneath. |
| `.hz-lightbox-figure` | `child element` | The figure wrapping each item. |
| `.hz-lightbox-caption` | `child element` | The caption. |
| `.hz-lightbox-img` | `on an Image's wrapper` | Rides through Image’s class prop — so it names a div, not an img. Reach the picture itself through .hz-lightbox-img .hz-image__img. |
| `.hz-lightbox-video` | `child element` | The wrapper around a video item’s Video. |

#### Accessibility

Each thumbnail is a real `<button>` with `aria-haspopup="dialog"`, named by its item.

The viewer is a native `<dialog>` opened with `showModal()`. Focus is trapped. Escape and the backdrop both close it, and focus returns to the thumbnail that opened it.

Multi-item viewers embed the Carousel (labeled slides, live announcements), and ArrowLeft/ArrowRight page through it from anywhere in the dialog. Body scroll is locked while open.

### Logo

Renders a raw inline SVG mark at a size normalized against its own aspect ratio, so a wide wordmark, a square badge, and a tall crest read as consistent side by side. With no SVG it falls back to the brand name as text.

Docs: https://design.hyzer.sh/docs/components/logo

```ts
import { Logo } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Names the mark for assistive technology, and is the visible text when no SVG is given. |
| `svg` | `string` | `—` | Raw SVG markup, rendered as-is and never sanitized. Pass only a static asset you control — a `?raw` import or a build-time constant, never user input or a fetched string. Missing (or whitespace-only) renders `name` as text instead. |
| `children` | `Snippet` | `—` | Another way to supply the mark: an `<svg>` written directly as markup. Logo can only measure it once it mounts in the browser, while `svg` is measured during server rendering. If both are given, `svg` wins. |
| `scale` | `number` | `1` | A multiplier on top of the normalized width — the optical-weight knob. A positive number, typically 0.7-1.4. |
| `brightness` | `number` | `1` | A filter: brightness() nudge for a mark that reads too dark or too light. Written inline only when it differs from 1. |
| `decorative` | `boolean` | `false` | Set when adjacent text already names the brand — hides the mark from assistive technology entirely. |
| `monochrome` | `boolean` | `true` | Recolors the mark to one color that follows the surrounding text. Set to false to keep the SVG's own colors. |
| `class` | `string` | `—` | Merged after the hz-logo class. |

#### Styling

Root class: `hz-logo`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-fallback` | `present with no svg` | The text form — no injected SVG, .hz-logo-text renders the name instead. |
| `data-monochrome` | `present by default` | Absent when monochrome={false}. Gates the fill rule below, so an unset SVG keeps its own colours. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-logo-size` | `<length> — default clamp(4rem, 8vw, 6rem)` | The normalization base every logo scales against. Override it on a wall container (Cluster/Grid) to resize every logo inside at once. |
| `--hz-logo-brightness` | `<number> — default 1` | Applied as filter: brightness(). Usually set through the brightness prop, which stamps it inline only when != 1 — the hook stays directly settable in CSS for container-wide muting. |
| `--hz-logo-color` | `<color> — default currentColor` | Read, not declared, in the monochrome fill rule — a wall mutes itself with one override, the Container --hz-breakout-shift precedent for a read-only hook. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-logo-text` | `child element` | The text fallback. |

#### Accessibility

An informative logo (the default) gets `role="img"` and an `aria-label` taken from `name`. Assistive technology reads one graphic with one name, however many paths or groups the SVG holds inside. Set `decorative` when nearby text already says the brand name; the mark is then hidden from assistive technology. With no `svg`, `name` renders as real, selectable text and needs no `role` at all.

### Video

Video player supporting YouTube, Vimeo embeds, and native HTML5 video. Detects provider from URL and builds the correct embed.

Docs: https://design.hyzer.sh/docs/components/video

```ts
import { Video } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `src` | `string` | `—` | Required. Native file URL, or a YouTube/Vimeo URL — the provider is detected and the right embed is built. |
| `title` | `string` | `—` | Required for accessibility. |
| `aspectRatio` | `'16/9' \| '4/3' \| '1/1' \| '9/16'` | `'16/9'` |  |
| `autoplay` | `boolean` | `false` | Requires muted; suppressed under prefers-reduced-motion. |
| `muted` | `boolean` | `false` |  |
| `controls` | `boolean` | `true` |  |
| `loop` | `boolean` | `false` |  |
| `poster` | `string` | `—` | Native provider only. |
| `loading` | `'lazy' \| 'eager'` | `'lazy'` |  |
| `class` | `string` | `—` | Merged after the hz-video class. |

#### Styling

Root class: `hz-video`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-provider` | `'youtube' \| 'vimeo' \| 'native'` | Detected from src. Styling hook for provider-specific chrome. |
| `data-aspect-ratio` | `'16/9' \| '4/3' \| '1/1' \| '9/16'` | Mirrors the prop; the ratio lands as an inline style. Closed union — unlike Image, there is no auto. Default 16/9. |
| `data-state` | `'idle' \| 'playing' \| 'paused' \| 'ended'` | Read-only playback state. Native embeds only — a YouTube or Vimeo iframe stays idle, because the provider owns those controls. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-video__el` | `child element` | The player — the iframe or the native video, whichever the src resolved to. One class across all three branches, so it fills the ratio box either way. |

#### Accessibility

The `title` prop is required and maps to the iframe title or video aria-label. `autoplay` requires `muted`, both because browsers refuse to autoplay sound and because motion a reader did not ask for is disorienting.

## Forms

### Form

A form wrapper that renders an accessible error summary and moves focus on failed submits, while staying out of the way of native submission and SvelteKit's use:enhance.

Docs: https://design.hyzer.sh/docs/components/form

```ts
import { Form, toFormErrors } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `errors` | `FormError[]` | `[]` | The summary renders when non-empty. See FormError below. |
| `onSubmit` | `(e: SubmitEvent) => void` | `—` | Omit for native submission / use:enhance (the default path); provide it for client-side validation — preventDefault runs first. |
| `summaryTitle` | `string \| ((count: number) => string)` | `'There is a problem'` | A string overrides the default outright; a function receives the error count. The default is count-aware and plural-safe: "There is a problem" for 1, "There are 3 problems" for 3. |
| `summaryHeadingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | Match the page's heading structure. |
| `focusTarget` | `'summary' \| 'firstField'` | `'summary'` | What receives focus after a submit with errors. |
| `novalidate` | `boolean` | `false` |  |
| `ariaLabel` | `string` | `—` | Names the form landmark. |
| `children` | `Snippet` | `—` | Required. The form content. |
| `class` | `string` | `—` | Merged after the hz-form class. |

#### FormError

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Field name to link to. Empty or unresolved names become non-interactive form-level errors, listed last. |
| `message` | `string` | `—` | Required. |

#### Styling

Root class: `hz-form`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'error' \| absent` | Present once the summary has errors. Two-state, unlike the field family’s three — a form is never disabled. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-form-error-summary` | `on an Alert` | The summary box — an Alert underneath. Load-bearing beyond styling: the focus-on-submit path queries this class. |
| `.hz-form-error-list` | `child element` | The list of errors. |
| `.hz-form-error-summary-item` | `child element` | One error row, including its jump link. |

#### Accessibility

The error summary is the first child of the form and has `role="alert"`, so it is announced when it appears. It takes focus when errors arrive after a submit. With `focusTarget="firstField"`, the first invalid field takes focus instead.

Each summary item links to its field and focuses it on activation, scrolling smoothly unless `prefers-reduced-motion` is set.

Set `summaryHeadingLevel` so the summary title fits your page's heading outline.

### TextInput

A labeled single-line input covering the common HTML input types, with description, inline error, and decorative prefix and suffix slots.

Docs: https://design.hyzer.sh/docs/components/text-input

```ts
import { TextInput } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `type` | `'text' \| 'email' \| 'password' \| 'tel' \| 'url' \| 'search' \| 'number' \| 'date' \| 'time' \| 'datetime-local'` | `'text'` | Date/time types render the native platform picker. |
| `value` | `string` | `''` | Bindable. |
| `placeholder` | `string` | `—` |  |
| `autocomplete` | `HTMLInputAttributes['autocomplete']` | `—` | Native autofill hint, e.g. "email", "name". |
| `maxlength` | `number` | `—` |  |
| `pattern` | `string` | `—` | Native validation regex. |
| `inputmode` | `HTMLInputAttributes['inputmode']` | `—` | Virtual-keyboard hint, e.g. "numeric", "tel". |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `prefix` | `Snippet` | `—` | Decorative leading content (icon, symbol); rendered aria-hidden. |
| `suffix` | `Snippet` | `—` | Decorative trailing content (unit, icon); rendered aria-hidden. |
| `class` | `string` | `—` | Merged after the hz-field class. |

#### Styling

Root class: `hz-field`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-has-prefix` | `present when a prefix is set` | On .hz-input-wrapper. The reference theme ships no rule for it — it exists so you can, e.g., retune padding when an affix is present. |
| `data-has-suffix` | `present when a suffix is set` | On .hz-input-wrapper. Same: yours to use. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-input-wrapper` | `child element` | The bordered box. It carries the border, so prefix and suffix sit inside it. |
| `.hz-input-prefix` | `child element` | The leading affix. |
| `.hz-input-suffix` | `child element` | The trailing affix. |

#### Accessibility

The input is associated with its label via `id`/`for`. With `hideLabel`, the label stays in the DOM as screen-reader-only text.

`description` and `error` chain into `aria-describedby`, description first. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

`prefix` and `suffix` are rendered `aria-hidden`. Keep them decorative, and put any meaning in the label or description instead.

### Textarea

A labeled multi-line text area with configurable resize behavior, including an auto-grow mode, plus description and inline error.

Docs: https://design.hyzer.sh/docs/components/textarea

```ts
import { Textarea } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `value` | `string` | `''` | Bindable. |
| `rows` | `number` | `3` |  |
| `resize` | `'none' \| 'vertical' \| 'both' \| 'auto'` | `'vertical'` | 'vertical' and 'auto' grow with content; 'vertical' keeps the drag handle, 'auto' hides it. rows is the minimum height. |
| `maxlength` | `number` | `—` |  |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field class. |

#### Styling

Root class: `hz-field`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-resize` | `'none' \| 'vertical' \| 'both' \| 'auto'` | On the textarea. Default vertical; auto uses field-sizing: content. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |

#### Accessibility

The textarea is associated with its label via `id`/`for`. With `hideLabel`, the label stays in the DOM as screen-reader-only text.

`description` and `error` chain into `aria-describedby`, description first. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

### Checkbox

A labeled checkbox with description, inline error, and an indeterminate state for select-all patterns.

Docs: https://design.hyzer.sh/docs/components/checkbox

```ts
import { Checkbox } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `checked` | `boolean` | `false` | Bindable. |
| `indeterminate` | `boolean` | `false` | Set via the DOM .indeterminate property; visual only, checked is unaffected. |
| `value` | `string` | `—` | Submitted value when checked. |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-field--checkbox classes. |

#### Styling

Root class: `hz-field hz-field--checkbox`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `:checked / :indeterminate` | `native pseudo-classes` | Checkbox stamps no attribute for either — style the native pseudo-classes. (indeterminate is set as a DOM property, so only :indeterminate sees it.) |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |

#### Accessibility

The input is associated with its label via `id`/`for` (the label renders after the box). `description` and `error` chain into `aria-describedby`, description first. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

`indeterminate` is applied through the DOM `.indeterminate` property, so screen readers announce the mixed state natively.

### RadioGroup

A group of radio buttons in a fieldset with a legend, vertical or horizontal layout, and standard field accessibility.

Docs: https://design.hyzer.sh/docs/components/radio-group

```ts
import { RadioGroup } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Shared by every radio in the group. |
| `label` | `string` | `—` | Required. Rendered as the fieldset legend; sr-only with hideLabel. |
| `options` | `FormOption[]` | `—` | Required. See FormOption below. |
| `value` | `string` | `''` | Bindable. The selected option value. |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` |  |
| `description` | `string` | `—` | Help text below the legend. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` | Disables the whole group. |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-field--radio-group classes. |

#### FormOption

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `string` | `—` | Required. |
| `label` | `string` | `—` | Required. |
| `disabled` | `boolean` | `—` | Disables only this option. |

#### Styling

Root class: `hz-field hz-field--radio-group`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Default vertical. The root is a fieldset and the label is its legend. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-radio-options` | `child element` | The radiogroup container. |
| `.hz-radio-option` | `child element` | One option row. |

#### Accessibility

The group is a `<fieldset>` whose `label` renders as the `<legend>`. With `hideLabel`, the legend stays in the DOM as screen-reader-only text. Each radio has its own label.

The options sit in an inner `role="radiogroup"` container that carries `aria-describedby` (description first, then error), `aria-invalid` on error, and `aria-required` when required.

Arrow-key movement between radios is native browser behavior.

### Toggle

A switch for binary on and off settings. It is a native checkbox exposed with the switch role, so it submits a form value like any other field.

Docs: https://design.hyzer.sh/docs/components/toggle

```ts
import { Toggle } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `checked` | `boolean` | `false` | Bindable. |
| `value` | `string` | `—` | Submitted value when on. |
| `description` | `string` | `—` | Help text on its own row. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-field--toggle classes. |

#### Styling

Root class: `hz-field hz-field--toggle`

> `.hz-field--toggle input.hz-toggle` — the track and thumb — is the one rule in the reference theme shipped outside `@layer hz-theme`, on purpose: headless, Toggle is a bare native checkbox, so this rule needs to out-rank the component's own scoped structural reset unconditionally, and a layer can only lose to an unlayered rule regardless of specificity. It sits at a raw `(0,2,1)` specificity. A normal override written inside a layer — or even an unlayered rule that ties on specificity and loses on source order — silently does nothing; the toggle keeps its default look with no error. To win reliably, give your override enough specificity to clear `(0,2,1)` outright, e.g. by scoping it under your own theme's root class: `.your-theme .hz-field--toggle input.hz-toggle { … }`. See the Terminal example theme for a worked example (`theme/examples/terminal/components/toggle.css`), which does exactly this. The same applies to the `--hz-toggle-width` / `--hz-toggle-height` custom properties below — they're declared directly on that selector, so setting them from a lower-specificity or losing rule never reaches the element.

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state (on the root)` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, as on every field. Precedence is fixed: error beats disabled. |
| `data-state (on input.hz-toggle)` | `'on' \| 'off'` | A second data-state nested inside the root’s, with a disjoint vocabulary — this is the stable hook for the track and thumb. It exists rather than relying on :checked because the toggle rules must win the specificity fight described above, and an attribute selector composes into them cleanly. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-toggle-width` | `<length> — default 2.5rem` | Track width, and the distance the thumb travels. |
| `--hz-toggle-height` | `<length> — default 1.5rem` | Track height. The thumb derives from it (height minus a 2px inset all round), so there is no separate thumb knob — and the travel stays correct under any override. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-toggle` | `the checkbox input` | The track. Its ::before is the thumb, so the thumb has no class of its own. |

#### Accessibility

Toggle renders an `<input type="checkbox" role="switch">` associated with its label via `id`/`for`. Screen readers announce it as a switch, while the native checked state, keyboard behavior (Space toggles, Enter submits the form), and form participation all come from the platform.

`description` and `error` chain into `aria-describedby`, description first. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

### Select

A labeled native select with flat options, option groups, a placeholder option, and standard field accessibility.

Docs: https://design.hyzer.sh/docs/components/select

```ts
import { Select } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `options` | `SelectOption[]` | `—` | Required. Flat options and optgroups mix freely — see SelectOption below. |
| `multiple` | `boolean` | `false` | Renders the native multiple attribute; switches value to string[]. |
| `value` | `string \| string[]` | `'' (single) / [] (multiple)` | Bindable. A discriminated union on multiple: string when omitted/false, string[] when true. |
| `placeholder` | `string` | `'Select...'` | Rendered as a disabled leading option. |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field class. |

#### SelectOption (flat arm: FormOption)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `string` | `—` | Required. |
| `label` | `string` | `—` | Required. |
| `disabled` | `boolean` | `—` | — |

#### SelectOption (group arm)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `group` | `string` | `—` | Group form: renders an <optgroup> with this label. |
| `options` | `FormOption[]` | `—` | Group form: the flat options inside the group. |

#### Styling

Root class: `hz-field`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |

#### Accessibility

The select is associated with its label via `id`/`for`. With `hideLabel`, the label stays in the DOM as screen-reader-only text.

`description` and `error` chain into `aria-describedby`, description first. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

The control is the native `<select>`, so keyboard and assistive-tech behavior come from the platform.

### Combobox

A multi-select, filterable text input that follows the WAI-ARIA APG combobox (list-autocomplete) pattern, with each pick rendered as a dismissible chip.

Docs: https://design.hyzer.sh/docs/components/combobox

```ts
import { Combobox } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Repeated on every hidden input. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `options` | `FormOption[]` | `—` | Required. Flat, multi-select — see FormOption below. |
| `value` | `string[]` | `[]` | Bindable. Selected option values, in selection order. |
| `placeholder` | `string` | `'Search...'` | Shown only while nothing is selected — once chips exist, they say it better. |
| `filter` | `(query: string, option: FormOption) => boolean` | `—` | Overrides the default case-insensitive substring match. |
| `emptyText` | `string` | `'No results'` |  |
| `toggleLabel` | `string` | `'Show options'` |  |
| `chipProps` | `ComboboxChipProps` | `{}` | Styling applied to every chip — see ComboboxChipProps below. Resolves to size: 'sm'. |
| `onchange` | `(value: string[]) => void` | `—` | Fires on every selection change: toggle, chip dismiss, or Backspace removal. |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-combobox classes. |

#### FormOption

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `string` | `—` | Required. |
| `label` | `string` | `—` | Required. Shown on the chip and in the option row. |
| `disabled` | `boolean` | `—` | Inert — visible but never toggleable; an existing selection stays removable. |

#### ComboboxChipProps

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `intent` | `Intent` | `'neutral'` | See Foundation → Colors & Intent. |
| `variant` | `'soft' \| 'solid' \| 'outline'` | `'soft'` |  |
| `size` | `'sm' \| 'md'` | `'sm'` | Combobox's own default overrides Badge's md default. |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` |  |
| `class` | `string` | `—` |  |

#### Styling

Root class: `hz-field hz-combobox`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-open` | `present while the popup is open` | On the root. Rotates the toggle chevron and gates the popup. |
| `data-active` | `present on the active option` | Virtual focus — the highlighted option. Real focus stays in the input. |
| `data-selected` | `present on selected options` | Selected options; the theme adds a checkmark. |
| `data-disabled` | `present on disabled options` | Per-option. Disabled options stay focusable (aria-disabled, not the native attribute). |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-combobox-control` | `child element` | The bordered row holding the input, chips, and toggle. |
| `.hz-combobox-input` | `child element` | The text input. |
| `.hz-combobox-toggle` | `child element` | The chevron button. |
| `.hz-combobox-popup` | `child element` | The floating panel. |
| `.hz-combobox-listbox` | `child element` | The option list. |
| `.hz-combobox-option` | `child element` | One option. |
| `.hz-combobox-empty` | `child element` | The no-results message. |

#### Accessibility

The visible input carries `role=combobox` with `aria-autocomplete=list`, `aria-expanded`, and `aria-controls` pointing at the `role=listbox` popup, which is `aria-multiselectable`. DOM focus never moves into the list: the highlighted option is tracked as virtual focus with `aria-activedescendant` on the input, so screen readers announce the active option while the field stays editable.

`description`/`error` chain into `aria-describedby` on the input (description first), still computed even while the popup visually overlays that region. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

Each selected value renders as a `Badge` chip inside the control. Every chip has a labeled dismiss button, announced as Remove followed by the option's label. Each of those buttons is a real tab stop of its own, so tabbing into the field reaches the chips before the input.

Keyboard: `ArrowDown`/`ArrowUp` open the popup and move the active option, wrapping and skipping disabled entries. `Alt+ArrowDown` opens without moving, and `Alt+ArrowUp` closes without changing anything. `Home`/`End` jump to the first and last enabled option while open (they're native text-cursor moves while closed). `Enter` toggles the active option's membership and keeps the popup open so you can keep picking. `Backspace` on an empty query removes the last chip. `Escape` closes the popup and clears the filter query. It never clears a selection, since every chip has its own dismiss button. `Tab` closes the popup and lets focus move on.

The input is the only tab stop that opens the popup. The trailing toggle button is `tabindex=-1`, reachable by pointer only.

### FileUpload

A file selection field backed by a real native input, single or multiple, with accept, maxSize, and maxFiles validation, a removable file list, and an optional drag-and-drop dropzone. It selects files rather than uploading them: the named input carries the chosen files into a plain form submission or into your own upload code.

Docs: https://design.hyzer.sh/docs/components/file-upload

```ts
import { FileUpload } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Carried by the native input. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `files` | `File[]` | `[]` | Bindable. Selected files in selection order — not a FileList. |
| `multiple` | `boolean` | `false` | Single mode replaces on each pick; multiple mode appends + de-dupes. |
| `accept` | `string` | `—` | Native accept syntax: extensions, exact MIME types, or wildcard MIME types. |
| `maxSize` | `number` | `—` | Bytes, per file. No total-size cap. |
| `maxFiles` | `number` | `—` | Multiple mode only — ignored in single mode (the cap is always 1). |
| `dropzone` | `boolean` | `false` | Swaps the visible input for a drag-and-drop surface + activation button. |
| `buttonText` | `string` | `'Browse files'` | Dropzone mode only. |
| `dropzoneText` | `string` | `'Drag and drop files here, or'` | Dropzone mode only. |
| `onchange` | `(files: File[]) => void` | `—` | Fires on every accepted change: add, remove, or single-mode replace. |
| `onreject` | `(rejections: FileRejection[]) => void` | `—` | Fires whenever a pick or drop yields rejected files — see FileRejection below. |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. The component never sets this itself. |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-file-upload classes. |

#### FileRejection

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `file` | `File` | `—` | The rejected file. |
| `reason` | `'type' \| 'size' \| 'too-many'` | `—` | Accept mismatch, over maxSize, or beyond the count cap. |
| `message` | `string` | `—` | A ready-to-display English string. |

#### Styling

Root class: `hz-field hz-file-upload`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-dropzone` | `present in dropzone mode` | On the root. The reference theme discriminates the two modes by targeting the parts instead, so this one is yours. |
| `data-dragover` | `present while dragging over` | On .hz-file-dropzone. Backed by a depth counter, so it survives dragging across child elements. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-file-control` | `child element` | The box in basic mode. |
| `.hz-file-dropzone` | `child element` | The box in dropzone mode. |
| `.hz-file-dropzone-text` | `child element` | The dropzone prompt. |
| `.hz-file-button` | `child element` | The browse button. |
| `.hz-file-list` | `child element` | The selected-file list. |
| `.hz-file-item` | `child element` | One file row. |
| `.hz-file-name` | `child element` | The file name. |
| `.hz-file-size` | `child element` | The formatted size. |
| `.hz-file-remove` | `child element` | The per-file remove button. Also load-bearing: focus placement after a removal queries it. |

#### Accessibility

Drag-and-drop is a progressive enhancement, so the non-drag alternative is always present. In basic mode, the visible native input opens the platform picker directly. In dropzone mode, a real `<button>` (`buttonText`) opens the same picker. No function ever depends on a dragging movement (WCAG 2.5.7).

The native input is labeled by the field's `<label for>`. In dropzone mode the input is `aria-hidden` and out of the tab order, because the button is the control you operate. `description` and `error` chain into `aria-describedby` on the input, description first. `required` sets `aria-required`, and an `error` sets `aria-invalid`.

Each selected file's remove button carries its own `Remove` label naming that file. Additions, removals, and rejection counts are announced through a polite `aria-live` status region. That region sits outside the file list, so screen reader users hear changes the re-rendered list alone would not surface.

The theme's dragover state changes the background and the border, not the color alone.

### Slider

A labeled range slider paired with a synced number field for fine-tuned keyboard entry. Typed values commit on change, snapped to the step and clamped to the range.

Docs: https://design.hyzer.sh/docs/components/slider

```ts
import { Slider } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name (on the range input). |
| `label` | `string` | `—` | Required. Labels the range; sr-only with hideLabel. |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `value` | `number` | `min` | Bindable. |
| `showInput` | `boolean` | `true` | Renders the exact-entry number field next to the slider. |
| `ticks` | `SliderTick[]` | `—` | Decorative marks under the track. See SliderTick below. |
| `unit` | `string` | `—` | Visual suffix after the number field; rendered aria-hidden. |
| `inputLabel` | `string` | ``${label} (exact value)`` | Accessible name for the number field. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical uses writing-mode: vertical-lr (bottom-up growth); horizontal is unchanged. |
| `inputPosition` | `'start' \| 'end'` | `'end'` | Logical on both axes: horizontal trailing/leading, vertical below/above the track. |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` | Label indicator only. |
| `disabled` | `boolean` | `false` | Disables both inputs. |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-field--slider classes. |

#### SliderTick

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `number` | `—` | Required. A bare number is shorthand for an unlabeled tick. Out-of-range ticks are skipped. |
| `label` | `string` | `—` | Small text under the mark. |

#### Styling

Root class: `hz-field hz-field--slider`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-has-ticks` | `present when ticks render` | On .hz-slider-row; reserves room for the tick strip. Reflects the normalized list — out-of-range ticks are dropped — so it is not derivable from the prop. |
| `data-has-input` | `present when the number field shows` | On .hz-slider-row. The reference theme targets the parts instead, so this one is yours. |
| `data-orientation` | `'horizontal' \| 'vertical'` | On .hz-slider-row; always present. Drives the writing-mode-based vertical mechanism and the theme rotation (fill, ticks). Default horizontal. |
| `data-input-position` | `'start' \| 'end'` | On .hz-slider-row; always present. Logical on both axes — reorders the track vs. the number field/readout. Default end. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-slider-track-height` | `<length> — default 0.375rem` | Track thickness. |
| `--hz-slider-thumb-size` | `<length> — default 1.125rem` | Thumb width and height. The fill edge tracks the thumb centre, so the fill and ticks stay aligned at any size. |
| `--hz-slider-length` | `<length> — default 12rem` | The track's block length in vertical orientation. Ignored in horizontal, where the track flexes to fill the row instead. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-slider-row` | `child element` | The track-and-readout row. |
| `.hz-slider-track` | `child element` | The painted track. |
| `.hz-slider` | `the range input` | The native input carrying the thumb. |
| `.hz-slider-ticks` | `child element` | The tick strip. |
| `.hz-slider-tick` | `child element` | One tick. |
| `.hz-slider-tick-label` | `child element` | A tick’s label. |
| `.hz-slider-number` | `child element` | The editable number field. |
| `.hz-slider-value` | `child element` | The read-only readout. |
| `.hz-slider-unit` | `child element` | The unit suffix. |

#### Accessibility

The range input is the labeled (`id`/`for`), named, form-participating control. Its slider semantics (value, min, max) are native, and arrow keys step it.

The number field is an exact-entry affordance with its own accessible name (`inputLabel`) and no `name`, so it never submits.

`description` and `error` chain into `aria-describedby` on the range (description first), and an `error` sets `aria-invalid`. `required` renders the label indicator only. `aria-required` is not part of the slider role's supported ARIA attributes, so it is never applied.

`unit` is decorative and `aria-hidden`. Put meaning-bearing units in the label or description instead. In vertical orientation the component stamps `aria-orientation="vertical"` on the range explicitly, since writing-mode does not reliably flip a native range's implicit `horizontal` orientation in the accessibility tree across engines and assistive tech.

### RangeSlider

A dual-thumb slider that selects a min to max interval on one track, with paired number fields for exact entry. The thumbs can meet but never cross.

Docs: https://design.hyzer.sh/docs/components/range-slider

```ts
import { RangeSlider } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Base name — the thumbs submit as {name}-min and {name}-max. |
| `label` | `string` | `—` | Required. Rendered as the fieldset legend; sr-only with hideLabel. |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `valueMin` | `number` | `min` | Bindable. The lower thumb. |
| `valueMax` | `number` | `max` | Bindable. The upper thumb. |
| `showInput` | `boolean` | `true` | Renders the pair of exact-entry number fields. |
| `ticks` | `SliderTick[]` | `—` | Decorative marks under the track. See SliderTick below. |
| `unit` | `string` | `—` | One visual suffix after the pair; rendered aria-hidden. |
| `minThumbLabel` | `string` | ``${label} (minimum)`` | Accessible name for the lower thumb (and its number field). |
| `maxThumbLabel` | `string` | ``${label} (maximum)`` | Accessible name for the upper thumb (and its number field). |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical uses writing-mode: vertical-lr (bottom-up growth) on both ranges; horizontal is unchanged. |
| `inputPosition` | `'start' \| 'end'` | `'end'` | Logical on both axes. The two exact-entry fields stay one inline cluster, placed above or below the track in vertical rather than stacked to mirror the thumbs. |
| `description` | `string` | `—` | Help text below the legend. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` | Legend indicator only. |
| `disabled` | `boolean` | `false` | Disables all four inputs. |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-field--slider hz-field--slider-range classes. |

#### SliderTick

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `number` | `—` | Required. A bare number is shorthand for an unlabeled tick. Out-of-range ticks are skipped. |
| `label` | `string` | `—` | Small text under the mark. |

#### Styling

Root class: `hz-field hz-field--slider hz-field--slider-range`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |
| `data-has-ticks` | `present when ticks render` | On .hz-slider-row, as on Slider. |
| `data-has-input` | `present when the number fields show` | On .hz-slider-row. Unstyled by the reference theme. |
| `data-orientation` | `'horizontal' \| 'vertical'` | On .hz-slider-row; always present, as on Slider. Both ranges pick up writing-mode: vertical-lr; direction: rtl. |
| `data-input-position` | `'start' \| 'end'` | On .hz-slider-row; always present, as on Slider. The min–max pair stays one inline cluster, reordered as a unit. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-slider-track-height` | `<length> — default 0.375rem` | Track thickness. |
| `--hz-slider-thumb-size` | `<length> — default 1.125rem` | Thumb width and height. The fill edge tracks the thumb centre, so the fill and ticks stay aligned at any size. |
| `--hz-slider-length` | `<length> — default 12rem` | The track's block length in vertical orientation. Ignored in horizontal, where the track flexes to fill the row instead. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-slider-row` | `child element` | The track-and-readout row. |
| `.hz-slider-track` | `child element` | Paints the track and the between-thumbs fill. |
| `.hz-slider-min` | `the lower range input` | Carries .hz-slider too. |
| `.hz-slider-max` | `the upper range input` | Carries .hz-slider too. |
| `.hz-slider-inputs` | `child element` | Wraps the number-field pair (or the readout) so it stays one inline cluster regardless of orientation. |
| `.hz-slider-number-min` | `child element` | The lower number field. |
| `.hz-slider-number-max` | `child element` | The upper number field. |
| `.hz-slider-sep` | `child element` | The dash between the readouts. |
| `.hz-slider-ticks` | `child element` | The tick strip. |

#### Accessibility

The group is a `<fieldset>` whose `label` renders as the `<legend>`. Each thumb is a real range input with its own accessible name (`minThumbLabel`/`maxThumbLabel`) and native slider semantics. Tab reaches both thumbs, arrow keys step them, and a thumb dragged past its partner clamps rather than crossing.

The number fields carry derived accessible names and never submit. The two thumbs submit as the base `name` plus `-min`/`-max` suffixes.

`description` and `error` chain into `aria-describedby` on both ranges, and an `error` also sets `aria-invalid` on both. `required` renders the legend indicator only. `aria-required` is not part of the slider role's supported ARIA attributes, so it is never applied.

Ticks, the separator, and the readout are decorative and `aria-hidden`. In vertical orientation the component stamps `aria-orientation="vertical"` on both ranges explicitly, since writing-mode does not reliably flip a native range's implicit `horizontal` orientation in the accessibility tree across engines and assistive tech.

### ColorInput

A labeled native color picker paired with a synced hex field for exact keyboard entry. Typed values commit on change, validated and normalized.

Docs: https://design.hyzer.sh/docs/components/color-input

```ts
import { ColorInput } from "@hyzer-labs/ui"
```

#### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `string` | `—` | Required. Form field name. |
| `label` | `string` | `—` | Required. Always in the DOM; sr-only with hideLabel. |
| `value` | `string` | `'#000000'` | Bindable. The platform normalizes to 7-char lowercase hex. |
| `showInput` | `boolean` | `true` | Renders the exact-entry hex field beside the swatch. |
| `inputLabel` | `string` | ``${label} (hex value)`` | Accessible name for the hex field. |
| `description` | `string` | `—` | Help text below the label. |
| `error` | `string` | `—` | Inline error message; sets the error state. |
| `required` | `boolean` | `false` | Label indicator only. |
| `disabled` | `boolean` | `false` |  |
| `hideLabel` | `boolean` | `false` |  |
| `class` | `string` | `—` | Merged after the hz-field hz-field--color classes. |

#### Styling

Root class: `hz-field hz-field--color`

| Attribute | Values | Notes |
| --- | --- | --- |
| `data-state` | `'default' \| 'error' \| 'disabled'` | The universal field state hook, on the root. Precedence is fixed: error beats disabled. |

| Custom property | Values | Notes |
| --- | --- | --- |
| `--hz-color-swatch-size` | `<length> — default 2rem` | The swatch height; its width follows at 1.5×, so the 3:2 shape is fixed. Declared on input.hz-color — set it there or deeper, not on the .hz-field root, or the local declaration wins over your inherited value. |

| Part | Values | Notes |
| --- | --- | --- |
| `.hz-field-label` | `child element` | The label. |
| `.hz-field-required` | `child element` | The required marker. |
| `.hz-field-description` | `child element` | The hint text. |
| `.hz-field-error` | `child element` | The error message. |
| `.hz-color-row` | `child element` | The swatch-and-readout row. |
| `.hz-color` | `the color input` | The native swatch. |
| `.hz-color-hex` | `child element` | The editable hex field. |
| `.hz-color-value` | `child element` | The read-only hex readout. |

#### Accessibility

The color input is the labeled (`id`/`for`), named, form-participating control. Activating it opens the platform picker, which owns the picking experience.

The hex field is there for typing an exact value. It has its own accessible name (`inputLabel`) and no `name`, so it never submits.

`description` and `error` chain into `aria-describedby`, description first, and an `error` sets `aria-invalid`. `required` renders the label indicator only, since a color input always holds a value.

Do not let color alone carry meaning; the visible hex value helps.