Audit and improve site-wide accessibility

[mikearnaldi]

Summary

Audit the site's documentation, API reference, marketing pages, blog, podcasts, events, and playground. Fix repeated problems through shared components, tokens, and keyboard behavior.

• Add shared main landmarks, native disclosures, search fields, filter announcements, carousel controls, and controlled media figures.
• Improve dialog/menu focus recovery, visible focus, contrast, text enlargement, narrow layouts, and short-height layouts.
• Make playground file actions, sharing, trace selection, and column resizing keyboard accessible. Document Monaco's Tab-navigation shortcut and enable terminal screen-reader support.
• Add explicit controls for quote scrolling, transcript following, silent videos, and seven looping GIF demos.
• Correct heading hierarchy, comparison-table headers, chart descriptions, and code-region names.
• Add a repeatable axe/Playwright crawler, interaction regressions, and the audit report at specs/accessibility/site-wide-audit.md.

Rebased onto current main after #1533 merged.

Verification

Post-rebase checks passed:

• pnpm install --frozen-lockfile
• pnpm exec vp run check: formatting, lint, TypeScript, and Astro checks
• pnpm exec vp run test: 332 tests in 29 files
• Playwright article/site accessibility and playground file-sync suites: all 20 passed in one run after the visual corrections; homepage/merch checks passed again after the final theme/reflow fixes
• git diff --check

Audit coverage before the rebase:

• 1,573-route full crawl
• 984 layout/theme states across 164 representative routes
• 108 targeted states after the final media, input-boundary, and code-region fixes
• 18 final control states, with zero violations
• Keyboard, 200% text enlargement, WCAG text spacing, reduced motion, short viewports, selected no-JavaScript flows, and accessibility-tree inspection

The completed crawls had no navigation/readiness errors or root-width overflow. The report distinguishes implementation stages and records incomplete-rule counts.

Visual regression correction

The initial audit introduced visual regressions. The correction compares the PR
with pre-audit revision 86af6759 across 47 routes and 158 baseline/corrected
screenshot pairs. It restores docs navigation, version segments, install-panel
logos and layout, theme/category menus, merch controls, playground sharing and
confirmations, file actions, trace controls, callout colors, and media sizing.
The report contains the component-by-component review and verification details.

The final 24-state targeted accessibility check has zero violations. Homepage
and docs reflow checks pass in 28 normal/enlarged-text states. Populated trace
selection passes in both themes. The 32-state open-control review records axe's
landmark recommendation for portalled menus and the pointer-initialized category
menu's scrollability flag; keyboard navigation and scrolling were verified.

The September 9 review follow-up restores neutral search focus outlines,
dimmed Share/Reset buttons, navbar search borders, and shared panel-divider
colors. The fixes use theme tokens and shared controls. The project check and
all 20 browser regressions passed again after these changes.
The follow-up also compared 18 baseline/corrected screenshot pairs at
1280/390/320px in both themes and verified keyboard resizing in six states.
All 18 corrected axe states had zero violations and no root-width overflow;
incomplete-rule counts remain documented in the report.

Remaining findings

• The third-party Luma calendar has contrast, unnamed-link, and loading-heading issues.
• The published v3 Order source table has an empty fourth header. Its source JSDoc and API snapshot need an upstream correction.

The crawler retains those findings and exits nonzero when they occur. Direct screen-reader listening and individual review of embedded-media captions and visual alternatives remain outstanding. The report documents these limits; it does not claim full WCAG conformance.

[github-actions]

Cloudflare Preview

URL: https://effectwebsite-websiteworker-pr-1539-rojkonta7wq6oiax.matechs.workers.dev

Built from commit 9488333.

---

This comment updates automatically with each deployment.

[IMax153]

There's a visual regression with the package manager selector on the landing page:

Old:

New:

[IMax153]

Also the hierarchy of links after clicking into the docs

Old:

New:

[f15u]

Now search input borders are emerald instead of white:

Old:

New:

[f15u]

Share button in playground has a different style. It should be dimmed:

Old:

New:

The same problem is on:

• the right border in playground sidebar
• the search input in the navbar

[mikearnaldi]

@f15u addressed both comments in 9488333.

• Restored the original white search focus outline in dark mode and zinc-900 in light mode through the shared focus token.
• Restored Share's dimmed fill, text, and border. Share and Reset now use the same shared button variant.
• Restored navbar search borders and hover colors, and moved both playground divider styles into the shared resizable component.

Compared against pre-audit revision 86af6759 at 1280px, 390px, and 320px in both themes. Share/Reset colors and dimensions, search focus styling, and desktop navbar/divider resting and hover colors match the baseline. Keyboard resizing and focus recovery passed.

Formatting, lint, TypeScript, Astro, and all 20 browser tests passed. The 18 targeted axe states had zero violations and no page overflow. Incomplete-rule counts are recorded in the audit report.

@IMax153 the earlier package-manager selector and docs-navigation comments were addressed in 0104f60.