К основному содержанию
скилл CX Codex

nextjs-shadcn-builder — скилл для Claude Code: создание и миграция

Скилл nextjs-shadcn-builder для Claude Code создаёт приложения на Next.js с shadcn/ui и переносит туда существующий фронтенд. Разбирает компоненты и переводит их поэтапно.

MIT 263 установок ★ 56 обновлён 2025-11-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add ovachiever/droid-tings --skill nextjs-shadcn-builder -a claude-code
Открыть на GitHub

Что делает nextjs-shadcn-builder

Скилл помогает начать проект на Next.js с App Router и TypeScript либо мигрировать фронтенд на React, Vue, Angular или vanilla JS. Для миграции он сначала анализирует кодовую базу: определяет фреймворк и зависимости, составляет список компонентов и ищет захардкоженные стили. Результаты анализа сохраняются в JSON и Markdown-отчёты.

Затем скилл предлагает план миграции: сопоставляет компоненты с вариантами из shadcn/ui и разбивает работу на партии. Во время переноса он проверяет компоненты через MCP, заменяет заданные вручную значения CSS-переменными и тестирует каждую партию. В финале предусмотрены проверки тестов, адаптивности и доступности. Для анализа нужны Python и Bash: именно ими запускаются скрипты из scripts/. Если в окружении нет Python или Bash, соответствующие этапы анализа не запустятся.

Какие задачи решает

  • создать приложение Next.js с App Router и TypeScript
  • составить список компонентов и зависимостей существующего фронтенда
  • найти цвета и отступы, заданные напрямую в коде
  • разбить миграцию интерфейса на партии компонентов
  • заменить жёстко заданные стили CSS-переменными

Примеры запросов агенту

  • Проанализируй этот фронтенд и составь план миграции на Next.js с shadcn/ui.
  • Создай новое приложение Next.js с App Router и настрой систему дизайн-токенов.
  • Найди в проекте захардкоженные значения и подготовь компоненты к переносу на shadcn/ui.

Как установить nextjs-shadcn-builder

1Через Skills CLI (Vercel)

npx skills add ovachiever/droid-tings --skill nextjs-shadcn-builder -a claude-code

2Вручную: положить файлы

~/.claude/skills/nextjs-shadcn-builder/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/nextjs-shadcn-builder/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о nextjs-shadcn-builder

Как установить nextjs-shadcn-builder в Claude Code?

Выполните npx skills add ovachiever/droid-tings --skill nextjs-shadcn-builder -a claude-code. Файл скилла будет доступен по пути ~/.claude/skills/nextjs-shadcn-builder/SKILL.md.

Что делает nextjs-shadcn-builder?

Он создаёт приложения Next.js или помогает переносить существующий фронтенд на Next.js и shadcn/ui. При миграции скилл анализирует компоненты, составляет план и переводит их партиями.

Что нужно для анализа кодовой базы?

Скрипты анализа запускаются через Python и Bash. Скилл также предусматривает подключение MCP-сервера shadcn для доступа к документации.

Исходный текст

SKILL.md · MIT
---
name: nextjs-shadcn-builder
description: Build new Next.js applications or migrate existing frontends (React, Vue, Angular, vanilla JS, etc.) to Next.js + shadcn/ui with systematic analysis and conversion. Enforces shadcn design principles - CSS variables for theming, standard UI components, no hardcoded values, consistent typography/colors. Use for creating Next.js apps, migrating frontends, adopting shadcn/ui, or standardizing component libraries. Includes MCP integration for shadcn documentation and automated codebase analysis.
license: Complete terms in LICENSE.txt
---

# 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 `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:

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

If MCP is not available, install it:

```bash
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`

```markdown
# 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-based conversion (5-10 components per batch)
- Test after each batch before proceeding
- Feature flag new components during transition

### Success Criteria
- All components use shadcn/ui or shadcn patterns
- Zero hardcoded colors/spacing (CSS variables only)
- 100% TypeScript coverage
- Passing test suite
- Lighthouse score >= 90
- No accessibility violations

## Detailed Batch Plan

[Include all batches from 2.2 with specific components listed]

## Timeline

Batch 1: Layout & Structure (Days 1-2)
Batch 2: Simple UI (Days 3-4)
[etc.]

## Notes and Considerations
[Any special requirements, blockers, or dependencies]
```

---

## Phase 3: Next.js + shadcn Setup (Detailed Instructions)

### 3.1 Check/Install shadcn MCP Server

**CRITICAL: Always use MCP for shadcn component discovery**

1. Check if MCP server is accessible:
   - Try to access documentation at `https://ui.shadcn.com/docs/mcp`
   - Check if you can query shadcn components via MCP

2. If not available, install MCP server:

```bash
npx shadcn@latest mcp init --client claude
```

This enables:
- Real-time shadcn documentation access
- Component discovery and search
- Block and chart template discovery
- Theme and design token reference

**Using MCP during development:**
- "What components are available for [use case]?"
- "Show me the props for shadcn Button"
- "Available chart types in shadcn"
- "How to use shadcn Form with validation"

### 3.2 Initialize Next.js Project

Run the initialization script:

```bash
bash ./scripts/init-nextjs-shadcn.sh [project-name]
```

**Or manually initialize:**

```bash
# Check Node.js version (18+ required)
node -v

# Create Next.js project with App Router
npx create-next-app@latest [project-name] \
  --typescript \
  --tailwind \
  --app \
  --src-dir \
  --import-alias "@/*" \
  --no-turbopack

cd [project-name]
```

### 3.3 Install and Configure shadcn/ui

```bash
# Initialize shadcn/ui
npx shadcn@latest init

# Configuration prompts:
# - TypeScript: Yes
# - Style: Default
# - Base color: Choose from slate/gray/zinc/neutral/stone
# - CSS variables: Yes (CRITICAL - required for theming)
# - Import alias: @/components
```

This creates:
- `components.json` config file
- `lib/utils.ts` with cn() helper
- Updated `tailwind.config.ts` with shadcn theme
- CSS variables in `app/globals.css`

### 3.4 Configure Design Tokens (CSS Variables)

**VERY IMPORTANT: All theming MUST use CSS variables**

**Color Format: OKLCH (Recommended)**

This skill uses **OKLCH** (OKLab Lightness Chroma Hue) color space instead of HSL for better perceptual uniformity and color accuracy.

**OKLCH Benefits:**
- Perceptually uniform (equal changes = equal perceived differences)
- Better gradient interpolation
- More predictable lightness
- Better for accessibility (more accurate contrast ratios)

Edit `app/globals.css` to define your design system:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --radius: 0.65rem;

    /* Background - Pure white */
    --background: 1 0 0;
    --foreground: 0.141 0.005 285.823;

    /* Card */
    --card: 1 0 0;
    --card-foreground: 0.141 0.005 285.823;

    /* Popover */
    --popover: 1 0 0;
    --popover-foreground: 0.141 0.005 285.823;

    /* Primary - Warm orange */
    --primary: 0.646 0.222 41.116;
    --primary-foreground: 0.98 0.016 73.684;

    /* Secondary - Light purple-gray */
    --secondary: 0.967 0.001 286.375;
    --secondary-foreground: 0.21 0.006 285.885;

    /* Muted - Subtle elements */
    --muted: 0.967 0.001 286.375;
    --muted-foreground: 0.552 0.016 285.938;

    /* Accent */
    --accent: 0.967 0.001 286.375;
    --accent-foreground: 0.21 0.006 285.885;

    /* Destructive - Red */
    --destructive: 0.577 0.245 27.325;

    /* Border and Input */
    --border: 0.92 0.004 286.32;
    --input: 0.92 0.004 286.32;

    /* Focus ring */
    --ring: 0.75 0.183 55.934;

    /* Chart colors */
    --chart-1: 0.837 0.128 66.29;
    --chart-2: 0.705 0.213 47.604;
    --chart-3: 0.646 0.222 41.116;
    --chart-4: 0.553 0.195 38.402;
    --chart-5: 0.47 0.157 37.304;
  }

  .dark {
    /* Dark mode backgrounds */
    --background: 0.141 0.005 285.823;
    --foreground: 0.985 0 0;

    /* Dark mode card */
    --card: 0.21 0.006 285.885;
    --card-foreground: 0.985 0 0;

    /* Dark mode popover */
    --popover: 0.21 0.006 285.885;
    --popover-foreground: 0.985 0 0;

    /* Dark mode primary - Brighter for contrast */
    --primary: 0.705 0.213 47.604;
    --primary-foreground: 0.98 0.016 73.684;

    /* Dark mode secondary */
    --secondary: 0.274 0.006 286.033;
    --secondary-foreground: 0.985 0 0;

    /* Dark mode muted */
    --muted: 0.274 0.006 286.033;
    --muted-foreground: 0.705 0.015 286.067;

    /* Dark mode accent */
    --accent: 0.274 0.006 286.033;
    --accent-foreground: 0.985 0 0;

    /* Dark mode destructive */
    --destructive: 0.704 0.191 22.216;

    /* Dark mode borders (with alpha) */
    --border: 1 0 0 / 10%;
    --input: 1 0 0 / 15%;

    /* Dark mode focus ring */
    --ring: 0.408 0.123 38.172;

    /* Chart colors (consistent) */
    --chart-1: 0.837 0.128 66.29;
    --chart-2: 0.705 0.213 47.604;
    --chart-3: 0.646 0.222 41.116;
    --chart-4: 0.553 0.195 38.402;
    --chart-5: 0.47 0.157 37.304;
  }
}

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }
}
```

**Customizing for Migrated Project:**

If migrating an existing app with a design system, extract existing colors and map to CSS variables:

```bash
# Use the detection script to find existing colors
bash ./scripts/detect-hardcoded-values.sh /path/to/old/codebase

# Map old colors to new CSS variables (OKLCH format)
# Use https://oklch.com or https://colorjs.io to convert
# Example:
# Old: #FF6B35 (brand orange) → --primary: 0.646 0.222 41.116
# Old: #3B82F6 (blue) → --primary: 0.630 0.213 255.5
# Old: #10B981 (green) → --success: 0.710 0.180 165.4
```

### 3.5 Install Essential shadcn Components

**Use MCP to discover which components you need!**

Install core components:

```bash
# Layout & Structure
npx shadcn@latest add card
npx shadcn@latest add separator

# Forms
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add label
npx shadcn@latest add select
npx shadcn@latest add checkbox
npx shadcn@latest add radio-group
npx shadcn@latest add form

# Navigation
npx shadcn@latest add navigation-menu
npx shadcn@latest add tabs
npx shadcn@latest add breadcrumb

# Feedback
npx shadcn@latest add alert
npx shadcn@latest add toast
npx shadcn@latest add dialog
npx shadcn@latest add tooltip

# Data Display
npx shadcn@latest add table
npx shadcn@latest add badge
npx shadcn@latest add avatar

# Overlays
npx shadcn@latest add popover
npx shadcn@latest add dropdown-menu
npx shadcn@latest add sheet
```

**Query MCP for additional components as needed during development.**

### 3.6 Set Up Theme Provider (Dark Mode Support)

Install next-themes:

```bash
npm install next-themes
```

Create `components/theme-provider.tsx`:

```typescript
"use client"

import * as React from "react"
import { ThemeProvider as NextThemesProvider } from "next-themes"
import { type ThemeProviderProps } from "next-themes/dist/types"

export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>
}
```

Update `app/layout.tsx`:

```typescript
import { ThemeProvider } from "@/components/theme-provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}
```

### 3.7 Create Example Component

Create `components/example-card.tsx` demonstrating best practices:

```typescript
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

export function ExampleCard() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>shadcn/ui Best Practices</CardTitle>
        <CardDescription>
          This card demonstrates proper shadcn patterns
        </CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">
          Notice: No hardcoded colors, using CSS variables via Tailwind classes,
          standard shadcn components, and proper typography scale.
        </p>
      </CardContent>
      <CardFooter className="flex justify-between">
        <Button variant="outline">Cancel</Button>
        <Button>Continue</Button>
      </CardFooter>
    </Card>
  )
}
```

**Key Patterns Demonstrated:**
- Uses standard shadcn components (Card, Button)
- No hardcoded colors (uses `text-muted-foreground`)
- CSS variables automatically applied via Tailwind
- Semantic variants (`outline`, default)
- Proper component composition

---

## Phase 4: Systematic Conversion (Detailed Instructions)

### 4.1 Component Conversion Workflow

For each batch of 5-10 components:

**Step 1: Review Components in Batch**

Load the component files and understand:
- Current functionality
- Props/API
- Styling approach
- State management
- Event handlers

**Step 2: Query MCP for shadcn Equivalents**

Before converting, use MCP:
- "What's the shadcn component for [component type]?"
- "Show me shadcn [component] props and examples"
- "How to use shadcn [component] with [feature]?"

**Step 3: Convert Component**

Follow this pattern:

```typescript
// OLD: Custom button with hardcoded styles
const CustomButton = ({ children, onClick, variant = 'primary' }) => {
  const styles = {
    primary: {
      backgroundColor: '#3b82f6', // HARDCODED!
      color: '#ffffff',
      padding: '8px 16px', // HARDCODED!
      borderRadius: '6px'
    },
    secondary: {
      backgroundColor: '#6b7280',
      color: '#ffffff',
      padding: '8px 16px',
      borderRadius: '6px'
    }
  }

  return (
    <button style={styles[variant]} onClick={onClick}>
      {children}
    </button>
  )
}

// NEW: shadcn Button with CSS variables
import { Button } from "@/components/ui/button"

const CustomButton = ({ children, onClick, variant = 'default' }) => {
  return (
    <Button variant={variant} onClick={onClick}>
      {children}
    </Button>
  )
}
```

**Conversion Checklist:**
- ✅ Replace with shadcn component
- ✅ Remove all hardcoded colors
- ✅ Remove inline styles
- ✅ Use Tailwind classes only
- ✅ Use semantic variants (default, outline, destructive, etc.)
- ✅ Preserve all functionality
- ✅ TypeScript types properly defined

**Step 4: Replace Hardcoded Values with CSS Variables**

```typescript
// OLD: Hardcoded spacing and colors
<div style={{
  backgroundColor: '#f3f4f6',  // WRONG
  padding: '20px',              // WRONG
  margin: '10px 0'              // WRONG
}}>

// NEW: Tailwind classes using CSS variables
<div className="bg-secondary p-5 my-2.5">

// Or for custom spacing:
<div className="bg-secondary" style={{ padding: 'var(--spacing-5)' }}>
```

**Step 5: Test Functionality**

After converting each component:

```bash
# Run tests
npm test

# Visual testing
npm run dev
# Manually verify component renders correctly
```

**Step 6: Verify No Violations**

Run detection script on new components:

```bash
bash ./scripts/detect-hardcoded-values.sh src/components/[batch-name]
```

Should return 0 violations.

**Step 7: Mark Batch Complete, Move to Next**

Update todo list and migration-plan.md with progress.

### 4.2 Common Component Migrations

**Refer to `./references/shadcn-component-mapping.md` for detailed mappings.**

Quick reference:

| Pattern | Old Approach | shadcn Approach |
|---------|-------------|-----------------|
| Button | Custom styled button | `<Button variant="...">` |
| Modal/Dialog | Custom overlay | `<Dialog>` with `<DialogTrigger>` and `<DialogContent>` |
| Form Input | Custom input with validation | `<Form>` + `<FormField>` + react-hook-form |
| Dropdown | Custom select | `<Select>` or `<DropdownMenu>` |
| Table | Custom table | `<Table>` or DataTable pattern |
| Tooltip | Custom hover component | `<Tooltip>` |
| Toast/Notification | Custom notification | `useToast()` hook + `<Toaster>` |
| Tabs | Custom tab component | `<Tabs>` with `<TabsList>` and `<TabsContent>` |
| Card | Custom card | `<Card>` with subcomponents |
| Badge | Custom badge/pill | `<Badge variant="...">` |

### 4.3 Handling Complex Components

For components without direct shadcn equivalents:

**Option 1: Composition**

Build using shadcn primitives:

```typescript
// Complex dashboard widget using shadcn primitives
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
import { Button } from "@/components/ui/button"
import { Badge } from "@/components/ui/badge"

export function DashboardWidget({ title, data, onRefresh }) {
  return (
    <Card>
      <CardHeader className="flex flex-row items-center justify-between">
        <CardTitle>{title}</CardTitle>
        <Button variant="outline" size="sm" onClick={onRefresh}>
          Refresh
        </Button>
      </CardHeader>
      <CardContent>
        {data.map(item => (
          <div key={item.id} className="flex items-center justify-between py-2">
            <span className="text-sm">{item.label}</span>
            <Badge variant={item.status === 'success' ? 'default' : 'destructive'}>
              {item.value}
            </Badge>
          </div>
        ))}
      </CardContent>
    </Card>
  )
}
```

**Option 2: Extend shadcn Components**

Create custom components that extend shadcn:

```typescript
// Custom component extending shadcn Button
import { Button } from "@/components/ui/button"
import { cn } from "@/lib/utils"

interface IconButtonProps extends React.ComponentProps<typeof Button> {
  icon: React.ReactNode
}

export function IconButton({ icon, children, className, ...props }: IconButtonProps) {
  return (
    <Button className={cn("flex items-center gap-2", className)} {...props}>
      {icon}
      {children}
    </Button>
  )
}
```

**Option 3: Use shadcn Blocks**

Use MCP to discover shadcn blocks (pre-built complex components):

"What blocks are available in shadcn for [use case]?"

Install blocks:

```bash
npx shadcn@latest add [block-name]
```

### 4.4 Page and Route Conversion

Convert pages to Next.js App Router structure:

**Old Structure (React Router):**
```
src/
  pages/
    Home.tsx
    About.tsx
    Dashboard.tsx
    users/
      UserList.tsx
      UserDetail.tsx
```

**New Structure (Next.js App Router):**
```
app/
  page.tsx          # Home
  about/
    page.tsx        # About
  dashboard/
    page.tsx        # Dashboard
    layout.tsx      # Dashboard layout
  users/
    page.tsx        # UserList
    [id]/
      page.tsx      # UserDetail
  layout.tsx        # Root layout
  loading.tsx       # Loading state
  error.tsx         # Error boundary
```

**Example Conversion:**

```typescript
// OLD: React Router page
// src/pages/Dashboard.tsx
import { useNavigate } from 'react-router-dom'

export function Dashboard() {
  const navigate = useNavigate()
  return (
    <div style={{ padding: '20px' }}>
      <h1>Dashboard</h1>
      <button onClick={() => navigate('/users')}>
        View Users
      </button>
    </div>
  )
}

// NEW: Next.js App Router page
// app/dashboard/page.tsx
import Link from 'next/link'
import { Button } from '@/components/ui/button'

export default function DashboardPage() {
  return (
    <div className="container py-6">
      <h1 className="text-3xl font-bold mb-6">Dashboard</h1>
      <Link href="/users">
        <Button>View Users</Button>
      </Link>
    </div>
  )
}
```

**Key Changes:**
- Default export for pages
- Use Next.js `<Link>` instead of router navigation
- Remove hardcoded padding → Tailwind classes
- Use shadcn Button

### 4.5 State Management Migration

**Load reference:** `./references/react-to-nextjs.md` for state management patterns

Common patterns:

**Local State (useState):**
- Remains the same in Next.js App Router
- Mark client components with `"use client"`

**Global State:**
- **Redux → Zustand or React Context**
- **MobX → Zustand**
- **Recoil → Zustand or Jotai**

**Server State:**
- **React Query → TanStack Query (still works in Next.js)**
- **SWR → SWR (Next.js compatible)**
- Or use Next.js Server Components for server data

---

## Phase 5: Verification & Cleanup (Detailed Instructions)

### 5.1 Run Test Suite

```bash
# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Ensure 100% of migrated components have passing tests
```

### 5.2 Visual Regression Testing

Manual verification checklist:

- [ ] All pages render correctly
- [ ] All components match design system
- [ ] Dark mode works correctly
- [ ] Responsive design maintained
- [ ] No hardcoded colors visible
- [ ] Consistent spacing thro...

© ovachiever · MIT · ovachiever/droid-tings

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
typescript-shadcn-ui-nextjs-cursorrules-prompt-fil PatrickJS Правило typescript-shadcn-ui-nextjs-cursorrules-prompt-fil задаёт стандарты TypeScript, React Server Components и shadcn/ui для Next.js в Cursor. Пригодится при сборке интерфейсов на Tailwind и Radix. CX Codex +1 ★ 41 178звёзд репо nextjs-supabase-shadcn-pwa-cursorrules-prompt-file PatrickJS Правило nextjs-supabase-shadcn-pwa-cursorrules-prompt-file задаёт стандарты стека Next.js 15+, Supabase и Shadcn UI для Cursor. Вводит лимит на 150 строк в файле и строгий регламент ведения заметок сборки. CX Codex +1 ★ 41 178звёзд репо nextjs-shadcn laguagu Скилл nextjs-shadcn для Claude Code и Codex настраивает интерфейсы Next.js на базе shadcn/ui. Агент подключает его при сборке и редизайне страниц, компонентов и дизайн-систем. CX Codex +1 861установок nextjs-react-typescript Mindrally Скилл nextjs-react-typescript задаёт стиль кода для Next.js App Router, React, TypeScript, Shadcn UI и Tailwind. Агент пишет функциональные компоненты, серверные по умолчанию, с TypeScript-интерфейсами. CX Codex +1 5 400установок nextjs-app-router-fundamentals wsimmonds Скилл nextjs-app-router-fundamentals ведёт агента по Next.js App Router: перенос с Pages Router, вложенные layout, метаданные, динамические маршруты. Пригодится при переходе на app/. CX Codex +1 2 200установок shadcn-ui jezweb Ставит и настраивает компоненты shadcn/ui в React-проекте: подбирает их по задаче, следит за порядком установки и зависимостями. CX Codex +1 3 600установок

Из того же набора6

security-auditor Скилл security-auditor ищет дыры в коде по паттернам OWASP Top 10: SQL-инъекции, XSS, утечки секретов, слабую авторизацию. Срабатывает сам при правках файлов и перед деплоем. CX Codex +1 784установок react-hook-form-zod Скилл react-hook-form-zod учит агента собирать формы на React Hook Form с валидацией через Zod. Одна схема работает и на клиенте, и на сервере. CX Codex +1 725установок reportlab Скилл помогает агенту создавать PDF через ReportLab: отчёты, счета, формы, таблицы, графики и QR-коды. CX Codex +1 140установок threejs-graphics-optimizer Скилл threejs-graphics-optimizer для Claude Code задаёт правила оптимизации THREE.js: сокращает вызовы отрисовки, настраивает мобильные fallback и помогает удерживать 16,67 мс на кадр. CX Codex +1 125установок react-native-expo Скилл react-native-expo помогает разрабатывать приложения на Expo SDK 52 и React Native 0.76–0.82+. Подсказывает правила New Architecture, изменения React 19 и отладку через DevTools. CX Codex +1 105установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой