frontend-engineering

前端工程方法论

前端工程是构建应用面向用户的层面的技艺，包括组件、状态管理、API 集成、响应式布局和客户端性能。这套方法论衔接 UX 设计（用户旅程、线框图、无障碍标准）与质量验证（qa-methodology）。

前端工程师的职责范围

你负责	你不负责
组件实现 — UI 组件组合、props/state 接口、渲染模式、生命周期	用户旅程、线框图、无障碍标准、交互设计 — 这些属于 product-design-and-ux
状态管理 — 客户端状态架构、数据获取模式、缓存、乐观更新	API 契约设计 — 这属于 api-design-and-evolution
API 集成 — 前端到后端的数据流、身份验证流程（OAuth、JWT）、实时更新	测试策略和自动化 — 这属于 QA-engineer
响应式设计实现 — 布局系统、断点、跨设备测试	视觉识别和品牌指南 — 这属于 brand-designer
客户端性能 — 包优化、延迟加载、Core Web Vitals、渲染优化	编辑内容和文案 — 由内容和营销团队负责，不在本技能的范围内
前端测试 — 组件测试、集成测试、视觉回归、无障碍测试	代码审查和质量门禁 — 这属于 qa-methodology
前端功能的端到端测试场景和用户流程覆盖	操作浏览器测试工具（Playwright）— 编写/运行规格、选择器、网络模拟、网页抓取 — 请参阅 playwright
移动应用实现（iOS/Android/Flutter/React Native）	移动平台工作 — 项目搭建、构建和代码签名、设备/模拟器测试、应用商店提交、移动端生命周期 — 请参阅 mobile-development；本技能负责 Web 前端
构建工具 — 打包器配置、TypeScript 配置、代码检查、格式化、开发环境	CI/CD 流水线基础设施 — 这属于 platform-engineer

对于 React 组件和 hooks 相关工作，请加载 react；对于 Vite 配置、模式、插件和构建，请加载 vite。本技能仍负责与框架无关的架构和前端策略。

参考文件

参考文件	加载时机
references/component-architecture.md	设计组件树时 — 组合模式、props/state 接口、生命周期、无障碍基础知识
references/state-management.md	选择和实现状态管理时 — 客户端状态与服务端状态、数据获取、缓存、乐观更新
references/api-integration.md	将前端连接到后端时 — API 客户端设计、身份验证令牌流程、UI 中的错误处理、实时订阅
references/responsive-layout-testing.md	实现响应式设计（布局系统选择 — Grid 与 Flexbox 与 Container Queries、断点策略、跨设备测试方法）以及测试前端代码（使用 Testing Library 进行组件测试、使用 Playwright/Cypress 进行集成测试、视觉回归、使用 axe-core 和 Lighthouse CI 进行无障碍测试、测试数据管理）
references/performance.md	优化客户端性能时 — Core Web Vitals、包分析、代码拆分、渲染优化

模板

模板	使用时机
templates/component-state-design-record.md	为某项功能设计组件树和状态归属时 — 分解、状态作用域、数据获取以及错误/加载体验
templates/performance-budget.md	定义性能目标时 — 包体积预算、Core Web Vitals 预算、测量设置和 CI 强制执行

脚本

脚本	使用时机
scripts/bundle-budget-checker.py	检查 bundle 大小报告是否符合总预算和各分块预算；超出预算时会失败（退出码为 1），以便 CI 阻止性能回退

核心原则

组件是组合的基本单位，而不是页面 — 将组件设计并构建为可复用、可组合的单元。页面由组件组装而成，而不是构建成整体。设计良好的组件可以在创建者从未设想过的场景中复用。

将状态与需要它的组件放在一起 — 并非每一份状态都应放入全局存储。局部状态留在局部。服务端状态需要获取并缓存。只有真正共享的应用状态才应放入全局上下文。

为每种状态进行设计，而不只是理想情况 — 每个依赖数据的组件至少有四种状态：加载、空、错误和成功。为这四种状态都进行设计并非可有可无，而是能打造更有韧性的用户体验。

无障碍不是一项功能，而是必需条件 — 键盘导航、屏幕阅读器支持、色彩对比度和焦点管理都不是增强项，而是实现约定的一部分。

性能关乎用户体验 — 加载时间的每一毫秒、每一次布局偏移、每一次卡顿的交互，都会削弱用户的信任。性能预算、bundle 分析和渲染优化都是前端工程的一部分，而不是事后才考虑的事项。