peiiii / frontend-interaction-quality

前端交互体验质量

重复操作与状态归 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。