# Frontend Interaction Quality

> 当设计、修改或评估前端交互、链接/按钮语义、控件状态、tooltip/popover/menu、键盘可达性、紧凑模式，或要求对齐 Windows/macOS/成熟产品体验时使用。

- Skill: `peiiii/frontend-interaction-quality` (Agent Skill)
- Install (CLI): `npx skillmds@latest add peiiii/frontend-interaction-quality`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peiiii/frontend-interaction-quality/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: peiiii (https://skillmd.com/u/peiiii)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/peiiii/frontend-interaction-quality

---


# 前端交互体验质量

先确定 primitive、共享组件、业务组件或页面编排 owner。重复操作骨架复用 shared primitive；紧凑、hover、禁用或图标态归组件，不由宿主 CSS 补洞。

## 参考体验

NextClaw 的界面与交互以至少达到 ChatGPT 的成熟度为默认质量基线，不以“功能能用”作为完成标准。对齐的是清晰、稳定、一致和低操作负担，非照搬配色、布局或功能；工作台停靠等特有场景可参考 VS Code、Notion 的对应交互，但不能降低同类基础体验要求。

- **一致性**：同一 surface 上的同级入口复用组件及状态样式，统一密度、圆角、对齐、hover、焦点与选中反馈；排查调用处覆盖，不能只证明用了同名组件。
- **操作层级**：主任务与高频业务动作优先，更多位于业务操作尾部，关闭等容器控件独立；低频布局操作按语义收进二级菜单，危险操作分组置后。普通设置页不因通用资源能力多出工具栏或停靠操作。
- **交互完整性**：行内更多与内容共用整行反馈和边界，点击互不误触；鼠标、键盘和触控均可达，菜单开关、焦点返回、滚动与窄容器不丢失主任务。
- **验收证据**：在真实页面完成代表任务，检查默认、hover、焦点、选中、菜单展开及适用的加载/错误状态；横向对照相邻入口、相关明暗主题和窄容器。共享组件变更抽查不同消费者，不只看被指出的截图。功能或样式存在可复现偏差时先修复，不以用户未逐页检查作为完成依据。

涉及参考产品对照时，拆解信息架构、选择/导航模型、空间层级和反馈，并说明实际查看的版本、入口或证据。未实际对照不得声称“已达到 ChatGPT 水准”；明确已验证范围与剩余差距。平台能力确实不可复制时列为非目标，其余标准不降级。纯文案、无界面变化的实现及无关页面不强加全产品截图审计。

## 控件合同

- URL、路由、文档和来源使用 `<a>`/`Link`/`NavLink`，状态修改、命令和无稳定 URL 面板使用 `<button>`。站内目标保留真实 href 并由 Router 接管普通左键，避免整页刷新。
- 禁止交互元素嵌套、clickable span 和伪语义。普通文本链接默认态就有链接线索；按钮式链接只用于明确 CTA/下载/鉴权/卡片操作，底层仍保持链接语义。
- 外链/方向图标只在语义成立时使用。重复导航收敛到 shared primitive，统一焦点、target/rel 和桌面宿主行为。
- icon-only 控件同时提供可访问名称、tooltip/popover 和 focus-visible；tooltip 在 floating/fullscreen/portal 中仍可见。disabled 控件需要解释原因时，用可触发 tooltip 的 wrapper。
- 行内操作 tooltip 优先上方，由 primitive 避让；纵向图标栏可侧向提示，不遮挡同级内容。
- modal overlay/content 都高于触发面板，content 高于 overlay，不能只有遮罩可见。
- 紧凑模式保留操作含义或当前值；直接动作优先 tooltip，选项/二级动作优先 popover/menu/select。
- hover、focus-visible、active、disabled、selected 表达一致层级。文本输入框例外：光标和选区已表达焦点，聚焦前后容器背景、边框、阴影和 ring 不变。
- 普通 hover/按下/键盘高亮消费 `--interaction-hover`，选中消费 `--interaction-selection`，边框消费 `--interaction-selection-border`。主题定义颜色，组件承载状态，业务页不临时调色；反馈轻微，选中略强，不降级、叠加或升高表面层次。
- 统一 owner 而非同色。例外须有理由、owner 与渲染证据：移动会话用 `--session-interaction-*`，侧栏用 `--sidebar-interaction-*`，分段用 `--sidebar-segment-selection`。主 CTA、危险、状态按语义例外；回归与明暗渲染必验。
- hover 浮动操作默认零视觉、零占位、零 hit target，显示后恢复命中；浮层在触发面外时提供不可见 hover bridge。
- 危险、不可逆、跨系统或可能丢数据的操作有清晰文案、确认或撤销；普通导航不滥用确认。

## 常见复合交互

- **高数据量表格与列表**：只要结果可能超过单页可读范围，默认态必须分页或虚拟化，不能把全部记录直接铺在页面上。管理员需要先浏览全貌时，优先提供稳定排序、当前范围/总数、上一页/下一页和每页大小；默认每页 10 条，除非任务或既有惯例证明更高密度更合适，常用上限为 20 条。可按名称、类别、平台或状态定位的数据集必须提供与任务相符的搜索和筛选；筛选、搜索、每页大小变化后回到第 1 页，空结果说明当前条件没有匹配项。数据可能持续增长时，筛选与分页参数由 API/D1 等数据 owner 处理，前端不得全量加载后伪分页。验收需覆盖超过一页、筛选命中/无结果、换页、每页大小变化、刷新后返回当前条件，以及窄容器横向阅读与键盘焦点。
- **触发式输入面板**：只有用户真实插入 `/`、`@` 等 marker 才创建 session；Esc、选中、blur 或离开范围后销毁，文本同步/删除/selection change 不得自动复活。active index、键盘高亮和滚动归面板实例。
- **对象操作菜单**：更多按钮和右键共享一份菜单模型、分组和 primitive；右键只是效率入口，显式入口仍可发现、可聚焦。disabled、危险态、焦点移交一致，菜单关闭不得抢回已移交焦点。
- **二级菜单**：桌面端使用保留父菜单的侧向级联，不把子菜单替换成带返回按钮的导航页。支持悬停、点击和右方向键打开，左方向键/Escape 只关闭当前层并恢复父条目焦点；鼠标跨入子菜单不闪退，边缘自动避让，窄容器不裁切操作。页面不得另建菜单状态机或平行子菜单组件，统一消费 `shared/components/ui/context-menu` 的模型与渲染；不同输入设备的适配也留在同一 owner。
- **可折叠行/卡片**：整个 header 是点击目标，箭头只是提示；折叠态保留关键预览。行内独立控件通过稳定隔离合同避免冒泡误展开，并为 hover/展开提供明确反馈。

## 密度与反馈

- 共享尺寸区分表单和紧凑场景；打开菜单、标签和面包屑验收行高、间距与选中态。
- loading、pending、success、error、empty、disabled 有即时可见反馈，不只靠变灰。
- 移动端不能只证明无横向溢出；检查关键视口首屏主任务、chrome 占用、导航探索成本、唯一主滚动面和触控可达。
- 用户文案说结果，不暴露内部 state 名。

## 收尾

可复用的交互纠偏同时落实到共享组件和本 skill：组件承载行为与样式，skill 规定复用与验收，回归测试保护失败路径。检查已有 owner、调用方及局部覆盖，再修正、迁移并删除旧实现；禁止只加规则却保留各页自制组件，或为同类交互新建第二套组件。验收覆盖普通入口和不同宿主入口；二级菜单证明父子同时可见、鼠标跨层、键盘退层及边缘表现。

证据匹配断言：组件测试证明事件和状态；hover、焦点、选中等视觉反馈须在真实页面触发，对照默认态及最终渲染，检查承载背景、伪元素、透明度和主题覆盖。class/token、静态截图或工具调用成功均不能替代。共享样式抽查明暗主题和不同承载面；输入框比较聚焦前后计算样式。指定参考产品时按同视口逐项对照，问题优先修共享 owner。