Skip to content

docs: give screenshots their own alt text and fill empty table headers - #30873

Merged
nickvigilante merged 1 commit into
mainfrom
vigilante/docs-a11y-fixes
Oct 21, 2026
Merged

nickvigilante merged 1 commit into
mainfrom
vigilante/docs-a11y-fixes

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Summary

An axe sweep of every page on https://coder.com/beta-docs (coder/docs-engine#224) found two content-side problems. Nine screenshots have alt text identical to the italic caption right after them, so screen readers read the same words twice (axe image-redundant-alt). Four hand-written tables have an empty top-left header cell, which leaves their row-label column without a name (axe empty-table-header). This fixes both. These are content fixes on main only; earlier release lines keep the old text.

Findings

Rule Pages Cause Fixed where
image-redundant-alt 4 Alt text repeats the caption This PR
empty-table-header 4 hand-written Empty corner header cell This PR
empty-table-header 105 CLI reference pages, audit-logs.md Generated tables with empty headers Not here: needs a generator change
empty-table-header admin/networking/port-forwarding.md Spanning corner cells in a raw HTML matrix Not here: needs a rework of that table
heading-order remote-desktops.md <div class="tab"> typo Separate PR
link-name, scrollable-region-focusable, aria-valid-attr-value, label many Engine coder/docs-engine #220, #217, #224

Fix

Each of the nine screenshots gets alt text that describes what it shows (for example, "Preset dropdown with Ruby Development added between Full Stack and Web Development"), and keeps its caption. The corner cells become "Permission" (Groups and roles), "Component" (air-gapped comparison), "Scenario" (scale-testing workloads) and "Input" (workspace tags). Tables were re-padded with markdown-table-formatter.

QA

  1. Open each production page below. Expected: the screenshots and tables look the same as before, except the four tables now show a word in their top-left header cell.
  2. In Chrome DevTools (Elements) or Firefox's Inspector, select a screenshot on the Add a language page. Expected: its alt differs from the italic caption under it.

Pages to compare

What to check Production Preview
Screenshot alt text vs caption https://coder.com/beta-docs/@main/get-started/customize-your-template/add-a-language/ This PR's GitHub preview: https://github.com/coder/coder/blob/vigilante/docs-a11y-fixes/docs/get-started/customize-your-template/add-a-language.md
Roles table corner cell https://coder.com/beta-docs/@main/admin/users/groups-roles/ https://github.com/coder/coder/blob/vigilante/docs-a11y-fixes/docs/admin/users/groups-roles.md
Scale-testing table corner cell https://coder.com/beta-docs/@main/install/validate/scale-testing/ https://github.com/coder/coder/blob/vigilante/docs-a11y-fixes/docs/install/validate/scale-testing.md

Testing

markdownlint-cli2 and markdown-table-formatter over the eight changed files: 0 errors. Re-running the sweep after merge should drop image-redundant-alt and the four tables' empty-table-header findings from @main.

Upstream

No: these are Coder content fixes, not Fumadocs bugs.

Linear: DOCS-1303


🤖 Built with AI assistance.

An accessibility sweep of the beta docs site found screenshots whose alt
text repeats the italic caption beside them, so screen readers read the
same words twice, and tables with an empty top-left header cell, which
leaves the row-label column unnamed. Each alt now describes what the image
shows, and each corner cell names its column.

Assisted-by: AI
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

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

Seems good. But I couldn't test it

Open each production page below. Expected: the screenshots and tables look the same as before, except the four tables now show a word in their top-left header cell.

I couldn't find this to verify

@nickvigilante
nickvigilante merged commit fda1ed5 into main Oct 21, 2026
58 of 59 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-a11y-fixes branch October 21, 2026 17:28
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 21, 2026
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

@chrifro thanks for flagging this, and sorry: the QA steps pointed at production, which still showed the old version before merge, and the "Preview" links went to GitHub's file view instead of the rendered docs.
The working previews were the ones in the Docs preview comment above (coder.com/docs/@vigilante%2Fdocs-a11y-fixes/...).

I ran axe (image-redundant-alt and empty-table-header) on production vs. that preview for all eight changed pages before merge:

Page Production Preview Top-left header cell
Workspace tags 1 violation clean empty → "Input"
Groups and roles 1 violation clean empty → "Permission"
Air-gapped 1 violation clean empty → "Component"
Scale testing 1 violation clean empty → "Scenario"
Add a language 5 violations clean n/a
Authenticate to GitHub 2 violations clean n/a
Customize your template 1 violation clean n/a

13 violations went to 0.
The docs/README.md image doesn't render on coder.com/docs, so I checked it by hand: beta-docs/@main still had the old alt text, and the preview had the new one.

Testing also turned up a mismatch: the captions on Add a language called the Programming Languages parameter a "dropdown", but it's a multi-select. That fix is in #31133.
I'll write QA steps with before/after links from now on.


🤖 Generated by Coder Agents on behalf of @nickvigilante.

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