# Zc Frontend UI Engineering

> 前端界面工程

- Skill: `zmice/zc-frontend-ui-engineering` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zmice/zc-frontend-ui-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmice/zc-frontend-ui-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: zmice (https://skillmd.com/u/zmice)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zmice/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
- 只实现理想态，没有加载、空、错或权限态
- 用颜色、悬停或拖拽作为唯一交互方式
- 关闭缩放、粘贴、焦点轮廓或原生键盘行为
- 用伪造数据填充真实产品页面
- 仅凭源码推断主观视觉问题，却没有渲染证据