Accessibility on phones and iPads: contrast, touch targets, settings layout, screen-reader labels

[anantham]

Owner request: make the mobile and iPad UI work well, with accessibility.

Audit (before)

Playwright with axe-core (WCAG 2.2 AA) covered the library, reader, text-selection sheet and settings at phone 390×844 / 844×390 and iPad 820×1180 / 1180×820, in light and dark mode, with touch emulation.

• 68 color-contrast violations. The main cause is text-blue-500 on white at 3.76:1; the minimum is 4.5:1.
• 48 links distinguishable by color alone, and 1 dropdown with no label.
• About 45 controls under 44 px in settings, and 9–15 per screen elsewhere. The Original/English toggle was 24 px.
• Form fields under 16 px. iOS Safari zooms the page when one is focused and leaves it zoomed.
• Phone settings layout: a fixed 191 px sidebar left the form 165 px wide, cutting off the model search.
• Keyboard and screen readers: a clickable div over a canvas (the oscilloscope minimap), mode toggles that didn't announce their state, and modal overlays with no dialog semantics or focus management.

Changes

• Contrast: links and value read-outs use blue-700 / dark:blue-400, and inline links are underlined. Dark-mode greys on tabs, toggles and labels are fixed, and Export uses green-700.
• Touch targets:
  • The pointer-coarse:min-h-11 Tailwind variant gives controls 44 px on touch screens only, so desktop density is unchanged.
  • A coarse-pointer rule in index.css gives form fields 16 px text (no iOS zoom) and a 44 px height.
• Settings on phones: below sm, a labelled native section picker replaces the sidebar (iOS shows its picker wheel). On larger screens the sidebar is a nav landmark with aria-current and aria-expanded. The modal uses dvh height so iOS toolbars don't clip it.
• Modal dialogs (useModalDialog, WAI-ARIA dialog pattern): Settings, the mobile version picker and the illustration dialog each:
  • move focus inside when they open;
  • keep Tab and Shift+Tab inside, and pull focus back if it has escaped to the page behind;
  • close on Escape, and return focus to the control that opened them.
• Screen-reader labels:
  • The version dropdown and delete buttons are labelled, and the mode toggles have aria-pressed.
  • The oscilloscope minimap is a labelled button with a decorative canvas.
  • The mobile version picker uses full-row radio labels and respects the home-indicator safe area.
  • The comment field has a visible focus ring.
• Phone layout: the settings gear shares the chapter row instead of taking its own row. "Loading chapters…" no longer pulses, which fixed a contrast dip and removes motion.

Gate

tests/e2e/mobile-a11y.spec.ts:

• Matrix: 5 screens × 4 devices × 2 color schemes = 40 cases. 6 are skipped because the mobile version picker only exists below md, leaving 34 applicable. Each requires:
  • zero axe violations;
  • no horizontal overflow;
  • no zooming fields;
  • targets of at least 44 px, with WCAG 2.5.8's exceptions: links inside running text, sliders, and radio buttons counted with their labels.
• Keyboard (3 cases): Settings on iPad landscape and on phone, and the version picker on phone. Each opens the dialog with the keyboard and checks that focus is inside, stays inside through a full Tab and Shift+Tab cycle, and returns to the opener after Escape. All 3 fail on ac2acc1 and pass now.

Putting back one old link color fails the matrix. It's a local gate, because Playwright isn't in CI yet (T0.4). Run it with npx playwright test tests/e2e/mobile-a11y.spec.ts (37 pass, 6 skipped).

Review fix

An independent review of ac2acc1 found that the dialogs were marked aria-modal but only handled Escape. Commit 7bb5217 adds useModalDialog and its tests. The unit tests cover focus entry, wrapping in both directions, recapturing escaped focus and focus return; the focus-return test was mutation-checked. The review also corrected the applicable-case count to 34.

Verification

• tsc and the Playwright tsconfig: clean. eslint: 0 errors. vite build: pass.
• vitest run: 9,609 passed, 1 failed. The failure is the known Node-22-only indrasNetImageProvider.test.ts case.
• The existing mobile-selection-affordance and chapter-change-perf specs pass.

Limits

• This container only has Chromium. Real iOS Safari and iPadOS weren't run; Safari's input zoom is handled by the 16 px rule rather than observed.
• An iPad with a trackpad reports a fine pointer, so it gets the desktop sizes.
• The settings panels were checked on the default Providers panel only. Other panels benefit from the global field rules but weren't individually audited.

🤖 Generated with Claude Code

https://claude.ai/code/session_011d1MbSabs9nA9d9w8pxP1W

[vercel]

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

Project	Deployment	Actions	Updated
lexicon-forge	Ready	Preview	Sep 26, 2026 6:13pm UTC