Skip to content

feat(desktop): add ARIA live-region & navigation semantics to the console UI#350

Merged
ceilf6 merged 1 commit into
developfrom
improve/desktop-aria-semantics
Jun 14, 2026
Merged

feat(desktop): add ARIA live-region & navigation semantics to the console UI#350
ceilf6 merged 1 commit into
developfrom
improve/desktop-aria-semantics

Conversation

@ceilf6

@ceilf6 ceilf6 commented Jun 14, 2026

Copy link
Copy Markdown
Owner

Linked Issue Or Context

Closes #348

Summary

Assistive technology could not perceive the console's dynamic surfaces. #344 added visual keyboard-focus rings and reduced-motion, but AT semantics were still missing. This PR adds purely-additive ARIA semantics — no behavior, layout, text, or styling changes:

  • StatusPillrole="status" + aria-live="polite" so run-status transitions (planning → running → completed/failed) are announced; decorative beacon marked aria-hidden.
  • EventStream logrole="log" + aria-live="polite" + aria-relevant="additions" + aria-label="遥测流" so streamed telemetry lines are announced as they append.
  • App navaria-label="主导航" on the nav, aria-current="page" on the active item, decorative nav-dots marked aria-hidden.
  • ApprovalDrawer — rendered as a labelled <section> (aria-label naming the pending tool) so the approve/reject surface is a named group.

Impact Scope

Renderer-only, leaf/near-leaf components. No store, IPC, or contract changes.

GitNexus Impact Summary

  • Risk level: LOW
  • Critical skeleton changes: none (renderer presentational components)
  • GitNexus impact: detect_changes → exactly the 4 expected symbols touched (App, StatusPill, EventStream, ApprovalDrawer); 1 affected process App → Submit (step 1, App) — additive attributes only, no behavioral change. impact(upstream) on each = LOW (single parent caller, all flow into App).
  • Verification: see below.

Verification

  • biome check on all 4 files — clean.
  • pnpm --filter @frontagent/desktop typecheck — clean.
  • pnpm --filter @frontagent/desktop test — 13 files, 96 tests passing.

Design note on the ApprovalDrawer element

The issue suggested role="group" on the drawer, but biome's a11y/useSemanticElements rule (correctly) prefers a native semantic element over a role on a generic <div>, and aria-label is unsupported on a bare <span>. So the drawer is a native <section aria-label=…> (semantic, label-supported, no layout impact since .approval owns all styling, no biome-ignore needed), and the risk badge keeps its visible text (already announced inline) rather than an unsupported aria-label.

Note on tests

apps/desktop follows an established no-DOM-test architecture (no @testing-library/jsdom installed; logic lives in the store layer, components are not unit-tested). Per the repo-guard issue note, rather than introduce a DOM-testing stack (a much larger, convention-breaking change) for attribute assertions, verification relies on typecheck + biome's a11y ruleset + the contained additive diff. Happy to add a lightweight render assertion if maintainers want to adopt that stack.

Checklist

  • I have linked an issue or explained why this PR stands alone.
  • I have kept the diff focused on the stated change.
  • I have run pnpm quality:precommit, or explained why it could not run.
  • I have run pnpm quality:local for critical skeleton changes — N/A, not a critical skeleton change.
  • I have updated docs or tests when behavior, public APIs, or Harness contracts changed — purely-additive ARIA, no behavior/API/contract change; test convention noted above.
  • For critical skeleton changes, I have filled the GitNexus impact summary with concrete results — filled despite being non-critical.

🤖 Generated with Claude Code

…sole

Assistive tech could not perceive the console's dynamic surfaces. Add
purely-additive ARIA semantics (no behavior/visual change):

- StatusPill: role="status" + aria-live="polite" so run-status changes are
  announced; beacon marked aria-hidden.
- EventStream log: role="log" + aria-live="polite" + aria-relevant="additions"
  + aria-label so streamed telemetry lines are announced.
- App nav: aria-label on the nav, aria-current="page" on the active item,
  nav-dot marked aria-hidden.
- ApprovalDrawer: rendered as a labelled <section> (aria-label naming the
  pending tool) so the approve/reject surface is a named group.

#344 covered only visual focus + reduced motion; this adds the AT semantics.

Closes #348
@github-actions

Copy link
Copy Markdown

🛡️ ceilf6/repo-guard

代码评审报告: feat(desktop): add ARIA live-region & navigation semantics to the console UI

风险等级:
处理建议: 批准
决策摘要: ** 可以合并;变更仅触及 renderer 叶子组件的附加 ARIA 语义,关联 issue #348 的主要验收点已覆盖,剩余风险主要是缺少 DOM/AT 层面的自动断言。

级联分析

  • 变更符号: 原始模型未提供结构化级联字段。
  • 受影响流程: 原始模型未提供结构化级联字段。
  • 变更集外调用方: unknown
  • 置信度: degraded

问题发现

模型未返回可结构化的问题发现;已提取可用的决策字段,原始非契约内容未附在评论中。

行级发现

  • 无明确变更行归属。

Karpathy 评审

  • 假设: 模型输出需要归一化为固定 Markdown 契约。
  • 简洁性: 已提取 summary、finding、evidence 与 fix;原始 prose 不再附在评论中,避免占用下游解析与代理上下文。
  • 变更范围: 原始模型未提供结构化范围字段。
  • 验证: 需要查看 CI、测试或人工 CR 证据补强合并信心。

缺失覆盖

  • 输出未命中 Repo Guard Markdown 契约;建议补充真实模型质量评估覆盖。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(desktop): add ARIA live-region & navigation semantics to the console UI

1 participant