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

# 前端交互体验质量

重复操作与状态归 shared primitive，宿主不补 CSS。

## 参考体验

界面以 ChatGPT 成熟度为基线：清晰、稳定、一致、低操作负担；不以可用代替完成。工作台停靠可参考 VS Code、Notion，标准不降级。

- **一致性**：同级入口复用语义命名的共享组件和状态样式，不耦合产品名；产品布局留在宿主，通过 surface/token 消费通用反馈。统一密度、圆角、对齐、hover、焦点和选中态，验收不同底色及调用处覆盖。
- **操作顺序**：常规操作 → 更多 → 关闭；无关闭时更多最后，DOM/键盘顺序一致。共享工具栏固定槽位，业务不自排。低频布局入二级菜单，危险操作置后；普通设置页不加停靠工具栏。
- **交互完整性**：行内更多与内容共用整行反馈，点击互不误触；鼠标、键盘和触控均可达，焦点返回、滚动与窄容器不丢失主任务。
- **成品审阅分级**：无呈现影响免审；局部低风险改动定向看改动处及相邻关系；信息层级、主要路径、共享界面或影响不明时读取[真实界面审阅](references/real-ui-review.md)，做开放式检查并复验。

每个新交互实现前对照顶级同类产品；复用控件验收组合。新复合交互或无把握时读[范式与取证预算](references/real-ui-review.md)，查具体实例；常规小点不重复搜索。

## 控件合同

- 更多操作默认用竖向三点 `MoreVertical`，用户指定或平台约定可例外。
- URL、路由、文档和来源使用 `<a>`/`Link`/`NavLink`，状态修改、命令和无稳定 URL 面板使用 `<button>`。站内目标保留真实 href 并由 Router 接管普通左键，避免整页刷新。
- 禁止交互元素嵌套、clickable span 和伪语义。普通文本链接默认态就有链接线索；按钮式链接只用于明确 CTA/下载/鉴权/卡片操作，底层仍保持链接语义。
- 链接图标须增加语义（如 Markdown 类型）；否则无图标、无占位。共享导航统一焦点、target/rel 和宿主行为。
- 紧凑操作优先图标配 tooltip，菜单图标加文字；陌生/关键动作保留文字，按空间与任务判断。icon-only 有可访问名称、focus-visible；提示在 portal 可见。disabled 解释用可触发 wrapper。
- 操作 tooltip 默认上方、不足时避让；纵向栏可侧向。标签滚动条固定细度，hover 不增粗。
- modal overlay/content 都高于触发面板，content 高于 overlay，不能只有遮罩可见。
- 标题内边距归共享 Header：`DialogHeader` 或 `WorkbenchSurface title/moreActions`；不借导航槽、不加竖线。验收窄屏长标题、顺序、命中。
- 紧凑模式保留操作含义或当前值；直接动作优先 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 设备常显。全局菜单和工具栏操作常显。浮层提供 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/展开提供明确反馈。
- **动效**：展开/收起、浮层和视图切换默认复用共享过渡；Markdown 折叠用 `ChatCollapsibleContent`，箭头同步。支持反向打断、动态高度及减少动态效果；首屏不重播、不加装饰循环。真实操作验收中间态。
- **展开与滚动**：主动展开不贴底，嵌套动画不重播。工具组限半屏、按溢出渐隐。内部阅读区到顶/底后向外传递，禁用 `overscroll-behavior: contain/none` 或吞滚轮；弹窗/浮层外边界隔离背景、画布缩放除外。验收双向传递和输入框可见，测试后恢复真实视口。

## 密度与反馈

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

## 收尾

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

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