# @hyzer-labs/ui

> A headless, accessible Svelte 5 component library. Components ship behavior,
> structure and accessibility — every visual decision is yours. A token engine
> generates the CSS custom properties and grades every color pairing against
> WCAG AA; named themes scope to any element, not just the document root.

Install with `pnpm add @hyzer-labs/ui`. Components import from the package root;
the token engine, motion helpers, observers, icons, utilities and types each have
their own subpath. See the Agents page for the conventions that keep generated
code correct.

Every component's props and styling hooks in one file: https://design.hyzer.sh/llms-full.txt
The same reference as JSON, for keyed lookup rather than reading straight through: https://design.hyzer.sh/llms-full.json

## Start here

- [Getting Started](https://design.hyzer.sh/docs): Adopt the library in three tiers, each one optional and a superset of the last. The library makes the accessibility and behavior choices, and you decide how things look.
- [Philosophy](https://design.hyzer.sh/docs/philosophy): The commitments that underpin this library: accessibility first, headless structure with documented hooks and opt-in theming tiers, all in plain language.
- [Agents](https://design.hyzer.sh/docs/agents): How to wire this library up to a coding agent: where llms.txt lives, the import surface, and the house rules that keep generated code correct.

## Foundation

- [Colors & Intent](https://design.hyzer.sh/docs/foundation/colors): Color works in two layers: the palette (--hz-palette-*) authors hues per mode, and the semantic layer (--hz-color-*, --hz-intent-*) says what a color does and what it means. Dark mode overrides land mostly on the palette, and the semantic layer follows automatically.
- [Contrast & Accessibility](https://design.hyzer.sh/docs/foundation/contrast): WCAG contrast ratios for every graded color pairing, computed live per mode from the token metadata. The library ships the same functions, so you can run the identical check against a theme of your own.
- [Typography](https://design.hyzer.sh/docs/foundation/typography): Type tokens: three font families, a six-step type scale, four weights, and three line heights.
- [Spacing & Sizing](https://design.hyzer.sh/docs/foundation/spacing): Three sizing systems, each answering a different question: a fixed spacing scale for explicit distances, density spacing that tightens as content nests, and breakpoint width tokens.
- [Borders & Elevation](https://design.hyzer.sh/docs/foundation/borders-elevation): Tokens for border radius, border width, box shadows, and the z-index scale.
- [Motion](https://design.hyzer.sh/docs/foundation/motion): Duration and easing tokens, plus the @hyzer-labs/ui/motion module: token-bridged transitions, easing evaluators, a scroll-reveal attachment, and a view-transition helper. All of it respects reduced-motion settings by default.
- [Observers](https://design.hyzer.sh/docs/foundation/observers): @hyzer-labs/ui/observers wraps IntersectionObserver, ResizeObserver, and MutationObserver as Svelte attachments named intersect, resize, and mutate, each starting when the element mounts and disconnecting when it is removed. The module also exports announce, which sends a message to a visually hidden live region when a callback has loaded more content or spotted a change.
- [Positioning](https://design.hyzer.sh/docs/foundation/positioning): Tooltip, Popover, and the Dropdown menu all place a floating element next to its trigger through one engine. It prefers CSS anchor positioning where the browser supports it and measures the element itself where it does not, flipping at the viewport edge, escaping clipping ancestors, and reporting back exactly what it rendered.
- [CSS Reset](https://design.hyzer.sh/docs/foundation/reset): An optional adaptation of Josh Comeau's custom CSS reset, covering box sizing, margins, media elements, and text wrapping. It says nothing about color or typefaces, so it works the same with the reference theme or fully headless.
- [Utilities](https://design.hyzer.sh/docs/foundation/utilities): Three families of utility class, from least to most opt-in: the always-on .sr-only, component conventions the theme already ships, and a generated sheet of token-derived helpers you import separately. It also covers the JavaScript helpers the package exports.
- [Config & CLI](https://design.hyzer.sh/docs/foundation/config): One optional file, hyzer.config.ts, describes your design system; the hyzer CLI turns it into a token sheet, a trimmed icon barrel and an optional utility sheet, each graded against WCAG AA on the way out.

## Components

### Content

- [Accordion](https://design.hyzer.sh/docs/components/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.
- [Blockquote](https://design.hyzer.sh/docs/components/blockquote): A semantic quote: a figure wrapping a blockquote, with an optional visible attribution and an optional machine-readable source URL.
- [Button](https://design.hyzer.sh/docs/components/button): A button with solid, outline, ghost, and soft variants, plus intent colors, sizes, a loading state, and icon slots.
- [Card](https://design.hyzer.sh/docs/components/card): A content container with optional media, actions, horizontal layout, and clickable-overlay support.
- [Carousel](https://design.hyzer.sh/docs/components/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.
- [CodeBlock](https://design.hyzer.sh/docs/components/code-block): 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).
- [Divider](https://design.hyzer.sh/docs/components/divider): A thematic separator: a native hr when bare, and a labeled role=separator element when it wraps a centered text label.
- [Hero](https://design.hyzer.sh/docs/components/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.
- [Icons](https://design.hyzer.sh/docs/components/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.
- [Link](https://design.hyzer.sh/docs/components/link): An accessible anchor component with variant styles, external link support, and icon slots. Links inherit the surrounding text size.
- [Metatags](https://design.hyzer.sh/docs/components/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.
- [Table](https://design.hyzer.sh/docs/components/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.
- [Tabs](https://design.hyzer.sh/docs/components/tabs): An accessible tab interface with roving tabindex, arrow-key navigation, and horizontal or vertical orientation. Tab labels accept plain strings or snippets.

### Feedback & Status

- [Alert](https://design.hyzer.sh/docs/components/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.
- [Badge](https://design.hyzer.sh/docs/components/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.
- [Banner](https://design.hyzer.sh/docs/components/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.
- [Loading](https://design.hyzer.sh/docs/components/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.
- [Skeleton](https://design.hyzer.sh/docs/components/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.

### Overlays

- [Dropdown](https://design.hyzer.sh/docs/components/dropdown): A generic action menu built on the WAI-ARIA APG menu button pattern, with real roving-tabindex keyboard focus.
- [Modal](https://design.hyzer.sh/docs/components/modal): An accessible dialog built on the native <dialog> element with focus trap, Esc-to-close, scroll lock, and configurable sizes.
- [Popover](https://design.hyzer.sh/docs/components/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.
- [Tooltip](https://design.hyzer.sh/docs/components/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.

### Layout

- [Container](https://design.hyzer.sh/docs/components/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.
- [Stack](https://design.hyzer.sh/docs/components/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.
- [Cluster](https://design.hyzer.sh/docs/components/cluster): Lays children out in a horizontal row that wraps to new lines as needed.
- [Grid](https://design.hyzer.sh/docs/components/grid): Responsive CSS grid that adapts its column count to its own width via container queries.
- [Split](https://design.hyzer.sh/docs/components/split): Two-column layout with configurable proportions that stacks to a single column when its own width gets narrow.
- [Virtualizer](https://design.hyzer.sh/docs/components/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.

### Navigation

- [Nav](https://design.hyzer.sh/docs/components/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.
- [Header](https://design.hyzer.sh/docs/components/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.
- [Footer](https://design.hyzer.sh/docs/components/footer): Site footer with auto-fitting multi-column link groups, optional logo, social links, and a bottom bar.
- [Breadcrumbs](https://design.hyzer.sh/docs/components/breadcrumbs): A wrapping breadcrumb trail of navigation links with chevron separators and automatic current-page semantics.
- [Pagination](https://design.hyzer.sh/docs/components/pagination): A navigation landmark of page controls: previous and next, boundary and sibling windows with ellipsis truncation, and button or real-link modes.
- [Toc](https://design.hyzer.sh/docs/components/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.

### Media

- [Image](https://design.hyzer.sh/docs/components/image): Responsive image with aspect-ratio, object-fit, rounded corners, color and blur placeholder states, and a picture mode for art direction.
- [Lightbox](https://design.hyzer.sh/docs/components/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.
- [Logo](https://design.hyzer.sh/docs/components/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.
- [Video](https://design.hyzer.sh/docs/components/video): Video player supporting YouTube, Vimeo embeds, and native HTML5 video. Detects provider from URL and builds the correct embed.

### Forms

- [Form](https://design.hyzer.sh/docs/components/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.
- [TextInput](https://design.hyzer.sh/docs/components/text-input): A labeled single-line input covering the common HTML input types, with description, inline error, and decorative prefix and suffix slots.
- [Textarea](https://design.hyzer.sh/docs/components/textarea): A labeled multi-line text area with configurable resize behavior, including an auto-grow mode, plus description and inline error.
- [Checkbox](https://design.hyzer.sh/docs/components/checkbox): A labeled checkbox with description, inline error, and an indeterminate state for select-all patterns.
- [RadioGroup](https://design.hyzer.sh/docs/components/radio-group): A group of radio buttons in a fieldset with a legend, vertical or horizontal layout, and standard field accessibility.
- [Toggle](https://design.hyzer.sh/docs/components/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.
- [Select](https://design.hyzer.sh/docs/components/select): A labeled native select with flat options, option groups, a placeholder option, and standard field accessibility.
- [Combobox](https://design.hyzer.sh/docs/components/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.
- [FileUpload](https://design.hyzer.sh/docs/components/file-upload): 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.
- [Slider](https://design.hyzer.sh/docs/components/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.
- [RangeSlider](https://design.hyzer.sh/docs/components/range-slider): 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.
- [ColorInput](https://design.hyzer.sh/docs/components/color-input): A labeled native color picker paired with a synced hex field for exact keyboard entry. Typed values commit on change, validated and normalized.

## Theming

- [Overview](https://design.hyzer.sh/docs/theming/overview): The components are headless: they ship structure, behavior, and accessibility, and every visual decision stays yours to keep, override, or replace. Styling arrives in opt-in tiers, each importable on its own.
- [Tokens & Overrides](https://design.hyzer.sh/docs/theming/tokens): Theme tokens come in two layers: the palette (--hz-palette-*) authors single-value hues per mode, and the semantic roles (--hz-color-*) and intents (--hz-intent-*) are var() indirection that chains through it. Override one hue and the change cascades everywhere it is used.
- [Styling Components](https://design.hyzer.sh/docs/theming/components): Components expose a stable styling contract: an hz-* root class, a data-* attribute per variant and state, and a class prop merged after the root class. The reference theme styles exactly these hooks from @layer hz-theme, wrapped in :where() so everything stays at single-class specificity, which means your unlayered CSS wins by default.
- [Section Themes](https://design.hyzer.sh/docs/theming/sections): A theme does not have to own the whole page. Any element can carry one and everything inside it follows, so a single long page can change character section by section.
- [Example Themes](https://design.hyzer.sh/docs/theming/examples): Three example themes, sorted by how much of the reference theme each one keeps: Ocean keeps all of it and only redefines --hz-* tokens, Docs keeps all of it and layers one class-hook override on top with no palette of its own, and Terminal keeps none of it. Ocean and Terminal are generated from a hyzer.config.ts beside them and, like the base tokens, meet WCAG AA on every graded pairing, in both modes.
- [Using with Tailwind](https://design.hyzer.sh/docs/theming/tailwind): The library and Tailwind coexist cleanly: settle on one reset, order the cascade layers so Tailwind utilities win when you want them to, and pass utility classes to components through their class prop. None of it is Tailwind-specific plumbing; it is the same layer model the rest of the theme uses.

## Patterns

- [Homepage](https://design.hyzer.sh/docs/patterns/homepage): A marketing-style landing page assembled entirely from library components, with no bespoke layout code.
- [Article](https://design.hyzer.sh/docs/patterns/article): A long-form editorial page: a Hero opener, a byline, and a body that runs through a Blockquote pull-quote and a breakout image.
- [Recipe](https://design.hyzer.sh/docs/patterns/recipe): A recipe page where the main dish photo opens as a Hero's split media, ahead of the ingredients and instructions.
- [Docs shell](https://design.hyzer.sh/docs/patterns/docs-shell): A documentation layout: a sidebar of collapsible nav sections, a reading column, and an "On this page" rail that follows the column's headings.
- [Command palette](https://design.hyzer.sh/docs/patterns/command-palette): A ⌘K quick-search overlay built on Modal, which supplies the backdrop, focus trap, and Escape to close.
- [Product listing](https://design.hyzer.sh/docs/patterns/product-listing): A filterable shop page where the form controls drive the visible results.
- [Product detail](https://design.hyzer.sh/docs/patterns/product-detail): A single product page with a thumbnail gallery and a buy panel that updates as you pick options.
- [Contact form](https://design.hyzer.sh/docs/patterns/contact-form): The minimal end of the Form spectrum: four fields, one Select, and no order summary.
- [Checkout form](https://design.hyzer.sh/docs/patterns/checkout-form): The full Form workflow on a realistic checkout page: submit-time validation, a linked error summary, and inline field errors.
- [Virtualized table](https://design.hyzer.sh/docs/patterns/virtualized-table): A 6,000-row dataset windowed by Virtualizer, dressed as an ARIA table.
- [Virtualized combobox](https://design.hyzer.sh/docs/patterns/virtualized-combobox): A multi-select autocomplete over tens of thousands of rows, windowed by Virtualizer.