Skip to content

fix(site/src): open docs links in a new tab - #31603

Merged
aqandrew merged 3 commits into
mainfrom
a11y/semantic-hidden-2
Nov 3, 2026
Merged

aqandrew merged 3 commits into
mainfrom
a11y/semantic-hidden-2

Conversation

@aqandrew

@aqandrew aqandrew commented Oct 31, 2026 •

Copy link
Copy Markdown
Collaborator

Docs links showed the external-link icon but opened in the same tab. Since #31587, Link announces " (opens in new tab)" only when it really opens one, so screen reader users still heard nothing for these, and the icon misled sighted users. Every docs link now opens in a new tab, which matches coder.com's docs link behavior.

  • All 27 Links with a docs(...) href and no target get target="_blank" rel="noreferrer". Several of them are inside forms (template settings, workspace parameters, create workspace, model form), where a same-tab link used to throw away unsaved input.
  • WorkspaceWildcardWarning linked to its docs page with a react-router Link, so it couldn't open a new tab. It is now an anchor with NewTabLabel.
  • Notification inbox markdown links open in a new tab when they point to another origin, such as the docs. Absolute links back into this deployment ({{base_url}}/@owner/...) stay in the same tab.
  • Three stories matched these links by their exact name; they now use a regex.

Closes DEQ-238, Closes DEQ-268, Closes DEQ-319, Closes DEQ-401, Closes DEQ-531, Closes DEQ-574, Closes DEQ-598

Ticket Surface
DEQ-238 Notification inbox: the "dormant" docs link
DEQ-268 Templates: help tooltip (Manage templates)
DEQ-319, DEQ-574 AI Gateway sessions and session threads: header View docs
DEQ-401 Users: Roles and Groups help tooltips
DEQ-531 Audit logs: help tooltip
DEQ-598 Workspaces: help tooltip (Create Workspaces, Connect with SSH)
Decision log
  • @aqandrew decided that every docs link should open in a new tab, not only the ones in these tickets. These seven tickets were Refs in fix(site/src): give screen readers the meaning of hidden icons #31587 because their remaining links opened in the same tab.
  • I fixed each call site instead of making Link default to target="_blank" for absolute URLs. The default would be shorter, but it is an implicit change to a core primitive and would also affect external links that are not docs.
  • Links that are not docs links stay as they are: internal links, the GitHub link on the Icons page, mailto: links, and the license banner, which already sets its own target.
  • In the inbox, relative links still show the external icon. That predates this PR and is out of scope. Fixing it means removing the icon, which is a visual change.
  • Self-review (frontend-review and all 8 frontend-deep-review roles) found three stories that matched links by exact name (fixed), the WorkspaceWildcardWarning link (fixed), and inbox links to this deployment, which would have opened a new tab (fixed by comparing the origin).
  • The new InboxItem.test.tsx checks the accessible name for external, relative, and same-deployment links. The rest of this PR only adds attributes, and that behavior is already covered by Link.test.tsx.
  • Review round 1: the inbox origin check now compares parsed origins (URL.parse), with a look-alike-origin test, and the three header "View docs" links use SettingsHeaderDocsLink. The three loosened story matchers stay: they predate this PR, and deleting play assertions is out of scope.
  • Not checked with NVDA in a browser.

🤖 Generated by Coder Agents on behalf of @aqandrew.

Docs links showed the external-link icon but opened in the same tab,
so Link never announced "(opens in new tab)" and the icon misled
sighted users. Give every docs Link target="_blank", turn the wildcard
access URL docs button into a new-tab anchor, and open external
notification inbox links in a new tab while links back into this
deployment stay in the same tab.
@linear-code

linear-code Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

@aqandrew
aqandrew marked this pull request as ready for review October 31, 2026 00:43
@aqandrew
aqandrew requested a review from jeremyruppel October 31, 2026 00:43

@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.

[reviewer-agent] round 1: changes needed.

The new-tab fix works. In Storybook, every changed link that a story renders (Templates, Workspaces, Audit, Users and org members Roles/Groups popovers, WorkspaceWildcardWarning, InboxItem markdown) now has target="_blank", its accessible name ends with " (opens in new tab)", and it shows a focus ring. The PR adds no axe violations. Every non-test docs(...) link on the branch now sets target.

Inline findings:

  • [should-fix] InboxItem's origin check is a string prefix match.
  • [should-fix] ×3: header "View docs" links should use SettingsHeaderDocsLink.

Nits:

  • The 3 loosened story matchers (CoderAgentsProductCard.stories.tsx:36, LicenseCard.stories.tsx:237, TemplateVersionEditor.stories.tsx:187) sit in play assertions that FE1 bans. Deleting them would be cleaner than loosening them.
  • No story renders AIBridgeSessionsLayout, so that link was verified in code only.

Follow-ups: added evidence to DEQ-608 (same-tab links that show the external-link icon: relative inbox links, and the IconsPage GitHub link).

🤖 Generated by Coder Agents on behalf of @jeremyruppel.

@jeremyruppel
jeremyruppel marked this pull request as draft November 2, 2026 16:51
@aqandrew
aqandrew requested a review from jeremyruppel November 3, 2026 18:29
@aqandrew
aqandrew marked this pull request as ready for review November 3, 2026 18:36

@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.

LGTM!

@aqandrew
aqandrew merged commit ccf5ec7 into main Nov 3, 2026
54 of 57 checks passed
@aqandrew
aqandrew deleted the a11y/semantic-hidden-2 branch November 3, 2026 19:01
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 3, 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