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:
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:
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
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
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
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)
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)
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:
:root {
--primary: 270 80% 45%; /* Your brand color (HSL) */
--radius: 0.75rem; /* Border radius */
}
Test contrast ratios: https://webaim.org/resources/contrastchecker/
Adding Components
# 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:
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:
-
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:
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
- 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
- Use Semantic Tokens
[OK] Good (semantic) <div className="bg-primary text-primary-foreground">
[ERROR] Bad (hard-coded) <div className="bg-blue-600 text-white">
- Maintain Type Safety
Use TypeScript for all components:
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: 'default' | 'destructive' | 'outline' }
- Keep Accessibility in Mind
-
Always pair labels with inputs
-
Provide aria-label for icon-only buttons
-
Test keyboard navigation
-
Use semantic HTML
- 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
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.