Zc Frontend UI Engineering

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

交付时说明：

1. 实现的用户结果与范围
2. 复用和新增的设计系统资产
3. 外部视觉参考的固定来源、抽象采用项和明确拒绝项（未使用则省略）
4. 状态、响应式与无障碍处理
5. 实际运行的验证及结果
6. 未覆盖风险或需要产品确认的选择

Red Flags

• 未读取项目设计系统就引入新的视觉语言
• 复制外部品牌 token、logo、专有字体或文案，却没有授权和本地 owner
• 只实现理想态，没有加载、空、错或权限态
• 用颜色、悬停或拖拽作为唯一交互方式
• 关闭缩放、粘贴、焦点轮廓或原生键盘行为
• 用伪造数据填充真实产品页面
• 仅凭源码推断主观视觉问题，却没有渲染证据