frontend-interaction-quality

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

前端交互体验质量

先确定 owner 是通用 primitive、共享组件、业务组件还是页面编排。重复操作骨架复用 shared primitive；紧凑、hover、禁用或图标态由组件自己负责，不由宿主 CSS 补洞。先保证可理解和可达，再做视觉精致度。

参考体验

用户指定成熟产品时，拆解信息架构、选择/导航模型、空间层级、鼠标/键盘行为和反馈；不能用“按钮都有”代替体验对齐。平台能力确实不可复制时列为非目标，但其余交互标准不降级。验收必须包含真实页面完整任务和视觉检查。

控件合同

• 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。
• modal overlay/content 都高于触发面板，content 高于 overlay，不能只有遮罩可见。
• 紧凑模式保留操作含义或当前值；直接动作优先 tooltip，选项/二级动作优先 popover/menu/select。
• hover、focus-visible、active、disabled、selected 表达一致层级。文本输入框例外：光标和选区已表达焦点，聚焦前后容器背景、边框、阴影和 ring 不变。
• Hover 反馈跟随承载 surface：同一背景、同一层级里的同级按钮、列表项和图标动作复用同一反馈色阶，默认在原 surface 上做轻微加深或提亮，不切换成 card、popover、background 等另一层实体表面。Shared primitive 用语义 tone 承载差异，宿主只选择 tone，不复制临时颜色；选中、危险和浮层状态按自身语义例外处理。
• 状态强度匹配任务权重：次级视图切换、筛选和排序只在原 surface 内使用同色系 tonal fill，不获得 card/popover 级亮度、白色浮面或 elevation；只有主任务、需要持续定位的重要选择，或真实浮层对象才提升表面层级。
• hover 浮动操作默认零视觉、零占位、零 hit target，显示后恢复命中；浮层在触发面外时提供不可见 hover bridge。
• 危险、不可逆、跨系统或可能丢数据的操作有清晰文案、确认或撤销；普通导航不滥用确认。

常见复合交互

• 触发式输入面板：只有用户真实插入 /、@ 等 marker 才创建 session；Esc、选中、blur 或离开范围后销毁，文本同步/删除/selection change 不得自动复活。active index、键盘高亮和滚动归面板实例。
• 对象操作菜单：更多按钮和右键共享一份菜单模型、分组和 primitive；右键只是效率入口，显式入口仍可发现、可聚焦。disabled、危险态、焦点移交一致，菜单关闭不得抢回已移交焦点。
• 可折叠行/卡片：整个 header 是点击目标，箭头只是提示；折叠态保留关键预览。行内独立控件通过稳定隔离合同避免冒泡误展开，并为 hover/展开提供明确反馈。

密度与反馈

• 窄容器优先保留主任务、当前值和主要动作；次要说明可收起，入口不能消失。
• loading、pending、success、error、empty、disabled 有即时可见反馈，不只靠变灰。
• 移动端不能只证明无横向溢出；检查关键视口首屏主任务、chrome 占用、导航探索成本、唯一主滚动面和触控可达。
• 用户文案说结果，不暴露内部 state 名。

收尾

按触达面检查语义 role/真实目标、Router、嵌套控件、默认可发现性、aria/tooltip、键盘焦点、disabled 和 portal 层级。文本输入框比较真实 DOM 聚焦前后计算样式。用户指定参考产品时，用同视口截图与完整操作逐项对照；普通交互至少提供一个组件、DOM、浏览器或截图证据。可复用问题优先修 shared primitive，避免页面临时补丁。