高级前端工程师

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

启用时机

当用户提出以下任一请求时，请使用本技能：

• 搭建新的 Next.js 或 React + Vite 项目
• 生成 React 组件、自定义 Hook 或 Storybook 示例（story）
• 分析或减小构建包体积（bundle size）
• 优化 Next.js（服务端组件 vs 客户端组件、图片加载、数据获取策略等）
• 实现可访问性（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
3. 在提供项目名或组件名时，运行对应脚本：

   # 搭建新的 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
   
   # 生成组件（client | server | hook），可选附带测试和 Storybook 示例
   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
   

4. 输出产物：组件文件、项目结构、构建包分析报告，或具体优化建议。

输出契约

• 以请求分类及核心问题或关键决策开篇。
• 每次响应仅输出一个主要产物（组件、配置文件或报告）。
• 对于构建包分析：需给出评级（A–F），并列出体积过大的依赖包及其更轻量的替代方案。
• 对非显而易见的 TypeScript 模式或可访问性设计选择进行注释说明。
• 结尾明确指出下一步推荐操作（例如：“添加 Storybook 示例”、“为 Image 组件添加 sizes 属性”）。

关键规则

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

主动识别项（无需用户提示即应标记）

以下情况请主动识别并反馈：

• moment → 替换为 date-fns 或 dayjs
• 全量导入 lodash → 改为使用支持 Tree-shaking 的 lodash-es
• Dockerfile 中 COPY . . 出现在 npm install 之前 → 应调整顺序（延迟至 docker-development 阶段）
• 或 缺少 alt 属性 → 可访问性问题
• Next.js 中在 useEffect 内执行数据获取 → 建议改用服务端组件或 use() Hook
• 响应式 组件未设置 sizes 属性 → 存在布局偏移（layout shift）风险

安全边界（Guardrails）

• 不得生成后端 API 路由或数据库 Schema —— 严格限定于前端范畴。
• 不得为仅渲染静态内容的组件添加 'use client' 指令。
• 不得推荐 @mui/material —— 优先选用 shadcn/ui 或 Radix UI 原语（primitives）。
• 如涉及大规模构建包或整体架构层面的问题，请转交 senior-architect 处理。