57 lines
5.9 KiB
Markdown
57 lines
5.9 KiB
Markdown
# UX 走查 — Web Interface Guidelines 合规（2026-10-05）
|
||
|
||
> 范围：src 下 43 个 .vue 文件（以工作区未提交改动为主，机械反模式全量扫描含存量）。
|
||
> 方法：三路子代理分组走查（A 审批/工具卡域 6 文件、B aichat 域 9 文件、C 项目/知识/审计域 11 文件）+ 主会话 grep 全量机械扫描（transition:all / outline:none / div@click / overscroll / aria 语义）。子代理发现经行号复核；A 组子代理两轮超限，由主会话直读补核。
|
||
|
||
## 一、总体结论
|
||
|
||
**质量中上，无阻断项。** 本批新增代码 a11y 意识明显：svg 批量补 aria-hidden、复制/编辑按钮带 aria-label、MessageList 有 role=log+aria-live、hover 反馈普遍到位、i18n 完整。缺口高度集中在 **4 类系统性模式**，其中 2 类可用全局样式一刀切收敛大半。
|
||
|
||
## 二、系统性缺口（grep 全量实证）
|
||
|
||
### 1. 弹层缺 overscroll-behavior: contain —— 全仓 0 命中【覆盖面最广】
|
||
43 文件所有 modal/overlay/浮层（`modal-overlay`×6、`ai-shortcuts-mask`、`ai-agent-peek-mask`、`dep-graph__modal-overlay`、`confirm-mask`、审批浮层等约 12+ 处）无一声明 overscroll-behavior。弹层内容滚到边界后滚轮穿透到底层内容。
|
||
**修复**：全局样式一刀切（`[class*="overlay"], [class*="mask"] { overscroll-behavior: contain; }`）或逐弹层补。P2，一处 CSS。
|
||
|
||
### 2. transition: all —— 33 处 / 22 文件【密度最高】
|
||
行号清单：ApprovalPopup×4(594/632/728/809)、ApprovalOverlay×3(128/200/211)、ChatInput×2(1222/1236)、FilePreview×2、GitChanges×2、Knowledge.vue×2(501/546)、ProjectDetail×2、Tasks×2、App.vue:340(toast)、ConfirmDialog:103、Paginator:146、ToolCard:494、ToolResultBody:542、EmptyState×1、TopBar×1、IdeaDetail×1、AppSidebar:276、FileExplorer×1、ProjectCard×1、AuditLog:659、Ideas:588、Projects×1。
|
||
风险：布局属性被动画（掉帧）、主题切换时全属性过渡发糊。
|
||
**修复**：机械替换为具体属性（color/background-color/border-color/transform/box-shadow）。P3 批量低风险。
|
||
|
||
### 3. outline: none 无 :focus-visible 补偿 —— 19 处 / 14 文件【键盘可达性】
|
||
行号清单：IdeaDetail×3(1096/1112/1153)、ConversationSidebar×2(702/829)、Knowledge.vue×2、Tasks×2、AiChat:972、ChatInput:1197、TaskBoundaryCard:454、TopBar:718、KnowledgeDetail:453、GitChanges×1、SettingsNav×1、TaskBatchBar×1、WorkflowDagDisplay×1、AuditLog:471。
|
||
**修复**：全局兜底 `:focus-visible { outline: 2px solid var(--df-accent); outline-offset: 2px; }`，input 类可保留 border-color 补偿不强制 outline。P2。
|
||
|
||
### 4. div/span 充当可点击元素 —— @click 共 56 处，去 @click.self mask 合规项后约 20 处真缺口【键盘不可达】
|
||
典型（高频优先）：ToolCard.vue:11 工具卡折叠头、MessageList.vue:1423 轨迹折叠头、ConflictResolver.vue:7 冲突行、ConversationSidebar.vue:205 归档组折叠头、TopBar.vue:176/192 历史/摘要行、AuditLog.vue:67 审计展开行 + :119 会话行、Dashboard.vue:38/42/46 统计卡、FileExplorer.vue:29/37/42 下拉项+面包屑、FilePreview.vue:124 大纲头、GitChanges.vue:120 加载更多、ProjectCard.vue:2 整卡。
|
||
（`@click.self` 的 mask 点击关闭是合理模式，不在修列。）
|
||
**修复**：高频 3 处改 button+样式重置；其余补 tabindex=0 + @keydown.enter/space + role。P2 分批。
|
||
|
||
### 5. icon-only 按钮缺 aria-label（子代理域审 + 抽查）
|
||
TopBar 多数按钮有 title（弱补偿）；EnrichmentPanel 关闭钮仅 title；ProjectDetail:185/189 编辑/删除 icon 钮仅 title。title 与 aria-label 非等价（部分读屏不读 title）。
|
||
**修复**：aria-label 与 title 同 i18n 键复用，机械补齐。P3。
|
||
|
||
## 三、亮点（已做对的）
|
||
|
||
- MessageList.vue:1391 `role="log" + aria-live="polite"`：流式消息读屏可感知（UX 第五轮 P2-G1）
|
||
- 本批 git diff 新改 svg 批量补 `aria-hidden="true"`（审批拒绝按钮等实证）
|
||
- MessageItem 复制/编辑按钮带 aria-label，hover-only 操作区有 `:focus-within` 显形补偿
|
||
- 消息区键盘链（Esc/IME/滚动锚定）质量好；AuditLog 模板全 button + Paginator 组件分页规范
|
||
|
||
## 四、修复分期建议
|
||
|
||
| 期 | 内容 | 量级 |
|
||
|---|---|---|
|
||
| P2-1 | 全局两刀：:focus-visible 兜底 + 弹层 overscroll-contain | 全局 CSS ~2 处，收敛 2 类大半缺口 |
|
||
| P2-2 | 高频 div→button：ToolCard 卡头 / MessageList 轨迹头 / AuditLog 行 | 3 处 |
|
||
| P3-1 | transition:all 33 处机械替换具体属性 | sed 级批量 |
|
||
| P3-2 | icon-only aria-label 补齐 + 剩余 div 键盘化 | ~15 处 |
|
||
|
||
**拍板点**：修复范围「存量 vs 仅本批改动」——机械扫描含存量（transition:all/outline:none 大半为存量代码），若仅清本批改动则这两类大半豁免，工作量降 60%+。
|
||
|
||
## 附：三路子代理域审摘要
|
||
|
||
- **B 组（aichat 域 9 文件）**：22 处。集中 icon-only 缺 aria-label（~12）与 outline 无补偿；4 处 transition:all；3 处 div 点击不可键盘达。逻辑层键盘处理（Esc/IME/双确认）质量好。MessageItem pass。已知线索复核：TopBar model select outline 无补偿属实（:718）；EnrichmentPanel 关闭钮仅 title 属实。
|
||
- **C 组（项目/知识/审计域 11 文件）**：弹层 overscroll 系统性缺失（本组 4 文件）+ icon-only ~6 + div 可点击 ~5 + AppSidebar:276 transition:all、KnowledgeDetail:453 outline 裸删。无 v-for 超百项无虚拟化、无 aria-live 缺失。AuditLog/Knowledge.vue cat-chip 规范。
|
||
- **A 组（审批/工具卡域 6 文件，主会话补核）**：ToolCard.vue:11 卡头 div 可点击 + :494 transition:all（diff 中另一处 svg aria-hidden 为本批已修好的实证）；ApprovalPopup transition:all×4；ApprovalOverlay×3(128/200/211)；ToolResultBody:542；AiChat.vue:972 outline:none，:139 mask 为 @click.self 合规。
|