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.

Using with @strongtie/design-system

If your project uses @strongtie/design-system as a package dependency (rather than copying components via the shadcn CLI), you need to import the design system's styles. The approach depends on whether your app already has its own Tailwind CSS setup.

Next.js and Existing Tailwind Apps (Recommended)

For Next.js applications or any project that already imports Tailwind CSS, use the modular imports. This avoids duplicate Tailwind output and works correctly with Turbopack's lightningCSS processor.

In your globals.css:

/* 1. SST fonts and design tokens (pre-compiled, no Tailwind directives) */
@import "@strongtie/design-system/styles/tokens";
/* 2. Tailwind CSS — single source of utility classes */
@import "tailwindcss";
/* 3. Design system theme — must come AFTER tailwindcss */
@import "@strongtie/design-system/styles/theme";
/* 4. Animations (optional) */
@import "tw-animate-css";
 
/* Tell Tailwind to scan your app AND design system components */
@source "../app";
@source "../components";
@source "../node_modules/@strongtie/design-system/dist";
 
/* Map SST font to Tailwind's font-sans utility */
@theme {
  --font-sans: var(--font-family);
}

What each import provides:

./styles/tokens — SST font-face declarations and design token CSS custom properties (--space-*, --font-size-*, etc.)
./styles/theme — CSS custom properties for light/dark modes, @theme inline mappings for Tailwind utilities (bg-primary, text-foreground, etc.), @custom-variant dark, and @layer base rules

The @source directive for the design system dist is required. Without it, Tailwind won't generate utility classes used by design system components and they will render unstyled.

Why not ./styles? The monolithic ./styles export includes its own @import "tailwindcss" which conflicts with your app's Tailwind setup. The modular imports let your app own the single Tailwind framework import.

Apps Without Tailwind

For projects that don't have their own Tailwind CSS setup, use the monolithic import:

@import "@strongtie/design-system/styles";

This includes everything: Tailwind CSS, SST fonts, design tokens, theme configuration, and base styles. No @source directive is needed since Tailwind is bundled within the import.

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 Using with @strongtie/design-system Next.js and Existing Tailwind Apps (Recommended)Apps Without Tailwind 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