用途
本技能用于两类工作流：一是创建全新的 Next.js 应用，二是将现有前端代码库（React、Vue、Angular、原生 JS 等）系统性地迁移到 Next.js + shadcn/ui。其核心目标是让项目 100% 遵循 shadcn/ui 设计原则，包括：所有主题（颜色、间距、字体）使用 CSS 变量；仅使用标准 shadcn/ui 组件，不创建自定义 UI 组件；不硬编码颜色、间距、字体等值；全应用统一设计令牌；移动优先的响应式设计（手机、平板、桌面）；符合 WCAG 2.1 Level AA 无障碍标准；并遵循 https://ui.shadcn.com 的最佳实践。
主要能力
技能围绕一个工作流决策树展开：创建新应用时从“创建新应用”工作流（Phase 3 起）开始；迁移现有代码库时依次执行 Phase 1 代码库分析、Phase 2 迁移规划、Phase 3 Next.js + shadcn 搭建、Phase 4 系统性转换、Phase 5 验证与清理。
Phase 1 代码库分析：通过自动化脚本检测框架与版本、构建工具、依赖与目录结构；生成组件清单（含组件名、路径、类型、复杂度、shadcn 对应组件、硬编码值、依赖）；检测硬编码颜色、内联间距、自定义字体、魔法数字、内联样式及非标准模式；最终生成综合分析报告。
Phase 2 迁移规划：将现有组件映射到 shadcn/ui 等价组件，识别需要自定义开发的组件，按每批 5-10 个组件组织转换批次，评估每批风险与复杂度，并生成详细迁移计划。技能强调使用 MCP 发现 shadcn 组件，若不可用则通过 npx shadcn@latest mcp init --client claude 安装。
Phase 3 Next.js + shadcn 搭建：检查/安装 shadcn MCP 服务器；初始化 Next.js 15+（App Router、TypeScript）；安装配置 Tailwind CSS；运行 shadcn/ui 初始化；设置 CSS 变量与设计令牌；配置路径别名（@/）；安装必要 shadcn 组件；创建设计系统文档。
Phase 4 系统性转换：按批次转换组件，每批后测试。批次示例包括：布局与结构（Header、Footer、Layout 包装器）、简单 UI 组件（Button、Card、Badge、Alert）、表单组件（Input、Select、Checkbox、Form）、复杂组件（Table、Dialog、Command 菜单、数据可视化）、样式标准化（移除硬编码值、应用 CSS 变量）、页面与路由（转换页面、设置 Next.js 路由）。每批工作流为：选择 5-10 个相关组件、用 MCP 查找合适的 shadcn 组件、按 shadcn 模式转换、用 CSS 变量替换硬编码值、测试功能、验证视觉一致性、进入下一批。
Phase 5 验证与清理：运行完整测试套件、视觉回归测试、响应式设计测试（手机、平板、桌面）、性能审计、无障碍审计（WCAG 2.1 AA）、移除旧框架代码、更新文档、生成完成报告。
使用方式
技能提供多个脚本与命令。代码库分析：python ./scripts/analyze-codebase.py /path/to/existing/codebase，输出 codebase-analysis.json 与 component-inventory.json。硬编码值检测：bash ./scripts/detect-hardcoded-values.sh /path/to/existing/codebase，输出 hardcoded-values-report.md。生成迁移报告：python ./scripts/generate-migration-report.py，输出 migration-analysis-report.md。初始化项目：bash ./scripts/init-nextjs-shadcn.sh [project-name]，或手动执行 npx create-next-app@latest [project-name] --typescript --tailwind --app --src-dir --import-alias "@/*" --no-turbopack，随后 npx shadcn@latest init。技能还提供框架特定迁移指南引用文件，如 React 用 ./references/react-to-nextjs.md、Vue 用 ./references/vue-to-nextjs.md、Angular 用 ./references/angular-to-nextjs.md、样式用 ./references/styling-migration.md。
设计令牌方面，技能推荐使用 OKLCH 颜色空间而非 HSL，理由是感知均匀、渐变插值更好、亮度更可预测、对比度更准确。示例中在 app/globals.css 的 @layer base 内定义 :root 与 .dark 的 CSS 变量，涵盖 --radius、--background、--foreground、--card、--popover、--primary、--secondary、--muted、--accent、--destructive、--border、--input、--ring 及 --chart-1 至 --chart-5。
适用场景
适用于需要从零搭建符合 shadcn/ui 设计规范的 Next.js 15+ 应用，或需要将既有 React、Vue、Angular、原生 JS 前端系统化迁移到 Next.js + shadcn/ui 的项目。尤其适合重视设计一致性、CSS 变量主题、响应式与无障碍合规的团队。
限制
资料未提供该技能的具体收费、价格、平台支持范围、性能效果保证或实际使用案例数据。技能依赖 Node.js 18+ 环境，并建议使用 shadcn MCP 服务器进行组件发现；若 MCP 不可用需另行安装。迁移过程需要人工按批次测试与验证，资料未说明自动化程度或失败回滚机制。