nextjs-shadcn-builder

What this skill does

# Next.js + shadcn/ui Builder & Migration Tool

Build production-grade Next.js applications or systematically migrate existing frontends to Next.js + shadcn/ui following strict design principles and best practices.

## Overview

This skill handles two primary workflows:

1. **Creating New Next.js Applications** - Initialize projects with Next.js 15+ (App Router), shadcn/ui, and proper design system setup
2. **Migrating Existing Frontends** - Analyze any frontend codebase (React, Vue, Angular, vanilla JS) and systematically convert to Next.js + shadcn/ui

**Core Philosophy**: 100% adherence to shadcn/ui design principles:
- CSS variables for all theming (colors, spacing, typography)
- Standard shadcn/ui components only (no custom UI components)
- No hardcoded values (colors, spacing, fonts)
- Consistent design tokens across the application
- Mobile-first responsive design for all devices (phone, tablet, desktop)
- WCAG 2.1 Level AA accessibility compliance
- Best practices from https://ui.shadcn.com

## Workflow Decision Tree

```
User Request
    ├─ Creating New Next.js App
    │   └─ Follow "Creating New Application" workflow (Phase 3 onwards)
    │
    └─ Migrating Existing Codebase
        ├─ Phase 1: Codebase Analysis
        ├─ Phase 2: Migration Planning
        ├─ Phase 3: Next.js + shadcn Setup
        ├─ Phase 4: Systematic Conversion
        └─ Phase 5: Verification & Cleanup
```

---

## High-Level Workflow for Migration

### Phase 1: Codebase Analysis
Automated analysis of existing frontend to understand scope and complexity.

**Steps:**
1. Framework and version detection
2. Component inventory and categorization
3. Hardcoded value detection (colors, spacing, custom components)
4. Styling approach analysis (CSS, SCSS, CSS-in-JS, Tailwind, etc.)
5. State management and routing pattern identification
6. Generate comprehensive analysis report

**Deliverables:**
- Framework analysis report
- Component inventory (JSON)
- Hardcoded values report
- Complexity assessment

### Phase 2: Migration Planning
Create systematic conversion plan with prioritized batches.

**Steps:**
1. Map existing components to shadcn/ui equivalents
2. Identify components requiring custom development
3. Organize conversion into batches (5-10 components per batch)
4. Assess risk and complexity per batch
5. Create detailed migration plan

**Deliverables:**
- Component mapping table
- Batched conversion plan
- Risk assessment
- Estimated complexity per component

### Phase 3: Next.js + shadcn Setup
Initialize Next.js infrastructure alongside or replacing existing codebase.

**Steps:**
1. Check/install shadcn MCP server for documentation access
2. Initialize Next.js 15+ with App Router and TypeScript
3. Install and configure Tailwind CSS
4. Run shadcn/ui initialization
5. Set up CSS variables and design tokens
6. Configure path aliases (@/)
7. Install essential shadcn components
8. Create design system documentation

**Deliverables:**
- Configured Next.js project
- Design token system (CSS variables)
- Component library setup
- Path aliases configured

### Phase 4: Systematic Conversion
Convert components batch by batch with testing after each batch.

**Steps:**
1. **Batch 1: Layout & Structure** (Header, Footer, Layout wrappers)
2. **Batch 2: Simple UI Components** (Buttons, Cards, Badges, Alerts)
3. **Batch 3: Form Components** (Inputs, Selects, Checkboxes, Forms)
4. **Batch 4: Complex Components** (Tables, Dialogs, Command Menus, Data visualizations)
5. **Batch 5: Styling Standardization** (Remove hardcoded values, apply CSS variables)
6. **Batch 6: Pages & Routes** (Convert pages, set up Next.js routing)

**Per Batch Workflow:**
1. Select 5-10 related components
2. Use MCP to find appropriate shadcn components
3. Convert components following shadcn patterns
4. Replace hardcoded values with CSS variables
5. Test functionality
6. Verify visual consistency
7. Move to next batch

**Deliverables:**
- Migrated components (batch by batch)
- Updated styling with CSS variables
- Next.js App Router pages
- Passing tests per batch

### Phase 5: Verification & Cleanup
Final testing, optimization, and old code removal.

**Steps:**
1. Run full test suite
2. Visual regression testing
3. Responsive design testing (mobile, tablet, desktop)
4. Performance audit
5. Accessibility audit (WCAG 2.1 Level AA compliance)
6. Remove old framework code
7. Documentation updates
8. Generate completion report

**Deliverables:**
- Test results
- Responsive design verification report
- Performance metrics
- Accessibility audit report (WCAG 2.1 AA)
- Clean codebase
- Migration summary

---

## Phase 1: Codebase Analysis (Detailed Instructions)

### 1.1 Framework Detection

Run the automated analysis script:

```bash
python ./scripts/analyze-codebase.py /path/to/existing/codebase
```

This script will:
- Detect framework (React, Vue, Angular, Svelte, vanilla JS, etc.)
- Identify framework version
- Detect build tool (Vite, Webpack, Parcel, etc.)
- Find package.json dependencies
- Map directory structure

**Output:** `codebase-analysis.json` with framework metadata

### 1.2 Component Inventory

The analysis script automatically generates a component inventory including:

- Component name and file path
- Component type (functional, class, Vue SFC, etc.)
- Props/inputs
- State usage
- Child components
- External dependencies

**Output:** `component-inventory.json`

Example structure:
```json
{
  "components": [
    {
      "name": "UserCard",
      "path": "src/components/UserCard.tsx",
      "type": "functional",
      "complexity": "simple",
      "shadcn_equivalent": "Card",
      "hardcoded_values": ["#3b82f6", "16px padding"],
      "dependencies": ["react", "styled-components"]
    }
  ]
}
```

### 1.3 Hardcoded Value Detection

Run the detection script:

```bash
bash ./scripts/detect-hardcoded-values.sh /path/to/existing/codebase
```

This script detects:
- **Hardcoded colors**: `#hex`, `rgb()`, `rgba()`, `hsl()`, color names
- **Inline spacing**: `margin: 20px`, `padding: 1rem`
- **Custom font declarations**: non-standard fonts
- **Magic numbers**: arbitrary values in components
- **Inline styles**: `style={{...}}`
- **Non-standard patterns**: CSS-in-JS, styled-components that should be Tailwind

**Output:** `hardcoded-values-report.md` with violations grouped by category

### 1.4 Generate Analysis Report

Run the report generator:

```bash
python ./scripts/generate-migration-report.py
```

This combines all analysis data into a comprehensive markdown report:

**Output:** `migration-analysis-report.md`

```markdown
# Frontend Migration Analysis Report

## Executive Summary
[One-paragraph overview: framework, size, complexity]

## Current State Analysis
- **Framework**: React 18.2.0
- **Build Tool**: Vite 4.3.0
- **Component Count**: 47 components
- **Styling**: styled-components + custom CSS
- **State Management**: Redux Toolkit
- **Routing**: React Router v6

## Hardcoded Values Detected
- Colors: 142 instances across 34 files
- Spacing: 89 instances across 28 files
- Custom fonts: 3 non-standard fonts
- Inline styles: 67 instances

## Component Categorization
- **Simple (shadcn mapping exists)**: 28 components
- **Moderate (requires adaptation)**: 13 components
- **Complex (custom development needed)**: 6 components

## Recommended Migration Plan
1. Phase 3: Setup Next.js + shadcn infrastructure
2. Phase 4.1: Convert layout components (Header, Footer, Layout)
3. Phase 4.2: Convert simple UI (Button, Card, Badge → shadcn equivalents)
4. Phase 4.3: Convert forms (Input, Select → shadcn/ui Form components)
5. Phase 4.4: Convert complex components (DataTable, Charts)
6. Phase 4.5: Styling standardization (CSS variables)
7. Phase 4.6: Pages and routing
8. Phase 5: Verification and cleanup

## Estimated Effort
- **Total Components**: 47
- **Batches**: 9-10 batches
- **Complexity**: Moderate
```

---

## Phase 2: Migration Planning (Detailed Instructions)

### 2.1 Component Mapping Strategy

Review the