software-frontend

前端工程

在 React、Next.js、Vue、Nuxt、Angular、Svelte 及相关工具链中进行生产级 Web 前端开发时，请使用此技能。它涵盖框架选择、前端实现模式、水合与 SSR 调试、状态管理与数据获取模式，以及前端发布规范。

快速参考

任务	使用
全栈 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

何时使用此技能

• 构建或搭建前端应用。
• 修复水合、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。
• 专注于编写端到端测试：使用 qa-testing-playwright。
• 在 Web 应用中实现自然对话式聊天界面（Chrome 内置 AI window.ai、WebLLM / transformers.js 浏览器内推理、云端 LLM 流式传输，以及设备端不可用时的确定性回退）：使用 ai-context-layer/references/conversational-surfaces-cross-platform.md。

默认选择

• 根据路由和渲染需求选择合适的框架，不要盲目默认使用某一种技术栈。
• 优先选择仓库中已有且广泛采用的稳妥方案，而不是最新的框架特性。只有在某项新原语（渲染模式、编译器、路由约定）稳定发布一段时间后，且团队有明确理由时，才采用它——不要仅仅因为它是新的。
• 保持仓库结构；对于新应用，使用官方 CLI 脚手架以及对应的脚手架后检查清单。
• 添加新的提供程序、存储或约定前，先查找仓库本地的前端模式。
• 将无障碍性和性能视为发布门槛。
• 采用某个 API 前，先检查已安装的框架、锁文件和官方迁移指南。仅将 data/versions.json 用作带日期的发现快照；固定版本前确认其受支持。
• 迁移 TypeScript 编译器时，检查官方发行说明以及每个依赖 API 的工具的支持情况：类型化 ESLint、vue-tsc、Angular 编译器和 svelte-check。确认兼容性之前，使用这些工具支持的编译器版本线；保留锁文件中的精确解析结果。

按能力划分的 React 原语

采用前先检查已安装的 React/react-dom 以及框架兼容性；以下版本是功能边界，不是当前版本固定值。

• React 19.2：Activity 在清理其 Effects 的同时保留隐藏 UI 状态；useEffectEvent 在由 Effect 触发的逻辑中，于调用时读取 props/state，且不改变 Effect 的响应式依赖。它不是抑制依赖项的变通手段。cacheSignal 用于 RSC 缓存生命周期/取消操作，而不是客户端缓存。参见发行说明。
• React 19.3：ViewTransition 为过渡更新添加动画；Fragment refs 无需额外包装即可提供分组 DOM 操作；React/react-dom 中的 use(browser()) 会通过 Suspense 回退，让仅适用于浏览器的组件退出 SSR。尽可能保留有意义的服务器 HTML。参见发行说明。
• 使用框架支持的渲染/缓存集成，而不是引入原始 React 预渲染/恢复流程。针对所选原语，确认 Hooks lint 支持以及浏览器/减少动态效果行为。

工作流

1. 明确渲染模型、路由需求、SEO 约束和部署形式。
2. 选择适合问题的框架和模板。
3. 仅加载与用户所用框架或问题相匹配的参考资料。
4. 按照仓库本地的状态管理、数据获取、样式和测试模式进行实现。
5. 签字验收前，检查 hydration、无障碍性、性能和交接要求。

核心决策

框架选择

需求	框架	说明
全栈 React、SEO	Next.js	App Router；RSC 用于服务端组件；固定次版本前，请查看 data/versions.json 中的 next，确认当前主版本
以路由为中心的渐进增强	React Router（框架模式，默认）	Loader/action 数据契约。对于旧版 Remix，选择新的脚手架前，请查看官方迁移／支持指南；不要假设其他 Remix 分支也采用 React Router 框架 API
仅客户端的 React SPA	Vite + React	无 SSR 复杂性
Vue 全栈	Nuxt	自动导入、服务端路由；Vapor 模式（无虚拟 DOM）为可选项，在确认 Nuxt、Pinia 和 VueUse 支持之前并非默认模式——引用版本前，请查看 data/versions.json 中的 vue 条目以及 vuejs.org/about/releases
Angular 应用	Angular（当前主版本，参见 data/versions.json 中的 @angular/core）	独立组件、优先使用信号、无区域变更检测；固定版本前，请查看 angular.dev/reference/releases，确认当前主版本和 LTS 版本线，并查看 angular.dev，确认该主版本中的无区域默认设置
Svelte 优先	SvelteKit	基于 Runes 的响应式；请查看 data/versions.json 中的 svelte，确认当前主版本

先选择渲染模式（CSR / SSR / SSG / 混合），再选择框架。当两个框架都适用时，优先选择团队已在生产环境中使用的框架——引入第二种框架会带来持续的实际成本（构建工具、测试配置、招聘、思维上下文切换），而这些成本很少能通过单个功能得到回报。

服务端与客户端渲染的判断

• 对于主要承载内容、对 SEO 敏感，或受益于快速首次绘制且无需发送客户端数据请求瀑布的场景，默认采用服务端渲染（RSC、SSR 或 SSG）。
• 有意选择客户端渲染：高度交互的组件、SEO 无关的登录后应用，或必须无需往返请求即可保留状态的场景（拖放、画布／WebGL、实时协作）。
• 每个客户端组件都有水合成本：在组件可交互之前，JS 必须发送、解析并执行。将 'use client'（或框架中的对应方式）视为需要主动选择的成本，而不是免费的捷径——只在实际需要交互性的组件树下层使用，而不要因为某个子组件需要 onClick 就把整个路由树标记为客户端渲染。
• 如果组件只有一小部分需要交互性（例如手风琴切换、工具提示），通常可以让组件继续采用服务端渲染，只在该部分周围添加一个小型客户端岛，而不是将整页改为客户端渲染。

设计系统与组件库

• 组件库（shadcn/ui、Radix、Angular Material、PrimeNG、Nuxt UI）提供没有或只有少量预设风格的构建块——按钮、对话框、表单控件等——以及行为原语，但仍需进行符合无障碍要求的组合、添加标签、管理焦点并验证；视觉语言很大程度上由使用者决定。
• 设计系统是一项产品决策：一套有文档、有版本管理的设计令牌（颜色、间距、字体比例）和使用规则，通常还会在一个或多个组件库之上提供组件 API。它旨在确保产品在不同团队和时间维度上保持视觉与行为一致。
• 如果组件库已经能解决问题，就不要构建设计系统——对于单个应用或小团队，这通常属于过度设计。当多个团队或产品需要保持外观和行为一致，或同样的视觉不一致问题在多个 PR 中反复出现时，应当采用设计系统（或至少共享设计令牌）。
• 如果代码仓库已有设计系统，应将其组件 API 视为权威来源，而非底层组件库的原始组件——除非设计系统确实存在缺口，否则不要绕过设计系统，直接使用 Radix/shadcn 原语。

状态与数据获取

数据类型	默认工具	仅在以下情况下添加
服务端状态（异步、已缓存）	TanStack Query（或路由器已提供加载器时使用框架加载器）	仅当仓库已统一使用 SWR 时才使用它
全局客户端状态（跨路由共享）	Zustand（Vue 中使用 Pinia）	仅当状态确实是原子化／细粒度的，而非只是需要共享时，才改用 Jotai
RSC 应用中由服务端拥有的状态	服务端组件 + React cache	仅当交互式／乐观 UI 需要时才使用客户端状态库
URL 驱动的状态（筛选、分页）	URL 搜索参数	不要将其重复存入状态库

当本地状态或服务端驱动模式已足够时，不要创建新的全局状态层。

UI 状态完整性检查

列出界面实际可能达到的每种状态，并有针对性地处理。适用时，加载、空、错误和成功是基本状态；仅当数据和授权契约可能产生相应状态时，才添加后台刷新、部分加载、过期、权限被拒、可恢复和终止等状态。审查时明确标记不适用的状态。在适当情况下，重试时保留用户输入和最后一次安全渲染的状态。

Hydration 与 SSR 安全性

注意：

• SSR 期间使用仅限浏览器的值
• 在服务端组件中使用客户端 Hook
• 过期的 Effect 依赖项
• 重构后路由和链接发生偏移

如果问题看起来与 hydration 有关，请从 references/production-gotchas.md 入手。

发布规范

最低发布门槛：

• 对编辑过的文件运行 Lint
• 对修改涉及的部分进行类型检查（tsc --noEmit 或等效命令）
• 交付前运行一次范围更广的 Lint、类型检查和构建
• 无障碍门槛：自动化检查，并针对受影响的行为进行键盘／辅助技术验证；仅通过 axe-core 检查并不能证明符合 WCAG 2.2 AA。WCAG 2.2 增加了新准则，但移除了 4.1.1 Parsing；如果某项政策要求符合 2.1，则按需继续测试／报告该准则。欧盟（EAA）：法律依据是《官方公报》中引用的 EN 301 549 版本；在采用 WCAG 2.2 的更新版本被引用之前，它并非法律最低要求。将 2.2 AA 作为工程目标，并从 software-accessibility 确认引用状态
• 性能预算：在面向用户的路径上，页面加载的第 75 百分位 LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1（现场数据，分别统计移动端和桌面端）
• 已验证 hydration：导航后，SSR/RSC 页面控制台中无错误
• 检查 AI 生成的代码是否违反 Hook 规则、原生语义薄弱或 ARIA 不正确

AI 生成的前端代码风险

AI 生成的前端代码常见问题：

• 违反 Hook 规则
• 混淆客户端／服务端边界
• 滥用 div，语义薄弱
• 闭包过期和依赖项缺失
• 组件中过度获取数据
• 键盘和屏幕阅读器支持薄弱
• 导入项在项目实际依赖树中不存在，或虽然存在，但其版本／API 形式与生成代码的假设不符
• 组件重新实现了仓库中已有的模式（例如第二种模态框实现、并行的数据获取封装），而非沿用现有模式

应将这些问题视为需要检查的预期缺陷，而非罕见边缘情况。接受 AI 生成的前端代码之前，应对照真实代码库进行验证，而不只是判断其内部逻辑是否合理：确认每个导入项都能在 package.json／锁文件中解析，确认所用的组件／Hook API 与已安装版本一致（而非模型训练数据中更新或更旧的版本），并确认样式和数据获取方式符合仓库本地惯例，而不是引入第二套相互竞争的模式。

输出模式

默认采用以下其中一种：

• 前端实现计划： 框架、模板、状态、测试和发布门槛。
• 问题诊断： 可能的前端故障模式、受影响的层级和修复路径。
• 脚手架建议： 框架选择、模板和理由。
• 生产环境加固简报： 水合、性能、无障碍和测试检查清单。

已知陷阱

• 在 SSR 或支持 RSC 的技术栈中，随意跨越服务端和客户端边界，之后再调试那些由渲染模型本身导致的水合不匹配。
• 在服务端渲染期间读取仅限浏览器的值，并假设框架能安全地协调差异。
• 在确认本地状态和服务端状态工具无法满足需求之前，就引入新的全局状态存储。
• 重构路由、链接或布局组合，却不验证 SEO、导航语义和 URL 行为是否保留。
• 接受看似合理、实际却悄悄导致语义、键盘支持或 Hook 正确性退化的 AI 生成组件代码——导入项在当前安装版本中无法解析，或在现有模式旁又添加了另一套模态框或数据获取模式。
• 因为某个框架时髦就选择它，而不是根据它是否符合渲染模型来选择。

导航

• 框架参考：references/fullstack-patterns.md、references/vite-react-patterns.md、references/remix-react-patterns.md、references/vue-nuxt-patterns.md、references/angular-patterns.md、references/svelte-sveltekit-patterns.md
• 运维参考：references/production-gotchas.md、references/operational-playbook.md、references/state-management-patterns.md、references/testing-frontend-patterns.md、references/performance-optimization.md、references/web-platform-apis.md（原生浏览器替代方案；通过特性检测确认支持情况）、references/artifacts-builder.md、references/mui-integration-notes.md（MUI 主题、SSR、MUI X 许可、表单集成）
• 模板：assets/nextjs/template-nextjs-tailwind-shadcn.md、assets/vite-react/template-vite-react-ts.md、assets/remix/template-remix-react.md、assets/vue-nuxt/template-nuxt4-tailwind.md、assets/angular/template-angular21-standalone.md（脚手架搭建后的检查清单）、assets/svelte/template-sveltekit-runes.md
• 相关技能：software-backend、software-ui-ux-design、software-localisation、qa-testing-playwright、ops-devops-platform

源映射位于 data/sources.json。

经验总结循环

当先前的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史记录或它是可用的备用文件时，才使用 learnings.md。否则跳过这两个文件。

应用经验后，如果遇到了值得记住的模式、值得避免的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目符号。不要修改 SKILL.md 本身。