Tailwind Design System

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(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

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

Usage: <div className="bg-warning text-warning-foreground">Warning</div>

Wrapping shadcn/ui Components as Design System Primitives

See references/component-wrapping.md for complete examples including Button, Text, and Stack primitives with full TypeScript types.

Create constrained design system components that enforce token usage. Inline example:

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

export function Button({ variant = "primary", size = "md", ...props }) {
  const variantMap = { primary: "default", secondary: "secondary" };
  const sizeMap = { sm: "sm", md: "default", lg: "lg" };
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      {...props}
    />
  );
}

Multi-Theme Support

For applications requiring multiple brand themes beyond light/dark:

[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --primary-foreground: oklch(0.985 0 0);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --primary-foreground: oklch(0.985 0 0);
}

const [theme, setTheme] = useState("light");
useEffect(() => {
  document.documentElement.setAttribute("data-theme", theme);
}, [theme]);

Design Token Validation

Verify all required tokens are defined:

#!/bin/bash
REQUIRED=("--background" "--foreground" "--primary" "--primary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/styles/globals.css || echo "Missing: $token"
done

Constraints and Warnings

• oklch color format: Use oklch for perceptual uniformity. Not all browsers support oklch natively; check compatibility if targeting older browsers
• Token naming: Follow the shadcn/ui convention (--primary, --primary-foreground) for seamless integration
• `@`theme inline vs `@`theme: Use @theme inline when bridging CSS variables to Tailwind utilities; use @theme for direct token definition
• Component wrapping: Keep wrapper components thin. Only add constraints that enforce design system rules; avoid duplicating shadcn/ui logic
• Dark mode: Always define dark mode values for every token in :root. Missing dark tokens cause visual regressions
• CSS variable scoping: Tokens defined in :root are global. Use [data-theme] selectors for multi-theme without conflicts
• Performance: Avoid excessive CSS custom property chains. Each var() lookup adds minimal but non-zero overhead
• Tailwind v4 vs v3: The @theme directive and @theme inline are v4.1+ features. For v3 projects, use tailwind.config.js with theme.extend

Best Practices

1. Single source of truth: All design tokens live in globals.css. Never hardcode color values in components 2. Semantic naming: Use purpose-based names (--primary, --destructive) not appearance-based (--blue-500, --red-600) 3. Foreground pairing: Every background token must have a matching -foreground token for contrast compliance 4. Token scale: Define a complete scale for custom palettes (50-950) to provide flexibility 5. Component barrel exports: Export all DS components from a single index.ts for clean imports 6. Accessibility: Ensure all token pairs (background/foreground) meet WCAG AA contrast (4.5:1 for text, 3:1 for large text) 7. Document tokens: Maintain a visual reference of all tokens for the team 8. Consistent spacing: Use Tailwind's spacing scale (gap-2, gap-4, gap-6) through DS components rather than arbitrary values

References

• Tailwind CSS v4 Theme Configuration: https://tailwindcss.com/docs/theme
• Tailwind CSS Functions and Directives: https://tailwindcss.com/docs/functions-and-directives
• shadcn/ui Theming Guide: https://ui.shadcn.com/docs/theming
• shadcn/ui Installation (Manual): https://ui.shadcn.com/docs/installation/manual
• oklch Color Space: https://oklch.com

Wrapping shadcn/ui Components as Design System Primitives

This guide shows how to wrap shadcn/ui components into design system primitives that enforce token usage and provide consistent API.

Button Component

// components/ds/Button.tsx
import { Button as ShadcnButton, type ButtonProps } from "@/components/ui/button";
import { cn } from "@/lib/utils";

type DSButtonVariant = "primary" | "secondary" | "destructive" | "ghost" | "outline";
type DSButtonSize = "sm" | "md" | "lg";

interface DSButtonProps extends Omit<ButtonProps, "variant" | "size"> {
  variant?: DSButtonVariant;
  size?: DSButtonSize;
}

const variantMap: Record<DSButtonVariant, ButtonProps["variant"]> = {
  primary: "default",
  secondary: "secondary",
  destructive: "destructive",
  ghost: "ghost",
  outline: "outline",
};

const sizeMap: Record<DSButtonSize, ButtonProps["size"]> = {
  sm: "sm",
  md: "default",
  lg: "lg",
};

export function Button({ variant = "primary", size = "md", className, ...props }: DSButtonProps) {
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      className={cn("font-medium transition-colors", className)}
      {...props}
    />
  );
}

Typography Component

// components/ds/Text.tsx
import { cn } from "@/lib/utils";

type TextVariant = "h1" | "h2" | "h3" | "h4" | "body" | "body-sm" | "caption" | "overline";

interface TextProps {
  variant?: TextVariant;
  as?: keyof JSX.IntrinsicElements;
  className?: string;
  children: React.ReactNode;
}

const variantStyles: Record<TextVariant, string> = {
  h1: "text-4xl font-bold tracking-tight",
  h2: "text-3xl font-semibold tracking-tight",
  h3: "text-2xl font-semibold",
  h4: "text-xl font-medium",
  body: "text-base leading-relaxed",
  "body-sm": "text-sm leading-relaxed",
  caption: "text-xs text-muted-foreground",
  overline: "text-xs font-semibold uppercase tracking-widest text-muted-foreground",
};

const defaultElements: Record<TextVariant, keyof JSX.IntrinsicElements> = {
  h1: "h1",
  h2: "h2",
  h3: "h3",
  h4: "h4",
  body: "p",
  "body-sm": "p",
  caption: "span",
  overline: "span",
};

export function Text({ variant = "body", as, className, children }: TextProps) {
  const Component = as || defaultElements[variant];
  return <Component className={cn(variantStyles[variant], className)}>{children}</Component>;
}

Stack Layout Component

// components/ds/Stack.tsx
import { cn } from "@/lib/utils";

type StackSpacing = "xs" | "sm" | "md" | "lg" | "xl";

interface StackProps {
  direction?: "row" | "column";
  spacing?: StackSpacing;
  align?: "start" | "center" | "end" | "stretch";
  justify?: "start" | "center" | "end" | "between" | "around";
  className?: string;
  children: React.ReactNode;
}

const spacingMap: Record<StackSpacing, string> = {
  xs: "gap-1",
  sm: "gap-2",
  md: "gap-4",
  lg: "gap-6",
  xl: "gap-8",
};

export function Stack({
  direction = "column",
  spacing = "md",
  align = "stretch",
  justify = "start",
  className,
  children,
}: StackProps) {
  return (
    <div
      className={cn(
        "flex",
        direction === "row" ? "flex-row" : "flex-col",
        spacingMap[spacing],
        `items-${align}`,
        `justify-${justify}`,
        className
      )}
    >
      {children}
    </div>
  );
}

Barrel Export

// components/ds/index.ts
export { Button } from "./Button";
export { Text } from "./Text";
export { Stack } from "./Stack";

Design System Directory Structure

src/
├── components/
│   ├── ui/                    # Raw shadcn/ui components (auto-generated)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── ...
│   └── ds/                    # Design system primitives (manually curated)
│       ├── Button.tsx         # Wrapped button with DS constraints
│       ├── Text.tsx           # Typography component
│       ├── Stack.tsx          # Layout primitive
│       └── index.ts           # Barrel export
├── styles/
│   └── globals.css            # Design tokens + theme configuration
└── lib/
    └── utils.ts               # cn() helper

Usage Example

import { Button, Text, Stack } from "@/components/ds";

function Hero() {
  return (
    <Stack spacing="lg" align="center" className="py-20">
      <Text variant="h1">Welcome to our Design System</Text>
      <Text variant="body">Consistent, accessible, beautiful UI</Text>
      <Stack direction="row" spacing="md">
        <Button variant="primary" size="lg">Get Started</Button>
        <Button variant="secondary" size="lg">Learn More</Button>
      </Stack>
    </Stack>
  );
}

Design System Theming References

Official Documentation

Tailwind CSS

• Tailwind CSS v4 Theme Configuration
• Tailwind CSS Functions and Directives
• Dark Mode
• Customizing Colors
• Customizing Spacing

shadcn/ui

• Theming Guide
• Installation (Manual)
• Component Documentation
• CLI Documentation

Color Theory

• oklch Color Space - Perceptually uniform color picker
• WCAG Contrast Checker

Design Token Architecture

Semantic Token Naming

--{category}-{variant}-{state}

Examples:
--color-primary-default
--color-primary-hover
--color-primary-disabled
--color-surface-elevated
--color-text-primary
--color-text-secondary
--color-border-subtle

Token Categories

oklch Color Format

Why oklch?

• Perceptually uniform: Same lightness value appears equally light regardless of hue
• Wide gamut: Access to modern display colors (P3)
• Predictable: Changing hue doesn't affect perceived lightness

Format: oklch(L C H)

• L (Lightness): 0 to 1 (0 = black, 1 = white)
• C (Chroma): 0 to ~0.4 (saturation/intensity)
• H (Hue): 0 to 360 degrees

Common Color Values

/* Grays */
--gray-50:  oklch(0.985 0 0);
--gray-100: oklch(0.967 0 0);
--gray-200: oklch(0.92 0 0);
--gray-300: oklch(0.87 0 0);
--gray-400: oklch(0.70 0 0);
--gray-500: oklch(0.56 0 0);
--gray-600: oklch(0.44 0 0);
--gray-700: oklch(0.37 0 0);
--gray-800: oklch(0.27 0 0);
--gray-900: oklch(0.20 0 0);
--gray-950: oklch(0.14 0 0);

/* Blue */
--blue-500: oklch(0.58 0.19 250);

/* Red */
--red-500:  oklch(0.58 0.25 25);

/* Green */
--green-500: oklch(0.62 0.17 145);

/* Yellow */
--yellow-500: oklch(0.84 0.16 84);

CSS Variable Strategy

Layered Tokens

/* 1. Primitive/Raw values */
:root {
  --color-blue-50: oklch(0.97 0.01 250);
  --color-blue-500: oklch(0.58 0.19 250);
  --color-blue-900: oklch(0.27 0.08 250);
}

/* 2. Semantic mapping */
:root {
  --color-primary: var(--color-blue-500);
  --color-primary-light: var(--color-blue-50);
  --color-primary-dark: var(--color-blue-900);
}

/* 3. Component-specific (rarely needed with shadcn) */
.button {
  --button-bg: var(--color-primary);
}

Tailwind v4.1+ @theme Directive

Basic Theme Extension

@theme {
  /* Custom colors */
  --color-brand: #3b82f6;
  --color-brand-light: #93c5fd;
  --color-brand-dark: #1e40af;

  /* Custom fonts */
  --font-display: "Satoshi", sans-serif;

  /* Custom spacing */
  --spacing-18: 4.5rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 120rem;
}

Theme with CSS Variables

@theme inline {
  /* Bridge CSS vars to Tailwind */
  --color-primary: var(--primary);
  --color-secondary: var(--secondary);
}

Custom Utilities

@utility content-auto {
  content-visibility: auto;
}

@utility contain-layout {
  contain: layout;
}

Dark Mode Patterns

Class-based Strategy (Recommended)

@custom-variant dark (&:is(.dark *));

:root {
  --background: white;
  --foreground: black;
}

.dark {
  --background: black;
  --foreground: white;
}

Media Query Strategy

@media (prefers-color-scheme: dark) {
  :root {
    --background: black;
    --foreground: white;
  }
}

Combined Strategy

:root {
  --background: white;
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: black;
  }
}

/* Override with class */
.dark {
  --background: black;
}

.light {
  --background: white;
}

Multi-Theme Support

Data Attribute Themes

[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --accent: oklch(0.65 0.12 190);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --accent: oklch(0.70 0.10 100);
}

Theme Switcher Component

function ThemeSwitcher() {
  const [theme, setTheme] = useState("light");

  useEffect(() => {
    document.documentElement.setAttribute("data-theme", theme);
  }, [theme]);

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="ocean">Ocean</option>
      <option value="forest">Forest</option>
    </select>
  );
}

Best Practices

1. Use semantic naming: --primary not --blue-500 2. Always pair foreground: Every background needs a matching foreground 3. Consistent scale: Define complete color scales (50-950) 4. oklch for colors: Use oklch for perceptual uniformity 5. Single source: All tokens in one globals.css file 6. Test contrast: Verify WCAG AA compliance (4.5:1 for normal text) 7. Document tokens: Maintain visual reference