opsinjs
Migrating from shadcn/ui
What maps one to one from shadcn/ui, what changes, and the order to move things in.
The registry mechanism, code ownership, cn() and Tailwind all carry over, and both registries install side by side under their own namespaces. Three things change.
- Radix becomes Base UI, so
asChildbecomesrender. See Styling. variantsplits in two.categorysays what a reading is about andstatussays how urgent it is, and they never mix. See Two colour axes.destructivehas no equivalent, because nothing about a person's reading is destructive.
Components
| shadcn/ui | opsinjs | Note |
|---|---|---|
Alert | AlertBanner | Takes status, not variant |
Badge | StatusPill | Status only. A neutral label is Badge |
Card, Dialog, Sheet, Skeleton, Button, Toast | Card, Dialog, Sheet, Skeleton, Button, Toast | Same role |
Form and FormField | Field | Library-agnostic. See Forms |
Progress | Progress | Same role. RangeBar is a different component |
Props and attributes
| shadcn/ui | opsinjs |
|---|---|
asChild and a single child | render={<element />} |
variant="destructive" | status="urgent", only where a clinical status genuinely applies |
variant="secondary" as a category tint | category="sleep" |
data-state="open" and data-state="closed" | data-open and data-closed |
Entry and exit animation on data-state | data-starting-style and data-ending-style |
Tokens
opsinjs components use shadcn role utilities such as bg-card and border-border, so your role variables still reach them. To adopt the opsinjs values, point each role at its token.
| shadcn/ui role | Point it at |
|---|---|
--background, --foreground | --opsin-chrome-background, --opsin-chrome-foreground |
--muted, --muted-foreground | --opsin-chrome-muted, --opsin-chrome-muted-foreground |
--border | --opsin-chrome-border |
--destructive | Nothing. --opsin-status-urgent-* is for a clinical status only |
--opsin-status-<level>-* and --opsin-category-<name>-* have no shadcn counterpart. Names may change before 1.0, and Tokens lists every one.
Order of work
- Add the
@opsinjsentry and the token layer from Getting started, keeping shadcn/ui installed. - Re-check contrast, because your shadcn values were never measured against the opsinjs floor. See Theming.
- Migrate screens that show a health value first, a whole screen at a time.
- Rewrite each
variantby hand as identity or severity. One that meant both was a bug. - Move overlays as a group, because Radix and Base UI focus management can fight on one screen.
- Commit the files
shadcn addwrites in their own commit. Nothing in a copied file says which system it came from.
Pitfalls
- Keeping
variantbesidestatuson your own wrappers. That is how the axes get mixed. - Running two theme providers. opsinjs adds none, because its theme is a class on
<html>. - Porting
globals.csswholesale. The import order differs, and it is load-bearing. - Swapping
asChildforrenderby find and replace.rendertakes an element, so the result type-checks and renders one element too many. - Expecting
--radiusto set the shape. opsinjs derives a radius ladder and usescorner-shapewhere supported. See Shape.