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:

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:

{
  "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 ./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:

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

This combines all analysis data into a comprehensive markdown report:

Output: migration-analysis-report.md

# 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 component-inventory.json and create a mapping table using the shadcn component reference.

VERY IMPORTANT: Use MCP to discover shadcn components

Before mapping, check if shadcn MCP server is available:

# Check if MCP server is available
# Try accessing https://ui.shadcn.com/docs/mcp

If MCP is not available, install it:

npx shadcn@latest mcp init --client claude

Use MCP to query available components:

• "What shadcn components are available for buttons?"
• "Show me form components in shadcn"
• "What's the shadcn equivalent of a modal/dialog?"
• "Available data display components in shadcn"

Component Mapping Table Template:

Existing Component	shadcn Equivalent	Complexity	Priority	Notes
CustomButton	Button	Low	1	Props mostly compatible
Modal	Dialog	Medium	2	Different API, uses Radix
DataTable	Table + DataTable	High	3	Requires custom hooks
Dropdown	DropdownMenu	Low	1	Direct mapping
DatePicker	Calendar + Popover	Medium	2	Composition pattern

Load framework-specific migration guide:

• For React: Read ./references/react-to-nextjs.md
• For Vue: Read ./references/vue-to-nextjs.md
• For Angular: Read ./references/angular-to-nextjs.md
• For styling: Read ./references/styling-migration.md

2.2 Batch Organization

Organize components into batches following these principles:

Batching Strategy:

1. Group by type (layout, forms, data display, navigation)
2. Simple to complex (start with easy wins)
3. Dependency order (convert dependencies first)
4. Batch size: 5-10 components per batch

Example Batch Plan:

Batch 1: Layout & Structure (Priority: Critical)

• Header
• Footer
• MainLayout
• Container
• Sidebar

Batch 2: Simple UI Components (Priority: High)

• Button → shadcn Button
• Card → shadcn Card
• Badge → shadcn Badge
• Alert → shadcn Alert
• Avatar → shadcn Avatar

Batch 3: Form Components (Priority: High)

• Input → shadcn Input
• Select → shadcn Select
• Checkbox → shadcn Checkbox
• RadioGroup → shadcn RadioGroup
• Form validation → shadcn Form + react-hook-form

Batch 4: Navigation (Priority: Medium)

• NavBar → shadcn NavigationMenu
• Breadcrumbs → shadcn Breadcrumb
• Tabs → shadcn Tabs
• Pagination → shadcn Pagination

Batch 5: Data Display (Priority: Medium)

• Table → shadcn Table
• DataGrid → shadcn DataTable (with sorting, filtering)
• List → shadcn custom composition
• Accordion → shadcn Accordion

Batch 6: Overlays & Modals (Priority: Medium)

• Modal → shadcn Dialog
• Tooltip → shadcn Tooltip
• Popover → shadcn Popover
• DropdownMenu → shadcn DropdownMenu

Batch 7: Complex Components (Priority: Low)

• Charts → shadcn Charts (Recharts integration)
• Calendar/DatePicker → shadcn Calendar
• CommandPalette → shadcn Command
• DataVisualization → Custom with shadcn primitives

Batch 8: Styling Standardization (Priority: Critical)

• Extract all hardcoded colors → CSS variables
• Convert spacing to Tailwind classes
• Standardize typography
• Apply theme system consistently

Batch 9: Pages & Routing (Priority: Critical)

• Convert pages to Next.js App Router
• Set up layouts with Next.js layout.tsx
• Implement routing patterns
• Add loading and error states

2.3 Risk Assessment

For each batch, identify risks:

• API Differences: Components with significantly different APIs
• Missing Features: Features in old components not in shadcn
• State Management: Complex state that needs refactoring
• Dependencies: External libraries that need replacement
• Custom Logic: Business logic tightly coupled to UI

Risk Mitigation:

• Document API differences before conversion
• Create adapter/wrapper components when needed
• Write tests before migration
• Keep old components temporarily during transition

2.4 Create Detailed Migration Plan

Generate a detailed plan document: migration-plan.md

# Next.js + shadcn Migration Plan

## Project: [Project Name]
## Date: [Current Date]
## Estimated Timeline: [X batches]

## Migration Strategy

### Approach
- Incremental migration with parallel running old and new code
- Batch-b