# Ouro HX > Designed down to the last tap and the last prop. Interactions that feel right to the humans using them. Code that's obvious to the agents building with them. Copy-in source distributed as a shadcn/ui registry on GitHub (ourostack/ouro-ui). It is not an npm package: the shadcn CLI copies the components you add into your app. Under construction. Ouro HX is the component library within Ouro UI. Ouro AX is coming soon; its scope is still being defined. The repository, @ouro namespace and install addresses are unchanged. ## Install In an existing Vite or Next.js app with Tailwind CSS v4[^tailwind-4] and an "@/*" path alias, run shadcn init once, with the Base UI base and without -t/--template, then add items: ```sh npx shadcn@latest init --base base --preset nova --yes --no-monorepo npx shadcn@latest search 'ourostack/ouro-ui#v1.2.13' # list the items npx shadcn@latest view 'ourostack/ouro-ui/dialog#v1.2.13' # read one item # Once per app, before the first component: the tokens every component needs. npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.2.13 npx shadcn@latest add ourostack/ouro-ui/dialog#v1.2.13 # install a component ``` - Add ouro-base once, before the first component. No component installs it, so no later add changes the app's stylesheet (in v0.7.0 every component still installs it, and an add can rewrite the stylesheet).[^ouro-base-only][^v0.7.0] Without it, overlays have no backdrop or motion and fields no border, and in development the first component to mount logs the command to run.[^theme-check] - A new Vite app needs @tailwindcss/vite, @import "tailwindcss";, a Vite @ alias, and "paths": { "@/*": ["./src/*"] } in both tsconfig.json and tsconfig.app.json (no baseUrl on TypeScript 6) before init: shadcn reads the root file, and tsc -b builds the app one.[^vite-app] - --preset nova lets init run without prompts. It sets shadcn's starting theme, font and icons, which Ouro components read like any shadcn theme. The install test runs nova and vega; other presets are untested. - A GitHub source is owner/repo#ref; an item is owner/repo/item#ref. @v1.2.13, github: and /tree/ URLs do not work. - A release tag (#v1.2.13) installs the item and every Ouro dependency at that tag.[^release-pins] Without a ref, items come from main, which is for contributors and can hold unreleased changes; use a release tag or @ouro. - Components land in components/ouro// and the helpers they import in lib/ouro/, one file each.[^lands] Ouro UI never writes to components/ui/, so do not pass --overwrite on a first install.[^not-ui] - Tests are optional: add -tests beside the item (npx shadcn@latest add ourostack/ouro-ui/dialog#v1.2.13 ourostack/ouro-ui/dialog-tests#v1.2.13), or ouro-tests for all of them.[^ouro-tests] They need Vitest 4.1.11 or later in browser mode, Playwright 1.58.1 or later, axe-core 4.13.0 or later and Storybook 10.2.10 or later, and never change a version the app already has (v0.7.0's items still carry versions: after add, restore the versions you had pinned).[^minimums][^v0.7.0] Ouro UI's own CI runs them on Vitest 5 only; Vitest 4 is the stated minimum, not a tested one.[^vitest-5][^minimums] The ouro-testing install message lists the config files to add. - The @ouro namespace serves the newest release (the same code as #v1.2.13)[^namespace]: add "registries": { "@ouro": "https://ui.ouro.bot/r/{name}.json" } to components.json, then npx shadcn@latest add @ouro/ouro-base @ouro/dialog (ouro-base once per app). ## Items - `ouro-base`: Add it once per app, before your first component; no component installs it, so later adds never touch your stylesheet. What every Ouro UI component needs in the app's CSS: success and warning colors, a destructive foreground, the field border color (--input) and --radius when your theme has none, the motion tokens, the press utility, the keyframes for spinners, progress bars and skeletons, and --ouro-layer, the z-index of sheets and dialogs (50; raise it in a :root rule of your own if your app has fixed bars above z-50). - `ouro-theme`: Ouro UI's own look, as a shadcn theme for :root and .dark. Skip it to keep your app's theme. - `ouro-lib`: Every helper in lib/ouro in one item. You don't need to add it: each component installs only the helpers it imports (the lib- items). - `ouro-testing`: Installed with every -tests item; you don't need to add it. The test kit Ouro UI's tests use: Vitest browser projects with the drag, flick, tap, touchDrag, touchStep, pointerPress, emulateMedia, pageZoom, resetPageZoom, setPageZoom and restoreTouch commands, the rotate helper (which turns the phone viewport and resets Chromium's zoom; the ouro-touch project fails a test that leaves the page zoomed), the act helper, the holdFrames helper (which holds animation frames and the clock still so a test steps a spring itself), the motion helpers (expectMotion, expectNoMotion, expectGestureSettle, expectTransition and parseDuration, which prove exactly which CSS properties a state change runs on each part), watchAnnouncements (which records what live regions announce, so a test proves a message is heard once per change), axeExclude, and the end-to-end story helper. - `button`: A button, or a link styled as one. Docs: https://ui.ouro.bot/docs/button.md - `text`: Body text in the theme's type scale and colors. Docs: https://ui.ouro.bot/docs/text.md - `heading`: A section title, `

` to `

`, in the theme's foreground color. Docs: https://ui.ouro.bot/docs/heading.md - `sheet`: A panel that slides in from an edge and is dragged back to dismiss: the mobile form of a dialog. Docs: https://ui.ouro.bot/docs/sheet.md - `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). Docs: https://ui.ouro.bot/docs/dialog.md - `confirm-dialog`: Asks the user to confirm an action, with Cancel focused first. Docs: https://ui.ouro.bot/docs/confirm-dialog.md - `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. Docs: https://ui.ouro.bot/docs/field.md - `fieldset`: A titled group of related fields, such as an address, rendered as a `
` named by its legend. Docs: https://ui.ouro.bot/docs/fieldset.md - `link`: A text link that navigates through your router. Docs: https://ui.ouro.bot/docs/link.md - `text-field`: A labeled one-line text input on the Field contract: pass `label`, and `error` from your server action or client check. Docs: https://ui.ouro.bot/docs/text-field.md - `text-area`: A labeled multi-line text field on the Field contract, a native `