[Master] Accessibility requirements for the UI/UX overhaul (WCAG 2.1 Level A)

[saubyk]

Context

An automated accessibility scan of the shipped RTL app (Feb 2026) filed a series of WCAG 2.1 Level A issues: RTL#1557–RTL#1564 and RTL#1566 (fixed by RTL#1609). The findings are template-level and pervasive (e.g. ~579 positive tabindex values across 136 templates), so instead of patching the current UI and then redoing the work, the upcoming design overhaul should bake these requirements in structurally. This issue distills the series into requirements for the new design.

Source issues

RTL issue	Severity	Finding
#1557	Critical	Positive tabindex values (1–22, per-component numbering) scramble tab order across components
#1559	Critical	Clickable <div>/<span> elements with no keyboard handler or role (nav items, theme swatches, stepper dots)
#1560	High	Icon-only buttons with no accessible name (menu trigger, pager/scroller arrows)
#1562	High	Dialog close buttons are a bare "X" with no aria-label
#1566	High	Form fields without visible labels (fixed in the current app — keep in new designs)
#1558	Medium	No "skip to main content" link
#1561	Medium	No aria-live regions for loading states, validation errors, dynamic updates
#1563	Medium	No <main> landmark
#1564	Medium	Custom tabs missing role="tablist" / aria-selected state

Design requirements

1. Keyboard navigation & focus (#1557, #1559)

• No positive tabindex anywhere. Tab order comes from DOM order; layouts must be designed so DOM order matches visual order.
• Every interactive element is a native <button> or <a> — never a click-handler <div>/<span>. Custom widgets that must stay non-native get tabindex="0", an appropriate role, and Enter/Space activation.
• Visible focus indicator on every interactive element, in all themes (light/dark, all color skins).

2. Page structure (#1558, #1563)

• The app shell provides a skip link as the first focusable element, targeting a <main id="main-content"> landmark. Nav, header, and content live in proper landmarks (<nav>, <header>, <main>).

3. Accessible names (#1560, #1562, #1566)

• Icon-only buttons are a design-system component that requires an aria-label (tooltips alone don't count).
• One standard dialog header component with a labelled close button ("Close" + dialog name), replacing the per-modal "X".
• Every form field has a visible label as part of the component spec.

4. State & announcements (#1561, #1564)

• Loading, success/error, and validation feedback render in aria-live regions (role="status" / role="alert") as part of the standard feedback components.
• Tabs follow the ARIA tabs pattern: tablist/tab roles with aria-selected managed by the component.

Acceptance criteria

• Design-system component specs encode the rules above, so per-screen regressions can't recur
• axe/Lighthouse accessibility pass is clean on the key screens (login, dashboard, a table view, a modal flow)
• Full keyboard walk of each screen: focus order matches visual order, nothing unreachable
• Screen reader pass (VoiceOver/NVDA): names, roles, states, and dynamic updates announced

Notes

• The individual RTL issues stay open until the overhaul ships or they're fixed in a 0.15.x point release; #1557 in particular is deletion-only and merges cleanly, so it may still land in the current app if the overhaul timeline stretches.
• The docker/ regtest fixture now covers all three implementations — LND, Core Lightning, and Eclair (RTL#1632) — so the keyboard-walk, screen-reader, and axe/Lighthouse passes above can be run against real backends with deterministic seeded data (channels, payments, invoices) on every implementation's screens, and redesign screenshots are reproducible across runs.