# jarvis-react-ui

> Sharp, dark, HUD-style React 19 component library (JARVIS look: JetBrains Mono, glow instead of shadows): primitives, inputs, dialogs, toasts, tables, charts, a window/slot-grid system, a CSS and a Three.js orb, and built-in UI sound effects.

Version 0.5.0. Docs: https://joeyash.github.io/jarvis_ui_lib/

## Usage rules

- Install `jarvis-react-ui` with its peers `react` and `react-dom` (^19) and `lucide-react`. `three` is an optional peer, needed only for `ThreeOrb`.
- Import the stylesheet once at the app root: `import 'jarvis-react-ui/style.css';`. Tailwind is not required in the consuming project.
- Import components, hooks and types from the package root only: `import { Button, Panel } from 'jarvis-react-ui';`. Never deep-import from `jarvis-react-ui/dist/...`.
- `ThreeOrb`, `createOrb` and `OrbEngine` come from `jarvis-react-ui/orb` (separate entry so `three` stays out of the main bundle). `CssOrb` is in the main entry.
- Wrap the app once in `JarvisProvider` (UI sounds, toasts, `useJarvis()`). `useToast()` and `useJarvis()` throw outside of it; without a provider the other components work but stay silent.
- Give the page the dark surface: `body { background: var(--bg); color: var(--text); }`. Style with the design tokens (`var(--accent)`, ...), not hard-coded colors.
- Every component accepts `className`; components wrapping a native element accept its attributes and forward `ref`.
- Layout: use `Stack` (rows/columns) and `Grid` (columns) with token gaps (`xs`–`xl`); sizes via the project's own CSS classes, or Tailwind only if the project has Tailwind. The demos below use Tailwind utilities (`flex gap-3`, `w-[280px]`) for layout; without Tailwind, replace them with `Stack`, `Grid` or own CSS. Do not rely on utility classes from `style.css`: it contains only an internal subset that changes between releases.
- Windows built at runtime from JSON (e.g. by an assistant): `UiRenderer`, `useUiWindows` and `validateUiSpec` come from `jarvis-react-ui/generative`. A spec may only use the components and props of `UI_REGISTRY` (see the UiRenderer page); validate specs before opening them. The JSON Schema of a spec and Claude tool definitions ship as `jarvis-react-ui/ui-schema.json` and `jarvis-react-ui/ui-tools.json`.
- Use only the props listed in the API tables; do not invent props or variants. Helper types used by props (e.g. `TabItem`, `TableColumn<T>`) are documented under "Type" after each API table.

## Overview

- [Overview](https://joeyash.github.io/jarvis_ui_lib/index.md)

## Getting started

- [Installation](https://joeyash.github.io/jarvis_ui_lib/getting-started/installation.md): Install the package and its peer dependencies, import the stylesheet once, and you are ready to render your first component.
- [Usage](https://joeyash.github.io/jarvis_ui_lib/getting-started/usage.md): Components are plain React components with typed props. Compose them like any other UI kit; the HUD look comes from the shared design tokens.
- [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md): Interactive components play short UI sounds (hover, click, drag, boot, ...) through a React context. Without a provider they stay silent, so audio is strictly opt-in.
- [JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md): The root provider of a JARVIS app. It starts the audio engine for UI sounds, provides toasts and exposes app-level controls through `useJarvis()`. Wrap your app in it once.
- [Using with AI](https://joeyash.github.io/jarvis_ui_lib/getting-started/ai.md): The docs are also published as plain Markdown for AI coding assistants, so they use the real props and imports instead of guessing. The same files ship in the npm package and always match the installed version.

## Customization

- [Theming](https://joeyash.github.io/jarvis_ui_lib/customization/theming.md): Every color, glow, radius, spacing step and timing is a CSS custom property. Components read only those tokens, so overriding a few variables re-themes the whole library at runtime.
- [Design tokens](https://joeyash.github.io/jarvis_ui_lib/customization/tokens.md): The tokens live in one stylesheet as CSS custom properties on `:root`. The tables below are read from that file at build time, so they always match the installed version.
- [Tailwind](https://joeyash.github.io/jarvis_ui_lib/customization/tailwind.md): The library is styled with Tailwind v4 internally, but ships compiled CSS. You do not need Tailwind. If your project uses it, you can map the same tokens into your own theme.

## Primitives

- [Stack](https://joeyash.github.io/jarvis_ui_lib/components/stack.md): Lays out its children in a column or a row with spacing from the design tokens. It covers most layout needs without Tailwind, and it is the layout building block for generated windows.
- [Grid](https://joeyash.github.io/jarvis_ui_lib/components/grid.md): Lays out its children in equal columns with spacing from the design tokens: a fixed number of columns, or as many as fit.
- [Button](https://joeyash.github.io/jarvis_ui_lib/components/button.md): Buttons trigger an action. They come in four variants, two sizes, and play the hover and click sounds of the JARVIS sound set.
- [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md): A square button that shows only a `lucide-react` icon. Use it for compact toolbar actions; the required `label` gives it an accessible name.
- [Link](https://joeyash.github.io/jarvis_ui_lib/components/link.md): A styled anchor for inline text links, secondary links and navigation. It can open external pages in a new tab and mark the current page in a navigation bar.
- [Tooltip](https://joeyash.github.io/jarvis_ui_lib/components/tooltip.md): A small text bubble that explains its trigger on hover or keyboard focus. It is the standard companion of IconButton.
- [Divider](https://joeyash.github.io/jarvis_ui_lib/components/divider.md): A hairline that separates content. It runs horizontally or vertically, can fade in the accent color and can carry a small caption.
- [Pill](https://joeyash.github.io/jarvis_ui_lib/components/pill.md): A small uppercase tag with a hairline border. Use it to show the state of a system, a connection or a task at a glance.
- [Label](https://joeyash.github.io/jarvis_ui_lib/components/label.md): A small uppercase caption in the secondary text color. Use it to name a reading, a group of values or a form control.
- [Mono](https://joeyash.github.io/jarvis_ui_lib/components/mono.md): A text element in JetBrains Mono with four size steps and three text colors. Use it for body text, readouts and log lines inside HUD panels.
- [Metric](https://joeyash.github.io/jarvis_ui_lib/components/metric.md): A numeric reading in the bright accent color with an optional unit. Its digits use tabular figures, so values that update live do not make the layout jump.
- [ProgressBar](https://joeyash.github.io/jarvis_ui_lib/components/progress-bar.md): A thin glowing bar that shows a fraction of a whole: load, capacity or the progress of a task. It fills the width of its container.
- [Sparkline](https://joeyash.github.io/jarvis_ui_lib/components/sparkline.md): A tiny line chart with a soft fill, without axes or labels. Use it to show the trend of a reading next to its current value.
- [Icon](https://joeyash.github.io/jarvis_ui_lib/components/icon.md): Renders a `lucide-react` icon at one of three HUD sizes with a consistent stroke width. Use it for status glyphs and icons next to text.
- [Hint](https://joeyash.github.io/jarvis_ui_lib/components/hint.md): A muted line of text that tells the user about a keyboard shortcut. `Hint.Key` renders a single key chip and also works on its own, for example inside an Input.
- [Kbd](https://joeyash.github.io/jarvis_ui_lib/components/kbd.md): A keyboard key chip. Use it to show shortcuts in hints, menus, tooltips and docs. It renders a semantic `<kbd>` element.
- [Toast](https://joeyash.github.io/jarvis_ui_lib/components/toast.md): Toasts are short, non-blocking notifications that appear in a corner and close themselves. Call `useToast()` anywhere below a `JarvisProvider` (or `ToastProvider`) to show one.
- [Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md): Panels are the framed surfaces of the HUD: a translucent glass body with corner brackets, side rails, a light trace and a header strip. They hold the content of a dashboard tile or a window.
- [TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md): The TopBar is the status strip at the top of the HUD. It has three slots, left, center and right, and carries the panel chrome: corner brackets and a light trace that circles its border.
- [BrandMark](https://joeyash.github.io/jarvis_ui_lib/components/brand-mark.md): The spaced-out `J A R V I S` wordmark in muted text, with an optional `MK XLII` subline. Use it as the brand in a top bar or a status dock.

## Forms

- [Input](https://joeyash.github.io/jarvis_ui_lib/components/input.md): A single-line text field in a hairline HUD frame. It accepts icons or keyboard hints on either side, comes in two sizes and has an invalid state for validation errors.
- [Textarea](https://joeyash.github.io/jarvis_ui_lib/components/textarea.md): A multi-line text field in the same hairline frame as Input, for notes, prompts and log entries.
- [Select](https://joeyash.github.io/jarvis_ui_lib/components/select.md): A dropdown to pick one option from a list. The list opens in a portal, so it is never clipped by a scrolling window body and stays above floating windows.
- [Checkbox](https://joeyash.github.io/jarvis_ui_lib/components/checkbox.md): A checkbox for options that are submitted or applied together. For a setting that takes effect immediately, use a Switch.
- [RadioGroup](https://joeyash.github.io/jarvis_ui_lib/components/radio-group.md): A set of mutually exclusive options. Use it when all choices should stay visible; for long lists use a Select.
- [Switch](https://joeyash.github.io/jarvis_ui_lib/components/switch.md): An on/off toggle for settings that take effect immediately. The track glows in the accent color when the switch is on.
- [Slider](https://joeyash.github.io/jarvis_ui_lib/components/slider.md): A horizontal range input for values such as volume, gain or a scan radius. Drag the glowing thumb, click anywhere on the track, or use the keyboard.

## HUD decoration

- [CornerBrackets](https://joeyash.github.io/jarvis_ui_lib/components/corner-brackets.md): CornerBrackets draws four small L-shaped marks at the corners of its content, the signature frame of the HUD. Wrap any box in it to give it the same targeting look as a Panel.
- [Scanlines](https://joeyash.github.io/jarvis_ui_lib/components/scanlines.md): Scanlines lays fine horizontal CRT lines over its content. Use it to give a readout, a metric or a media tile the look of a HUD display.
- [GridBackground](https://joeyash.github.io/jarvis_ui_lib/components/grid-background.md): GridBackground is a faint blueprint grid behind the whole page. It fades out toward the edges with a radial mask, so it frames the content without competing with it.
- [GlowFrame](https://joeyash.github.io/jarvis_ui_lib/components/glow-frame.md): GlowFrame is a hairline frame with an accent glow around its content. Use it to highlight a single element, such as the current voice state or an active readout.
- [Reticle](https://joeyash.github.io/jarvis_ui_lib/components/reticle.md): Reticle is a small crosshair glyph. Use it as a decorative marker next to labels, in corners or on targets.
- [LightTrace](https://joeyash.github.io/jarvis_ui_lib/components/light-trace.md): LightTrace sends four short strips of light around the border of its parent. It marks a surface as live or active.
- [PanelBloom](https://joeyash.github.io/jarvis_ui_lib/components/panel-bloom.md): PanelBloom is a soft accent glow that fills a surface from its top and bottom edges. Use it to show that a surface is focused or active.
- [PanelRails](https://joeyash.github.io/jarvis_ui_lib/components/panel-rails.md): PanelRails adds two dashed vertical rails just outside the left and right edges of a surface. Use them as an extra highlight for a hovered or selected panel.
- [ViewportCorners](https://joeyash.github.io/jarvis_ui_lib/components/viewport-corners.md): ViewportCorners pins four large L-shaped marks to the corners of the screen, each with a small glowing dot. They frame the whole HUD like the corners of a viewfinder.
- [StarField](https://joeyash.github.io/jarvis_ui_lib/components/star-field.md): StarField scatters tiny twinkling stars over a surface. Use it for a deep-space backdrop behind the orb or inside a dark tile.
- [Reactor](https://joeyash.github.io/jarvis_ui_lib/components/reactor.md): Reactor is a large, soft hemisphere of accent light rising from the bottom of the screen, with a thin arc at its rim. It gives the space below the orb an ambient glow.
- [Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md): Scene is the full-screen backdrop of the HUD: a dark radial background with a drifting grid, scanlines, stars, a vignette, film grain and a horizon glow. Render it once behind everything else.

## Voice & status

- [PushToTalkButton](https://joeyash.github.io/jarvis_ui_lib/components/push-to-talk-button.md): The round microphone button of the voice HUD. It toggles the mic and, while `active`, shows two pulsing rings and a stronger glow so the user can see that JARVIS is listening.
- [WaveformMeter](https://joeyash.github.io/jarvis_ui_lib/components/waveform-meter.md): A row of animated accent bars that signals live audio, such as the user speaking or JARVIS answering. It is purely decorative and does not measure a real signal.
- [WaveStrip](https://joeyash.github.io/jarvis_ui_lib/components/wave-strip.md): A compact, seven-bar waveform that sits inline with text, for example next to a "now playing" caption. It is the small sibling of WaveformMeter.
- [StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md): A two-line caption for the orb: the current voice state on top and a spaced-out brand mark below. Place it under the orb or the PushToTalkButton.

## Compositions

- [Callout](https://joeyash.github.io/jarvis_ui_lib/components/callout.md): Callouts highlight a short note, tip or warning next to the content it belongs to. Four semantic variants set the accent color and the default icon.
- [CodeBlock](https://joeyash.github.io/jarvis_ui_lib/components/code-block.md): CodeBlock shows a snippet of source code in a dark frame with an optional header for a file name, a language label, custom actions and a copy-to-clipboard button.
- [Dialog](https://joeyash.github.io/jarvis_ui_lib/components/dialog.md): A modal dialog for confirmations and short forms. It renders above the page, keeps keyboard focus inside, and returns focus to the trigger when it closes.
- [GlassCard](https://joeyash.github.io/jarvis_ui_lib/components/glass-card.md): GlassCard is a Panel in an `inline-block` wrapper, framed by the panel's own corner brackets. Use it for standalone dashboard tiles that size themselves to their content.
- [HUDShell](https://joeyash.github.io/jarvis_ui_lib/components/hud-shell.md): HUDShell is the full-screen frame of a JARVIS app. It draws the complete backdrop and gives you slots for the top bar, the orb, your panels and the voice dock, layered in the right order. Start every app with it.
- [NavList](https://joeyash.github.io/jarvis_ui_lib/components/nav-list.md): NavList is a vertical navigation list for sidebars: grouped link entries with optional headings, trailing badges and a highlighted current entry. The sidebar of this documentation is a NavList.
- [StatusBadge](https://joeyash.github.io/jarvis_ui_lib/components/status-badge.md): A small connection indicator: a colored dot followed by an uppercase label. Put it in a TopBar or a panel header to show whether a link or service is up.
- [StatusDock](https://joeyash.github.io/jarvis_ui_lib/components/status-dock.md): The voice control at the bottom center of the HUD: a push-to-talk button between two waveform meters, with the current assistant state underneath. It is driven by a single `AppOrbState`.
- [Table](https://joeyash.github.io/jarvis_ui_lib/components/table.md): Table renders typed rows as a data table. Columns describe how each cell is rendered, so the same row objects can carry plain values, pills or any other content.
- [Tabs](https://joeyash.github.io/jarvis_ui_lib/components/tabs.md): Tabs switch between panels of related content in the same place. Only the selected panel is rendered, and the tab bar has room for actions on the right.
- [ToastProvider](https://joeyash.github.io/jarvis_ui_lib/components/toast-provider.md): The provider behind `useToast()`. It keeps the list of toasts, handles their timers and renders the notification stack. `JarvisProvider` already includes it.
- [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md): WindowManager lays out a set of windows on a fixed slot grid. Windows dock into slots, can be dragged onto other slots to move or swap, and can be undocked into free-floating, resizable windows.

## Charts

- [LineChart](https://joeyash.github.io/jarvis_ui_lib/components/line-chart.md): Shows how values change over an ordered axis such as time. Lines are drawn as SVG in the token colors, scale to their container and can be inspected by pointer or keyboard.
- [AreaChart](https://joeyash.github.io/jarvis_ui_lib/components/area-chart.md): A line chart with the area below the line filled. Use it for volumes over time, and stack the series to show how parts add up to a total.
- [BarChart](https://joeyash.github.io/jarvis_ui_lib/components/bar-chart.md): Compares values across categories. Several series are grouped side by side or stacked into one bar per category; negative values grow downward from zero.

## Media

- [MediaControls](https://joeyash.github.io/jarvis_ui_lib/components/media-controls.md): Transport controls for any media source: play/pause, seek bar, time, mute and volume, plus optional previous/next and fullscreen. They only report what the user does, so they drive a video, an audio file, a YouTube player or a speaker in another room alike.
- [MediaPlayer](https://joeyash.github.io/jarvis_ui_lib/components/media-player.md): Plays a video or audio file with the HUD MediaControls instead of the browser's own controls. Through its ref, code (or a voice assistant) can play, pause, seek and change the volume.
- [YouTubePlayer](https://joeyash.github.io/jarvis_ui_lib/components/you-tube-player.md): Plays a YouTube video through the YouTube IFrame Player API, with the HUD MediaControls instead of YouTube's own controls.
- [WebFrame](https://joeyash.github.io/jarvis_ui_lib/components/web-frame.md): Shows a web page inside your interface, for example in a floating window, with a small toolbar: the address, reload and "open in new tab".

## Window

- [Window](https://joeyash.github.io/jarvis_ui_lib/components/window.md): Window is the draggable, resizable panel shell that WindowManager places on its slot grid. Use it directly when you build your own window layout; for the standard nine-slot HUD, use WindowManager.
- [SnapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/snap-overlay.md): SnapOverlay draws the nine slots of the window grid as glowing drop zones and highlights the one under the pointer. WindowManager shows it while a docked window is dragged.
- [SwapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/swap-overlay.md): SwapOverlay draws a dashed ghost over the window that a drop would swap with. WindowManager shows it while a docked window is dragged onto an occupied slot.
- [SlotGhost](https://joeyash.github.io/jarvis_ui_lib/components/slot-ghost.md): SlotGhost is a dashed placeholder for an empty slot, with an optional caption. Use it to show where windows can go in a custom window layout.

## Orb

- [CssOrb](https://joeyash.github.io/jarvis_ui_lib/components/css-orb.md): CssOrb is the animated JARVIS orb, built from CSS gradients, rings and a few orbiting particles. It shows the assistant's state at a glance and needs no WebGL. For the Three.js particle version see ThreeOrb.
- [ThreeOrb](https://joeyash.github.io/jarvis_ui_lib/components/three-orb.md): ThreeOrb renders the JARVIS orb in WebGL with Three.js, in six visual designs, either as a full-screen background layer or inside a container. It ships in its own entry point, `jarvis-react-ui/orb`, so Three.js only loads when you use it. For a lightweight CSS version see CssOrb.

## Generative UI

- [UiRenderer](https://joeyash.github.io/jarvis_ui_lib/components/ui-renderer.md): Renders a window from a JSON spec, for example one an assistant produced: a tree of library components with state, bindings, conditions and actions. Nothing has to exist in your code beforehand, and only allowlisted components and props can be used.
- [Connecting an assistant](https://joeyash.github.io/jarvis_ui_lib/generative/assistant.md): Let a language model build and control windows: give it the four tools the package ships, validate what it sends, and run the calls with `useUiWindows`. The model never writes code, only JSON that the UiRenderer turns into library components.

## Hooks

- [Sound hooks](https://joeyash.github.io/jarvis_ui_lib/hooks/sound-hooks.md): `useClickSfx`, `useHoverSfx` and `useSfx` give your own components the same UI sounds as the library components. They read the nearest `SfxProvider`, which `JarvisProvider` sets up.
- [useAudioEngine](https://joeyash.github.io/jarvis_ui_lib/hooks/use-audio-engine.md): The React binding of the Web Audio engine that plays all UI sounds. `JarvisProvider` calls it for you; use it directly only for a custom setup.
- [useDraggable](https://joeyash.github.io/jarvis_ui_lib/hooks/use-draggable.md): A low-level pointer drag hook. It tracks the drag offset, keeps the pointer captured when it leaves the element and plays the drag sounds. `Window` and `useSlotDrag` build on it.
- [useResizable](https://joeyash.github.io/jarvis_ui_lib/hooks/use-resizable.md): A low-level pointer resize hook. `onPointerDown(dir)` creates a handler per edge or corner and reports the resize offset while the pointer moves.
- [useSlotDrag](https://joeyash.github.io/jarvis_ui_lib/hooks/use-slot-drag.md): A drag hook for the 9-slot grid. While dragging it reports which slot is under the pointer and whether a window already sits there, so you can show snap and swap previews. `WindowManager` is built on it.

## Utilities

- [Slot grid](https://joeyash.github.io/jarvis_ui_lib/utilities/slot-grid.md): The geometry behind the window system: nine fixed slots around the edges of the viewport, leaving the center free for the orb.
- [cx & time helpers](https://joeyash.github.io/jarvis_ui_lib/utilities/helpers.md): Small, dependency-free helpers the components use internally and that are handy in HUD apps: a class name joiner and formatters for clocks, ages and durations.

## Dev tools

- [StateSimulator](https://joeyash.github.io/jarvis_ui_lib/components/state-simulator.md): A development toolbar with one button per orb state. Use it to preview how the orb and the voice UI react to each `AppOrbState` without a real voice pipeline.
- [Tweaks](https://joeyash.github.io/jarvis_ui_lib/components/tweaks.md): A floating development panel for adjusting the HUD theme live: accent hue, glow intensity and five on/off flags. Pair it with `useTweakApply` to write the hue and glow into the design tokens.

## Optional

- [Full documentation in one file](https://joeyash.github.io/jarvis_ui_lib/llms-full.txt): every page above with demo code and API tables.
- [Changelog](https://joeyash.github.io/jarvis_ui_lib/changelog)