tailwind-shadcn-ui-setup
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.
What this skill does
# 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:
```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:
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:
```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:
1. **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
```
2. **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
```
3. **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/`:
1. **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
```
2. **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 cRelated in Design
contribute
IncludedLocal-only OSS contribution command center. Auto-refreshes the user's in-flight PR and issue state on invoke so conversations start with full context — no need to brief Claude on what's in flight. Helps the user find issues to contribute to on GitHub, builds per-repo dossiers of what each upstream expects (CLA, DCO, branch convention, AI policy, draft-first, review bots, issue templates), runs deterministic gates before any external action so AI-assisted contributions don't reach maintainers as slop. State is markdown-only: candidate files at ~/.contribute-system/candidates/, repo dossiers at ~/.contribute-system/research/, append-only event log at ~/.contribute-system/log.jsonl. No database, no cloud calls. Use when the user asks about their PRs / issues / contributions, wants to find new work to take on, claim an issue, build/refresh a repo's dossier, or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR status", "find a contribution", "claim issue X", "draft a Design Issue for Y", "refresh dossier for Z".
architectural-analysis
IncludedUser-triggered deep architectural analysis of a codebase or scoped subtree across eight modes — information architecture, data flow, integration points, UI surfaces, interaction patterns, data model, control flow, and failure modes. This skill should be used when the user asks to "diagram this codebase," "map the architecture," "show the data flow," "give me an ERD," "trace control flow," "find the integration points," "verify the layout pattern," "audit the UX architecture," or any similar request whose primary deliverable is mermaid diagrams plus cited reports under docs/architecture/. Dispatches haiku/sonnet sub-agents in parallel for per-mode exploration, then verifies every citation mechanically before any node lands in a diagram. Not for one-off prose explanations of code (use code-explanation) or for high-level system design from scratch (use system-design).
mcp
IncludedModel Context Protocol (MCP) server development and tool management. Languages: Python, TypeScript. Capabilities: build MCP servers, integrate external APIs, discover/execute MCP tools, manage multi-server configs, design agent-centric tools. Actions: create, build, integrate, discover, execute, configure MCP servers/tools. Keywords: MCP, Model Context Protocol, MCP server, MCP tool, stdio transport, SSE transport, tool discovery, resource provider, prompt template, external API integration, Gemini CLI MCP, Claude MCP, agent tools, tool execution, server config. Use when: building MCP servers, integrating external APIs as MCP tools, discovering available MCP tools, executing MCP capabilities, configuring multi-server setups, designing tools for AI agents.
react-native-skia
IncludedDesign, build, debug, and optimise high-polish animated graphics in React Native or Expo using @shopify/react-native-skia, Reanimated, and Gesture Handler. Use when the user wants canvas-driven UI, shaders, paths, rich text, image filters, sprite fields, Skottie, video frames, snapshots, web CanvasKit setup, or performance tuning for custom motion-heavy elements such as loaders, hero art, cards, charts, progress indicators, particle systems, or gesture-driven surfaces. Also use when the user asks for fluid, glow, glass, blob, parallax, 60fps/120fps, or GPU-friendly animated effects in React Native, even if they do not explicitly say "Skia". Do not use for ordinary form/layout work with standard views.
plaid
IncludedProduct Led AI Development — guides founders from idea to launched product. Six capabilities: Idea (discover a product idea), Validate (pressure-test the idea against fatal flaws, problem reality, competition, and 2-week MVP feasibility), Plan (vision intake + document generation), Design (translate image references into a design.md spec), Launch (go-to-market strategy), and Build (roadmap execution). Use when someone says "PLAID", "plaid idea", "help me find an idea", "product idea", "idea from my business", "idea from my expertise", "plaid validate", "validate my idea", "pressure-test", "is this idea good", "find fatal flaws", "validate the problem", "plan a product", "define my vision", "generate a PRD", "product strategy", "plaid design", "design from image", "translate image to design", "create design.md", "extract design tokens", "plaid launch", "go-to-market", "launch plan", "GTM strategy", "launch playbook", "plaid build", "build the app", "start building", or "execute the roadmap".
nextjs-framer-motion-animations
IncludedAdds production-safe Motion for React or Framer Motion animations to Next.js apps, including reveal, hover and tap micro-interactions, whileInView, stagger, AnimatePresence, layout and layoutId transitions, reorder, scroll-linked UI, and lightweight route-content transitions. Use when the user asks to add, refactor, or debug Motion or Framer Motion in App Router or Pages Router codebases, especially around server/client boundaries, reduced motion, LazyMotion, bundle size, hydration, or route transitions. Avoid for GSAP-style timelines, WebGL or 3D scenes, heavy scroll storytelling, or CSS-only effects unless Motion is explicitly requested.