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

sidebarLayout = true

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

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.

tailwind-shadcn-ui-setup

NPX Install

Tags

SKILL.md Content

Tailwind + shadcn/ui Setup for Next.js 16

Overview

Prerequisites

Setup Workflow

Step 1: Gather User Requirements

Step 2: Run Automation Script

Step 3: Copy Configuration Files

Step 4: Add Core Components

Step 5: Update App Layout

Step 6: Generate Example Pages (Optional)

Step 7: Add Additional shadcn Components

Step 8: Verify Installation

Step 9: Document Changes

Configuration Options

Theme Presets

Tailwind v4 Considerations

Sidebar Layout Options

Troubleshooting

Issue: npm install fails

Issue: TypeScript errors in components

Issue: Dark mode not working

Issue: shadcn components not found

Issue: Focus styles not visible

Resources

References (Loaded as Needed)

Scripts (Executable)

Assets (Templates for Output)

Best Practices

1. Always Test Both Themes

2. Use Semantic Tokens

3. Maintain Type Safety

4. Keep Accessibility in Mind

5. Document Customizations

Post-Setup Tasks

Summary