Repository navigation
v1.3.6
Install an item at this release, npx shadcn@latest add ourostack/ouro-ui/<item>#v1.3.6; 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.6 ourostack/ouro-ui/dialog#v1.3.6The tests, stories and specs are optional, one item per component: npx shadcn@latest add ourostack/ouro-ui/dialog#v1.3.6 ourostack/ouro-ui/dialog-tests#v1.3.6, or ourostack/ouro-ui/ouro-tests#v1.3.6 for all of them. List every item with npx shadcn@latest search 'ourostack/ouro-ui#v1.3.6'.
Changes in this release
- Added: Ouro AX:
ax-precise-copy,vagueFailureInandvagueFailuresIn, which find a vague failure ("couldn't", "could not", "something went wrong", "unable to", "failed to load", "an error occurred", a bare "Error" or "Failed") in a message or an answer, andcheckFailureCopyAllow, an allow-list whose every entry needs a match and a reason (test) - Added: Ouro AX: the X-ray's must claim
copy.precise-failure: every refusal, error, outcome error and summary,human.reason, doctor finding andhelp --jsontext says what happened and why, not only "couldn't" or "something went wrong";--failure-copy-allow <file>lets precise text through with its reason; the claim set and the X-ray are at 1.5.0 (test) - Changed: Ouro AX: a checks report says a check "threw before finishing", not that it "couldn't run", heads its failed checks "Found a problem", not a bare "Failed", and the example tool's exit code 3 means "the service didn't answer" (test, source)
- New: Composer
expanded(withonExpandedChange) ordefaultExpandedopens a bigger box for a long message from an expand button first among the actions: taller (expandedRows,expandedMaxRows), with thetoolbar, where Enter starts a new line and Ctrl+Enter (Command+Enter on a Mac) sends; it keeps the text, focus and caret, Escape collapses it, and the box grows and shrinks over a moment, at once with reduced motion (docs, test). - Fixed: Composer never sends while a suggestion list (
Autocomplete) is open, Ctrl+Enter included (test). - Fixed: Composer puts focus back in the text after a press of Send without scrolling a box around it, such as an app's frame with
overflow: hidden(test). - New: Composer
formattingtakes Teams' formatting keys (⌘B bold, ⌘I italic, ⌘U underline, ⌘⌥X strikethrough, ⌘⇧C code; Ctrl and Alt off Apple platforms) as light Markdown,editorReflets a formatting bar, an emoji button or a link dialog format and insert,pasteTextturns a paste into the box's text, and each change goes through the browser's own editing, so Undo and Redo step through them as through typing;composerShortcuts(fromcomposer-styles) gives the keys for a toolbar's tooltips (docs, test). - New: ⌘⇧X (Ctrl+Shift+X off Apple platforms) expands and collapses a Composer that expands, as in Teams, and the expand button's tooltip shows the key (test).
- Changed: Autocomplete's insert focuses the field without scrolling a box around it (test).
ouro-source-rules: a new category,vague-failure-copy, counts a string, template literal or JSX text that says "couldn't", "could not", "something went wrong", "unable to", "failed to load" or "an error occurred", or whose whole text is a bare "Error" or "Upload failed", and its message says what to write instead: what happened and precisely why, who or what caused it, and the next step. After updating the kit, record the copy an app already has with--write-baseline --allow-regression <reason>and from there the count can only fall.ouro-source-rules: a new setting,failureCopyAllowinouro-source-rules.json, lets precise copy that holds one of those phrases through, each entry with itsmatchand a requiredreason; against--basea new entry needs--allow-regression <reason>, as a newexcludedoes.- Changed:
CopyButton: when the browser refuses to copy, it shows "Browser blocked copying" for two seconds, short enough to keep the button's width, with "The browser blocked copying. Select the text and copy it by hand." as its tooltip and its announcement, a sentence the newfailedMessageprop sets. - Changed:
ShareButton: when neither sharing nor copying works, it shows "Browser blocked sharing" for two seconds, or "Browser blocked copying" where there is no share sheet, with what happened and how to copy the link by hand as its tooltip and its announcement, a sentence the newfailedMessageprop sets. - Changed:
SyncStatus: its defaulterrorlabel is now "Not saved: the server refused the changes", beside its Retry button. - Changed:
EditSheet: without afailureMessage, a rejected save now says "Your changes were not saved: " with the error's own message and "Press Save to try again.", or that the save stopped without saying why when the error carries an empty message; the button it names is thesubmitLabel. - Changed:
ImageCropper: its defaultlabels.openErroris now "The browser can't read this file as a photo. Choose a JPEG or PNG photo instead." for aFileorBlob, and for a URL "The browser didn't load the photo at this address: it is missing, blocked, or not a photo the browser can read. Choose another photo."; itslabels.saveErroris "The browser didn't turn the crop into a file. Press Save to try again, or choose another photo.", naming Save bylabels.save. - Changed:
ImageField: a photo the browser cannot open is turned away with "The browser can't read" and the file's name, "as a photo. Choose a JPEG or PNG photo instead." - Changed:
toast.error's type error now namestoast("Not saved: you are offline", { tone: "destructive" })as its example call. - Changed: Ouro check: a config or report it cannot read prints "Reading" with the file, "stopped the check:" with the reason, and the way on, and a crash prints "Ouro check stopped before it finished:" with the reason; Ouro images prints "Not written:" with the file and the reason.
- Changed: the test kit's failure messages say what happened:
audit's contrast reasons say axe left the contrast undecided and the screenshot to measure it threw, andtouchStepsays the frame at the touch was not ready for it, and why: no watcher there, or one whose frame Chromium's hit test does not reach yet, or that the watch for a later touch of the gesture did not start in its frame. - EmojiPicker: with a catalogue, the quick row's and the grid's first eight rows' images are fetched at high priority and the rest at low, in order; while the browser asks to save data, the rest wait until they near the screen.
- Lightbox: pressing a thumbnail starts fetching its full image before the viewer opens (a mouse's press, or a finger's or pen's tap as it lifts without having moved, so a scroll that starts on a thumbnail fetches nothing), and the viewer fetches the image shown first (
fetchPriority="high"), then the ones a step either side, then the rest (fetchPriority="low"). - Changed:
EditSheet: without afailureMessage, the alert a rejected save shows now includes the rejected error's own message, so rejectonSubmitwith a message a person can read, or passfailureMessage. - New: MediaTile, a tile for one live picture in a call (a camera, a photo when the camera is off, or a shared screen) that reads as one sentence, "Mara Lind, speaking, camera on, hand raised", draws a two-state speaking ring held for
hysteresisthat never moves the layout, reports throughonVisibilityChangewhether it can be seen and its size, once a frame and never twice the same, and declares its agent side inmediaTileAx: aparticipantread and a privatepinan agent may take (docs). - MessageList: the springs follow the whole of a fling, through a long frame on a busy page, and settle only once it stops, so the scroll position no longer moves after they have settled.
- MessageList: when the last page of older messages comes and
hasOlderturnsfalse, the room kept above the first message goes without moving the reader's message for even one frame; before, the messages in view jumped 44px for one frame, a layout shift Chromium scored, as the room went. - MessageList: a scroll reads the places of only the messages near the view, not every message, so scrolling through a long conversation costs what scrolling a short one does, as does keeping the reader's place while older history loads; a message that fills the view is held by itself and the few after it, not by every message to the newest.
- Changed: MessageList draws one action bar for all its messages, on the message the pointer is over, rather than one per message, and listens for it once, on the list (test); the bar goes as the pointer leaves, the list scrolls under it, the window loses focus or the menu opens, so none stays behind (test). Message's props are unchanged; a Message outside a MessageList keeps its own bar.
- Added: MessageList's one menu for its messages, opened by a message's "…" button, a right-click on it, or Shift+F10 or the context-menu key on it, with the message's
quickReactionson top and each entry'sshortcutat its end, named "Message actions for" its author (actionsMenuLabel) (test); Escape puts focus back on the message (test). - Added:
lib-row-hover, one shared layer for a list's rows (useRowHover), shown within the pointer's own event (test); a pointer that has not moved takes nothing, so the events a browser sends for it as the page changes under it neither move nor hide the layer, and MessageList's bar stays on the message keyboard focus is in (test). - Added:
MessageAction'sshortcut, the keys an app binds to an action, shown after its name in its tooltip and under its emoji in the menu's row of reactions, and given to screen readers asaria-keyshortcuts(test). - Changed: MessageList moves its one action bar from message to message, updated rather than built again, so it is in place within the pointer's event even on a slowed computer (test); an Escape in a field in a message, such as an inline editor, is the field's and leaves the bar (test).
- Changed: a key in MessageList's one bar reaches the list's keyboard handling as a key in its message does, so Tab goes on from the bar through the message and out of the list (test); a right-click on a link or picture in a message keeps the browser's menu (test).
- MessageList: the reader's place holds to a pixel while older messages go in above a row at a time: what a correction of the scroll position could not take (WebKit keeps it in whole pixels, and a move under half a pixel was not made) is carried into the next, so it no longer adds up.
- MessageList: messages that come after the list mounted empty open it at the end before the browser draws them.
- MessageList:
conversation, which conversation the messages are: named with its messages or before them, as an app that keeps the last messages while it fetches does, it opens at the newest as they come, the first one named for messages already shown moves nothing, and re-keying messages within one is never a switch. Without it, messages that share no key with those the list held open at their newest, from wherever the reader was, and focus on a message moves to the newest one in view instead of scrolling to the old message's place. - MessageList: focus on a message replaced in place goes to its replacement, not to whichever message is now at its old index, which scrolled the reader far up after older messages went in above.
- MessageList: a list at its end stays there when something in a message gets shorter for a moment and longer again, such as a picture's placeholder swapped for the picture with a layout read between, where WebKit pulled the scroll position up and the list stopped following.
- Fixed: NavigationRail measures what fits only when its labels, their order, the current item,
hideLabels,moreLabelor its classes change, or when a resize observer reports a new size, so a render with only a new count, or the same items, costs the page no forced layout. - Fixed: NavigationRail brings an item back from More when the text gets smaller or the rail wider, rather than holding it to the height it had at the old size.
- Fixed: NavigationRail measures its labels again when a font loads, so a word the new face makes too wide is set a size smaller rather than cut.
- New:
ouro-testing:watchLayoutReads()records the reads that lay the page out, so a test proves a render costs no forced layout.
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.12 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.3 The release notes list every change.4
-
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).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.5 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.6 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.7 -
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".8 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.8 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>.9 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.8 -
v0.8.0: no component installs
ouro-base; add it once (step 1 does), and later adds leave your stylesheet alone.8 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.8 The-testsitems no longer set a version for Vitest, Storybook or Playwright.10 The specs importtestandexpectfrome2e/ouro-fixtures.ts, a file of yours (step 1).8lib/ouro/use-dev-warnings.tsis nowlib/ouro/use-dev-messages.ts(step 4).8 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).8OuroProvidernow 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.11 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.11 Withoutpage, the touch host stays 390x844.11 On Vitest 4, retain a host large enough for every requested test viewport, such as the Testing guide's 1600x1200 example.11 -
v1.0.0: the first stable release keeps the component APIs, theme tokens, defaults and test-tool minimums from v0.8.4.12 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.12 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.13 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.1314 -
After v1.0.1:
formErrorsnow declares its already-frozen message arrays readonly.15 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.15 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.16 A false or nulldownloadno longer forces document navigation; passreloadDocumentwhen a resource route needs it without a download.16 -
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>.17 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.18 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.19 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.20 Theouro-testingitem now namesaxe-coreamong its devDependencies, so an update adds it to an app that lacks it.21 -
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.22 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.23 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.24 -
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.25 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.26 -
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.27 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.27
0. Commit first
--overwrite replaces every Ouro file, including files you edited.28 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.29 Keep the new lines and step 2's deletions, and revert the rest. After this upgrade no component add opens the file again.8
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).1 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.8
This command finds the components, prints them and adds them. If it finds none, it stops before adding anything30; run it in the folder with components.json. If you use the Ouro theme, add ourostack/ouro-ui/ouro-theme#v1.3.6 to the add in it.
( p() { npx shadcn@latest info --json | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).config.resolvedPaths.$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.6 ourostack/ouro-ui/&-tests#v1.3.6|') ourostack/ouro-ui/ouro-base#v1.3.6 --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.28 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.31 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).32 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);.33 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 -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).config.resolvedPaths.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 -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).config.resolvedPaths.$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.8 From v0.8.0 a component installs only the helpers it imports, but an update deletes nothing.8 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).3
Or through the @ouro namespace, which serves the newest release: this one, once main is prepared for the next release. Add it to components.json once:
"registries": { "@ouro": "https://ui.ouro.bot/r/{name}.json" }npx shadcn@latest add @ouro/ouro-base @ouro/dialogRehearsed: the rehearsal of v1.3.6 passed on main's commit d6059dc6d81b8d6f2f165db3c6a8d55c668d56c1, which this release is cut from.
Items, by name. The docs describe each component, and the tag's registry.json holds every item's description:
ouro-base, ouro-theme, ouro-lib, ouro-testing, lib-announce, lib-appearance-hints, lib-claims, lib-class-name-check, lib-cn, lib-color-scheme, lib-color-scheme-script, lib-control-ref, lib-current-path, lib-dev, lib-env, lib-feedback, lib-floating, lib-focus-handoff, lib-form-answer, lib-halve, lib-insert-text, lib-keep-clear, lib-key-shortcuts, lib-last-input, lib-measure-interaction, lib-navigation-key, lib-open-mode, lib-ouro-provider, lib-page-scroll-hold, lib-people-cache, 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-stretched-link, 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-reduced-motion, lib-use-sheet-presentation, lib-use-timer, 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, lib-announce-tests, lib-appearance-hints-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-halve-tests, lib-insert-text-tests, lib-keep-clear-tests, lib-key-shortcuts-tests, lib-last-input-tests, lib-measure-interaction-tests, lib-navigation-key-tests, lib-ouro-provider-tests, lib-page-scroll-hold-tests, lib-people-cache-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-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-reduced-motion-tests, lib-use-sheet-presentation-tests, lib-use-timer-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, ouro-lib-tests, ouro-tests, ouro-census, ouro-source-rules, ouro-check, ouro-images, ax-checks, ax-claims, ax-cli, ax-command, ax-component, ax-dev-commands, ax-effects, ax-example, ax-exit-codes, ax-flows, ax-lint, ax-mcp, ax-outcome, ax-output, ax-precise-copy, ax-problem, ax-terminal, ax-voice, ax-wait, ax-work-event, ax-xray, ax-checks-tests, ax-claims-tests, ax-cli-tests, ax-command-tests, ax-component-tests, ax-dev-commands-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-problem-tests, ax-terminal-tests, ax-voice-tests, ax-wait-tests, ax-work-event-tests, ax-xray-tests, ouro-ax, ouro-ax-tests
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.1.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.1.0) ↩ ↩2
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.2.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.2.0) ↩ ↩2
-
scripts/install-test.sh; scripts/upgrade-note.mjs verify:testExists(scripts/upgrade-note.test.mjs::the upgrade install test runs the note's commands and copies none) verify:ciJob(install-upgrade) ↩ ↩2
-
https://github.com/ourostack/ouro-ui/releases; .github/workflows/release.yml; scripts/release-commit.sh verify:urlOk(https://github.com/ourostack/ouro-ui/releases) verify:fileLine(.github/workflows/release.yml, /scripts/release-commit.sh "$VERSION"/) verify:fileLine(scripts/release-commit.sh, /changes.mjs assemble/) ↩
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.3.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.3.0) verify:fileLine(registry/ouro/theme/ouro-base.css, /--ouro-layer: 50;/) ↩
-
scripts/source-rules.mjs verify:testExists(scripts/source-rules.test.mjs::every istanbul hint in registry/ carries @preserve, so it survives esbuild in an app) ↩
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.3.1 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.3.1) ↩
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.8.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.8.0) verify:testExists(scripts/registry.test.mjs::only ouro-base and ouro-theme touch the app's stylesheet, and no other item installs them) verify:testExists(scripts/registry.test.mjs::each lib helper is its own item, so an item installs only the helpers it imports) ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12
-
registry/ouro/components/ouro/link/link.touch.test.tsx verify:testExists(registry/ouro/components/ouro/link/link.touch.test.tsx::gives a link on its own line a 44px box, centred on its text) ↩
-
test:scripts/registry.test.mjs::devDependencies are named without a version, so the CLI installs it only when the app lacks it and never changes a version the app has verify:testExists(scripts/registry.test.mjs::devDependencies are named without a version, so the CLI installs it only when the app lacks it and never changes a version the app has) ↩
-
registry/ouro/lib/ouro/testing/vitest.ts; https://github.com/ourostack/ouro-ui/releases/tag/v0.8.3 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.8.3) verify:testExists(scripts/testing-kit.test.mjs::page sizes every Playwright host while the touch frame keeps its phone viewport and input) verify:testExists(scripts/testing-kit.test.mjs::ouroTestProjects leaves the page size to Vitest unless the app sets one) verify:fileLine(registry/ouro/lib/ouro/testing/vitest.ts, /390x844/) verify:fileLine(docs/guides/testing.md, /1600/) ↩ ↩2 ↩3 ↩4
-
https://github.com/ourostack/ouro-ui/releases/tag/v1.0.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v1.0.0) ↩ ↩2
-
https://github.com/ourostack/ouro-ui/releases/tag/v1.1.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v1.1.0) verify:fileLine(registry/ouro/theme/ouro-base.css, /--ouro-shadow-sheet-/) verify:fileLine(registry/ouro/theme/ouro-base.css, /--ouro-duration-draw:/) ↩ ↩2
-
test/theme-tokens.test.tsx verify:testExists(test/theme-tokens.test.tsx::standard shadow and font tokens > falls back to the inherited font for headings when the theme names none, and Kbd always keeps it) ↩
-
https://github.com/ourostack/ouro-ui/releases/tag/v1.0.2 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v1.0.2) verify:fileLine(registry/ouro/lib/ouro/form-answer.ts, /Snapshot arrays are readonly/) ↩ ↩2
-
https://github.com/ourostack/ouro-ui/releases/tag/v1.2.2; registry/ouro/components/ouro/button/button.test.tsx; registry/ouro/components/ouro/link/link.test.tsx verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v1.2.2) verify:testExists(registry/ouro/components/ouro/button/button.test.tsx::link branch > uses the document for reloadDocument and downloads, retaining router navigation otherwise) verify:testExists(registry/ouro/components/ouro/link/link.test.tsx::Link > treats only a present download as document navigation, including an empty filename) ↩ ↩2
-
registry/ouro/lib/ouro/portal-container.test.tsx verify:testExists(registry/ouro/lib/ouro/portal-container.test.tsx::usePortalContainer > leaves a popup at the end of , Base UI's default, without a portalContainer) verify:testExists(registry/ouro/lib/ouro/portal-container.test.tsx::usePortalContainer > warns once, in development, when a popup opens outside every landmark of a page that has a main) ↩
-
registry/ouro/lib/ouro/portal-container.test.tsx verify:testExists(registry/ouro/lib/ouro/portal-container.test.tsx::usePortalContainer > gives popups Base UI's own place again inside an OuroProvider whose portalContainer is null, as an app's own dialog needs) ↩
-
registry/ouro/lib/ouro/testing/axe.test.ts verify:testExists(registry/ouro/lib/ouro/testing/axe.test.ts::audit > fails a violation whatever its impact: content outside every landmark is only moderate) ↩
-
scripts/registry.test.mjs verify:testExists(scripts/registry.test.mjs::npm dependencies are pinned to the ranges this repository tests) ↩
-
registry/ouro/components/ouro/toast/toaster.test.tsx verify:testExists(registry/ouro/components/ouro/toast/toaster.test.tsx::Toaster > renders an empty Notifications landmark in a portal, which holds its own live regions) ↩
-
registry/ouro/components/ouro/toast/toaster.test.tsx verify:testExists(registry/ouro/components/ouro/toast/toaster.test.tsx::toast() > keeps every toast, its action and its dismiss button reachable by a screen reader while the stack rests collapsed) ↩
-
registry/ouro/lib/ouro/testing/axe.test.ts verify:testExists(registry/ouro/lib/ouro/testing/axe.test.ts::audit > fails, naming what changed, when its Tab walk closes a popup that focus leaving closes, which it cannot open again) ↩
-
registry/ouro/theme/ouro-base.css verify:fileLine(registry/ouro/theme/ouro-base.css, /--avatar-8:/) verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > picks the same hue for the same name, and spreads names across the hues) ↩
-
registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar shapes and icons > clips a square's picture to its corners) ↩
-
registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar inside a link or button that has its own name > the same link around initials written as text fails the rule, so the check can fail) verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > shows initials from the name, and the name to screen readers) ↩ ↩2
-
https://ui.shadcn.com/docs/cli verify:urlOk(https://ui.shadcn.com/docs/cli) ↩ ↩2
-
https://github.com/shadcn-ui/ui/blob/3502dbcde11d1eaf967a47ac375744dc336641f3/packages/registry/src/utils/updaters/update-css-vars.ts#L91-L124 verify:urlOk(https://github.com/shadcn-ui/ui/blob/3502dbcde11d1eaf967a47ac375744dc336641f3/packages/registry/src/utils/updaters/update-css-vars.ts#L91-L124) verify:testExists(scripts/install-check.test.mjs::a complete install passes, for each variant and stage) ↩
-
UPGRADING.md verify:fileLine(UPGRADING.md, /[ -n "$items" ] || { echo "No Ouro components/) ↩
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.7.0 verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.7.0) ↩
-
scripts/registry.mts verify:fileLine(scripts/registry.mts, /vitest: "4.1.11"/) verify:fileLine(scripts/registry.mts, /playwright: "1.58.1"/) verify:fileLine(scripts/registry.mts, /storybook: "10.2.10"/) ↩
-
https://github.com/ourostack/ouro-ui/releases/tag/v0.2.0; scripts/install-check.mjs verify:urlOk(https://github.com/ourostack/ouro-ui/releases/tag/v0.2.0) verify:testExists(scripts/install-check.test.mjs::a token that refers to itself fails) ↩