高级前端开发

React、Next.js、TypeScript 与 Tailwind CSS —— 从项目搭建到生产环境部署。

激活条件

当用户提出以下需求时使用本技能：

• 搭建新的 Next.js 或 React + Vite 项目
• 生成 React 组件、自定义 Hook 或 Storybook 示例
• 分析或减少打包体积
• 优化 Next.js（服务端组件与客户端组件的区分、图片加载、数据获取策略）
• 实现无障碍访问（WCAG、ARIA 标签、键盘导航）
• 审查或提升前端代码质量

工作流程

1. 分类请求：scaffold | component | bundle | optimize | accessibility | review
2. 加载相关参考文档：

- React 设计模式（复合组件、自定义 Hook、渲染属性） → {baseDir}/references/react_patterns.md

- Next.js 优化策略（服务端组件、Suspense、图片处理、缓存机制） → {baseDir}/references/nextjs_optimization_guide.md

- 无障碍访问、测试策略、Tailwind 命名规范 → {baseDir}/references/frontend_best_practices.md

1. 根据项目或组件名称执行对应脚本：

   # 搭建新的 Next.js 或 React 项目
   python {baseDir}/scripts/frontend_scaffolder.py my-app --template nextjs
   python {baseDir}/scripts/frontend_scaffolder.py my-app --template nextjs --features auth,api,forms,testing

   # 生成组件（客户端 | 服务端 | Hook），可选添加测试文件与 Story
   python {baseDir}/scripts/component_generator.py Button --dir src/components/ui
   python {baseDir}/scripts/component_generator.py UserProfile --type server --with-test --with-story

   # 分析打包体积，识别大依赖项与优化机会
   python {baseDir}/scripts/bundle_analyzer.py ./project --verbose

1. 输出结果：组件文件、项目结构、打包分析报告或优化建议。

输出规范

• 开头明确请求分类及核心问题或决策点。
• 每次响应仅输出一个主要产物（组件、配置文件或报告）。
• 打包分析结果需提供评分（A–F），列出体积较大的依赖项及其更轻量的替代方案。
• 对非显而易见的 TypeScript 使用模式或无障碍设计选择进行标注说明。
• 结尾给出下一步建议（如：“添加 Storybook 示例”，“为 Image 组件添加 sizes 属性”）。

关键规则

• 在 Next.js 中默认使用 服务端组件。仅在需要状态管理、副作用或浏览器 API 时才添加 'use client'。
• 所有生成代码默认采用 TypeScript。
• 条件性 Tailwind 类名使用 cn() 函数（来自 @/lib/utils），禁止直接拼接字符串。
• 每个生成的组件必须明确定义 prop 类型，不得使用隐式的 any。
• 打包得分低于 70（即 C 及以下）时，触发依赖项替换建议。

主动检测提示

即使未被询问，也应主动标记以下情况：

• 使用 moment → 建议替换为 date-fns 或 dayjs
• 全量导入 lodash → 改用支持树摇的 lodash-es
• Dockerfile 中 COPY . . 位于 npm install 之前 → 应调整顺序（推迟至 docker-development 阶段）
• <img> 或 <Image> 缺少 alt 属性 → 存在无障碍访问问题
• 在 Next.js 中使用 useEffect 进行数据获取 → 建议改用服务端组件或 use() 钩子
• 响应式 <Image> 缺少 sizes 属性 → 存在布局偏移风险

安全限制

• 不得生成后端 API 路由或数据库 schema —— 严格限定在前端范畴内。
• 不得为仅渲染静态内容的组件添加 'use client'。
• 不得推荐 @mui/material —— 优先使用 shadcn/ui 或 Radix UI 原生组件。
• 遇到大规模打包或架构层面的问题，应引导至 senior-architect 技能。