Initial commit

2025-11-29 18:46:58 +08:00
commit 925b2de0f6
21 changed files with 3934 additions and 0 deletions
--- a/skills/tailwind-shadcn-ui-setup/SKILL.md
+++ b/skills/tailwind-shadcn-ui-setup/SKILL.md
@@ -0,0 +1,493 @@
+---
+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:
+
+```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 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**:
+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**:
+```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:
+
+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**
+   ```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.