Building a Scalable Design System with ShadCN, TypeScript & Tailwind

Stop copying generic components. Learn how to extend ShadCN to build a unique, maintainable design system for your brand.

zahid ansari

Building scalable systems by applying mental models to code and architecture.

General

Website

Resources

Install this app to stay connected and in the loop.

Building meaningful experiences one pixel at a time 😉.

Made with by Zahid

views

Scalable Design System with ShadCN UI

ShadCN UI took the React world by storm because it's not a library—it's copy-paste code you own. But how do you maintain consistency as your app grows?

The Problem I Faced

In a team setting, everyone started modifying the base ShadCN components differently. We had 5 different button styles and inconsistent spacing. We needed a centralized token system.

Understanding Customization

Since ShadCN uses Tailwind, we manage our design tokens (colors, radius, spacing) in

tailwind.config.js

and our CSS variables.

Code Example 1: extending the Theme

Don't hardcode hex values in components. Use semantic names.

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef2f2',
          500: '#ef4444', // Our primary red
          900: '#7f1d1d',
        }
      }
    }
  }
}

Code Example 2: Type-Safe Reusable Component

Wrapping a base component to enforce brand guidelines.

import { ButtonString } from '@/components/ui/button';
import { cn } from '@/lib/utils';

interface ActionButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'ghost'; // Restrict to only brand-approved variants
}

export const ActionButton = ({ className, variant = 'primary', ...props }: ActionButtonProps) => {
  return (
    <ButtonString
      className={cn(
        "uppercase tracking-widest font-bold", // Brand override
        variant === 'primary' && "bg-brand-500 hover:bg-brand-900",
        className
      )}
      {...props}
    />
  );
};

Common Pitfalls

Mistake 1: Editing the component library files directly for one-off changes.
- Don't: Change
  1components/ui/button.tsx
  for a single unique marketing button.
- Do: Pass
  1className
  props or create a wrapper component.

Pro Tips

Variables: Use CSS variables for colors (e.g.,
1--primary
) so implementing Dark Mode is just swapping variable values, not class names.
Storybook: If specific documentation is needed, Storybook pairs well, but for smaller teams, a messy
1/design
page showing all components is enough.

Wrapping Up

ShadCN gives you a head start, but your discipline with Tailwind config and TypeScript interfaces makes it a system.

Tech Stack: ShadCN, TailwindCSS, TypeScript