Frontend UI Engineering
Overview
构建或修改生产级用户界面。先读取项目真实设计系统、组件约定、数据与权限契约,再完成可访问、响应式、可验证的薄切片;不要用通用审美覆盖现有产品身份。
When to Use
- 新建或修改页面、组件、布局与交互
- 实现响应式、状态反馈或前端数据流
- 用户已经要求修复 UI/UX 问题并授权写代码
若任务只要求审计、点评或提出改进,先使用 skill:ui-ux-review,不要在审查阶段改源码。
1. Reconstruct the Local Contract
从目标路由或页面入口沿真实渲染路径读取:
- 项目级说明、设计文档和组件库
- 颜色、字号、间距、圆角、阴影与动效 token
- 共用组件、变体、主题和响应式规则
- API、权限、加载、空态、错误态与成功态契约
优先级固定为:项目设计系统 > 用户明确目标 > 可访问性与可用性 > 框架和浏览器事实 > 通用审美建议。外部清单只帮助发现问题,不能证明项目必须采用某种视觉风格。
需要逐项重建设计系统,或用户明确提供外部品牌、截图、站点或 DESIGN.md 参考时,读取 references/design-system-contract.md。外部资料先转换为项目 brief:固定来源版本,区分可迁移原则与禁止迁移的品牌资产,再映射到本地 token、组件 owner 和状态;不要直接复刻来源。
2. Plan One Thin Slice
一次选择一个可独立验证的用户结果,并写清:
- 目标用户和页面的单一任务
- 复用的组件、token、数据和权限入口
- 正常、加载、空、错、禁用和成功状态
- 移动端、桌面端、键盘与屏幕阅读器路径
- 对筛选、排序、分页、tab、展开项等状态显式决定 URL owner:需要刷新、分享、深链接或浏览器历史恢复时进入 query/hash/router;不进入时记录理由
- 页面包含 dialog、drawer、sheet、popover 或 toast 时,明确 overlay / layer owner、堆叠关系、滚动归属和关闭后的焦点与滚动恢复
- 引入新的 Web API、复杂 CSS 或非项目基线能力时,读取
references/design-system-contract.md的 Browser Capability Decision,记录支持策略、能力检测和核心流程 fallback - 可观察的验收标准
缺少设计稿时,从真实业务内容和现有页面推导,不虚构实时指标、入口或权限。若必须新建设计方向,先说明主题、受众、页面任务和一项有理由的视觉特征。
3. Implement with Existing Owners
- 优先语义化 HTML 和既有组件,不用
div模拟按钮或链接 - 组件保持单一职责;数据获取与纯展示分离
- 状态放在最小正确作用域:本地、父级、URL、服务端缓存或全局 store
- 样式使用项目 token 和既有尺度,避免散落的任意值
- 复用已有 owner;重复代码本身不足以证明应抽象新组件
- 动效必须服务于状态、方向或层级,并尊重用户的 reduced motion 偏好
- 乐观更新必须能够失败回滚或提供撤销
不要把某一上游的阴影、圆角、动画或框架偏好提升为全局规则。视觉选择必须能回到项目契约或当前 brief。
4. Cover Accessibility and States
以 WCAG 2.2 AA 为最低目标,详细检查读取 references/accessibility-checklist.md。至少保证:
- 所有流程可用键盘完成,焦点可见且不会被粘性区域遮挡
- 控件有可计算名称,表单错误与字段关联
- 文本、组件和状态具备足够对比度,不只靠颜色表达
- 拖拽有简单指针替代操作,目标尺寸满足最低要求
- 滑动、捏合、路径等复杂手势有点击与键盘替代,除非手势本身是任务本质
- 有意义媒体具备字幕、转录或描述,媒体控件可用键盘操作
- 登录与验证码流程兼容密码管理器、粘贴和辅助认证机制
- 200% 缩放、长文本与本地化内容不破坏布局
5. Verify the Rendered Result
完成前至少验证:
- 定向单元/组件测试和类型检查通过
- 目标页面无新增 console error 和失败请求
- 主流程覆盖加载、空、错、成功和权限边界
- 对 URL 管理的状态验证 reload、deep-link 和 Back/Forward;纯临时状态不得无理由污染 URL
- 对 SSR / hydration 界面验证首帧与客户端结果稳定;延迟 hydration 不能覆盖用户已输入内容,locale、时间和客户端专属值不能产生 mismatch 或闪烁
- 键盘顺序、焦点移动、缩放与辅助技术语义正确
- 代表性窄屏与宽屏无溢出、遮挡或不可达操作
- 全高或固定表面在移动端地址栏伸缩时验证动态 viewport 和 safe area,避免双滚动、内容裁剪或底部操作被手势区遮挡
- 截图或真实浏览器结果与项目设计系统一致
自动扫描只能发现部分问题;需要真实浏览器流程时使用 skill:browser-qa-testing,完成声明前使用 skill:verification-before-completion。
Output Contract
交付时说明:
- 实现的用户结果与范围
- 复用和新增的设计系统资产
- 外部视觉参考的固定来源、抽象采用项和明确拒绝项(未使用则省略)
- 状态、响应式与无障碍处理
- 实际运行的验证及结果
- 未覆盖风险或需要产品确认的选择
Red Flags
- 未读取项目设计系统就引入新的视觉语言
- 复制外部品牌 token、logo、专有字体或文案,却没有授权和本地 owner
- 只实现理想态,没有加载、空、错或权限态
- 用颜色、悬停或拖拽作为唯一交互方式
- 关闭缩放、粘贴、焦点轮廓或原生键盘行为
- 用伪造数据填充真实产品页面
- 仅凭源码推断主观视觉问题,却没有渲染证据