Repository navigation
fix(site/src): give screen readers the meaning of hidden icons - #31587
Conversation
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.
jeremyruppel
left a comment
There was a problem hiding this comment.
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.
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 (axesemantic-hidden). The icons stay hidden, and each one now getssr-onlytext next to it, matching #30715.Linkappends(opens in new tab)when it shows the external icon and hastarget="_blank". The newNewTabLabelis used inHelpPopoverLink, theFilterlearn-more items, and the externalTemplateAlternativesbuttons. Seven call sites that already added their own copy of this text (nine spans) drop it, so it isn't announced twice.Alertprefixes its content with the severity (Info:,Success:,Warning:,Error:), which also coversErrorAlert.TokenBadgesnames 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
Link,TemplateAlternativesLinkLinkHelpPopoverLinkDeploymentSidebarViewAlertLinkTokenBadgesFilterThe partial tickets use
Refs, by decision: aLinkthat 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)LinkrendersSquareArrowOutUpRightIconwith no text. Fixed once inLink.ExternalLinkIcon:HelpPopoverLink,Filter,TemplateAlternatives. Each getsNewTabLabel.Alertseverity icon is the only severity cue. Fixed with ansr-onlylabel from the existing severity table.TokenBadgesarrows and the deployment sidebar Groups arrow.Decisions (confirmed by @aqandrew)
Linkthat shows the icon withouttarget="_blank"(about 39 call sites, including the help tooltips that lost_blankin refactor(site/src): migrate click info popovers to hover tooltips #28875) announces nothing extra. Tickets that only partly come from these links useRefs.Alertlabel applies to all four severities.Notes
aria-hiddenfrom the SVGs was rejected because a bare SVG would still have no accessible name.\s*because jsdom's accessible-name computation drops the leading space ofsr-onlytext; browsers keep it.UserDropdownContent.test.tsxalready works around this the same way.NewTabLabel), test URLs on the real domain (nowexample.com), and theseverityIconsname (nowseverityConfig).<a>and router links inUserDropdownContent,NavbarView, andMarkdownare left unchanged because this PR does not touch that code.