Repository navigation
v1.3.344
Install an item at this release, npx shadcn@latest add ourostack/ouro-ui/<item>#v1.3.344; its Ouro dependencies install from the same tag. Every install from GitHub needs a release tag: main has no registry.json, so an address without one fails. In an app with Tailwind CSS v4 and an "@/*" path alias, run shadcn's init once first, with the Base UI base:
npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344 ourostack/ouro-ui/dialog#v1.3.344The tests, stories and specs are optional, one item per component: npx shadcn@latest add ourostack/ouro-ui/dialog#v1.3.344 ourostack/ouro-ui/dialog-tests#v1.3.344, or ourostack/ouro-ui/ouro-tests#v1.3.344 for all of them. List every item with npx shadcn@latest search 'ourostack/ouro-ui#v1.3.344'.
Changes in this release
- Changed: a windowed ConversationList forces no layout read while it mounts; the resize observer's first callback finds the scroll container, measures the rows and sets the window.
- Changed: a windowed ConversationList's first view is sized from the window's height (or the new
firstViewHeightprop) in its first render, so it renders once and reads no layout before the first paint, where the 1.3.338 layout effect read layout and drew the list a second time; server HTML and a hydrating client keep 1000 pixels. - New: What is proven on a device says per platform where its checks run and what has not run on a device.
Upgrading from v0.1.0
v0.1.0 installed each component with its tests, and v0.2.0 moves some shared helpers to new files, so update every Ouro component in one go. Run the commands in your app's root, the folder with components.json. They find your folders the way shadcn does, from the aliases in components.json and the paths in your tsconfig (npx shadcn@latest info shows them), so they work in a src/ or an app/ layout as written.
What changed, by version
What an app on v0.1.0 has to know beyond these steps. The release notes list every change.
-
v0.2.0: each component's tests became an optional
<name>-testsitem, some helpers moved to new files (step 4), and v0.1.0's self-referential theme lines can go (step 2). -
v0.3.0: sheets and dialogs stack at
--ouro-layer, a z-index of 50 by default, instead of level 0, so an app element at z-index 1 to 49 that used to show above an open sheet or dialog now sits under it. Raise the token in a:rootrule of your own if your app has fixed bars above z-50 (see "Theme" in the README), and drop any portal z-index workaround. A controlledDialogopened by a touch or pen tap focuses its popup instead of its first input, andConfirmDialog'sfinalFocusapplies only after a confirmed action; drop workarounds for either. Every coverage hint is/* istanbul ignore … @preserve */, so a build plugin that kept the hints can go. A-testsitem sets Vitest to^5. -
v0.3.1: every component starts with
"use client", so Next.js App Router pages can render them, and the@ouronamespace serves the newest release instead ofmain. -
After v0.7.0: a required field's
*is drawn with CSS on a new element around the label and is no longer a<span data-ouro-required>inside it, so tests that expected the label text "Email*" now find "Email". The clear, show-password and choose-date buttons in TextField and DatePicker are named by hidden text, notaria-label, so replacebutton[aria-label="…"]selectors with[data-ouro-clear],[data-ouro-show-password]or[data-ouro-choose-date]. The same goes for a file's remove button in FileField ([data-ouro-file-remove]), Combobox's clear and chip remove buttons ([data-ouro-combobox-clear],[data-ouro-combobox-chip-remove]) and NumberField's steppers ([data-ouro-increment],[data-ouro-decrement]). A remove button's hidden text holds the file or item name, so a loosegetByText("pasta.png")now finds it too; pass{ exact: true }.FieldLabel'sclassNamenow goes on the new element around the label, which also carries[data-ouro-required], and a group's labelidis on the inner<span>;style,id,data-*and handlers still go on the<label>. A numericsizeon TextField is now a type error and a development warning; set a width withclassName="w-40".FormErrorsvalues are nowErrorMessages | null | undefined, so code that readserrors.emailasstring | string[]no longer type checks until it handlesnulland React nodes. For action answers, importformErrorsfrom@/lib/ouro/form-answerand passerrors={formErrors(actionData, actionData?.errors)}from the initial render; this replaces the unreleased separateresultprop. It identifies equal new answers while keeping cleared fields masked on pending/client renders and rendering current uncleared messages. Cached/reused answers need{ key: acceptedAnswerKey }, changed on actual acceptance, not submit start. Raw records remain compatible but content-only. Reconstruct the value beside Form after JSON/spread/cloning or server-component transport: only messages serialize, not private identity; a safely transported acceptance key can identify the locally reconstructed answer. On a phone, a Link that is not in running text is now a box at least 44px tall and wide that takes its room in the layout, so a column of links grows; passinlineto a link in a sentence inside your own<div>or<span>. A Form's top message element exists only while there is a message. Component roots no longer setm-0, so a parent'sspace-y-*now spaces them; remove any margin you added to work around that. -
v0.8.0: no component installs
ouro-base; add it once (step 1 does), and later adds leave your stylesheet alone. A component installs only the helpers it imports, one item per file inlib/ouro, and a-testsitem brings the tests of everything its component installs. The-testsitems no longer set a version for Vitest, Storybook or Playwright. The specs importtestandexpectfrome2e/ouro-fixtures.ts, a file of yours (step 1).lib/ouro/use-dev-warnings.tsis nowlib/ouro/use-dev-messages.ts(step 4). Earlier releases installed every helper inlib/ourowith any component, and an update deletes nothing: audit references before deleting unused historical helpers and their own tests (step 5).OuroProvidernow comes only with the components that render links and withtooltip; your copy stays, and a new app addslib-ouro-providerby name. -
After v0.8.2:
ouroTestProjects({ page })also sizes the touch project's Playwright host, preventing Vitest 4 from scaling landscape touch frames. The logical touch viewport still starts at 390x844 with mobile/touch input, but an explicitly enlarged host changes outer-window/screen dimensions and screen orientation; do not treat those as hardware-phone measurements. Withoutpage, the touch host stays 390x844. On Vitest 4, retain a host large enough for every requested test viewport, such as the Testing guide's 1600x1200 example. -
v1.0.0: the first stable release keeps the component APIs, theme tokens, defaults and test-tool minimums from v0.8.4. An app already on v0.8.4 needs no component API migration: review the update with
--dry-runand--diff, then overwrite only the items it already uses and reapply its local edits. Runtime components and their optional-testsitems remain separate; keep your app-owned fixtures and test configuration. Apps on older releases still need the applicable migration steps above and below. -
After v1.0.2: sheets, and a Menu shown as a bottom sheet, read their shadow from
--ouro-shadow-sheet-<side>, and Checkbox's tick draws over--ouro-duration-draw, both of which only a freshouro-baseadds (step 1 adds it again); without it a sheet draws no shadow and the tick appears at once. Every other shadow reads shadcn's--shadow-*tokens, and headings and overlay titles--font-heading, so a theme that sets them now restyles Ouro too. -
After v1.0.1:
formErrorsnow declares its already-frozen message arrays readonly. Keep mutableFormErrorsandErrorMessagesfor raw builders; annotate returned snapshots asFormErrorValueorReadonlyFormErrors, or let their type infer. Form, EditSheet, fielderrorprops and the normalization helper accept readonly projections. This corrects a false mutation permission, so a snapshot no longer fits a mutable raw-map annotation. TypeScript'sArray.isArraynarrows toany[]and can bypass readonly; unchanged runtime freezing still rejects container mutation, without deeply freezing React nodes. -
After v1.2.2:
ButtonacceptsreloadDocumentfor a document request through an internalhref, and its downloads use a plain anchor likeLink's. A false or nulldownloadno longer forces document navigation; passreloadDocumentwhen a resource route needs it without a download. -
After v1.2.4: Select, Menu, Combobox, Popover, Tooltip, HoverCard and NavigationMenu open their popups at the end of
<body>unlessOuroProvideris given aportalContainer, and in development each warns once when it opens outside every landmark of a page with a<main>. To keep popups in a landmark, makeconst popups = useRef<HTMLDivElement>(null), wrap the app in<OuroProvider portalContainer={popups}>and render<div ref={popups} />last inside<main>, outside any element with atransform,filterorcontain, which would clip or move the popups. In a Next.js App Router layout, which is a server component, put the provider and the ref in a small client component. Inside a dialog your app draws itself, wrap its content in<OuroProvider portalContainer={null}>so its popups open where Base UI puts them. Dialogs, sheets and toasts still open at the end of<body>. The landmark warning goes toconsole.warn, so a test that fails on console output fails until the popups are in a landmark. SidebarLayout'sheadernow renders in a<header>, the page's banner, so remove a banner your page draws around SidebarLayout. Thetesting/axekit has a newaudit, which fails every violation at any impact and every result axe could not decide unless it measures it, in both color schemes. Theouro-testingitem now namesaxe-coreamong its devDependencies, so an update adds it to an app that lacks it. -
After v1.2.8: the Toaster's Notifications region is no longer a live region: two live regions last inside it say each toast's message and description, the assertive one a
role="alert", so for its first seven seconds a toast's words are in the page twice. Find a toast in a test by its role and name,getByRole("dialog", { name: "Saved" }), or"alertdialog"for a destructive toast, not withgetByText, and expect noaria-liveon the region. Dismiss buttons and destructive toasts are no longer hidden from screen readers while the stack is collapsed. Thetesting/axekit'sauditnow leaves focus, the selection and every scroll position as it found them, and throws, naming what changed, when its Tab walk closes a popup it cannot open again; audit the page before that popup opens. -
After v1.2.14: Avatar's initials take a hue from the name, from the tokens
--avatar-1to--avatar-8, which only a freshouro-baseadds (step 1 adds it again); without them the initials show with no tint. Passcolor="neutral"to keep the plain grey. Avatar's presence dot sits over its edge, so the picture now rounds its own corners instead of the avatar clipping it. -
After v1.3.3: Avatar's initials and AvatarGroup's "+N" count are drawn with CSS from a data attribute and are no longer text in the page, so a link or button that wraps an avatar and names itself passes WCAG 2.5.3, Label in Name. A test that found an avatar by its letters,
getByText("AL"), or expected them in a row's text, now finds it by role and name,getByRole("img", { name: "Ana Lind" }), or readsdata-ouro-avatar-initials. -
After v1.3.4:
ShowMoreno longer readsestimate, which it keeps only so an app that passes it still compiles; drop it when you like. -
After v1.3.5: several default failure messages changed, so a test that matches the old words needs the new ones.
SyncStatus'serrorlabel is "Not saved: the server refused the changes".CopyButtonandShareButtonshow "Browser blocked copying" or "Browser blocked sharing" for two seconds, with a sentence their newfailedMessagesets.ImageCropper'slabels.openErrorandImageField's refusal begin "The browser can't read".EditSheet's rejected save says "Your changes were not saved: " with the error's own message, so rejectonSubmitwith a message a person can read, or passfailureMessage.MessageListdraws one action bar for all its messages, on the message the pointer is over, so a test that looked for a bar inside each message finds that one; aMessageoutside aMessageListkeeps its own. -
After v1.3.6:
Moment'squietis words only: the compact row drops its 40px art (a loading spinner stays), andOuroProvider'squietsets it for the whole app; for a compact moment with art, usesize="inline"and its 24px art instead.Celebrate's confetti stays inside its own box, so give it room with layout classes (h-24 w-full) for a wider burst. At phone widthNavbarbuilds its menu sheet while the page is idle and keeps it hidden between opens, so a test that finds something in the bar by its label or text alone (getByLabelText("Menu"),getByText("Recipes")) also finds its copy in the sheet: find it by its role.Porthole's fresh headline reads "Up to date", not "Updated just now"; passlabels.freshfor other words. The site and the@ouronamespace moved to https://ui.ouroboros.bot/, so set"@ouro": "https://ui.ouroboros.bot/r/{name}.json"incomponents.json; the old host forwards until you do. -
After v1.3.9: Ouro check has new gated rules (
giant-picture,cramped-heading,nested-frame,baked-corner,type-scale,shadow-scale,grey-on-colour,heading-hierarchy,jank,repaintand, for a site on the web,https), andblurry-imagecovers videos, so a run that passed can now report findings. Fix them, or let a rule report without failing while you do: waive it inouro-check.jsonwith the reason, and remove the waiver once its findings are fixed.jankwalks every page at one size and theme;"walk": falseturns it off. -
After v1.3.9 (Navbar): on a page below a link,
NavbarandNavigationMenumark that linkaria-current="true", not"page", so a test that expected"page"on a section's link finds"true"; the current page is underlined in the primary colour instead of a bar at the start edge. -
After v1.3.10: Ouro check has new gated rules,
console-error(an uncaught error,console.errororconsole.warnwhile a page loads),failed-request(a request to the page's own server that fails),off-screen(text or a control the screen cuts off),duplicate-control(the same control twice in view),stray-scrollbar(a region that scrolls by a few pixels),leaked-value(undefined,NaN,[object Object], an id, a translation key or aTODO:on screen) andodd-timestamp(Invalid Date,1 January 1970, a raw or machine timestamp, a negative age)stretched-image(a picture or a video drawn out of its own shape),focus-ring(a control that shows no keyboard focus),dark-miss(a light surface left on a dark page) anddisabled-no-reason(a disabled control with no reason tied to it), so a run that passed can now report findings. Fix them, or mark people's own words, such as a message list, withdata-ouro-allow="leaked-value odd-timestamp"and a reason.check.tsimports four new files,text-check.ts,layout-check.ts,theme-check.tsandinteraction-check.ts: if your app pins the check's files in a list, addregistry/ouro/check/text-check.ts,registry/ouro/check/layout-check.ts,registry/ouro/check/theme-check.tsandregistry/ouro/check/interaction-check.tsto it.blurry-imagecan no longer be waived: it holds a picture to exactly its file's pixels at the density, checks raster CSS backgrounds too, reportsdata-ouro-allow="blurry-image"as a finding of its own, and a waiver of it inouro-check.jsonmakes the check exit 2. Give each picture it reports a larger source;--images-report <file.json>lists them with the width each needs.ouro-imagesrefuses a picture too small to draw sharp, and exits 1 for it. -
After v1.3.84 (radii): where the browser has no
corner-shape(Safari and WKWebView today), the theme's radius steps shrink to 0.7 of their size, so a circular corner follows the squircle closely. That factor is--ouro-corner-fallback, which only a freshouro-baseadds (step 1 adds it again), and from v1.3.111 an app's own--ouro-radius-scalemultiplies with it rather than replacing it. A test that expected a component's computedborder-radiusto equal--radiusor arounded-*step there now finds the smaller value: compare with the radius the theme computes for that step, or check the shape on a browser withcorner-shape. -
After v1.3.87 (Button, Dialog, Card, TextField): where the browser has no
corner-shape, Button draws its fill, border and pressed layer on a<span data-ouro-surface aria-hidden="true">inside it, clipped to a squircle, and Dialog's popup, Card'soutlinevariant and TextField'soutlinevariant draw theirs the same way in later releases. A variant now sets its colours as custom properties (--ouro-bg,--ouro-bd) instead of classes such asbg-primaryorborder border-border, so a test that expected those classes on the button, or read the button's ownbackground-colororborder-colorin Safari, now misses them. Test what a person sees instead: find the control by role and name, and read the computed colours from the element that paints them,[data-ouro-surface]where it is shown and the control itself where it is not. A test that counts a button's children finds one more, the surface span, between its touch target and its label. -
After v1.3.76 (Skeleton): Skeleton no longer sweeps a band across the placeholder: it holds still for its first second, then breathes, easing its opacity down and back on the keyframes
ouro-skeleton-breathe, which only a freshouro-baseadds (step 1 adds it again); without them it holds still.shimmer={false}still draws it with no breathing, and reduced motion holds it still too. -
After v1.3.11:
Chartdraws its legend in a row below the plot, so a chart with a legend is one row taller. A centeredDialogwhose body scrolls opens with focus on the body's first control, or its close button, not on the scrolling body. -
After v1.3.12: an icon-only
Buttonsizes its svg child as it sizesstartIcon, unless the icon has a size class of its own, so an icon that kept its own fixed size now matchesstartIcon. -
After v1.3.14: the testing kit keeps each test's media emulation (reduced motion, forced colours, colour scheme and contrast) to the test that set it, so a test that relied on one before it leaving reduced motion on now sets it itself, or in its file's
beforeAll. -
After v1.3.16: the testing kit moves the mouse off the page before each test in the mouse projects, so a test that relied on a hover left by the one before now hovers itself.
-
After v1.3.19 (Hero):
Hero'spicturetakes{ light, dark }, the same scene by day and at night, and no longer a single picture, so a hero that passed one picture fails to compile until it passes both; the dark one shows while the page is in dark mode. Ouro check has a new gated rule,hero-dark-art(a hero whose picture has no night art), so a run that passed can now report it. -
After v1.3.20:
ouro-imagesinstalls to@lib/ouro/images/, beside the Ouro AX kit it now runs on, where it was~/lib/ouro/images/, so re-adding it leaves the old copy behind: deletelib/ouro/images/at your project root once nothing imports it, and point any script that ran it at the new path. A refused option prints one line with the fix and exits 2. -
After v1.3.33:
ouro-checkinstalls to@lib/ouro/check/, beside the Ouro AX kit it now runs on, where it was~/lib/ouro/check/, so deletelib/ouro/check/at your project root once nothing imports it, and point any script that ran it at the new path. Its--helpand--jsoncome from the kit, a refused option or target prints one line with the fix and exits 2, and a flag given twice is refused, except--ready-event, which repeats.ax-flowsruns on the same kit: a refused option or suite module prints one line with the fix and exits 2 (a missing suite module or X-ray report used to stop with a stack trace and exit 1), and under--jsonstdout holds the outcome alone, with each flow's line on stderr. -
After v1.3.34: Ouro check has new gated rules for text that wraps by accident,
lone-word,tall-heading,one-word-line,hard-breakandnarrow-heading, anddark-art, a dark page that shows its light theme's hero art, so a run that passed can now report findings. Balance headings and wrap prose pretty, give hero art a night twin, or mark a finding you keep on purpose withdata-ouro-allowand a reason.check.tsimports a new file,wrap-check.ts: if your app pins the check's files in a list, addregistry/ouro/check/wrap-check.tsto it. -
After v1.3.225: Ouro check's
clipped-textfinds more: a text block, a heading or a picture pushed partly out of a box that hides its overflow, such as a card's title, so a run that passed can now report findings. Let the box grow to hold it, or mark a cut you keep on purpose withdata-ouro-allowand a reason. -
After v1.3.45:
ax-xrayruns on the Ouro AX kit, and its--jsonreport is unchanged, but under--jsona refused option now prints its error as JSON on stdout, where it printed nothing, so a script that readsxray.jsonmust gate on the exit code. -
After v1.3.49 (Dialog): a
Dialogopened from the keyboard whose body has nothing to focus now gives first focus to a field in its footer (an input, a text area or a select), where it gave it to Close, so a test that expected Close there now finds the field. -
Surfaces (Button, Card, Dialog, TextField, Badge, Toggle): where a browser lacks
corner-shape, Button, Card, Dialog, TextField, Badge and Toggle paint their fill and border on a[data-ouro-surface]span inside the element. Abg-*orborder-*class an app passes still wins, because the element then paints its own colour. -
ouro-plain (classes for plain markup): the classes for markup that is not an Ouro component (
ouro-focus-ring,ouro-row,ouro-disclosure,ouro-skip-link,ouro-reveal,ouro-nav-linkand the rest) moved fromouro-baseinto their own item,ouro-plain, so an app built only from components no longer carries their CSS. An app that uses them addsouro-plainonce, afterouro-base:npx shadcn@latest add ourostack/ouro-ui/ouro-plain#v1.3.344. Addingouro-baseagain leaves the rules it wrote before in your stylesheet, so nothing is lost before you addouro-plain, and addingouro-plainmerges into them. -
After v1.3.239 (trigger or open): on Dialog, ConfirmDialog, Sheet, EditSheet, Popover and EmojiPicker,
openbesidetriggeris typed as the literal "Pass trigger, or open and onOpenChange, not both" instead ofnever, so passing both is a type error that names the fix. A wrapper that readsopenfrom the whole props type (DialogProps["open"], oropendestructured fromDialogProps) now gets that literal too: read it from the controlled mode's type,DialogControlledProps["open"], or narrow it withtypeof open === "boolean". -
After v1.3.241: Ouro check, Ouro images, and the X-ray, flow runner and surfaces check with their tests now install under
scripts/ouro/, outside the app's TypeScript project, where they werelib/ouro/check/,lib/ouro/images/andlib/ouro/ax/. Ouro Current's update moves the files it installed there and adds the package.jsonimportsentry they need. Without Ouro Current, run the add again for those items, then set the entry withnpm pkg set "imports.#ouro-ax/*=./src/lib/ouro/ax/*"(withsrc/libyour lib folder), delete the oldlib/ouro/check/,lib/ouro/images/and the moved Ouro AX files at your project root once nothing imports them, and remove any tsconfigexcludeof those folders. -
After v1.3.244 (radius steps): components round their corners with Ouro's own steps,
rounded-ouro-lg(rounded-ouro-smtorounded-ouro-4xl), which ouro-base defines from--radius,--ouro-radius-scaleand--ouro-corner-fallback, so an app set up withshadcn initgets the Safari fallback and the scale, which shadcn's own--radius-*steps never carried. Adding ouro-base again appends the--radius-ouro-*steps the app does not have. An app that set Ouro components' corners by overriding--radius-smto--radius-4xlshould override--radiusor--ouro-radius-scaleinstead, or the--radius-ouro-*steps, since those no longer reach them. -
After v1.3.266 (cards): Ouro check has two new gated rules:
linked-card-dead-zone, a linked card or row where a click on some spot opens nothing, andreveal-reflow, a card whose hover or focus reveal moves the page. Ouro Current records the findings an app already has as known. A linked Card, Item or Table row now opens from a click anywhere on it itself, so the app can drop a click handler it added to its cards. -
After v1.3.276 (first run): Ouro check has three new gated rules:
blank-pane, a pane with nothing to read, press or wait for;dismissable-step, a modal dialog a person can put away onto a blank page, or onto a signed-out page with no way to sign in; andsigned-out-empty, an empty state shown while signed out. Ouro Current records the findings an app already has as known. Mark the app's shell withdata-ouro-session="signed-in"or"signed-out"so the check knows which it is looking at, and give its own words inouro-check.json'sfirstRunif they aren't English. -
After v1.3.298 (TextArea): TextArea's vertical padding is the
--ouro-text-area-pyvariable, whichautoGrowadds to itsrowsandmaxRowsbounds so its first frame has its final height, so an app that changed the padding with apy-*class on the textarea (className="[&_textarea]:py-3") sets the variable instead (className="[&_textarea]:[--ouro-text-area-py:12px]"); in development, TextArea warns with that fix. -
After v1.3.313 (wide-screen type):
ouro-basegrows the root type to 112.5% from 2400px wide and to 125% (20px) from 3200px, so a 4K display at 1x reads at a laptop's size. An app that grew its own root type for wide screens can drop that rule; one that wants another size keeps its ownhtml { font-size }outside any layer, which wins. -
After v1.3.314 (giant text): Ouro check has a new gated rule,
giant-text: the size most of a page's running text is drawn at is over 24px, as when an app grows its root type with the screen. Ouro Current records the findings an app already has as known. To fix one, drop the app's own wide-screen root rule, or set the reading size in rem.
0. Commit first
--overwrite replaces every Ouro file, including files you edited. Commit before you start. Afterwards, git diff shows your own edits being overwritten, so reapply the ones you need.
Review the diff of your Tailwind CSS file too, the one components.json names in tailwind.css, because step 1 adds ouro-base, the one item that writes there, and shadcn add rewrites more than Ouro's tokens. It adds @custom-variant dark (&:is(.dark *)); when the file has no @custom-variant (shadcn@4.21.1 does this for any item with theme variables on Tailwind CSS v4), adds the tokens your file lacks to :root, .dark and @theme inline (among them --input, --radius and the radius scale, if your theme has none), and collapses blank lines. Keep the new lines and step 2's deletions, and revert the rest. After this upgrade no component add opens the file again.
1. Update every Ouro component, with its tests
Update every Ouro component in your app, not only the items you typed: v0.1.0 added each component's dependencies too, so an app that added only dialog also has button and sheet. Each component is one .tsx file in your components/ouro/ folder (dialog/ holds dialog and confirm-dialog, and text/ holds text and heading). Add each one as <name> and <name>-tests, plus ouro-base, in one command at the same ref, with --overwrite (without it the CLI stops to ask about each file). For the app that added only dialog, that is ouro-base button button-tests dialog dialog-tests sheet sheet-tests. No component installs ouro-base any more, so this is where your stylesheet gets the tokens added since v0.1.0.
This command finds the components, prints them and adds them. If it finds none, it stops before adding anything; run it in the folder with components.json. If you use the Ouro theme, add ourostack/ouro-ui/ouro-theme#v1.3.344 to the add in it.
( p() { npx shadcn@latest info --json | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>console.log(JSON.parse(s).config.resolvedPaths[process.argv[1]]))' "$1"; }; ouro="$(p components)/ouro"; items=$(find "$ouro" -name '*.tsx' ! -name '*-parts.tsx' ! -name '*.test.tsx' ! -name '*.stories.tsx' 2>/dev/null | sed -E 's|.*/(.*)\.tsx$|\1|' | sort); [ -n "$items" ] || { echo "No Ouro components in $ouro. Run this in the folder with components.json." >&2; exit 1; }; echo "Updating: $(echo "$items" | paste -sd " " -)"; npx shadcn@latest add $(echo "$items" | sed -E 's|.*|ourostack/ouro-ui/&#v1.3.344 ourostack/ouro-ui/&-tests#v1.3.344|') ourostack/ouro-ui/ouro-base#v1.3.344 --overwrite )This keeps the tests v0.1.0 installed, deletes none of your files and adds no component you didn't have. shadcn may print Skipped N files: (files might be identical, use --overwrite to overwrite) even with --overwrite: those files already equal the release's, so nothing was missed. The -tests items name Vitest, Storybook and Playwright without a version, so the versions in your package.json stay as they are. v0.7.0's items still carry versions: after an add at v0.7.0, restore every test-tool version you had pinned (git diff package.json): Vitest and its companions, Playwright and Storybook. The tests need Vitest 4.1.11 or later, Playwright 1.58.1 or later and Storybook 10.2.10 or later; update those yourself if yours are older (the README's "Details" links the Testing page). The specs in e2e/ouro now import test and expect from e2e/ouro-fixtures.ts, a file of yours: add it with the one line export { expect, test } from "@playwright/test";, or export your own fixtures from it.
2. Remove the self-referential theme lines
v0.1.0 wrote a line into @theme inline for each Ouro token that points at itself, such as --ouro-press-scale: var(--ouro-press-scale);, and --color-ouro-backdrop-color: var(--ouro-backdrop-color);. Delete them from your Tailwind CSS file, the one components.json names in tailwind.css. The values stay in :root and .dark. This command finds the file and deletes the lines:
perl -i -ne 'print unless /^\s*--(color-)?ouro-[\w-]+:\s*var\(--ouro-[\w-]+\);\s*$/' "$(npx shadcn@latest info --json | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>console.log(JSON.parse(s).config.resolvedPaths[process.argv[1]]))' tailwindCss)"3. Optional: drop Ouro's tests
To keep only the components, delete the files Ouro owns for its tests: the test, type-test and story files in your components/ouro/ and lib/ouro/ folders, the test kit in lib/ouro/testing and the specs in e2e/ouro. The command stops if it can't find those folders.
( p() { npx shadcn@latest info --json | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>console.log(JSON.parse(s).config.resolvedPaths[process.argv[1]]))' "$1"; }; c="$(p components)/ouro"; l="$(p lib)/ouro"; [ -d "$c" ] && [ -d "$l" ] || { echo "No Ouro folders at $c and $l. Run this in the folder with components.json." >&2; exit 1; }; find "$c" "$l" \( -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.test-d.ts' -o -name '*.stories.tsx' \) -delete; find "$l/testing" e2e/ouro -delete )Then remove the ouroTestProjects import and call from your Vitest config. Only if Ouro's tests were the only tests using them, also delete vitest.config.ts, playwright.config.ts and .storybook/, and uninstall vitest, @vitest/browser-playwright, playwright, @playwright/test, storybook and @storybook/react-vite with your package manager.
4. Change imports of moved helpers
If your own code imports these helpers, change the import:
useOuro: fromlib/ouro/ouro-providertolib/ouro/use-ouro.sheetSides,sideWarning,sheetHint,iosBackdropandfooterClass: fromcomponents/ouro/sheet/sheet-partstocomponents/ouro/sheet/sheet-styles.dialogSizesanddialogSizeWarning: fromcomponents/ouro/dialog/dialog-partstocomponents/ouro/dialog/dialog-styles.alignClassesandcheckAlign: fromcomponents/ouro/text/texttocomponents/ouro/text/text-styles.useDevWarnings: fromlib/ouro/use-dev-warningstolib/ouro/use-dev-messages. Delete the oldlib/ouro/use-dev-warnings.ts; nothing imports it after step 1.
5. Delete the helpers nothing imports
Releases before v0.8.0 installed every helper in lib/ouro with any component. From v0.8.0 a component installs only the helpers it imports, but an update deletes nothing. Remove unused historical helpers rather than excluding them from coverage.
Before deleting anything, perform a read-only import/reference audit across the whole app, including scripts, tests, stories and configuration outside src/. Use the app's actual tsconfig and bundler aliases to resolve references to each helper's full path. Check relative imports, explicit extensions, re-exports and dynamic imports too; an importing file with the same basename is still a different file. A text search for lib/ouro/<name> alone cannot prove a helper is unused.
Delete a helper and its own tests only after verifying that no remaining app file or retained Ouro file references it (references from that helper's own tests do not require keeping an otherwise unused helper). Check again after each removal: another historical helper may have been used only by the one you removed. If a reference is unresolved or you cannot verify a file's use, keep it until you can. Keep ouro-provider.tsx if you mean to use it and have not yet, and retain ambient declarations such as env.d.ts that the app's type check needs even without an import.
Then type check and build your app. CI runs steps 1 to 3 on a v0.1.0 app, with these commands read from this file (scripts/install-test.sh upgrade).
Or through the @ouro namespace, which serves the newest release: this one once Pages deploys. Add it to components.json once:
"registries": { "@ouro": "https://ui.ouroboros.bot/r/{name}.json" }npx shadcn@latest add @ouro/ouro-base @ouro/dialogTagged from main's commit 14b9dfecc45c0fc01b0378edf2f66ae5a2f11126, which main's own runs passed, so nothing ran twice:
- CI run: https://github.com/ourostack/ouro-ui/actions/runs/44595749062
- CI run: https://github.com/ourostack/ouro-ui/actions/runs/44595749070
- CI run: https://github.com/ourostack/ouro-ui/actions/runs/44595748840
- Screen-reader lane (VoiceOver and NVDA): https://github.com/ourostack/ouro-ui/actions/runs/44595749349
Items, by name. The docs describe each component, and the tag's registry.json holds every item's description:
ouro-base, ouro-plain, ouro-theme, ouro-lib, ouro-testing, lib-a2ui-core, lib-announce, lib-appearance-hints, lib-celebration-cap, lib-claims, lib-class-name-check, lib-cn, lib-color-scheme, lib-color-scheme-script, lib-control-ref, lib-css-panel, lib-current-path, lib-dev, lib-env, lib-feedback, lib-floating, lib-focus-handoff, lib-form-answer, lib-fragment-focus-script, lib-halve, lib-hero-preload-script, lib-insert-text, lib-keep-clear, lib-keep-focus-clear, lib-key-shortcuts, lib-last-input, lib-mcp-app, lib-measure-interaction, lib-navigation-key, lib-open-mode, lib-ouro-provider, lib-page-direction, lib-page-scroll-hold, lib-people-cache, lib-platform, lib-portal-container, lib-porthole-view, lib-refs, lib-router-link, lib-row-hover, lib-scroll-fade, lib-server-element, lib-share, lib-spring, lib-squircle-polyfill, lib-stretched-link, lib-theme-preset, lib-theme-preset-script, lib-toast, lib-tones, lib-touch-target, lib-use-backdrop-anchor, lib-use-command-shortcut, lib-use-dev-messages, lib-use-drag, lib-use-field, lib-use-install-prompt, lib-use-keyboard-scrollable, lib-use-media-query, lib-use-mounted-open, lib-use-ouro, lib-use-person, lib-use-platform, lib-use-reduced-motion, lib-use-sheet-presentation, lib-use-timer, lib-use-until-found, button, text, heading, sheet, dialog, confirm-dialog, field, fieldset, link, text-field, text-area, checkbox, checkbox-group, radio-group, switch, form, edit-sheet, select, native-select, number-field, slider, combobox, toaster, spinner, progress, skeleton, avatar, badge, alert, separator, kbd, popover, tooltip, hover-card, menu, command, tabs, segmented-control, accordion, collapsible, show-more, card, item, item-group, empty, scroll-area, aspect-ratio, stack, row, navbar, sidebar, sidebar-layout, stacked-layout, auth-layout, breadcrumb, pagination, navigation-menu, table, description-list, toggle, toggle-group, button-group, otp-field, file-field, color-field, swipe-actions, reorderable, calendar, date-picker, carousel, resizable, chart, message, message-list, attachment, thread-summary, checklist, inspector, skip-link, tab-bar, route-progress, color-scheme-toggle, page-header, copy-button, code-block, timer, timer-tray, celebrate, choice-card, image-cropper, image-field, share-button, sync-status, local-date, relative-time, install-prompt, conversation-list, attention-card, reaction-bar, lightbox, composer, emoji-picker, navigation-rail, time-grid, toolbar, agent-presence, autocomplete, emoji, level-meter, live-captions, media-tile, moment, snap-pip, family-bar, family-footer, hero, porthole, a2ui-surface, thread-rail, ouro-mcp-app, composed-surface, unread-dot, agent-handoff, app-window, cover, section-header, thread-layout, chat-header, typing-indicator, read-receipt, theme-picker, page-shell, lib-announce-tests, lib-appearance-hints-tests, lib-celebration-cap-tests, lib-claims-tests, lib-class-name-check-tests, lib-cn-tests, lib-color-scheme-script-tests, lib-color-scheme-tests, lib-control-ref-tests, lib-current-path-tests, lib-dev-tests, lib-feedback-tests, lib-floating-tests, lib-focus-handoff-tests, lib-form-answer-tests, lib-fragment-focus-script-tests, lib-halve-tests, lib-hero-preload-script-tests, lib-insert-text-tests, lib-keep-clear-tests, lib-keep-focus-clear-tests, lib-key-shortcuts-tests, lib-last-input-tests, lib-mcp-app-tests, lib-measure-interaction-tests, lib-navigation-key-tests, lib-ouro-provider-tests, lib-page-direction-tests, lib-page-scroll-hold-tests, lib-people-cache-tests, lib-platform-tests, lib-portal-container-tests, lib-porthole-view-tests, lib-row-hover-tests, lib-scroll-fade-tests, lib-server-element-tests, lib-share-tests, lib-spring-tests, lib-squircle-polyfill-tests, lib-theme-preset-script-tests, lib-theme-preset-tests, lib-use-command-shortcut-tests, lib-use-dev-messages-tests, lib-use-drag-tests, lib-use-install-prompt-tests, lib-use-keyboard-scrollable-tests, lib-use-media-query-tests, lib-use-mounted-open-tests, lib-use-person-tests, lib-use-platform-tests, lib-use-reduced-motion-tests, lib-use-sheet-presentation-tests, lib-use-timer-tests, lib-use-until-found-tests, button-tests, text-tests, heading-tests, sheet-tests, dialog-tests, confirm-dialog-tests, field-tests, fieldset-tests, link-tests, text-field-tests, text-area-tests, checkbox-tests, checkbox-group-tests, radio-group-tests, switch-tests, form-tests, edit-sheet-tests, select-tests, native-select-tests, number-field-tests, slider-tests, combobox-tests, toaster-tests, spinner-tests, progress-tests, skeleton-tests, avatar-tests, badge-tests, alert-tests, separator-tests, kbd-tests, popover-tests, tooltip-tests, hover-card-tests, menu-tests, command-tests, tabs-tests, segmented-control-tests, accordion-tests, collapsible-tests, show-more-tests, card-tests, item-tests, item-group-tests, empty-tests, scroll-area-tests, aspect-ratio-tests, stack-tests, row-tests, navbar-tests, sidebar-tests, sidebar-layout-tests, stacked-layout-tests, auth-layout-tests, breadcrumb-tests, pagination-tests, navigation-menu-tests, table-tests, description-list-tests, toggle-tests, toggle-group-tests, button-group-tests, otp-field-tests, file-field-tests, color-field-tests, swipe-actions-tests, reorderable-tests, calendar-tests, date-picker-tests, carousel-tests, resizable-tests, chart-tests, message-tests, message-list-tests, attachment-tests, thread-summary-tests, checklist-tests, inspector-tests, skip-link-tests, tab-bar-tests, route-progress-tests, color-scheme-toggle-tests, page-header-tests, copy-button-tests, code-block-tests, timer-tests, timer-tray-tests, celebrate-tests, choice-card-tests, image-cropper-tests, image-field-tests, share-button-tests, sync-status-tests, local-date-tests, relative-time-tests, install-prompt-tests, conversation-list-tests, attention-card-tests, reaction-bar-tests, lightbox-tests, composer-tests, emoji-picker-tests, navigation-rail-tests, time-grid-tests, toolbar-tests, agent-presence-tests, autocomplete-tests, emoji-tests, level-meter-tests, live-captions-tests, media-tile-tests, moment-tests, snap-pip-tests, family-bar-tests, family-footer-tests, hero-tests, porthole-tests, a2ui-surface-tests, thread-rail-tests, ouro-mcp-app-tests, composed-surface-tests, unread-dot-tests, agent-handoff-tests, app-window-tests, cover-tests, section-header-tests, thread-layout-tests, chat-header-tests, typing-indicator-tests, read-receipt-tests, theme-picker-tests, page-shell-tests, ouro-lib-tests, ouro-tests, ouro-census, ouro-source-rules, ouro-check, ouro-images, ouro-feel-probe, dashboard-page, list-detail-page, settings-page, ax-bundle, ax-checks, ax-claims, ax-cli, ax-command, ax-component, ax-dev-commands, ax-doctor, ax-effects, ax-example, ax-exit-codes, ax-flows, ax-lint, ax-mcp, ax-outcome, ax-output, ax-precise-copy, ax-probe, ax-problem, ax-redact, ax-surfaces, ax-terminal, ax-voice, ax-wait, ax-work-event, ax-xray, ax-bundle-tests, ax-checks-tests, ax-claims-tests, ax-cli-tests, ax-command-tests, ax-component-tests, ax-dev-commands-tests, ax-doctor-tests, ax-effects-tests, ax-exit-codes-tests, ax-flows-tests, ax-lint-tests, ax-mcp-tests, ax-outcome-tests, ax-output-tests, ax-precise-copy-tests, ax-probe-tests, ax-problem-tests, ax-redact-tests, ax-surfaces-tests, ax-terminal-tests, ax-voice-tests, ax-wait-tests, ax-work-event-tests, ax-xray-tests, ouro-ax, ouro-ax-tests