Ouro UI
Every Ouro HX component, with a live demo, install commands, its props and what to use instead. The same docs live in each component's JSDoc, so an agent reading the installed source sees them too.
Actions
- Button A button, or a link styled as one.
- Toggle A button that stays pressed until it is pressed again, such as Bold in a text toolbar.
- ToggleGroup A row of related toggles that share one value, such as text alignment or bold, italic and underline in a toolbar.
- ButtonGroup Related buttons joined into one control, such as Previous, a page number and Next, or a split button.
- ColorSchemeToggle The control that switches the app between light, dark and the system's scheme, and keeps the choice.
- CopyButton A button that puts a piece of text on the clipboard: an API key, a link, a command.
- ShareButton A button that shares a link: through the system's share sheet where there is one (phones, Safari), and by copying it where there is not, when it says "Link copied" for two seconds and screen readers hear it once.
- Toolbar A row of controls for one surface, such as an editor's formatting: Button commands and Toggle states, in groups with separators.
Text
- Text Body text in the theme's type scale and colors.
- Heading A section title,
<h1>to<h6>, in the theme's foreground color. - Link A text link that navigates through your router.
- Kbd A keyboard shortcut, in the reader's platform's notation:
keys={["mod", "k"]}shows ⌘K on a Mac, iPhone or iPad and Ctrl+K elsewhere. - LocalDate A date (and time) in the reader's own time zone and language, in a
<time>that carries the exact instant. - RelativeTime How long ago (or how soon) something happens, in the reader's language: "3 days ago", "yesterday", "in 5 minutes", "now", kept current while it shows.
Forms
- Field A labeled form control: the label, an optional description, the control and its error, wired together with ids that match between the server and the browser.
- Fieldset A titled group of related fields, such as an address, rendered as a
<fieldset>named by its legend. - TextField A labeled one-line text input on the Field contract: pass
label, anderrorfrom your server action or client check. - TextArea A labeled multi-line text field on the Field contract, a native
<textarea>: passlabel, anderrorfrom your server action or client check. - Checkbox A labeled checkbox on the Field contract, with the label to its right: pass
label, andcheckedwithonCheckedChange(ordefaultChecked). - CheckboxGroup A group of checkboxes under one legend, on the Field contract, for picking any number of choices: pass
legend, andoptions(orCheckboxchildren). - RadioGroup A group of radios under one legend, on the Field contract, for picking exactly one choice: pass
legend, andoptions(orRadiochildren). - Switch A labeled on/off switch on the Field contract, with the label to its right: pass
label, andcheckedwithonCheckedChange(ordefaultChecked). - Form A form that validates with the browser's own constraints (
required,type="email",pattern) and shows server errors on the matching fields. - Select A labeled list of choices on the Field contract: pass
label,options(orSelectItemchildren) anderrorfrom your server action or client check. - NativeSelect A labeled native
<select>on the Field contract: passlabel,options(or<option>children) anderror. - NumberField A labeled number input on the Field contract: pass
label, anderrorfrom your server action or client check. - Slider A labeled slider on the Field contract: pass
label, and adefaultValue(orvaluewithonValueChange). - Combobox A text input that filters a list of items as people type, on the Field contract: pass
label,items, anderrorfrom your server action or client check. - OtpField A one-time code entry on the Field contract: one slot per character, with focus that moves as the person types, a whole code pasted at once, and
autoComplete="one-time-code"so phones offer the code from a text message. - FileField A labeled file input with a drop zone, on the Field contract.
- ColorField A color on the Field contract: a swatch that opens the system color picker, next to the same color as hex text, kept in step both ways.
- Calendar A month grid to pick a day or a range of days, with the arrow keys or a press.
- DatePicker A labeled date field.
- ChoiceCard A set of choices shown as cards, each with a picture, a label and a line of description, for picking exactly one: a cover photo, a plan, a layout.
- ImageCropper A dialog for cropping a photo to a shape before it is used: drag the photo (or move it the way the arrow keys point) to choose what shows in the frame, zoom with the slider (or Plus and Minus), and Save hands the cropped image to
onCropas aFile, ready for a form or an upload. - ImageField A field for one photo, shown large: the photo already saved (
src) or the one just chosen, with Choose photo (Change photo once one shows) and Remove. - Autocomplete Suggestions at the text caret: typing a trigger character, such as
@for people or:for emoji, in aTextAreaorTextFieldopens a list beside the caret, filtered by what follows the character.
Overlays
- Sheet A panel that slides in from an edge and is dragged back to dismiss: the mobile form of a dialog.
- Dialog A dialog that presents itself for the screen: a centered dialog on wider screens and a bottom sheet you can drag away on phones (below 640px).
- ConfirmDialog Asks the user to confirm an action, with Cancel focused first.
- EditSheet Edits something in a form inside a dialog: the whole interaction, done right.
- Popover A small non-modal panel beside its trigger, for a short form or a few choices: a share link, filters, a quick edit.
- Tooltip A short label that appears beside its trigger on hover and keyboard focus, for an icon button's purpose or a control's shortcut.
- HoverCard A preview of where a link goes, shown when a mouse rests on the link or the keyboard focuses it: a cook's profile, a recipe's summary.
Menus
Feedback
- Toaster Shows the toasts you send with
toast("Saved")from@/lib/ouro/toast: render it once, at the root of your app, insideOuroProviderif you use one, or alone. - Spinner A small spinning ring that says an action is under way, inline: in a field's adornment, a toast's or a menu entry's icon, or beside the words that say what is happening.
- Progress A bar that shows how far along a task is, or that it is under way when you can't tell.
- RouteProgress The thin bar across the top of the screen while the app loads the next page or submits a form, so a click that waits on the server never feels frozen: one global affordance instead of a pending state on every action.
- Timer A countdown timer with its own controls: the time left in large numbers, Start, then Pause and Cancel, Resume when paused, and at zero "Time's up" with Dismiss and Restart.
- TimerTray The timers that are running, paused or finished, in one strip, so a person who leaves a timer's screen can still see it count down, hear it at zero, and stop it.
- Celebrate A small moment of celebration for something the person finished: confetti bursts from a badge with the message ("List cleared") and screen readers hear the message once.
- SyncStatus One line that says where the person's changes are: Saved, Saving…, Offline (kept on this device) or Not saved (the server refused the changes), each with its icon, and Retry while there is a problem.
- InstallPrompt A quiet offer to install the web app, shown only where the browser can install it (Chromium on Android and desktops), never while it already runs installed, and not again for two weeks after Not now.
- AgentPresence The person's always-visible sign of which of their agents are listening to something on their behalf, such as a meeting, with Stop one click away.
- LevelMeter A small live input level: a row of bars that light from the start edge as a microphone picks up sound, so the person can tell it hears them before anyone else does (before joining a call, in a device menu, in a "test your microphone" row).
- Moment A moment in an app's life, shown in the space it is given: nothing here yet, on its way, something failed, a first run, or something finished.
- Porthole The status spot: a small round window with one line about how current the app's data is, which opens into the facts behind it.
Display
- Skeleton A shimmering placeholder in the shape and size of content that is still loading, so the content takes its place without moving anything.
- Avatar A person's picture, or their initials until it loads or when it fails, in a color picked from the name.
- Badge A short label for a status, category or count: "Draft", "Vegan", "3".
- Alert An inline message in the page: something saved, something failed, something to know before going on.
- Separator A thin line in the theme's border color between groups of content, horizontal or vertical.
- Card A surface that groups one thing's content: a media slot across the top, a title with a description and an action, a body, and a footer.
- Empty What a list, search or page shows when it has nothing in it: an icon, a title that says what is empty, a sentence on what to do, and the action that does it.
- DescriptionList One thing's details as pairs of a term and its value: a recipe's prep time and servings, an order's date and total, an account's email.
- Carousel A row of slides the user swipes or steps through with Previous and Next buttons: recipe photos, a few featured cards.
- CodeBlock Code or a command on a muted surface in the theme's monospace font, with a caption and a button that copies it.
- Lightbox Thumbnails that open a full-screen image viewer.
- LiveCaptions A caption band for a live call or video: what people are saying, as they say it.
- MediaTile A tile for one live picture in a call: a person's camera, their photo when the camera is off, or a shared screen.
Lists
- Accordion A stack of titles that each open their own content, for FAQs and long settings pages.
- Collapsible One section that opens and closes under its title, such as nutrition facts under a recipe.
- ShowMore "Show more" for a long list or a long text.
- Item One row of a list: leading media, a title with a description, and trailing actions.
- ItemGroup A list of
Itemrows, with an optional label that names it, lines between the rows, and what to show when it is empty. - SwipeActions A list row with actions beside it that a horizontal swipe reveals: swipe toward the start for the
trailingactions (Delete, Archive), toward the end for theleadingones (Pin). - Reorderable A list the user puts in order: recipe steps, a queue, favorites.
- Checklist A list of things to tick off, such as a recipe's ingredients or a shopping list: each row a checkbox the whole row toggles, with an optional value and action.
Layout
- ScrollArea A scrolling region with a slim scrollbar that matches the theme, inside a height you set.
- AspectRatio A frame that keeps an image, video or map at a fixed shape while its width follows the layout, so the page does not jump when the media loads.
- Stack Lays its children out top to bottom with an even gap.
- Row Lays its children out side by side with an even gap, centered up and down.
- Resizable Panels side by side (or stacked) with a draggable handle between each pair: a file list beside an editor, a preview above a console.
- PageHeader The top of a page: its title with an optional line above it (
eyebrow), a description under it, the page's actions beside it, and a trail and an image above. - SnapPiP A floating picture inside a container, such as the person's own camera in a call, that they drag and throw into a corner, where it comes to rest, as a phone's picture in picture does.
Navigation
- Tabs Tabs that switch between panels in place: an accessible tab list with roving focus, arrow-key navigation, a line that slides to the selected tab, and 44px tabs on touch screens.
- SegmentedControl An iOS-style segmented control: a row of equal segments with a raised thumb that slides to the checked one, for switching how one view shows its content in place, such as list or grid.
- Navbar The bar across the top of an app: your brand, the main links and a few controls, with the current page marked
aria-current="page", and the link of the section it is inaria-current="true", both underlined in the primary colour as inFamilyBar, distinct from hover and press highlights. - Sidebar The column of links down the side of an app, in sections, with the current page marked
aria-current="page"and a bar at the start edge, distinct from hover and press highlights. - SidebarLayout The shell of an app with a
Sidebar: the sidebar beside the page from 640px up, in view while the page scrolls, and a sticky top bar with the sidebar's menu button below 640px. - StackedLayout The shell of an app with a
Navbar: the bar across the top, in view while the page scrolls, an optionaltoolbarunder it for the page's own tools, and the page below them in a centered column. - AuthLayout The page for signing in, signing up or resetting a password: one
Cardin the middle of the screen, with your brand, the title as the page's<h1>, the form, and a line under the card. - Breadcrumb The trail from the top of the site to the current page: a labelled
<nav>with an ordered list of links, the last item markedaria-current="page". - Pagination Page navigation for a long list: Previous, the page numbers with gaps, and Next, with the current page marked
aria-current="page". - NavigationMenu A row of links where some open a panel of further links, each with a line of description: the navigation of a site with more pages than fit in a bar.
- SkipLink The "Skip to main content" link a keyboard or screen-reader user meets first on every page, so one Tab and Enter jump past the header and navigation.
- TabBar The bar of tabs at the bottom of a phone screen: two to five of the app's top-level pages, each an icon over a short label, with the current page marked
aria-current="page"and an accent wash. - NavigationRail The vertical bar of the app's top-level pages on the start edge of a wide screen, as in a chat or mail app or an editor's activity bar: each item an icon over a short label, the current one with its
currentIcon, a bar on the rail's edge andaria-current="page". - FamilyBar The slim strip above a site's own header that links every site of a family, the same links in the same order on each, with the site being shown marked
aria-current="true", in the text colour, underlined in the primary colour as Navbar marks the current page. - FamilyFooter The foot of a family's site: the
FamilyBar's links, in the same order, in a quiet row that wraps, with the site being shown marked the same way, and the site's own extras (children) after them.
Data
- Table A data table: a caption, column headers, and rows, from
columnsandrowsor from parts. - Chart A chart drawn in the theme's colors, which people can use without seeing it: a figure named by its
title, a summary for screen readers, and a table of every value (visible withshowTable). - TimeGrid A day, work week or week of hours, with events placed by their times: the calendar grid of a mail or meeting app.
Chat
- Message One message in a chat: who wrote it, their avatar and what they wrote, with any attachments under it.
- MessageList A conversation:
Messages in a scrolling, labeled region that opens at the newest one. - Attachment A file attached to a chat message, or waiting to be sent with one: an icon for its kind, its name and size.
- ThreadSummary The line under a post that leads to its thread: who replied, "N replies" (a button that opens the thread) and when the last reply came.
- ConversationList A list of conversations to choose from: each row shows the avatar, the title, when the latest message arrived and a line of it, and marks unread conversations with a bold title and a dot.
- AttentionCard Something that waits on the person: a mention, a question asked of them or a request still unanswered.
- ReactionBar A message's reactions: each one's emoji and how many chose it, with the person's own pressed and tinted, and quick reactions to add with a single press.
- Composer A chat message box: text that grows from one line as the person writes, a send button, and room for the rest of a composer, in one frame with one focus outline.
- EmojiPicker An emoji picker for reactions and for putting emoji into text.
- Emoji One emoji from an image catalogue, drawn as an
<img>the size of the text around it, named by itsalt(the emoji's name).
App setup
Parts and app setup
Pages for the exports that install with another component, or with the helpers in lib/ouro.
- canShare
- colorSchemeScript
- copyText
- share
- useColorScheme
- claim
- Radio
- MenuBar
- MenuCheckboxItem
- MenuGroup
- MenuItem
- MenuRadioGroup
- MenuRadioItem
- MenuSeparator
- MenuSub
- buzz
- chime
- createChimeContext
- formatDuration
- formatPortholeAge
- MomentProvider
- portholeStatus
- portholeView
- resetTimer
- restoreTimer
- toast
- useInstallPrompt
- useTimer
- AvatarGroup
- ResizableHandle
- ResizablePanel
- ResizablePanelGroup
- ChartContainer
- ChartLegend
- ChartTooltip
- createPeopleCache
- EmojiText
- readFailure
- usePerson
- webStorage
- ColorSchemeProvider
- measureInteraction
- onInteraction
- OuroProvider
Guides
- Make your CLI conformant Ouro AX checks the interface an agent uses from outside, the way an agent calls it (Ouro AX).
- The Ouro AX X-ray
ax-xraychecks an interface an agent uses against the Ouro AX claims (the claims). - The Ouro AX evaluation The X-ray says exactly whether a claim holds; only an agent evaluation says whether the claim matters (the claims).
- The Ouro AX claims The Ouro AX standard is a list of claims about the interfaces agents use.
- Ouro AX Ouro AX is for the interfaces agents use: a CLI, an HTTP API or an MCP server.
- CI speed and the merge queue How to keep Ouro UI's CI fast without hiding a failure: queue pull requests cleanly, read a latency failure before you blame the change, rehearse a release on the commit it tests, and quarantine a test only on the record.
- Claims A factual sentence in this repository is a claim: it carries the primary source it comes from and a check that it still holds, so the next reader, person or agent, can trust it without rebuilding the proof.
- The conformance matrix Some review findings come back again and again: focus lost when a control disappears, server HTML that a reader in another time zone or locale cannot hydrate, a part on the wrong side in a right-to-left page, a control that vanishes under forced colours, a message announced twice.
- Forms A form control is one component on the Field contract: pass
label,nameanderror, and wrap the controls in aFormthat takeserrorsstraight from your server action. - Guardrails The guardrail kits hold an app to Ouro UI.
- Installing Add
ouro-baseonce per app, then add components; no later add changes your stylesheet or your test-tool versions. - The Porthole snapshot Porthole is a small round window onto how current an app's data is: one line at a time, opened for detail.
- The screen-reader lane Ouro UI's components are read by real screen readers before every release: VoiceOver on macOS and NVDA on Windows, driven through Guidepup in this repository's CI.
- Static CSS Ouro HX's tokens also come as plain stylesheets, for a page with no build step and no Tailwind: a status page, a report or a prototype written in HTML.
- Status dashboards A status dashboard tells a person where some work stands: what is done, what failed, what is running, and what nobody has started.
- Testing Ouro UI's tests install beside each component and run in your app, in real browsers, against your theme.
- Theming Ouro HX parts paint themselves from a small set of CSS variables, the ones a shadcn/ui theme sets.
- Comparison results: app-shell Comparison overview, scores, protocol and limits
- Comparison results: command-palette Comparison overview, scores, protocol and limits
- Comparison results: confirm-delete Comparison overview, scores, protocol and limits
- Comparison results: recipe-list Comparison overview, scores, protocol and limits
- Comparison results: settings-form Comparison overview, scores, protocol and limits
- Why Ouro HX needs no skill Ouro HX puts component guidance in the source an agent already reads: required props, compiler hints and development messages.
- ax-checks A tool's checks, such as a doctor or a self-check, declared once: progress while they run, the verdict first and the results grouped for a person, the same facts as
--jsonfor an agent, the time taken and the exit code. - ax-claims The Ouro AX standard as data: a claim is one checkable rule about an interface an agent uses, with the reason, the evidence that admitted it, the check
ax-xrayruns and the fix. - ax-cli The whole front door for a tool built on the kit: parse, help, run (or, on
--dry-run, plan), print the result as text or--json, and turn every failure into the one error line and its exit code. - ax-command One definition of a command: its words, effect, arguments and flags, examples and output.
- ax-component A component's agent side: what an agent may read from it and which of its actions an agent may take, each bound to the CLI command that does the same (its twin).
- ax-dev-commands A message for an agent or a person names only what the installed tool runs: never a developer command, a repository path or a step that only works in a source checkout.
- ax-effects Effect classes: a command either touches only the person's own space ("private") or reaches other people ("others").
- ax-example A small tool built only from the kit, for the tests and as the pattern to copy: commands of both effects, an action that returns an outcome with a preview, a wait on a room, an ambiguous word, a tool-specific exit code and a voice.
- ax-exit-codes A tool's exit codes as one table: the overview, every command's footer,
help --jsonand the MCP error shape read it, so the numbers never drift. - ax-flows An adopter's agent flows as data, run in CI without a model: a flow is the calls a good agent makes for one task, and the runner checks the calls' exit codes, JSON shapes and fields, error text, time, size and voice.
- ax-lint The kit's check of a tool's declarations: what an agent needs from every declared command (a summary, an example, described arguments and flags,
--whyand a preview where other people see it, help that fits the width), and, against the tool's own command inventory, that every command it registers runs through its declaration. - ax-mcp The same definitions as an MCP server over stdio (newline-delimited JSON-RPC 2.0), with no dependencies: one tool per command, its inputSchema from the definition, calls checked before they run with the fix in the one error shape, effects as tool annotations, and results cut to a size an agent's context can hold.
- ax-outcome The outcome of an action: what became of it, who can see it, whether that was checked, how to find it again and what to run next, in one shape over a CLI's
--json, an HTTP route and an MCP tool. - ax-output One result, two renderings:
--jsonprints the data, text prints what the command's text() makes of the same data. - ax-precise-copy A failure says what happened and precisely why (the system and its answer: "The mail service says this file was deleted"), who or what caused it where that is known, and the next step as a working action.
- ax-problem One error shape for every agent surface: the CLI's stderr line, its
--jsonerror and an MCP tool error all carry the same fields, so an agent learns one repair loop. - ax-terminal What a terminal shows a person, with a plain fallback off a terminal: colour, status marks, the time something took, next steps and a progress line for anything slow.
- ax-voice A tool's voice: an optional line of character after the facts, for a person at a terminal, never where an agent parses.
- ax-wait A typed wait: the agent names a reference it already holds, the tool waits (polling, if it must, where the agent cannot see it) until something happens or the time limit passes, and returns what happened with the cursor that resumes the wait.
- ax-work-event An attributed work event: who acted and for whom, on what, why, with which receipt, when.
- ax-xray The Ouro AX conformance checker: it calls a CLI, an HTTP API or an MCP server the way an agent would, and reports which claims hold on which surface, with the fix where a claim does not hold.
- Switching from shadcn shadcn/ui components and props, and their Ouro HX equivalents.
- Updating installed components Review upstream changes, then overwrite and reapply your edits.