Keyboard navigation across CAMARON dashboards

Why keyboard-only matters in aquaculture

Keyboard operability is usually framed as a screen-reader concern. In aquaculture software it is broader than that. Farm office machines are often shared, older, and paired with a failing trackpad. Hatchery staff work in gloves. Users with motor impairments or repetitive strain injuries rely on keyboards, switch devices and voice control — and every one of those input methods rides on the same underlying requirement: the interface must be reachable, in a sensible order, with a visible indication of where you are.

So we treat keyboard operability as a functional requirement, not an accessibility extra. If a workflow cannot be completed without a pointer, it is a bug.

Global shortcuts and the shortcut panel

Authenticated pages register a small set of global shortcuts, discoverable by pressing ?. The panel lists what is available on the current surface rather than a static cheat sheet, so it stays honest as surfaces change.

• Tab / Shift+Tab — move forward and backward through interactive elements.
• Escape — close the topmost dialog, drawer or popover.
• ? — open the keyboard shortcut panel.
• Arrow keys — move within composite widgets: tab lists, menus, listboxes and date pickers.
• Enter / Space — activate the focused control.

Shortcuts are deliberately few. A large custom shortcut map competes with screen reader and browser bindings, and users cannot remember it anyway.

Focus rules we hold ourselves to

These are the rules the component library enforces, and what the automated sweep checks:

• Focus is always visible. Every interactive element carries a focus ring drawn from the design tokens, so it stays visible in both light and dark themes. We do not remove outlines without replacing them.
• Focus order follows reading order. Tab order comes from the DOM. We do not use positive tabIndex values to reorder anything.
• Focus is never lost. When content is replaced — an onboarding step advances, a table refreshes, a drawer closes — focus is moved deliberately to a meaningful target rather than falling back to the document body.
• Focus is not stolen. Pages do not auto-focus on load. Auto-focus is reserved for modal dialogs, where it is expected behaviour.

The onboarding wizard is the clearest example: advancing a step moves focus into the new step panel and announces the change, but the first render deliberately does not hijack focus from wherever the user arrived.

Dialogs, drawers and focus traps

A modal dialog must trap focus while it is open — otherwise a keyboard user tabs invisibly into the page behind it. Every modal surface in CAMARON uses a shared focus trap that:

1. Records the element that opened the dialog.
2. Moves focus into the dialog, to the heading or the first meaningful control.
3. Cycles Tab and Shift+Tab within the dialog's focusable elements.
4. Closes on Escape.
5. Restores focus to the opener on close.

The mobile navigation drawer, the export drawers and the evidence bundle viewer all share this behaviour, and each has end-to-end tests asserting the Escape path and the focus restoration. A trap without an escape route is worse than no trap at all, so the Escape assertion is the one we treat as non-negotiable.

Skip links and landmarks

Both the public shell and the authenticated shell start with a skip-to-content link. It is visually hidden until focused, and it targets the page's mainlandmark so a keyboard user does not tab through the entire navigation on every page. Dashboard shells offer a second target for the sidebar navigation.

Landmarks matter for keyboard users too, not just screen reader users: browser extensions and assistive utilities use them to offer jump targets. Each page renders exactly one main.

Where the gaps still are

We publish open items rather than implying completeness:

• Charts. Real-time sensor charts are reachable, but panning and zooming within a chart is pointer-oriented. The "View as Table" alternative on each chart is the supported keyboard path.
• Map surfaces. The pond map and disease heatmap rely on a third-party map library whose keyboard support we do not fully control. Region-level data is also available in the accompanying table and CSV export.
• Tier-3 surfaces. Calculators and internal admin consoles are built from the same audited components but are not swept individually.
• Manual verification. Everything above is verified by automated tooling. A third-party manual pass with real assistive technology is planned and has not been performed.