前端工程 是做什么的？
在撰写文案、注释或报告前，请先阅读 anti-ai-writing。阅读仓库说明、现有屏幕与组件、设计令牌、框架/依赖版本、路由、数据契约与测试规范。使用现有技术栈与工具；对于不熟悉的 API，请查阅该版本对应的官方文档。保留不相关的已有工作与既定产品行为。
确定屏幕的职责与设计
明确受众、用户任务、主要操作、内容层级、所需状态及验收标准。优先使用已有的设计和产品模式。对于实质性的新界面，需澄清缺失的关键需求，并在计划有帮助时使用 agent-planning。对于已明确的小改动，无需进行设计仪式。
当需要新的视觉方向时，研究相关参考，将其有用的层级、密度、导航和交互原则转换为产品自身的语言。不要复制专有品牌标识、文本、素材或精确布局。记录足够的设计决策以指导实现，但不要为单个屏幕创建一整套设计系统。
使用项目令牌中一致的排版、间距、颜色、圆角和强调方式。优先考虑用户的操作和信息，而不是默认使用通用英雄区、统一卡片、过大间距或装饰性渐变。当产品需要时，这些模式可以适当使用；不要施加审美禁令。使用真实内容，包括长标签和稀疏/密集数据。从产品文案中移除不相关的实现细节。保持所有公开控件可用，或明确标识为不可用；绝不可将占位符伪装成工作功能。
实现清晰的组件与状态
对于变更的前端/后端契约，使用 api-design 并保留所支持的消费者。不要从 UI 固定数据中推断后端契约。
使用 writing-clean-simple-code 确保职责清晰、抽象合理。优先选择组合和已建立的组件 API，而非大量不相关标志的矩阵。按职责拆分，而非按任意代码行数。保持数据与展现的归属清晰，但不要强制每个组件都使用单独的容器或 hook。
将状态放置在其所属位置：本地交互状态、共享状态、用于可导航/可分享视图的 URL 状态，以及用于远程数据的现有服务器状态工具。避免重复的派生状态和矛盾的布尔值。不要仅仅为了减少几个 props 就引入全局存储。在相关场景下，保留稳定的条目标识、历史导航、深度链接以及框架的渲染/水合契约。
处理适用的加载、空数据、成功、错误、禁用、待处理和权限状态。区分“无数据”与“筛选后无结果”。在可恢复错误后保留已输入的数据，说明如何继续操作，并防止重复提交。对于乐观更新，需考虑失败、并发变更、过期响应和一致性恢复。在取消共享请求前，明确取消的归属。切勿使用隐藏控件作为授权方式；服务端强制执行始终是必需的。
使布局与交互具有包容性
阅读 无障碍与响应式检查指南。优先使用原生语义 HTML 和经过测试的无障碍基础组件。自定义交互必须实现完整的键盘、焦点和状态契约。标签、错误和状态反馈应无需依赖颜色或动画即可理解。
根据内容需要选择断点，并尊重已有的布局令牌。使用弹性布局、合适的宽度限制和响应式素材。检查窄屏与宽屏、缩放、长文本、空状态及溢出。在小型屏幕上保留有意义的内容和操作，而非为了适配截图而隐藏它们。
保证安全与性能
将远程内容和 URL 视为不受信任。使用框架安全的渲染方式；仅在需要富 HTML 时，通过经过验证的机制进行转义。切勿在客户端 bundle、遥测或错误消息中暴露密钥或私有记录。将缓存数据限定到身份/租户，并在相关上下文变化时清除或使其失效。
避免不必要的 fetch 瀑布、昂贵的重复计算、过大的依赖以及布局偏移。使用框架的资产、渲染和加载约定。基于实测证据和产品预算进行优化；不要机械地添加记忆化、虚拟化或代码分割。实验室结果与现场性能是不同的证据，应分别报告。
验证渲染结果
使用 test-authoring 实现行为覆盖。运行相关仓库检查，并在可用浏览器中使用真实数据检查应用。测试受影响的操作和状态转换、键盘导航、焦点、验证、响应式布局及适用的浏览器目标。检查与变更相关的控制台和网络失败信息。截图仅用于确认外观，而非交互正确性；自动化无障碍扫描不能确认合规性。
将渲染输出与已接受的设计或项目已有的屏幕进行比较。修复发现的裁剪、间距、对比度或交互问题，并重新检查受影响的状态。切勿仅为验证 UI 而运行破坏性的实时操作；应使用安全的固定数据或已授权的测试环境。如果无法访问浏览器，应明确说明哪些内容仍未验证，而非称该界面已通过视觉验证。
报告实际变更、测试过的流程/视口以及实质性限制。当需要独立审查且获得授权时，使用 code-review。提交、推送和发布使用已授权的 git-delivery。