Switching from shadcn

Both live in one app

shadcn/ui installs to components/ui/. Ouro HX installs to components/ouro/, so a shadcn button and an Ouro button never collide.^beside Switch a screen at a time, and remove the shadcn file when nothing imports it any more.

Ouro components read shadcn's variables (--primary, --muted-foreground, --radius and the rest), so your theme carries over unchanged. Dark mode is the same .dark class. Ouro HX adds only what shadcn themes lack, in ouro-base.css: --success and --warning with their foregrounds, --destructive-foreground, the motion tokens, and --ouro-layer, the z-index of sheets and dialogs (50, as in the Base UI dialog of shadcn@4.21.1; raise it if your app has fixed bars above z-50).^layer To change any --ouro-* token, such as --ouro-layer, --ouro-press-scale or --ouro-backdrop-max, set it in a :root (or .dark) rule of your own after the Ouro tokens, outside any @layer. Don't edit the lines shadcn wrote: every shadcn add of an Ouro item rewrites them. The Ouro look (ouro-theme) is optional; skip it to keep yours.

Components

Button

Ouro HX: Button

Same name; the props differ (below).

Dialog with DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter

Ouro HX: Dialog with trigger, title, description and footer

Becomes a bottom sheet below 640px.^dialog-sheet Parts exist for layouts the props can't express.

Sheet with SheetTrigger, SheetContent, SheetHeader, SheetTitle

Ouro HX: Sheet with trigger, side and title

Dragged back to its edge to dismiss.

Drawer

Ouro HX: Sheet with snapPoints

snapPoints={[0.5, 1]} opens at half height.

AlertDialog

Ouro HX: ConfirmDialog

Cancel has focus first; an outside press doesn't dismiss it.

Classes on <h1> to <h6>

Ouro HX: Heading with level and size

level sets the tag; size only the look.

Classes on <p> (text-sm text-muted-foreground)

Ouro HX: Text with size and tone

<Text size="sm" tone="muted">

Button props

variant="default"

Ouro HX: The default: <Button>

variant="destructive"

Ouro HX: tone="destructive"

variant="secondary"

Ouro HX: tone="secondary"

variant="outline"

Ouro HX: variant="outline" tone="secondary"

variant="ghost"

Ouro HX: variant="plain", with tone="secondary" for foreground-colored text

variant="link"

Ouro HX: variant="plain" with href

size="default"

Ouro HX: size="md", the default

asChild around a link

Ouro HX: href, which renders a link (internal paths go through OuroProvider's linkComponent)

disabled while saving

Ouro HX: loading, which also shows a spinner and keeps focus

An icon as a child

Ouro HX: startIcon={Icon} or endIcon={Icon}

className="w-full"

Ouro HX: fullWidth

Appearance classes (bg-red-500)

Ouro HX: tone, variant and size; className is for layout

Dialog and Sheet props

open and onOpenChange

Ouro HX: The same

<DialogTrigger asChild> around a button

Ouro HX: trigger={<Button>Edit</Button>}

<DialogTitle>

Ouro HX: title, required (hideTitle hides it visually)

<DialogDescription>

Ouro HX: description

<DialogFooter>

Ouro HX: footer, primary action last

<SheetContent side="right">

Ouro HX: <Sheet side="right">

AlertDialog to ConfirmDialog

<AlertDialogTitle>

Ouro HX: title, the question

<AlertDialogDescription>

Ouro HX: description

<AlertDialogAction onClick={…}>Delete</AlertDialogAction>

Ouro HX: confirmLabel="Delete" and onConfirm; return a promise to show progress

<AlertDialogCancel>

Ouro HX: cancelLabel, "Cancel" by default

A destructive class on the action

Ouro HX: tone="destructive"

If you miss one

Shadcn's prop names that Ouro HX doesn't use, and its Button variant and size values, fail the type check, and the error names the Ouro prop to use. In development, Button's console message names the fix for each guard prop and each shadcn variant and size:^{button-guards}

<Button variant="destructive">Delete</Button>

[ouro-ui] Button: variant="destructive" is not a variant. Fix: <Button tone="destructive">.