Skip to content

fix(a11y): align DOM order with visual order in mobile bottom-nav (WCAG 1.3.2)#3441

Merged
bilal-karim merged 1 commit into
mainfrom
a11y/1.3.2-bottom-nav-links-order
Jun 3, 2026
Merged

fix(a11y): align DOM order with visual order in mobile bottom-nav (WCAG 1.3.2)#3441
bilal-karim merged 1 commit into
mainfrom
a11y/1.3.2-bottom-nav-links-order

Conversation

@bilal-karim
Copy link
Copy Markdown
Member

@bilal-karim bilal-karim commented May 22, 2026 •
edited by ardiewen
Loading

Summary

The mobile bottom-nav drawer used flex-col-reverse to put the most-important section closest to the user's thumb at the bottom of the screen. Visually correct, but the implementation chose to reverse via CSS rather than data:

  • Sighted users saw sections in order [C, B, A] (bottom-up importance)
  • Screen readers / keyboard tab encountered [A, B, C] (DOM order)

This is the canonical WCAG 1.3.2 Meaningful Sequence failure — visual reading order diverges from programmatic reading order.

Fix

Move the reversal from CSS to a $derived in script, then use plain flex-col:

-  const isNotLastSection = (i: number): boolean => i !== sections.length - 1;
+  const visualSections = $derived([...sections].reverse());
+  const isNotLastSection = (i: number): boolean =>
+    i !== visualSections.length - 1;
...
-  <div class="flex h-full flex-col-reverse ...">
-    {#each sections as section, i (i)}
+  <div class="flex h-full flex-col ...">
+    {#each visualSections as section, i (i)}

Visual output is identical. DOM order, keyboard tab order, and screen-reader reading order now all agree.

Audit context

  • WCAG 2.2 SC 1.3.2 Meaningful Sequence (Level A) — Moderate.
  • Issue file: audit-output/issues/1.3.2-bottom-nav-links-order.md.
  • The audit's Defect 2 (portal-tooltip aria-describedby linkage) was deferred to the 1.4.13 tooltip remediation. That dependency is already satisfied by PR fix(a11y): make Tooltip keyboard-accessible, dismissible, and hoverable #3429, which adds the aria-describedby wiring.

Test plan

  • On a mobile viewport (Chrome DevTools device mode → iPhone), open the bottom-nav drawer. Confirm the visual section order is unchanged from prod.
  • With VoiceOver iOS (or TalkBack Android) on a real device, swipe through the drawer sections. Sections should be announced in the same order as they appear visually, top to bottom.
  • Tab through the drawer with a Bluetooth keyboard on a tablet. Focus should move through links in visual order.
  • Inspect the rendered DOM — <NavSection> elements should appear in visualSections order, not the reversed-by-CSS original.

🤖 Generated with Claude Code

A11y-Audit-Ref: 1.3.2-bottom-nav-links-order

@bilal-karim bilal-karim requested a review from a team as a code owner May 22, 2026 16:16
@vercel
Copy link
Copy Markdown

vercel Bot commented May 22, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
holocene Ready Ready Preview, Comment Jun 3, 2026 6:45pm

Request Review

@github-actions github-actions Bot added a11y Accessibility audit PR a11y:no-fix-doc No A11y-Audit-Ref line; audit team triage a11y:bucket-3 Bucket 3: engineer required a11y:sc-1.3.2 and removed a11y:no-fix-doc No A11y-Audit-Ref line; audit team triage labels May 28, 2026
@ardiewen @claude
fix(a11y): align DOM order with visual order in mobile bottom-nav (WC…
9e4b0d7 
…AG 1.3.2)

Reimplements the 1.3.2 Meaningful Sequence fix on the linksSnippet
architecture introduced by #3445 (which deleted bottom-nav-links.svelte).

The drawer used flex-col-reverse to place the primary nav group at the
bottom near the thumb, so sighted users read top-to-bottom while AT and
keyboard users encountered the reverse DOM order. Move the reversal from
CSS into the data: emit the snippet in visual top-to-bottom order
(reversed copies of each group) and switch flex-col-reverse/justify-start
to flex-col/justify-end. Pixels are unchanged; DOM, tab, and screen-reader
order now match the visual order.

Copies ([...group].reverse()) are used so the arrays passed to the
desktop SideNavigation are not mutated.

A11y-Audit-Ref: 1.3.2-bottom-nav-links-order

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ardiewen ardiewen force-pushed the a11y/1.3.2-bottom-nav-links-order branch from ab77ca8 to 9e4b0d7 Compare June 3, 2026 18:44
@ardiewen
Copy link
Copy Markdown
Contributor

ardiewen commented Jun 3, 2026

⚠️ Updated approach — description above is now out of date

This branch was rebased onto main, which surfaced a modify/delete conflict: the file this PR originally edited, bottom-nav-links.svelte, was deleted by #3445 ("Make bottom-nav accept linksSnippet instead of sections"). The sections-prop component no longer exists.

The 1.3.2 fix has been reimplemented on the new linksSnippet architecture. Net change is now 2 files / 3 lines:

bottom-nav.svelte — natural DOM order, still bottom-anchored near the thumb:

- class="flex h-full flex-col-reverse justify-start gap-6 overflow-auto px-4 py-8"
+ class="flex h-full flex-col justify-end gap-6 overflow-auto px-4 py-8"

+layout.svelte (linksSnippet) — emit items in visual top-to-bottom order so reading order matches the pixels:

- {#each linkList as link, i (i)} ... {/each}
- <hr />
- {#each linkListForSecondGroup as link, i (i)} ... {/each}
+ {#each [...linkListForSecondGroup].reverse() as link, i (i)} ... {/each}
+ <hr />
+ {#each [...linkList].reverse() as link, i (i)} ... {/each}

Why this is equivalent: flex-col-reverse + justify-start ≡ flex-col + justify-end with the data pre-reversed. The reverse-axis form both bottom-anchors and flips reading order; moving the reversal into the data keeps the identical visual while making DOM / keyboard / screen-reader order match it (the actual SC 1.3.2 requirement). Reversed copies ([...group].reverse()) are used so the arrays passed to the desktop <SideNavigation> are not mutated.

Visual output is unchanged. DOM, tab, and screen-reader order now agree with the visual order.

Note: while reimplementing, I found a separate gap — the bottom-nav linksSnippet renders NavigationItem directly, bypassing NavSection's !item.hidden filter (added in #3434), so capability-gated links (Nexus / Standalone Activities) still render in the mobile bottom nav on incapable servers. That's a different SC (4.1.2) and is being handled in its own follow-up PR rather than expanding scope here.

@ardiewen ardiewen mentioned this pull request Jun 3, 2026
Open
4 tasks
@bilal-karim bilal-karim merged commit e2c95d5 into main Jun 3, 2026
18 checks passed
@bilal-karim bilal-karim deleted the a11y/1.3.2-bottom-nav-links-order branch June 3, 2026 20:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ardiewen ardiewen ardiewen approved these changes

Assignees

No one assigned

Labels

a11y:bucket-3 Bucket 3: engineer required a11y:sc-1.3.2 a11y Accessibility audit PR

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@bilal-karim @ardiewen