How should shadcn-ui be structured in a large-scale production design system?

[xqbuilds12]

Hi everyone,

I’m using shadcn-ui in a growing production app and I want to structure it properly as a scalable design system.

I’d like guidance on:

→ Should components be wrapped instead of modified directly?
→ Where should shared variants (like buttonVariants) live?
→ How do teams handle global theming without breaking future updates?
→ What folder structure works best for large apps?

Looking for real-world best practices from teams using shadcn-ui at scale.

Thanks!

[Om-singh-ui]

The safest way to customize shadcn-ui components in production is to treat them as your internal design system — not as a dependency you modify directly.

Since shadcn-ui copies components into your project, you have full control. But to keep things maintainable:

1. Prefer wrapping over editing core logic.

Instead of heavily modifying the original component file, create wrapper components:

// components/ui/custom-button.tsx
import { Button } from "@/components/ui/button"

export function PrimaryButton(props) {
  return (
    <Button
      className="bg-blue-600 hover:bg-blue-700 text-white"
      {...props}
    />
  )
}

This keeps upstream structure intact.

2. Use variants properly.

If a component exposes buttonVariants, extend it instead of rewriting styles. This keeps consistency across the app.

3. Avoid changing base component APIs.

Try not to rename props or alter internal logic unless absolutely necessary. Keep modifications stylistic when possible.

4. Track upstream changes manually.

Since components are copied, future updates won’t apply automatically. Periodically check the official repo changelog and compare diffs before upgrading.

5. Keep components organized by feature or design layer.

In large apps, consider:

/components
  /ui (base shadcn components)
  /design-system (custom wrappers & variants)

This separation prevents mixing upstream code with product-specific logic.

In production, this approach:

• Keeps upgrades manageable
• Reduces merge conflicts
• Maintains consistency
• Avoids breaking future updates