English for shadcn/ui Developers

shadcn/ui has changed how many teams think about component libraries, offering copy-paste components built on Radix and Tailwind rather than an installed package. If you work with shadcn/ui on an international team, you’ll need clear English to discuss component ownership, theming, and customisation. This guide covers the core vocabulary for shadcn/ui developers.

Key Vocabulary

Copy-paste component model — the approach where component source code is added directly to your project rather than installed as a versioned dependency. “With the copy-paste component model, we own the Button component’s code outright — there’s no library version to be blocked on upgrading.”

Registry — the collection of component definitions that the shadcn CLI can pull from and add to your project. “We host an internal registry so our design team’s custom components can be added with the same CLI command as the official ones.”

Variant — a predefined visual or behavioural style of a component, typically managed through a utility like class-variance-authority. “The Button component has default, destructive, and outline variants, each mapping to a different set of Tailwind classes.”

Theming tokens — CSS custom properties (variables) that define a design system’s colours, radii, and spacing, allowing global restyling without touching component code. “We override the --primary and --radius tokens in our CSS to reskin every component for our white-label product.”

Composability — the principle that components are built from smaller, unstyled primitives (often Radix) that can be recombined and customised freely. “Because the Dialog component is composable, we could add a custom footer without forking the entire component.”

Slot / asChild — a pattern that lets a component render as a different underlying element while keeping its behaviour, commonly used to make a Button render as a link. “We used asChild to make the Button component render as a Next.js Link, so it gets the button styling but behaves like client-side navigation.”

CLI (component installer) — the command-line tool used to add shadcn/ui components, and their dependencies, into a project’s source tree. “Running the CLI’s add dialog command dropped the Dialog component’s source directly into our components/ui folder.”

Ownership — the concept that once a component is added to your codebase, your team is responsible for maintaining and updating it, not an external package maintainer. “Since we own the component code, updating it to fix an accessibility issue didn’t require waiting on an upstream release.”

Discussing Customisation and Theming

• “We didn’t fork the Button component — we just added a new variant for our brand’s secondary call-to-action style.”
• “Switching our theme from light to dark mode is just a matter of swapping the CSS variable values, not touching component logic.”
• “Because we own the code, we removed a dependency the default component pulled in that we didn’t need.”

Talking About Trade-offs

• “The trade-off with copy-paste components is that we don’t get automatic upstream bug fixes — we have to track updates manually.”
• “Owning the components gave us full control to meet our accessibility requirements without waiting on an external maintainer.”
• “We keep a changelog of any component we’ve modified from the original, so future contributors know what diverged and why.”

Professional Tips

1. Explain the ownership trade-off explicitly in onboarding docs. New developers used to npm-installed libraries often assume components auto-update — they don’t.
2. Document any modifications to the original component source. This prevents confusion when comparing your codebase to shadcn/ui’s public documentation.
3. Use theming tokens instead of hardcoded values when customising. It keeps rebranding or dark-mode support centralised and easy to reason about.

Practice Exercise

1. Explain to a new teammate, in 3-4 sentences, how the copy-paste component model differs from installing a component library via npm.
2. Write a short explanation (4-5 sentences) of why your team chose to add a custom variant rather than forking a component entirely.
3. Describe, in plain English, a situation where owning the component code let you fix a bug faster than waiting for an upstream release.