用途
该技能面向生产环境的 Web 前端工作，覆盖 React、Next.js、Vue、Nuxt、Angular、Svelte 及其相关工具链。它负责框架选择、前端实现模式、hydration 与 SSR 调试、状态与数据获取模式，以及前端发布规范。
适用场景包括：构建或脚手架化前端应用；修复 hydration、SSR、构建或客户端-服务端边界问题；选择路由、状态、数据获取与组件模式；配置前端测试、性能预算与发布门禁；使用现代框架以生产安全默认值实现 UI。
不在范围内的情况：后端 API 或服务实现使用 software-backend；API 契约设计使用 dev-api-design；UI/UX 设计使用 software-ui-ux-design；无障碍实现与修复使用 software-accessibility；正式审计与测试使用 qa-testing-accessibility；性能审计使用 software-performance；移动原生开发使用 software-mobile；国际化设置使用 software-localisation；E2E 测试编写使用 qa-testing-playwright。Web 应用中的对话式聊天界面（Chrome window.ai、WebLLM / transformers.js 浏览器内推理、云 LLM 流式传输，并带设备端不可用时的确定性回退）参见 ai-context-layer/references/conversational-surfaces-cross-platform.md。
主要能力
技能按任务提供参考文档与模板，例如：全栈 React 应用对应 references/fullstack-patterns.md 与 assets/nextjs/template-nextjs-tailwind-shadcn.md；React SPA 对应 references/vite-react-patterns.md 与 assets/vite-react/template-vite-react-ts.md；React Router 或 Remix 对应 references/remix-react-patterns.md 与 assets/remix/template-remix-react.md；Vue 或 Nuxt 对应 references/vue-nuxt-patterns.md 与 assets/vue-nuxt/template-nuxt4-tailwind.md；Angular 对应 references/angular-patterns.md 与 assets/angular/template-angular21-standalone.md（脚手架后检查清单，使用已安装 CLI）；Svelte 或 SvelteKit 对应 references/svelte-sveltekit-patterns.md 与 assets/svelte/template-sveltekit-runes.md。状态、测试、性能与陷阱对应 references/state-management-patterns.md、references/testing-frontend-patterns.md、references/performance-optimization.md、references/production-gotchas.md、references/operational-playbook.md。
使用方式
工作流程为：澄清渲染模型、路由需求、SEO 约束与部署形态；选择匹配问题的框架与模板；只加载与用户框架或问题匹配的参考文档；使用仓库本地模式实现状态、数据获取、样式与测试；在签核前检查 hydration、可访问性、性能与交接要求。
默认约定：按路由和渲染需求选框架，而不是盲目默认某一技术栈；优先使用仓库中已采用的保守选择，而非最新框架特性；保留仓库结构，新应用使用官方 CLI 脚手架与匹配的脚手架后检查清单；在新增 provider、store 或约定前先搜索仓库本地前端模式；将可访问性与性能视为发布门禁；采用 API 前检查已安装框架、锁文件与官方迁移指南。
适用场景与核心决策
框架选择：全栈 React 与 SEO 选 Next.js；路由为中心的渐进增强选 React Router（框架模式，默认）；仅客户端 React SPA 选 Vite + React；Vue 全栈选 Nuxt；Angular 应用选 Angular；Svelte 优先选 SvelteKit。先选渲染模型（CSR / SSR / SSG / 混合），再选框架。两个框架都适合时，默认选择团队已在生产中使用的一个。
服务端与客户端渲染取舍：内容为主、SEO 敏感或需要快速首屏的场景默认服务端渲染（RSC、SSR 或 SSG）；高度交互的组件、登录后且 SEO 无关的应用，或必须不经往返即可保留的状态（拖拽、canvas/WebGL、实时协作）才谨慎选择客户端渲染。每个客户端组件都有 hydration 成本，将 'use client' 视为需主动付出的成本，尽可能下推到树中真正需要交互的位置。
设计系统与组件库：组件库（shadcn/ui、Radix、Angular Material、PrimeNG、Nuxt UI）提供不带或轻度带观点的构建块；设计系统是产品决策，是文档化、版本化的 token、使用规则与组件 API 集合。单一应用或小团队不要自建设计系统，多团队或多产品需要一致性时再坚持设计系统。仓库已有设计系统时，以其组件 API 为准。
状态与数据获取：服务端状态（异步、缓存）默认 TanStack Query（或路由已提供的框架 loader），仅当仓库已标准化 SWR 时使用 SWR；全局客户端状态（跨路由共享）默认 Zustand（Vue 中为 Pinia），仅当状态真正原子/细粒度时切换 Jotai；RSC 应用中的服务端拥有状态用服务端组件 + React cache；URL 驱动状态（筛选、分页）用 URL 搜索参数，不要复制到 store。
UI 状态完整性门禁：枚举界面实际可达的每个状态并逐一处理。加载、空、错误与成功是适用的基线；仅当数据与授权契约能产生时，才增加后台刷新、部分、过期、权限拒绝、可恢复与终态变体。
限制与注意事项
Hydration 与 SSR 安全需注意：SSR 期间使用仅浏览器值、服务端组件中使用客户端 hook、过期的 effect 依赖、重构后路由与链接漂移。若 bug 疑似 hydration，先从 references/production-gotchas.md 入手。
发布门禁最少包括：lint 已编辑文件；对改动面做类型检查（tsc --noEmit 或等价）；交接前运行更广泛 lint、类型与构建一次；可访问性门禁（自动化检查加键盘/辅助技术证明，仅 axe-core 通过不足以确立 WCAG 2.2 AA 合规）；性能预算（用户路径上第 75 百分位 LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1，现场数据，移动与桌面分开）；hydration 验证（SSR/RSC 页面导航后无控制台错误）；检查 AI 生成代码的 hook 规则违规、弱原生语义与错误 ARIA。
AI 生成前端常见风险：hook 规则违规、客户端/服务端边界混淆、div 汤与弱语义、过期闭包与缺失依赖、组件中过度获取、键盘与屏幕阅读器行为薄弱、导入在项目实际依赖树中不存在或版本/API 形态不匹配、组件重新发明仓库已有模式（第二个 modal 实现、并行 fetch 封装）。接受 AI 生成前端代码前，需对照真实代码库验证，而非仅看其自身合理性。
已知陷阱还包括：在 SSR 或 RSC 技术栈中随意跨越服务端与客户端边界，再调试渲染模型内置的 hydration 不匹配；服务端渲染时读取仅浏览器值并假设框架会安全调和；未检查本地状态加服务端状态工具是否已覆盖问题就引入新全局 store；重构路由、链接或布局组合而不验证 SEO、导航语义与保留的 URL 行为；因流行而非匹配渲染模型选择框架。
输出模式默认为：前端实现计划（框架、模板、状态、测试与发布门禁）；问题诊断（可能的前端故障模式、受影响层与修复路径）；脚手架推荐（框架选择、模板与理由）；生产加固简报（hydration、性能、可访问性与测试检查清单）。
学习循环：相关时查阅 learnings.consolidated.md（若存在），仅在需要历史或作为可用回退时使用 learnings.md，否则跳过两者；应用后若有值得记住的模式、需预防的错误或令人意外的领域事实，通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点，不要修改 SKILL.md 本身。