# ZUI

> A layered React UI system: a CSS token contract (@zuilib/tokens), a component set on it (@zuilib/components, Headless UI v2 + Tailwind v4), and composites such as the markdown text editor. Every visual decision is a CSS custom property; a design system is a set of overrides on :root or on any subtree.

Components are consumed either as npm packages (one subpath per component, default export) or as source through the ZUI registry at https://zuilib.com/r/latest/<name>.json (`npx @zuilib/cli add button`, after `npx @zuilib/cli init`). Every registry item carries its source, its npm dependencies and the names of the items it imports.

## Docs

- [Introduction](https://zuilib.com/docs): Why ZUI exists, what has shipped, and what comes next.
- [Components](https://zuilib.com/docs/components): @zuilib/components: accessible React primitives on Headless UI v2 and Tailwind v4, styled only through the tokens, so a brand is a set of CSS variables.
- [Accordion](https://zuilib.com/docs/components/accordion): Coordinated disclosure panels. Single or multiple open, three variants, controlled or uncontrolled, WAI-ARIA keyboard support.
- [AIButton](https://zuilib.com/docs/components/ai-button): A Button with a sparkle and a generating state. Everything Button does, minus `loading` and `leadingIcon`, which it owns.
- [Alert](https://zuilib.com/docs/components/alert): An inline callout. Five tinted variants, a live role that matches the urgency, and a dismissible mode that never drops focus.
- [Avatar](https://zuilib.com/docs/components/avatar): A person's picture with a graceful fallback. Five sizes on the control scale, two shapes, presence dots, and an overlapping group with overflow.
- [Badge](https://zuilib.com/docs/components/badge): A static label. Eight semantic variants in solid or subtle appearance, a status dot, an icon, and an optional remove button.
- [Button](https://zuilib.com/docs/components/button): The action control. Six variants, four sizes, a loading state that keeps focus, and a polymorphic `as` for links.
- [Card](https://zuilib.com/docs/components/card): A bounded surface with Header, Title, Description, Content and Footer parts, three variants, a padding scale, and an interactive mode that makes the whole card one control.
- [Checkbox](https://zuilib.com/docs/components/checkbox): A boolean toggle on Headless UI's Checkbox. Three sizes, an indeterminate state, an inline label and description, and FormItem inheritance for invalid and disabled.
- [Code](https://zuilib.com/docs/components/code): Inline code or, with block, a focusable, horizontally scrolling pre/code block. Language hint for highlighters; no colouring of its own.
- [Combobox](https://zuilib.com/docs/components/combobox): Searchable single- or multi-select. Convenience mode takes an `options` array; compound mode takes `Combobox.Input` / `Button` / `Options` / `Option` children.
- [Container](https://zuilib.com/docs/components/container): A centred, max-width column with a horizontal gutter. Five width steps from `--container-width-*`, a gutter from `--container-padding`, and a polymorphic `as` for landmarks.
- [Description](https://zuilib.com/docs/components/description): Helper text under a control. Inside a `FormItem` it is Headless UI's `Description`, so the control's `aria-describedby` points at it; outside one it is a plain `<p>`.
- [Dialog](https://zuilib.com/docs/components/dialog): Modal dialog on Headless UI. Portalled, focus-trapped and scroll-locked, with a backdrop, five panel sizes, inside or outside scrolling, and compound Header / Body / Footer / Close parts.
- [Disclosure](https://zuilib.com/docs/components/disclosure): A single collapsible card. A toggle button with a chevron, an uncontrolled open state, and a panel for whatever needs hiding.
- [Drawer](https://zuilib.com/docs/components/drawer): A dialog pinned to a viewport edge. Four sides, four sizes, a dismissible gate, and header/body/footer parts that lay the sheet out.
- [Empty State](https://zuilib.com/docs/components/empty-state): A centred placeholder for a region with nothing to show. Icon disc, title, description and an action row; prop-driven or compound.
- [Fieldset](https://zuilib.com/docs/components/fieldset): Groups related form items under a legend and description, and disables all of them at once.
- [FileUpload](https://zuilib.com/docs/components/file-upload): A drop zone around a native file input. Button plus drag and drop, accept, size and count validation, a removable file list, and native form submission.
- [FormItem](https://zuilib.com/docs/components/form-item): One form field. A Headless UI Field that generates the control id and wires label, description and message to the control, with shared disabled and invalid state.
- [Getting started](https://zuilib.com/docs/components/getting-started): Install @zuilib/components, pick one of the four stylesheet entries, wire dark mode, and import components by subpath.
- [Heading](https://zuilib.com/docs/components/heading): h1 to h6 on the type scale. The tag sets the outline level, size sets the look, and both read the --text-*, --font-weight-* and --tracking-* tokens.
- [Input](https://zuilib.com/docs/components/input): The single-line text field. Outline and ghost variants, three sizes, validation states, leading and trailing content, and automatic wiring inside a FormItem.
- [Kbd](https://zuilib.com/docs/components/kbd): A keyboard key or chord. One `<kbd>` per key, joined by a separator that screen readers hear.
- [Label](https://zuilib.com/docs/components/label): The form label. Wires itself to the control inside a FormItem, with a required marker and an unsaved badge.
- [Listbox](https://zuilib.com/docs/components/listbox): A custom select, generic over the value type. Options in, a button and floating panel out; or compose the parts yourself.
- [Menu](https://zuilib.com/docs/components/menu): A dropdown of actions. A Button trigger, a floating panel, and items that can be buttons or links.
- [Message](https://zuilib.com/docs/components/message): Validation text for a field. Takes a string or any object with a `message`, announces as an alert, and joins the control's `aria-describedby` inside a FormItem.
- [NumberInput](https://zuilib.com/docs/components/number-input): An Input that holds a number. Stepper buttons, arrow-key stepping, min/max/step/precision, and Intl formatting while the field is not focused.
- [PinInput](https://zuilib.com/docs/components/pin-input): One square cell per character of a short code. Typing advances, paste and SMS autofill spread across the cells, and the value stays a contiguous string.
- [Popover](https://zuilib.com/docs/components/popover): A floating panel opened by a button. Headless UI Popover with the ZUI surface, anchor placement, gap, transition, backdrop, group and close parts.
- [Progress](https://zuilib.com/docs/components/progress): A determinate or indeterminate progress bar. Four fill colours, three track heights, an optional value label, and full progressbar ARIA.
- [Radio Group](https://zuilib.com/docs/components/radio-group): Pick one of a few options. Card or list variants, two orientations, three sizes, an options array or composed RadioGroup.Option children, and FormItem wiring.
- [Registry](https://zuilib.com/docs/components/registry): Pull any ZUI component into your project as source with the zui CLI, or install it from npm. Plus llms.txt for coding agents.
- [Rich Textarea](https://zuilib.com/docs/components/rich-textarea): Textarea with label, description, error message and character counter in one component, wired through FormItem.
- [Search Input](https://zuilib.com/docs/components/search-input): An Input of type search with a leading magnifying glass, a clear button, an optional loading spinner, Enter-to-search and Escape-to-clear in every browser.
- [Select](https://zuilib.com/docs/components/select): The native single-choice field. Outline and ghost variants, three sizes, validation states, a token-positioned chevron and automatic wiring inside a FormItem.
- [Separator](https://zuilib.com/docs/components/separator): A horizontal or vertical rule drawn with the border token, optionally labelled, announced as a separator or hidden as decoration.
- [Skeleton](https://zuilib.com/docs/components/skeleton): Placeholder for loading content. Rect, circle and text shapes, pulse or wave animation, and an optional status label.
- [Slider](https://zuilib.com/docs/components/slider): A native range input with a token-styled track and thumb, three sizes, marks, a value readout and FormItem wiring.
- [Spinner](https://zuilib.com/docs/components/spinner): The standalone indeterminate loading indicator. A role="status" live region around the shared ring, with a visually hidden label, four sizes, and currentColor for colour.
- [Stack](https://zuilib.com/docs/components/stack): The flex layout primitive. A column or row of children with a spacing-scale gap, alignment, distribution, wrapping, an optional divider, and a polymorphic `as`.
- [Step Indicator](https://zuilib.com/docs/components/step-indicator): Progress through a multi-step flow. Numbered circles joined by connectors, horizontal or vertical, with optional click-to-go-back and skip-ahead.
- [Switch](https://zuilib.com/docs/components/switch): An on / off toggle on Headless UI's Switch. Three sizes, an inline label and description, label-first layout, and FormItem inheritance for invalid and disabled.
- [Table](https://zuilib.com/docs/components/table): Styled native table primitives. Line, striped and bordered variants, two densities, a sticky header, sortable column heads and selectable, keyboard-operable rows.
- [Tabs](https://zuilib.com/docs/components/tabs): Headless UI tab group with underline, pills and enclosed variants, three sizes, vertical layout and icon tabs.
- [Text](https://zuilib.com/docs/components/text): Body text on the type scale. Four sizes, four weights, five colour variants, truncation and line clamping, polymorphic across p, span, div and label.
- [Textarea](https://zuilib.com/docs/components/textarea): The multi-line text field. Outline and ghost variants, validation states, a resize control, an action slot inside the frame, and automatic wiring inside a FormItem.
- [Theming](https://zuilib.com/docs/components/theming): The override contract. A brand is CSS custom properties on :root or on a subtree; the components read them and nothing else.
- [Tooltip](https://zuilib.com/docs/components/tooltip): Short text that describes its trigger on hover and keyboard focus. Positioned by Floating UI, portalled, with an optional arrow.
- [Text editor](https://zuilib.com/docs/text-editor): @zuilib/text-editor: a complete markdown editor for React, built on Lexical, in a few lines of code.
- [AI authoring](https://zuilib.com/docs/text-editor/ai-authoring): Generating documents and diagrams for the editor programmatically, with LLMs or scripts.
- [API](https://zuilib.com/docs/text-editor/api): Every export of @zuilib/text-editor, grouped by concern.
- [Changelog](https://zuilib.com/docs/text-editor/changelog): Version history of @zuilib/text-editor.
- [Code blocks](https://zuilib.com/docs/text-editor/code-blocks): Syntax highlighting with the package's own lexer, the colour properties, and registering a language.
- [Diagrams](https://zuilib.com/docs/text-editor/diagrams): The drawing canvas, the diagram skeleton for generators, the drawing payload format, Mermaid export, and the ink style.
- [Editor](https://zuilib.com/docs/text-editor/editor): MarkdownEditor props, modes, the controlled value, outline and folding, shortcuts, and form integration.
- [Layout](https://zuilib.com/docs/text-editor/layout): Text measure and per-block width for tables and diagrams.
- [Tables](https://zuilib.com/docs/text-editor/tables): GFM tables edited in place, row and column rails, keyboard shortcuts, density, and the settings marker.
- [Theming](https://zuilib.com/docs/text-editor/theming): Stylesheets, dark mode, the Tailwind source scan, and every custom property the editor exposes.
- [Toolbar](https://zuilib.com/docs/text-editor/toolbar): The default toolbar, extending it, placing it elsewhere with compound components, and the headless useMarkdownEditor() hook.
- [Tokens](https://zuilib.com/docs/tokens): @zuilib/tokens: the CSS variables every ZUI package reads. Colour, shape, type, spacing, density, depth and motion, with light and dark values, mapped to Tailwind v4.
- [Token reference](https://zuilib.com/docs/tokens/reference): Every custom property in @zuilib/tokens with its light and dark value.
- [Themes](https://zuilib.com/docs/tokens/themes): One site, five looks. Pick a theme and the whole app changes; each one is a single block of CSS overrides.

## Components

- [Accordion](https://zuilib.com/r/latest/accordion.json): `import Accordion from '@zuilib/components/accordion'` — Single / multiple expandable items (compound parts as statics)
- [AIButton](https://zuilib.com/r/latest/ai-button.json): `import AIButton from '@zuilib/components/ai-button'` — Button with sparkle / generating state
- [Alert](https://zuilib.com/r/latest/alert.json): `import Alert from '@zuilib/components/alert'` — Inline status message, dismissible (compound parts as statics)
- [Avatar](https://zuilib.com/r/latest/avatar.json): `import Avatar from '@zuilib/components/avatar'` — Image with initials fallback and status; `Avatar.Group`
- [Badge](https://zuilib.com/r/latest/badge.json): `import Badge from '@zuilib/components/badge'` — Label / tag, removable
- [Button](https://zuilib.com/r/latest/button.json): `import Button from '@zuilib/components/button'` — Primary actions
- [Card](https://zuilib.com/r/latest/card.json): `import Card from '@zuilib/components/card'` — Surface with header / content / footer (compound parts as statics)
- [Checkbox](https://zuilib.com/r/latest/checkbox.json): `import Checkbox from '@zuilib/components/checkbox'` — Boolean / indeterminate toggle
- [Code](https://zuilib.com/r/latest/code.json): `import Code from '@zuilib/components/code'` — Inline code or code block
- [Combobox](https://zuilib.com/r/latest/combobox.json): `import Combobox from '@zuilib/components/combobox'` — Searchable single- or multi-select (compound parts as statics)
- [Container](https://zuilib.com/r/latest/container.json): `import Container from '@zuilib/components/container'` — Centred max-width wrapper
- [Description](https://zuilib.com/r/latest/description.json): `import Description from '@zuilib/components/description'` — Helper text
- [Dialog](https://zuilib.com/r/latest/dialog.json): `import Dialog from '@zuilib/components/dialog'` — Modal dialog (compound parts as statics)
- [Disclosure](https://zuilib.com/r/latest/disclosure.json): `import Disclosure from '@zuilib/components/disclosure'` — Collapsible section
- [Drawer](https://zuilib.com/r/latest/drawer.json): `import Drawer from '@zuilib/components/drawer'` — Side / top / bottom sheet (compound parts as statics)
- [EmptyState](https://zuilib.com/r/latest/empty-state.json): `import EmptyState from '@zuilib/components/empty-state'` — Icon + title + description + actions
- [Fieldset](https://zuilib.com/r/latest/fieldset.json): `import Fieldset from '@zuilib/components/fieldset'` — Grouped fields with legend
- [FileUpload](https://zuilib.com/r/latest/file-upload.json): `import FileUpload from '@zuilib/components/file-upload'` — Drop zone + file list
- [FormItem](https://zuilib.com/r/latest/form-item.json): `import FormItem from '@zuilib/components/form-item'` — Field wrapper (Headless UI `Field`): wires label / description / control ids
- [Heading](https://zuilib.com/r/latest/heading.json): `import Heading from '@zuilib/components/heading'` — `h1`–`h6` on the type scale
- [Input](https://zuilib.com/r/latest/input.json): `import Input from '@zuilib/components/input'` — Text input
- [Kbd](https://zuilib.com/r/latest/kbd.json): `import Kbd from '@zuilib/components/kbd'` — Keyboard key / shortcut
- [Label](https://zuilib.com/r/latest/label.json): `import Label from '@zuilib/components/label'` — Accessible label
- [Listbox](https://zuilib.com/r/latest/listbox.json): `import Listbox from '@zuilib/components/listbox'` — Single- or multi-select dropdown (compound parts as statics)
- [Menu](https://zuilib.com/r/latest/menu.json): `import Menu from '@zuilib/components/menu'` — Dropdown action menu (compound parts as statics)
- [Message](https://zuilib.com/r/latest/message.json): `import Message from '@zuilib/components/message'` — Validation / error text
- [NumberInput](https://zuilib.com/r/latest/number-input.json): `import NumberInput from '@zuilib/components/number-input'` — Input with stepper, clamping and number formatting
- [PinInput](https://zuilib.com/r/latest/pin-input.json): `import PinInput from '@zuilib/components/pin-input'` — One-time-code / PIN cells
- [Popover](https://zuilib.com/r/latest/popover.json): `import Popover from '@zuilib/components/popover'` — Anchored floating panel (compound parts as statics)
- [Progress](https://zuilib.com/r/latest/progress.json): `import Progress from '@zuilib/components/progress'` — Determinate / indeterminate progress bar
- [RadioGroup](https://zuilib.com/r/latest/radio-group.json): `import RadioGroup from '@zuilib/components/radio-group'` — Radio options, card or list (compound parts as statics)
- [RichTextArea](https://zuilib.com/r/latest/rich-textarea.json): `import RichTextArea from '@zuilib/components/rich-textarea'` — Textarea with label, description, error, char count
- [SearchInput](https://zuilib.com/r/latest/search-input.json): `import SearchInput from '@zuilib/components/search-input'` — Search field with clear button and loading state
- [Select](https://zuilib.com/r/latest/select.json): `import Select from '@zuilib/components/select'` — Native `<select>`
- [Separator](https://zuilib.com/r/latest/separator.json): `import Separator from '@zuilib/components/separator'` — Horizontal / vertical rule, optional label
- [Skeleton](https://zuilib.com/r/latest/skeleton.json): `import Skeleton from '@zuilib/components/skeleton'` — Loading placeholder
- [Slider](https://zuilib.com/r/latest/slider.json): `import Slider from '@zuilib/components/slider'` — Native range input with label, value read-out and marks
- [Spinner](https://zuilib.com/r/latest/spinner.json): `import Spinner from '@zuilib/components/spinner'` — Loading indicator with live-region label
- [Stack](https://zuilib.com/r/latest/stack.json): `import Stack from '@zuilib/components/stack'` — Flex row / column with gap and dividers
- [StepIndicator](https://zuilib.com/r/latest/step-indicator.json): `import StepIndicator from '@zuilib/components/step-indicator'` — Multi-step progress
- [Switch](https://zuilib.com/r/latest/switch.json): `import Switch from '@zuilib/components/switch'` — Boolean toggle
- [Table](https://zuilib.com/r/latest/table.json): `import Table from '@zuilib/components/table'` — Styled table primitives (compound parts as statics), no TanStack; data grids live in the separate `@zuilib/table` package
- [Tabs](https://zuilib.com/r/latest/tabs.json): `import Tabs from '@zuilib/components/tabs'` — Tab list + panels (compound parts as statics)
- [Text](https://zuilib.com/r/latest/text.json): `import Text from '@zuilib/components/text'` — Body text with size / weight / colour variants
- [Textarea](https://zuilib.com/r/latest/textarea.json): `import Textarea from '@zuilib/components/textarea'` — Multiline text
- [Tooltip](https://zuilib.com/r/latest/tooltip.json): `import Tooltip from '@zuilib/components/tooltip'` — Hover / focus tooltip (floating-ui)

## Helpers

- [lib/cn](https://zuilib.com/r/latest/lib-cn.json): `@zuilib/components/lib/cn` — `clsx` + `tailwind-merge` helper
- [lib/control-frame](https://zuilib.com/r/latest/lib-control-frame.json): `@zuilib/components/lib/control-frame` — `splitControlProps()` / `splitHoverHandlers()` for frame + native-element controls
- [lib/focus](https://zuilib.com/r/latest/lib-focus.json): `@zuilib/components/lib/focus` — `focusRingClasses`, `focusRingInsetClasses`, `dataFocusRingClasses`, `dataFocusRingInsetClasses`, `focusOutlineInsetClasses`, `fieldFocusRingClasses`: the shared focus-ring class strings
- [lib/form-item-context](https://zuilib.com/r/latest/lib-form-item-context.json): `@zuilib/components/lib/form-item-context` — `useFormItem()`, `FormItemContext`, `formItemStateAttributes()` for custom controls inside a `FormItem`
- [lib/form-variants](https://zuilib.com/r/latest/lib-form-variants.json): `@zuilib/components/lib/form-variants` — `formVariantClasses`, `formStateClasses`, `useResolvedFormState()` (the field frame styles)
- [lib/icons](https://zuilib.com/r/latest/lib-icons.json): `@zuilib/components/lib/icons` — `ChevronDownIcon`, `CheckIcon`, `XIcon`, `SearchIcon`, `InfoIcon` / `SuccessIcon` / `WarningIcon` / `ErrorIcon` (+ `statusIcons`): the glyphs the components share
- [lib/popover-panel](https://zuilib.com/r/latest/lib-popover-panel.json): `@zuilib/components/lib/popover-panel` — `popoverSurfaceClasses`, `popoverPanelClassName()`, the anchor classes and the option-row classes Listbox / Combobox / Menu / Popover / Dialog share
- [lib/reset](https://zuilib.com/r/latest/lib-reset.json): `@zuilib/components/lib/reset` — `nativeControlResetClasses`: zeroes the user-agent styles of a native `<button>` (padding, border, background, font) so button-rendered parts look the same without Tailwind's preflight. Put it first in `cn()`
- [lib/sizes](https://zuilib.com/r/latest/lib-sizes.json): `@zuilib/components/lib/sizes` — `ControlSize`, `controlSizeClasses`, `iconSizeClasses`, … the shared size maps
- [lib/spinner](https://zuilib.com/r/latest/lib-spinner.json): `@zuilib/components/lib/spinner` — Indeterminate spinner icon (also a named export)
- [lib/transitions](https://zuilib.com/r/latest/lib-transitions.json): `@zuilib/components/lib/transitions` — `fadeTransitionClasses`, `scaleFadeTransitionClasses`, `slideTransitionClasses()`: the `data-[closed]` enter / leave recipes for Headless UI's `transition` prop

## Tokens and styles

- [ZUI styles](https://zuilib.com/r/latest/zui-styles.json): The stylesheet entry every ZUI component needs: the tokens (Tailwind @theme mapping, custom properties, keyframes) plus the component css Tailwind utilities cannot express (the slider track and thumb).
- [ZUI tokens](https://zuilib.com/r/latest/zui-tokens.json): The token contract of @zuilib/tokens: every custom property (colour, radius, type, control density, motion) with light and dark values, the keyframes and animation classes, plus the Tailwind v4 @theme mapping and base styles.

## Optional

- [llms-full.txt](https://zuilib.com/llms-full.txt): the full component API reference (props, slots, conventions) and the token contract in one file.
- [index.json](https://zuilib.com/r/latest/index.json): the registry index (every item, its type, files and dependencies). Pinned: https://zuilib.com/r/v/0.1.0/index.json.