tailwind-shadcn-ui-setup

name

tailwind-shadcn-ui-setup

description

This skill should be used when setting up, configuring, or initializing Tailwind CSS (v3 or v4) and shadcn/ui for Next.js 16 App Router projects. Configure dark mode, design tokens, base layout with header/sidebar, accessibility defaults, and generate example components. Includes comprehensive setup automation, theme customization, and production-ready patterns. Use when the user requests "setup Tailwind", "configure shadcn/ui", "add dark mode", "initialize design system", or "setup UI framework" for Next.js projects.

Tailwind + shadcn/ui Setup for Next.js 16

Overview

Configure a production-ready Tailwind CSS (v3/v4) + shadcn/ui setup for Next.js 16 App Router projects. This skill automates dependency installation, configuration, component generation, and provides:

• Tailwind CSS v4-ready configuration (v3 with forward-compatible patterns)
• shadcn/ui components (Radix UI-based, fully accessible)
• Dark mode with next-themes (class strategy)
• Base application layout (header, optional sidebar, responsive)
• Design token system (CSS variables for easy theming)
• Accessibility defaults (WCAG 2.1 AA compliant)
• Example pages (forms, dialogs, theme showcase)

Prerequisites

Before running this skill, verify:

1. Next.js 16 project exists with App Router (app/ directory)
2. Package manager: npm (script uses npm install)
3. Project structure: Valid package.json at project root
4. TypeScript: Recommended (all templates use .tsx/.ts)

To verify:

# Check Next.js version
cat package.json | grep "\"next\":"

# Confirm app/ directory exists
ls -la app/

Setup Workflow

Step 1: Gather User Requirements

Use AskUserQuestion tool to collect configuration preferences:

1. Enable dark mode? (default: yes)
   • Installs next-themes, adds ThemeProvider, creates mode toggle
2. Theme preset (zinc | slate | neutral, default: zinc)
   • Determines base color palette in CSS variables
3. Include sidebar layout? (default: yes)
   • Adds responsive sidebar navigation using Sheet component
4. Include example pages? (default: yes)
   • Generates example pages for forms, dialogs, theme showcase

Step 2: Run Automation Script

Execute the Python setup script to install dependencies and initialize shadcn/ui:

cd /path/to/nextjs-project
python /path/to/skill/scripts/setup_tailwind_shadcn.py

The script will:

• Detect existing Tailwind/shadcn installations
• Install required npm packages (non-interactive)
• Create components.json for shadcn/ui
• Add baseline shadcn components (button, card, input, label, dialog, separator)
• Create lib/utils.ts with cn() helper

Step 3: Copy Configuration Files

Copy and process template files from assets/ directory:

1. Tailwind Configuration

   # Copy and create
   cp assets/tailwind.config.ts.template project/tailwind.config.ts
   cp assets/postcss.config.js.template project/postcss.config.js
   

2. Global Styles

   # Copy and replace {{THEME_PRESET}} with user's choice
   cp assets/globals.css.template project/app/globals.css
   # Replace: {{THEME_PRESET}} → zinc | slate | neutral
   

3. Utility Functions

   cp assets/lib/utils.ts project/lib/utils.ts
   

Step 4: Add Core Components

Copy theme and layout components from assets/components/:

1. Theme Provider (if dark mode enabled)

   cp assets/components/theme-provider.tsx project/components/theme-provider.tsx
   cp assets/components/mode-toggle.tsx project/components/mode-toggle.tsx
   

2. App Shell (if sidebar layout enabled)

   cp assets/components/app-shell.tsx project/components/app-shell.tsx
   

Step 5: Update App Layout

Update or create app/layout.tsx:

# If layout.tsx exists, carefully merge changes
# If not, copy template
cp assets/app/layout.tsx.template project/app/layout.tsx

Key additions:

• Import globals.css
• Wrap with ThemeProvider (if dark mode enabled)
• Add skip link for accessibility
• Include <Toaster /> from Sonner for notifications

Merge strategy if layout exists:

• Add missing imports at top
• Wrap existing content with ThemeProvider
• Add skip link before main content
• Add Toaster before closing body tag
• Ensure suppressHydrationWarning on <html> tag

Step 6: Generate Example Pages (Optional)

If user requested examples, copy example pages:

# Copy home page
cp assets/app/page.tsx.template project/app/page.tsx

# Copy examples directory structure
cp -r assets/app/examples/ project/app/examples/

Example pages include:

• Homepage (app/page.tsx): Hero, features grid, CTA
• Forms (app/examples/forms/page.tsx): Contact form, validation patterns
• Dialogs (app/examples/dialogs/page.tsx): Modal examples, A11y notes
• Theme (app/examples/theme/page.tsx): Color tokens, customization guide

Step 7: Add Additional shadcn Components

Install additional components as needed:

# Common components for examples
npx shadcn-ui@latest add dropdown-menu
npx shadcn-ui@latest add sheet
npx shadcn-ui@latest add separator

# Optional: Form components
npx shadcn-ui@latest add form
npx shadcn-ui@latest add checkbox
npx shadcn-ui@latest add select

Consult references/shadcn-component-list.md for full component catalog.

Step 8: Verify Installation

Run checks to ensure setup is complete:

# Check for TypeScript errors
npx tsc --noEmit

# Start dev server
npm run dev

# Open browser to http://localhost:3000

Visual verification:

• Page loads without errors
• Dark mode toggle works (if enabled)
• Colors match theme preset
• Example pages render correctly (if included)
• No accessibility warnings in console

Step 9: Document Changes

Add a "Design System & UI" section to project README.md:

## Design System & UI

This project uses Tailwind CSS and shadcn/ui for styling and components.

### Customizing Colors

Edit CSS variables in `app/globals.css`:

```css
:root {
  --primary: 270 80% 45%;  /* Your brand color (HSL) */
  --radius: 0.75rem;        /* Border radius */
}
```

Test contrast ratios: https://webaim.org/resources/contrastchecker/

### Adding Components

```bash
# Add any shadcn/ui component
npx shadcn-ui@latest add [component-name]

# Example: Add a combobox
npx shadcn-ui@latest add combobox
```

Available components: https://ui.shadcn.com/docs/components

### Dark Mode

Toggle theme programmatically:

```tsx
import { useTheme } from 'next-themes'

export function Example() {
  const { theme, setTheme } = useTheme()
  // theme: 'light' | 'dark' | 'system'
  // setTheme('dark')
}
```

### Accessibility

- All components meet WCAG 2.1 Level AA
- Focus indicators on all interactive elements
- Keyboard navigation supported
- Screen reader compatible

See `references/accessibility-checklist.md` for full guidelines.

Configuration Options

Theme Presets

Zinc (default) - Cool, neutral gray tones:

--primary: 240 5.9% 10%;
--muted: 240 4.8% 95.9%;

Slate - Slightly cooler, tech-focused:

--primary: 222.2 47.4% 11.2%;
--muted: 210 40% 96.1%;

Neutral - True neutral grays:

--primary: 0 0% 9%;
--muted: 0 0% 96.1%;

Customize further by editing app/globals.css :root and .dark blocks.

Tailwind v4 Considerations

Check Tailwind version before setup:

npm view tailwindcss version

If v4.0.0+ is available:

• Use v4 configuration format (@theme directive)
• Consult references/tailwind-v4-migration.md

If v4 not available (current default):

• Use v3 with forward-compatible CSS variables
• Add comments in generated files: // TODO: Upgrade to Tailwind v4 when stable

Sidebar Layout Options

If sidebarLayout = true:

• Uses AppShell component with responsive sidebar
• Mobile: Hamburger menu → Sheet (slide-over)
• Desktop: Fixed sidebar with navigation items

If sidebarLayout = false:

• Simple header + content layout
• Header contains site title + actions (mode toggle)

Users can customize navigation in layout files by passing navigation prop:

<AppShell
  navigation={[
    { title: 'Home', href: '/', icon: Home },
    { title: 'About', href: '/about', icon: Info },
  ]}
  siteTitle="My App"
>
  {children}
</AppShell>

Troubleshooting

Issue: npm install fails

Cause: Network issues, registry timeout, or package conflicts

Solution:

# Clear npm cache
npm cache clean --force

# Retry with verbose logging
npm install --verbose

# Or use specific registry
npm install --registry https://registry.npmjs.org/

Issue: TypeScript errors in components

Cause: Missing type definitions or tsconfig issues

Solution:

# Install missing types
npm install --save-dev @types/react @types/react-dom @types/node

# Check tsconfig.json paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Issue: Dark mode not working

Cause: ThemeProvider not wrapping content, or suppressHydrationWarning missing

Solution:

1. Verify <html suppressHydrationWarning> in layout
2. Ensure ThemeProvider wraps {children}
3. Check tailwind.config.ts has darkMode: 'class'

Issue: shadcn components not found

Cause: components.json misconfigured or components not installed

Solution:

# Reinitialize shadcn/ui
npx shadcn-ui@latest init

# Re-add components
npx shadcn-ui@latest add button card input

Issue: Focus styles not visible

Cause: Global CSS focus styles not applied

Solution:

• Verify app/globals.css includes focus styles layer
• Check *:focus-visible rule is present
• Ensure --ring CSS variable is defined

Resources

This skill bundles comprehensive resources for reference:

References (Loaded as Needed)

• tailwind-v4-migration.md: Tailwind v3 vs v4 differences, migration guide
• shadcn-component-list.md: Complete shadcn/ui component catalog with usage examples
• accessibility-checklist.md: WCAG 2.1 AA compliance checklist, best practices
• theme-tokens.md: Design token system, color customization guide

To read a reference:

# From skill directory
cat references/theme-tokens.md

Scripts (Executable)

• setup_tailwind_shadcn.py: Main automation script for dependency installation and configuration

Execute directly:

python scripts/setup_tailwind_shadcn.py

Assets (Templates for Output)

• Config templates: tailwind.config.ts.template, postcss.config.js.template, globals.css.template
• Component templates: theme-provider.tsx, mode-toggle.tsx, app-shell.tsx
• Utility templates: lib/utils.ts
• Page templates: app/layout.tsx.template, app/page.tsx.template
• Example pages: app/examples/forms/, app/examples/dialogs/, app/examples/theme/

Copy and customize as needed for the target project.

Best Practices

1. Always Test Both Themes

After setup, manually toggle dark mode and verify:

• Color contrast ratios meet WCAG standards
• All text remains readable
• Focus indicators are visible
• Components render correctly

2. Use Semantic Tokens

[OK] Good (semantic)
<div className="bg-primary text-primary-foreground">

[ERROR] Bad (hard-coded)
<div className="bg-blue-600 text-white">

3. Maintain Type Safety

Use TypeScript for all components:

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'default' | 'destructive' | 'outline'
}

4. Keep Accessibility in Mind

• Always pair labels with inputs
• Provide aria-label for icon-only buttons
• Test keyboard navigation
• Use semantic HTML

5. Document Customizations

When customizing tokens or components, document changes in project README or inline comments.

Post-Setup Tasks

After running this skill, recommend users:

1. Customize brand colors

   • Edit --primary in app/globals.css
   • Test contrast ratios

2. Add more components

   • Run npx shadcn-ui add [component] as needed
   • See references/shadcn-component-list.md for options

3. Configure responsive breakpoints

   • Adjust Tailwind screens in tailwind.config.ts if needed

4. Set up linting

   • Install eslint-plugin-jsx-a11y for accessibility linting
   • Add Prettier + Tailwind plugin for formatting

5. Test production build

   npm run build
   npm start
   

Summary

This skill provides a complete, production-ready Tailwind CSS + shadcn/ui setup for Next.js 16 App Router projects. It handles:

[OK] Dependency installation (Tailwind, shadcn/ui, next-themes) [OK] Configuration (Tailwind config, PostCSS, global CSS) [OK] Dark mode setup (ThemeProvider, toggle component) [OK] Base layout (responsive header, optional sidebar) [OK] Design tokens (semantic CSS variables) [OK] Accessibility (WCAG 2.1 AA, keyboard nav, screen readers) [OK] Example pages (forms, dialogs, theme showcase) [OK] Documentation (README updates, customization guides)

The setup is forward-compatible with Tailwind v4 and follows official Anthropic skill best practices.