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:

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

To verify:

bash

# 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:

•
Enable dark mode? (default: yes)
- •Installs next-themes, adds ThemeProvider, creates mode toggle
•
Theme preset (zinc | slate | neutral, default: zinc)
- •Determines base color palette in CSS variables
•
Include sidebar layout? (default: yes)
- •Adds responsive sidebar navigation using Sheet component
•
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:

bash

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:

•

Tailwind Configuration

bash

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

•

Global Styles

bash

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

•

Utility Functions

bash

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

Step 4: Add Core Components

Copy theme and layout components from assets/components/:

•

Theme Provider (if dark mode enabled)

bash

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

•

App Shell (if sidebar layout enabled)

bash

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

Step 5: Update App Layout

Update or create app/layout.tsx:

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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:

markdown

## 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:

css

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

Slate - Slightly cooler, tech-focused:

css

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

Neutral - True neutral grays:

css

--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:

bash

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:

tsx

<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:

bash

# 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:

bash

# 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:

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

Issue: shadcn components not found

Cause: components.json misconfigured or components not installed

Solution:

bash

# 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:

bash

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

Scripts (Executable)

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

Execute directly:

bash

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

tsx

[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:

tsx

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:

•
Customize brand colors
- •Edit --primary in app/globals.css
- •Test contrast ratios
•
Add more components
- •Run npx shadcn-ui add [component] as needed
- •See references/shadcn-component-list.md for options
•
Configure responsive breakpoints
- •Adjust Tailwind screens in tailwind.config.ts if needed
•
Set up linting
- •Install eslint-plugin-jsx-a11y for accessibility linting
- •Add Prettier + Tailwind plugin for formatting
•
Test production build
bash
```
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.