fix(a11y): address audit findings on docs site + sidebar#267
Merged
Conversation
Resolves WCAG 2.2 A/AA findings from the June 2026 accessibility audit for the VitePress docs site: - Focus ring: global 2px visible indicator with 2px offset (theme-aware via --vp-c-text-1); inset variant for elements clipped by overflow:hidden containers (FAQ accordion, code blocks, page outline) so the ring stays visible (2.4.7 / 2.4.11 / 1.4.11). - Code contrast: split the github shiki comment token (#6A737D, fails AA in both themes) into #57606a light / #8b949e dark; bump .code-filename to text-2 (1.4.3). - Landing links: underline manifesto link + cross-link card titles so they aren't color-only; fix .landing-xlinks__blurb contrast (text-3 -> text-2) (1.4.1 / 1.4.3). - Manifesto link: add sr-only context for link purpose (2.4.4). - Remove decorative manifesto quote mark. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sustained all-caps hurts readability for dyslexic users (WCAG 3.1.5 / 1.4.8 recommendation from the a11y audit). Remove text-transform: uppercase on the hero and landing eyebrows, sentence-case the adoption-line eyebrow/badge strings, and tighten the letter-spacing that was tuned for caps. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The 4th adoption-line card ("Merge with confidence") is intentionally not a
link, so it was skipped by Tab-key navigation and the auditor never heard it.
Promote each card's package name to an <h3> so screen-reader users reach every
card (including the non-link end-state) via heading navigation, giving the
adoption path proper document structure. Visual layout is unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sidebar test-list a11y tweaks from the audit: - Drop forced uppercase on describe group headers (COGA readability); they now render in the author's original casing. - Bold (700) weight + brighter default describeText (#94a3b8 -> #f1f5f9) so headers read as headers and clear AA contrast; test names use normal (400) weight. Hierarchy now carried by weight + box rather than uppercase. - Keep the --twd-describe-text token in CSS so the describeText theme option still works — only its default value changed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
kevinccbsg
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Accessibility fixes for the docs site (twd.dev), addressing findings from the June 2026 WCAG 2.2 A/AA audit. Scope is the VitePress docs site only — the twd-js sidebar tool (
src/) is a separate follow-up.Changes
Focus indicator (2.4.7 / 2.4.11 / 1.4.11)
:focus-visiblering: 2px solid--vp-c-text-1with 2px offset (theme-aware, clears 3:1 in both themes).outline-offset: -2px) for focus targets insideoverflow: hiddencontainers — FAQ accordion, custom + markdown code blocks, and the "On this page" outline — so the ring isn't clipped.outline: noneoverrides inLandingCrossLinksandAdoptionLineDiagram.Contrast (1.4.3)
#6A737D(fails AA in both themes) into#57606alight /#8b949edark..code-filenameand.landing-xlinks__blurb:--vp-c-text-3→--vp-c-text-2.Links (1.4.1 / 2.4.4)
Cognitive / readability (COGA — 3.1.5 / 1.4.8)
Screen-reader structure (4.1.2)
<h3>for the package name, so the non-link "Merge with confidence" end-state card is reachable via heading navigation.Not included (intentional)
src/— separate work.Verify
Run
npm run docs:dev, tab through the homepage + a sub-product page (e.g./twd-js) in both light and dark themes; confirm a visible focus ring everywhere (inset on accordion/code/outline), readable code comments, underlined landing links, and sentence-case eyebrows.🤖 Generated with Claude Code
Update: sidebar tool a11y (src/)
Also includes accessibility fixes for the twd-js sidebar test list:
describeText(#94a3b8 → #f1f5f9) for legibility and AA contrast; test names use normal (400). Hierarchy now carried by weight + box, not uppercase.--twd-describe-texttoken in CSS so thedescribeTexttheme option still works — only its default changed.