---

name: shadcn-component-adaptation description: Use when adding a shadcn/ui component to a project that has an opinionated design system, so the copied component matches the system instead of the shadcn defaults. Covers install, adaptation, and consistency.

shadcn Component Adaptation

When to trigger

Adding a button, dialog, dropdown, or any shadcn/ui component to a codebase with an established visual contract (specific radius, palette, borders, no gradients).

Why adapt, not just install

shadcn copies component source into your repo. That is the feature: you own it and edit it. The defaults (rounded corners, a specific ring color, subtle gradients) are opinions that will clash with a strict system. Reconcile them on install, not later.

Steps

1. Install one component at a time: npx shadcn@latest add button. Serialize installs; only one process should own package.json at a time or the lockfile races.
2. Open the copied file and reconcile it with the system contract before using it:
   • Corners: if the system is square, remove rounded-* classes or set the radius token to 0.
   • Color: replace default palette utilities with the system tokens.
   • Gradients and shadows: strip any bg-gradient-* or heavy shadow the system forbids.
3. Keep the accessibility wiring intact: the asChild pattern, focus-visible rings, aria attributes, and keyboard handlers. Adapt the look, not the behavior.
4. Standardize variants once. Edit the cva variant map so every usage pulls from the same source instead of one-off overrides at call sites.

Pitfalls

• Overriding styles inline at each call site instead of fixing the component leads to drift. Fix it once in the component file.
• Deleting the focus-visible ring to match a design removes keyboard accessibility. Restyle the ring, do not remove it.
• Running two shadcn add commands in parallel corrupts components.json or the lockfile. Serialize them.