frontend-engineering

前端工程

以恰当的严谨程度帮助规划、设计、构建和维护前端软件。将此技能应用于 Web 前端，并在适用时用于移动端或桌面客户端。与框架无关：切勿假设使用某个特定框架、设计系统、状态库或构建工具；应根据实际技术栈调整示例。

此技能负责前端工程实践。如果问题涉及跨领域流程（文档层级、制品组织、需求发现），且有 solution-design 技能可用，请交由该技能处理，并仅在此处保留与前端相关的影响。

激活约定

在用户执行以下操作时加载此技能：

• 从头开始启动前端项目；
• 规划 UI、用户流程、组件系统或前端架构；
• 实现涉及多个屏幕或组件的功能；
• 评审前端的可维护性、UX、无障碍性、性能或测试；
• 创建或更新前端设计文档；
• 使前端行为与后端 API 或产品需求保持一致。

对于微小且孤立的改动，不要加载此技能：检查相关上下文，完成实现，运行适当的检查，并总结剩余风险——无需执行完整工作流。

硬性规则

1. 修改代码前先了解情况。 对于现有项目，先检查代码库、包清单、路由、组件、样式、测试和现有文档，再提出修改建议。绝不可假设项目一片空白。
2. 根据规模和风险调整做法。 根据复杂度、用户影响、无障碍需求、安全与隐私、性能要求、集成、团队规模和不确定性，选择轻量、标准或严谨的流程——不能只看屏幕数量。
3. 避免文档膨胀。 记录重要决策；只有在拆分文件有助于协作、评审、追溯或维护时，才创建单独文件。
4. 将需求与实现分开。 说明用户需要什么，并另行说明用于实现需求的技术方案。
5. 明确标示假设。 区分已确认的需求、假设、待解决问题和建议。绝不可悄悄编造产品行为、角色、品牌或 API。
6. 设计各种状态，而不只是理想路径。 视情况考虑加载、空内容、错误、成功、禁用、权限被拒绝、离线和数据不完整等状态。
7. 无障碍性和响应式行为从一开始就是质量要求，而非最后的润色步骤。
8. 确保文档与代码保持一致。 只更新受影响的文档；保留一个事实来源，通过链接引用而非重复内容。
9. 逐步验证。 优先采用小而可测试的用户可见功能切片，而不是大规模推测性设计阶段。
10. 遵循项目约定。 没有明确理由并说明权衡时，不要引入新库或架构模式。
11. 客户端不是信任边界。 切勿在客户端代码中放置机密或特权授权逻辑；客户端验证可以提升易用性，但绝不能取代服务端验证。

决策关卡

文档级别

观察到的信号	级别	产物
范围小、风险低、视图/流程少，由一名开发者负责或属于快速原型	轻量级	一份 docs/frontend/design.md（参见 templates/frontend-design.md），必要时加上 README；合并需求、流程、架构、UI 规则、API 假设、无障碍设计和测试
功能较多、组件共享、客户端状态有一定复杂度、存在集成或由团队负责	标准级	简洁的设计概述；仅在独立负责或频繁更新有必要时，才添加针对性文档（ui-flows.md、design-system.md、frontend-architecture.md、frontend-testing.md、ADR）
影响重大或受监管的流程、敏感数据、复杂权限、严格的无障碍/性能目标、团队众多或应用规模庞大	严格级	需求可追溯性、设计系统文档、架构决策记录、测试策略、性能预算，以及适用的安全/隐私审查

项目规模可以很小，但风险很高：应根据风险提高严谨程度。范围发生变化时，重新评估级别。重新评估触发条件和文档整合标准：references/workflow.md。

交接

问题	负责方
跨领域流程：需求发现、文档级别、产物组织	如果有，则由 solution-design 技能负责；否则沿用上述轻量流程
前端实践：组件边界、状态、UX、无障碍设计、测试、性能	本技能
API/数据库契约细节	如果有，则由 api-design / database-design 技能负责

执行步骤

1. 建立上下文。 全新项目：明确产品目标、用户、主要任务、设备/浏览器、品牌限制、无障碍预期、数据敏感性、API 依赖和约束；仅在答案会实质影响设计时提出有针对性的问题，否则记录假设。现有项目：先检查框架版本、路由、样式策略、组件规范、状态/数据获取方式、API 契约、测试和当前设计系统。
2. 根据上文的决策门选择文档级别，并简要说明原因。
3. 定义用户和界面需求。 用户类型和目标、关键流程、导航、屏幕职责、响应式行为和验收标准。如果不同角色的访问权限不同，记录哪些操作和视图允许、隐藏、禁用或拒绝——可见性是 UX 规则，而不是安全边界。只有在能减少歧义时才使用线框图/示意图；如果用户要求视觉设计，先确定输出格式（图像、可编辑样稿或实现），再做选择。
4. 设计前端架构。 路由、组件职责（共享或特定于功能）、状态归属和数据流、API 客户端行为、表单与验证、权限感知式呈现、配置、本地化和错误边界（如适用）。优先采用满足当前需求的最简单架构；不要引入臆测的框架、不必要的全局状态或过早抽象。参照 references/frontend-architecture.md 进行分析。
5. 定义 UX 和视觉行为。 信息层级、交互模式、在确有设计系统必要时定义设计令牌和组件变体、表单 UX、所有界面状态、响应式布局和无障碍基线。扩展现有设计系统，而不是另建一套相互竞争的系统；切勿臆造品牌颜色或字体——应明确标注占位内容或提出询问。参照 references/ui-ux-accessibility.md 进行分析。
6. 对齐 API 和数据契约。 根据后端契约确认端点、方法、架构、分页、验证错误和身份验证预期；复用现有 OpenAPI 或生成的客户端。如果契约未知，应将其标为假设，绝不能声称已完成集成。详情请参阅：references/frontend-architecture.md。
7. 从一开始就规划质量。 根据项目选择适当的检查项——单元/组件/集成/e2e 测试、无障碍检查（自动化加键盘/手动）、针对支持目标的响应式/跨浏览器检查，以及相关时的性能检查（打包体积、渲染、Core Web Vitals）；仅在确有必要时进行视觉回归测试。将验收标准与可观察的测试或记录在案的手动方法关联起来。参照 references/quality-testing.md 进行规划。
8. 按纵向切片规划实现。 以小步增量交付完整的用户可见功能；对每个切片，明确相关屏幕/组件、API 依赖、状态、验收标准和测试。尽早解决高风险未知项；不要要求先完整规定每个屏幕，才能交付有用的首个增量。
9. 实现、验证并维护。 对重要工作进行编辑前，先概述计划范围。遵循代码仓库规范，运行相关检查，并说明未运行的检查及原因。当重要决策、交互、契约或架构发生变化时，更新文档。评审时检查正确性、无障碍、安全/隐私、响应式行为、可维护性、性能和回归风险；区分已验证的问题与潜在隐患。

文档规则

• 从最小但实用的文档集开始；简要说明为什么需要任何单独的文档。
• 轻量级：以 templates/frontend-design.md 为基础，编写一份 docs/frontend/design.md。
• 标准/严谨：仅在拆分有助于使用或维护时拆分章节。不要重复完整的 API 定义、产品需求或后端/数据库规范——链接到其权威文档，并仅记录与前端相关的影响。
• 仅当省略某章节需要解释时，才将其标记为 Not applicable；否则直接省略。
• 状态重要时，将决策标记为 Confirmed、Proposed 或 Open question。

参考指南

仅阅读与当前任务相关的参考资料：

• references/workflow.md：项目生命周期、重新评估触发条件、整合标准。
• references/frontend-architecture.md：架构、组件边界、状态、路由、API 集成。
• references/ui-ux-accessibility.md：用户流程、界面状态、响应式设计、无障碍、设计系统。
• references/quality-testing.md：测试、性能、安全/隐私、发布检查。
• references/document-templates.md：轻量级和专用文档的建议章节。
• templates/frontend-design.md：适用于小型项目的简洁一体化设计文档模板。

输出约定

在设计或实现任务结束时，报告：

1. 创建或修改的文件（如果合并了文档，还需说明各项职责记录在哪些位置）。
2. 选择的文档级别及原因。
3. 最重要的假设。
4. 未解决的问题、阻塞项和待定的高影响决策。
5. 已运行的检查、未运行的检查及原因。
6. 建议的下一步工作。

完成检查清单

在将设计或实现任务视为完成之前，核实相关事项：

• 已理解用户目标和范围；
• 主要流程和验收标准明确；
• 组件与状态的职责划分合理；
• API 依赖和未知事项已明确；
• 已考虑适用的加载、空白、错误、成功和权限状态；
• 已处理响应式行为和无障碍；
• 不会仅依赖客户端处理安全敏感行为；
• 已运行适当的测试/检查，或已报告尚存的缺口；
• 文档简洁、内容最新且没有不必要的重复。