ShadCN with Tailwind

Install shadcn/ui components that follow Strongtie design standards for maximum flexibility and control.

This is the recommended approach for new React applications. You own the component code, customize freely, and get the full shadcn/ui experience with Strongtie branding.

Why this approach? Components are copied into your project, not installed as dependencies. You own the code and never worry about breaking changes from package updates.

What You Get

Component ownership - Code lives in your project, fully customizable
Tree-shaking - Only ship what you use
Accessibility - Built on Radix UI (or Base-UI) primitives
TypeScript - Full type safety
AI-Native - All major AI assistants know shadcn natively

Quick Start (Recommended)

The fastest way to get started is using shadcn's preset feature:


npx shadcn@latest create --preset "https://ui.shadcn.com/init?base=radix&style=vega&baseColor=neutral&theme=neutral&iconLibrary=lucide&font=inter&menuAccent=subtle&menuColor=default&radius=default&template=vite" --template vite

This creates a new Vite + React project with Strongtie design standards pre-configured.

Already have a project? Follow the manual setup steps below.

Manual Setup

Follow the guide from shadcn

Start using components

Add components using the shadcn CLI:


npx shadcn@latest add button card dialog

Components are copied to your components/ui/ directory where you can customize them.

Best Practice: When adding custom functionality, create abstracted components instead of editing shadcn components directly. For example, if you need a button with custom props, create components/custom-button.tsx that wraps components/ui/button.tsx. This keeps shadcn components pristine and makes updates easier.

AI-Native Development

All major AI coding assistants (Claude, ChatGPT, Cursor, etc.) have native knowledge of shadcn/ui. Just ask "use shadcn to add a button" and they know exactly what to do. Plus, with the shadcn MCP server available, AI agents can directly add and modify components in your project—making UI development faster and more intuitive than ever.

Radix UI vs Base-UI

shadcn/ui supports two UI primitive libraries:

Radix UI (Default)

Extensive documentation
Large community
Widely adopted
Multiple packages

Base-UI

Single package
Lighter bundle
From MUI team
Growing community

To use Base-UI instead:


npx shadcn@latest create --preset "https://ui.shadcn.com/init?base=base&style=vega&baseColor=neutral&theme=neutral&iconLibrary=lucide&font=inter&menuAccent=subtle&menuColor=default&radius=default&template=vite" --template vite

Both produce the same visual output. The difference is the underlying accessibility primitives.

Customizing Components

Since you own the code, modify components directly:

components/ui/button.tsx

// Add custom variants to match your needs
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-all",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-white hover:bg-destructive/90",
        outline: "border bg-background hover:bg-accent",
        secondary:
          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
        // Add your own
        brand: "bg-orange-500 text-white hover:bg-orange-600",
      },
      // ...
    },
  }
)

When to Use Custom CSS

Tailwind CSS handles nearly all styling needs, but custom CSS is acceptable on a case-by-case basis when Tailwind lacks native utilities.

When custom CSS may be appropriate:

Complex keyframe animations not achievable with Tailwind's animation utilities
Print styles (@media print) with specific requirements
Targeting specific pseudo-elements Tailwind doesn't cover

Requirements for custom CSS:

Use Tailwind CSS variables for all values (var(--spacing), var(--primary), etc.) to maintain theme compatibility
Add a comment explaining why custom CSS is necessary
Evaluate case-by-case — Tailwind should remain the primary styling approach

This is not blanket permission to write custom CSS. Each case should be evaluated to ensure Tailwind utilities or plugins cannot accomplish the same result.

See the Design Standards FAQ for detailed guidance.

Troubleshooting

Components don't match expected styling

Ensure your CSS variables match the example above. shadcn components rely on variables like --background, --foreground, --primary, etc.

TypeScript errors after adding components

Restart your TypeScript server: Cmd/Ctrl + Shift + P > "TypeScript: Restart TS Server"
Verify path aliases in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Tailwind classes not applying

Verify globals.css is imported in your root layout
Check content paths in your Tailwind config
Restart your dev server

Next Steps

Installing the @strongtie/design-system Package Strongtie Registry

On This Page

What You Get Quick Start (Recommended)Manual Setup AI-Native Development Radix UI vs Base-UI Customizing Components When to Use Custom CSS Troubleshooting Components don't match expected styling TypeScript errors after adding components Tailwind classes not applying Next Steps

Contribute