Skip to content

fix(site/src): give screen readers the meaning of hidden icons - #31587

Merged
jeremyruppel merged 3 commits into
mainfrom
a11y/semantic-hidden
Oct 30, 2026
Merged

jeremyruppel merged 3 commits into
mainfrom
a11y/semantic-hidden

Conversation

@aqandrew

Copy link
Copy Markdown
Collaborator

Lucide icons render with aria-hidden="true". For external-link icons, alert severity icons, AI Gateway token arrows, and the deployment sidebar's Groups arrow, the icon was the only thing carrying that meaning, so screen reader users never got it (axe semantic-hidden). The icons stay hidden, and each one now gets sr-only text next to it, matching #30715.

  • Link appends (opens in new tab) when it shows the external icon and has target="_blank". The new NewTabLabel is used in HelpPopoverLink, the Filter learn-more items, and the external TemplateAlternatives buttons. Seven call sites that already added their own copy of this text (nine spans) drop it, so it isn't announced twice.
  • Alert prefixes its content with the severity (Info:, Success:, Warning:, Error:), which also covers ErrorAlert.
  • TokenBadges names each count (Input tokens: 1.2K), and the sidebar's Groups arrow announces (opens organization settings).

There is no visual change; only screen reader text is added.

Closes DEQ-29, Closes DEQ-35, Closes DEQ-140, Closes DEQ-169, Closes DEQ-301, Closes DEQ-350, Closes DEQ-388, Closes DEQ-403, Closes DEQ-505, Closes DEQ-537, Closes DEQ-556
Refs DEQ-238, Refs DEQ-268, Refs DEQ-319, Refs DEQ-401, Refs DEQ-531, Refs DEQ-574, Refs DEQ-598

Ticket Surface Fix
DEQ-35 Template builder: View docs/View details, Start from scratch, community templates, agent skill Link, TemplateAlternatives
DEQ-140 Template builder, module select: View docs, View details Link
DEQ-350 Template builder, customizations: View docs Link
DEQ-169 Workspace: ports Learn more, SSH popover links, build parameters Read the docs HelpPopoverLink
DEQ-505 Deployment sidebar: Groups ↗ DeploymentSidebarView
DEQ-29, DEQ-301, DEQ-388, DEQ-403, DEQ-537, DEQ-556 Create user, deployment overview, security settings, builder customizations, sharing dialog, login Alert
DEQ-319 (partial) AI session threads: attribution and AI Governance tooltips are fixed; the header View docs link opens in the same tab Link
DEQ-574 (partial) AI sessions: In/Out token arrows are fixed; the header View docs link opens in the same tab TokenBadges
DEQ-401, DEQ-531, DEQ-598 (partial) Users, audit, workspaces: the Filter menu docs link is fixed; the help tooltip links open in the same tab Filter
DEQ-268, DEQ-238 (not changed) Templates help tooltip, notification inbox links: these open in the same tab none

The partial tickets use Refs, by decision: a Link that shows the external icon but opens in the same tab now announces nothing extra. That is accurate, but an audit may still flag the icon.

Grouping and decision log

Root causes (18 eligible tickets, all rule semantic-hidden)

  • A. Shared Link renders SquareArrowOutUpRightIcon with no text. Fixed once in Link.
  • B. Hand-written anchors with ExternalLinkIcon: HelpPopoverLink, Filter, TemplateAlternatives. Each gets NewTabLabel.
  • C. Alert severity icon is the only severity cue. Fixed with an sr-only label from the existing severity table.
  • D. One-off icons: TokenBadges arrows and the deployment sidebar Groups arrow.

Decisions (confirmed by @aqandrew)

  1. A Link that shows the icon without target="_blank" (about 39 call sites, including the help tooltips that lost _blank in refactor(site/src): migrate click info popovers to hover tooltips #28875) announces nothing extra. Tickets that only partly come from these links use Refs.
  2. The Alert label applies to all four severities.
  3. The sidebar arrow wording is " (opens organization settings)".

Notes

  • Removing aria-hidden from the SVGs was rejected because a bare SVG would still have no accessible name.
  • The tests match names with \s* because jsdom's accessible-name computation drops the leading space of sr-only text; browsers keep it. UserDropdownContent.test.tsx already works around this the same way.
  • The self-review (frontend-review and all 8 frontend-deep-review roles) found three issues, all fixed: a repeated span (now NewTabLabel), test URLs on the real domain (now example.com), and the severityIcons name (now severityConfig).
  • Older spans on raw <a> and router links in UserDropdownContent, NavbarView, and Markdown are left unchanged because this PR does not touch that code.
  • Not checked with NVDA in a browser.

🤖 Generated by Coder Agents on behalf of @aqandrew.

Lucide icons are aria-hidden, so screen reader users missed what the
external-link, alert severity, token arrow, and sidebar arrow icons
convey. Keep the icons hidden and add sr-only text instead:

- Link announces "(opens in new tab)" when it shows the external icon
  and opens a new tab; drop the call-site copies that now duplicate it.
- HelpPopoverLink, Filter learn-more items, and TemplateAlternatives
  external buttons reuse the same NewTabLabel.
- Alert prefixes its content with the severity.
- TokenBadges names each count; the deployment sidebar Groups arrow
  announces that it opens organization settings.
@linear-code

linear-code Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

@aqandrew
aqandrew marked this pull request as ready for review October 30, 2026 20:04

@jeremyruppel jeremyruppel left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each of the 11 closed tickets' reported elements renders through a changed component (Link, HelpPopoverLink, TemplateAlternatives, Alert/ErrorAlert, DeploymentSidebarView), and the removed per-call-site spans leave no double announcements. Required CI passes; diff is site-only at 64 non-test lines.

Nits: NewTabLabel (Link.tsx:49) is exported without JSDoc; the PR body's self-review note still says severityIcons was renamed to severityConfig, which a70e7c1 reverted; Link reads target from its own props, so asChild with target="_blank" on the child gets no label (no current call site hits this); the raw-anchor copies in NavbarView.tsx:222 and UserDropdownContent.tsx:141 could reuse NewTabLabel later.

🤖 Generated by Coder Agents on behalf of @jeremyruppel.

@jeremyruppel
jeremyruppel merged commit d726605 into main Oct 30, 2026
32 of 33 checks passed
@jeremyruppel
jeremyruppel deleted the a11y/semantic-hidden branch October 30, 2026 20:36
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants