前端开发技能
高级、务实、生产级的前端工程。目标始终是编写可工作、可维护、高性能的代码，而非学术上的纯粹。
栈检测
在所有操作之前，从上下文中识别技术栈。如果不明确，请询问。然后加载相应的参考文件。
| 栈 | 加载 |
|---|---|
| React (不含 GraphQL) | references/react.md |
| React + GraphQL/Relay | references/react-graphql.md |
| Angular | references/angular.md |
| TypeScript (所有栈) | references/typescript.md (与栈文件同时加载) |
始终加载 references/typescript.md 以及栈文件，除非项目明确仅使用 JS。
通用原则
无论使用何种技术栈，这些原则都适用。不要跳过它们。
架构
- 积极分离关注点：UI 渲染、业务逻辑、数据获取和副作用应位于不同层。组件不应包含 fetch 调用、原始 API 字符串或业务规则。
- 按功能聚集，而非按类型：优先使用
features/user-profile/结构（包含组件 + hook + 测试 + 样式），而非顶层components/、hooks/、tests/文件夹。根据应用复杂度调整结构规模——不要为小型应用过度设计。 - 组合优于继承：通过组合小型、专注的组件来构建 UI。避免深层组件层级。
- 不进行过早抽象：先写两次，然后再抽象。基于单一用例的抽象通常是错误的。
组件设计
- 组件应只做一件事。如果一个组件有多个变更原因，则将其拆分。
- 将展示组件（纯 UI，无副作用）与容器/智能组件（数据、逻辑、编排）分开。
- Props 接口应显式且具有类型。不允许使用
any、object或{}作为类型。 - 默认对表单使用受控组件。
性能（不可妥协的基线）
核心 Web 指标目标（衡量真实用户的第 75 百分位数）：
- LCP ≤ 2.5 秒（加载）
- INP ≤ 200 毫秒（交互性——自 2024 年 3 月起取代 FID）
- CLS ≤ 0.1（视觉稳定性）
通用性能规则：
- 绝不使用长时间同步任务阻塞主线程
- 默认对路由和重型组件进行懒加载
- 为所有图像和媒体设置显式尺寸（防止 CLS）
- 在 LCP 图像上使用
fetchpriority="high" - 延迟加载非关键第三方脚本
- 避免布局抖动（批量进行 DOM 读写）
- 启用 bfcache 资格：避免使用
unload监听器，除非必要避免使用no-store
设计系统与令牌
- 将设计令牌（颜色、间距、排版、圆角、阴影）定义为真实来源——绝不在组件中硬编码值
- 使用 CSS 自定义属性 (
--color-primary) 或令牌系统（Style Dictionary、Tailwind 配置）以便集中管理主题 - 原子设计作为心智模型：原子 → 分子 → 有机体 → 模板 → 页面。不强制命名，但按此层级思考
- 在 Storybook 中记录组件，以便隔离、发现和视觉回归测试
- 无障碍不是可选项：WCAG 2.1 AA 最低标准。每个交互元素都需要键盘支持、焦点管理，以及在语义 HTML 不足时使用 ARIA
API 集成
- 绝不在组件中直接调用 API。使用数据层：自定义 hooks、服务或查询库
- 显式处理所有三种状态：加载、错误、成功——绝不假设一切顺利
- 在变更操作中使用乐观更新以提高用户感知性能
- 在边界处验证 API 响应（Zod、io-ts 或等效工具）——不要信任外部数据形状
- 集中管理 API 基础 URL 和认证令牌注入——绝不在组件中分散处理
测试策略
三层方法：
- 单元测试：纯函数、工具函数、自定义 hooks（Jest / Vitest）
- 组件测试：渲染行为、用户交互、状态变更（Testing Library —— 测试行为，而非实现）
- 端到端测试：仅针对关键用户路径（Playwright 或 Cypress）
规则：
- 从用户的角度测试行为，而非内部实现
- 逻辑部分不使用快照——它们很脆弱。仅在有意进行视觉回归时使用快照
- 旨在对业务逻辑实现高覆盖率，而非样板代码
- 将测试文件与所测试的代码放在一起：
Button.test.tsx与Button.tsx相邻
代码导航（tsserver）
通用的 LSP 文本搜索工作流程在 dev-standards 技能（"Code navigation"）中。TypeScript 特定说明：
LSP 工具路由到 tsserver 处理 TS/TSX。单文件操作在冷启动时可靠：documentSymbol、hover、goToDefinition。
警告 —— tsserver 的索引是懒加载的（与 gopls 不同）。 针对冷服务器运行的跨文件查询（findReferences/workspaceSymbol）可能会少计数：它只了解已加载到其项目中的文件，并返回一个看似自信但不完整的结果（例如仅返回声明）。防御方法：
- 将可疑的低引用计数视为未经验证。
- 从使用处（导入该符号的文件）查询
findReferences，而不是单独在声明处——这会强制加载项目图。 - 对于“此代码是否仍被使用？”的决策（死代码删除、安全重命名），请使用
grep确认——在此处少计数很危险。
工具默认配置（2025）
- 打包工具：Vite（新项目默认）；大型企业已有配置的可继续使用 Webpack 5
- 代码检查：ESLint +
@typescript-eslint+ Prettier（格式与 lint 分开） - 包管理器：首选 pnpm（用于 monorepo）；npm 或 yarn 也可接受
- 单仓：多包工作空间使用 Nx 或 Turborepo
- CI：在每个 PR 上运行类型检查、lint、测试和构建。绝不允许合并失败的流水线
输出模式
在生成输出时，请遵循以下指南：
组件代码：包含类型、处理边界情况、遵循参考文件中的栈模式。在同一个响应中提供组件及其测试，除非大小不允许。
架构 / 文件结构：首先展示目录树，然后解释理由。提供意见明确的建议——给出一个好的结构，而非一组选项。
性能审计：按严重程度（严重 / 警告 / 信息）列出发现。对每个发现：内容是什么、为何重要、如何修复。
设计系统设置：先令牌结构，然后组件原语，最后文档设置。
API 集成：展示针对特定栈的数据层模式，然后展示使用该模式的组件。
测试：将测试与所测试的代码一起展示。遵循 AAA（Arrange / Act / Assert）。
辅助技能
本技能涵盖工程方面。对于视觉美学——排版选择、颜色系统、动效设计、空间构图以及避免通用的 AI 美学——请参考 frontend-design 技能。在需要两者兼顾的任务上（例如“构建一个看起来很好的仪表盘”），同时使用这两个技能：frontend-dev 负责架构和代码质量，frontend-design 负责视觉方向。
参考文件
在生成栈特定输出之前，请阅读以下文件：
references/typescript.md— TypeScript 严格模式、模式、常见陷阱references/react.md— React 19、Next.js、hooks、状态管理、渲染策略references/react-graphql.md— Relay、共置片段、React 中的 GraphQL 模式references/angular.md— Angular v22、Signals、独立组件、无 Zone、NgRx