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:
- Creating New Next.js Applications - Initialize projects with Next.js 15+ (App Router), shadcn/ui, and proper design system setup
- 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:
- Framework and version detection
- Component inventory and categorization
- Hardcoded value detection (colors, spacing, custom components)
- Styling approach analysis (CSS, SCSS, CSS-in-JS, Tailwind, etc.)
- State management and routing pattern identification
- 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:
- Map existing components to shadcn/ui equivalents
- Identify components requiring custom development
- Organize conversion into batches (5-10 components per batch)
- Assess risk and complexity per batch
- 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:
- Check/install shadcn MCP server for documentation access
- Initialize Next.js 15+ with App Router and TypeScript
- Install and configure Tailwind CSS
- Run shadcn/ui initialization
- Set up CSS variables and design tokens
- Configure path aliases (@/)
- Install essential shadcn components
- 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:
- Batch 1: Layout & Structure (Header, Footer, Layout wrappers)
- Batch 2: Simple UI Components (Buttons, Cards, Badges, Alerts)
- Batch 3: Form Components (Inputs, Selects, Checkboxes, Forms)
- Batch 4: Complex Components (Tables, Dialogs, Command Menus, Data visualizations)
- Batch 5: Styling Standardization (Remove hardcoded values, apply CSS variables)
- Batch 6: Pages & Routes (Convert pages, set up Next.js routing)
Per Batch Workflow:
- Select 5-10 related components
- Use MCP to find appropriate shadcn components
- Convert components following shadcn patterns
- Replace hardcoded values with CSS variables
- Test functionality
- Verify visual consistency
- 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:
- Run full test suite
- Visual regression testing
- Responsive design testing (mobile, tablet, desktop)
- Performance audit
- Accessibility audit (WCAG 2.1 Level AA compliance)
- Remove old framework code
- Documentation updates
- 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:
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:
- Group by type (layout, forms, data display, navigation)
- Simple to complex (start with easy wins)
- Dependency order (convert dependencies first)
- 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
