shadcn/ui component maintenance

Purpose: Tracks the installed shadcn/ui component inventory and defines the process for checking updates, adding new components, and handling customizations.

Process for keeping shadcn/ui components in sync with upstream.

---

Current state

shadcn/ui version: Uses shadcn@latest CLI (no locked version) Radix UI: Using unified radix-ui@1.4.3 package (not scoped @radix-ui/react-*) Style: new-york Components: 31 installed Last checked: 2026-02-26

---

Component inventory

Component	Status	Customized	Notes
avatar	Stock	No
badge	Stock	No
breadcrumb	Stock	No
button	Stock	No
calendar	Stock	No
card	Stock	No
chart	Stock	No
checkbox	Stock	No
collapsible	Stock	No
command	Stock	No
dialog	Stock	No
dropdown-menu	Stock	No
input	Stock	No
label	Stock	No
pagination	Stock	No
popover	Stock	No
progress	Stock	No
radio-group	Stock	No
scroll-area	Stock	No
sonner	Stock	No	Theme-aware toast wrapper — always use instead of raw sonner
select	Stock	No
separator	Stock	No
sheet	Stock	No
sidebar	Stock	No
skeleton	Stock	No
switch	Stock	No
table	Stock	No
tabs	Stock	No
textarea	Stock	No
toggle	Stock	No
tooltip	Stock	No

Status values:

• Stock — Unmodified from shadcn/ui upstream
• Customized — Intentionally modified, do not overwrite
• Extended — Added functionality but base is compatible

---

Maintenance commands

Check for updates

cd tools/prototype-scaffold
pnpm dlx shadcn@latest diff

This compares local components against upstream and shows diffs.

Update a stock component

For components marked "Stock" (not customized):

cd tools/prototype-scaffold
pnpm dlx shadcn@latest add <component> --overwrite

Add a new component

cd tools/prototype-scaffold
pnpm dlx shadcn@latest add <component>

Then update this inventory table.

---

Radix UI package

The scaffold uses the unified radix-ui package (not scoped @radix-ui/react-* packages). This is valid and matches how shadcn/ui generates components as of late 2024.

Imports look like:

import { Dialog as DialogPrimitive } from "radix-ui"
import { Slot } from "radix-ui"

Not:

import * as DialogPrimitive from "@radix-ui/react-dialog"
import { Slot } from "@radix-ui/react-slot"

Both patterns work, but the unified package simplifies dependency management.

---

Automated sync

The GitHub Action at .github/workflows/upstream-sync-check.yml can be extended to run shadcn diff weekly. Currently, it only checks theme presets and admin dashboard version.

To add shadcn component checking:

1. Create script — Runs pnpm dlx shadcn@latest diff and captures output
2. Add to workflow matrix
3. Open PR — If diff output is non-empty

This is deferred until component drift becomes a real problem.

---

When to update components

Do update when:

• Security fix — Exists in upstream
• Bug fix — Affects your use case
• Accessibility improvement — Available upstream
• Breaking change — Needs adoption

Don't update when:

• Cosmetic only — Changes are purely cosmetic and unnecessary
• Customized component — Mark as "Customized" in inventory
• Theme breakage — The update would break your theming

---

Customization guidelines

If you need to customize a component:

1. Update inventory table — Change status from "Stock" to "Customized"
2. Add file comment — Explaining the customization at the top of the file:

   // CUSTOMIZED: Added support for loading state (2026-02-26)
   

3. Document the reason — In the Notes column
4. Consider extending instead — If possible, wrap the stock component rather than modifying it

---

Related

• shadcn/ui docs — https://ui.shadcn.com
• Radix UI docs — https://radix-ui.com
• Theme system — standards/reference/themes.md
• Script maintenance — tools/scripts/README.md

---

Last updated: 2026-02-26