Tailwind CSS & shadcn/ui Design System

Overview

Expert guide for creating and managing a centralized Design System using Tailwind CSS (v4.1+) and shadcn/ui. This skill provides structured workflows for defining design tokens, configuring themes with CSS variables, and building a consistent UI component library based on shadcn/ui primitives.

Relationship with other skills:

• tailwind-css-patterns covers utility-first styling, responsive design, and general Tailwind CSS usage
• shadcn-ui covers individual component installation, configuration, and implementation
• This skill focuses on the system-level orchestration: design tokens, theming infrastructure, component wrapping patterns, and ensuring consistency across the entire application

When to Use

• Setting up a new design system from scratch with Tailwind CSS and shadcn/ui
• Defining design tokens (colors, typography, spacing, radius, shadows) as CSS variables
• Configuring globals.css with a centralized theming system (light/dark mode)
• Wrapping shadcn/ui components into design system primitives with enforced constraints
• Building a token-driven component library for consistent UI
• Migrating from a JavaScript-based Tailwind config to CSS-first configuration (v4.1+)
• Establishing color palettes with oklch format for perceptual uniformity
• Creating multi-theme support beyond light/dark (e.g., brand themes)

Instructions

Step 1: Initialize Design System Configuration

Run these commands to set up the project:

# Check if Tailwind is installed
npx tailwindcss --version

# For Tailwind v4 (recommended)
npx @tailwindcss/vite@latest init   # or: npm install -D tailwindcss @tailwindcss/vite

# Initialize shadcn/ui CLI
npx shadcn@latest init

# Install core shadcn/ui components
npx shadcn@latest add button card input -y

Validation checkpoint: After setup, verify with:

ls src/components/ui/        # Should list installed components
cat src/app/globals.css       # Should contain @tailwind directives

Step 2: Define Design Tokens

Create src/app/globals.css with your design tokens:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* Brand Colors */
    --primary: oklch(0.55 0.18 250);
    --primary-foreground: oklch(0.985 0 0);

    /* Semantic Colors */
    --background: oklch(0.99 0 0);
    --foreground: oklch(0.15 0 0);
    --secondary: oklch(0.96 0.01 250);
    --secondary-foreground: oklch(0.20 0 0);

    /* Validation: all colors must have foreground pair */
    --destructive: oklch(0.55 0.22 25);
    --destructive-foreground: oklch(0.985 0 0);
  }

  .dark {
    --primary: oklch(0.65 0.20 250);
    --background: oklch(0.14 0 0);
    --foreground: oklch(0.97 0 0);
    --secondary: oklch(0.25 0.02 250);
  }
}

Validation checkpoint: Verify tokens are valid CSS:

grep -E "^[[:space:]]*--[a-z-]+:" src/app/globals.css | wc -l
# Should return count of defined tokens (e.g., 10+)

Step 3: Configure Theming Infrastructure

Bridge CSS variables to Tailwind utilities (Tailwind v4.1+):

@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

Add dark mode class toggle in components/providers/theme-provider.tsx:

import { useEffect } from "react";
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    document.documentElement.classList.toggle("dark", isDark);
  }, []);
  return <>{children}</>;
}

Validation checkpoint: Test dark mode:

document.documentElement.classList.contains("dark") // in browser console

Step 4: Wrap shadcn/ui Components

Create src/components/ds/Button.tsx:

import { Button as ShadcnButton } from "@/components/ui/button";

type DSVariant = "primary" | "secondary" | "destructive" | "ghost";
const variantMap: Record<DSVariant, "default" | "secondary" | "destructive" | "ghost"> = {
  primary: "default", secondary: "secondary",
  destructive: "destructive", ghost: "ghost",
};

export function Button({ variant = "primary", ...props }: { variant?: DSVariant } & React.ComponentProps<typeof ShadcnButton>) {
  return <ShadcnButton variant={variantMap[variant]} {...props} />;
}

Validation checkpoint: Verify build passes:

npx tsc --noEmit src/components/ds/Button.tsx

Step 5: Validate and Document

Run the token validation script:

REQUIRED=("primary" "primary-foreground" "background" "foreground" "secondary" "secondary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/app/globals.css || echo "MISSING: --$token"
done

Validation checkpoint: Ensure all shadcn components use DS tokens:

grep -r "bg-primary\|text-primary\|bg-background" src/components/ds/

Examples

Adding Custom Tokens

Extend the base tokens in globals.css:

:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(