Component-Library Adopter (shadcn-first) — refactor-chain · do-the-work (UI)

Bundle: refactor-chain (self-diagnosing, self-healing fix-it pipeline). Phase: do-the-work (UI lane) · Prerequisite: refactor-ui-tokens (and the visual/mobile pass) · Next: refactor-ui-a11y → refactor-code-principles. Adaptivity / conditional: activates on web UIs with bespoke primitives. shadcn/ui is the default registry; may use the shadcn MCP (mcp__Shadcn_UI__*) when connected to list/fetch components, blocks, and themes.

Purpose

Stop hand-rolling UI primitives. Replace bespoke buttons, inputs, dropdowns, dialogs, tabs, and the like with battle-tested registry components — shadcn/ui first — that already handle focus, keyboard, ARIA, and edge cases you'd otherwise reinvent (usually badly). Wire the registry's theme to the design tokens from refactor-ui-tokens so the adopted components look like your app, and keep every behavior identical so nothing the user does changes. This also covers the web-artifact pattern set: composing pages from registry blocks instead of one-off markup.

When to use

• Trigger phrases: "adopt shadcn/ui", "use a real component library", "replace our custom components", "stop reinventing buttons/modals/dropdowns", "standardize our components", "build this from shadcn blocks", "these hand-made primitives are inconsistent".
• After tokens and the visual/mobile pass exist, so the registry theme can be wired to real tokens.
• When the diagnostic pass flags many divergent copies of the same primitive.