How the editor stays usable without a mouse, without sight, and with the text scaled up — and what a change has to do to keep it that way.
This is a contract, not an aspiration: every claim below is pinned by a test named at the end of its section.
Everything else is built on these. They live in
resources/packages/web/runtime/graphden-popover.js (shared with the
standalone runtime bundle, so they carry no editor dependencies) and
resources/packages/app/editor/editor-a11y.js.
| Primitive | What it is for |
|---|---|
focusIntoDialog / returnFocusTo |
Move the keyboard into a surface when it opens, and hand it back when it closes |
installTabTrap({getEl, isVisible}) |
Keep Tab inside an open dialog. Driven by isVisible(), so it needs no open/close notification and is inert while closed |
setSiblingsInert(el, on) |
Make aria-modal="true" true — hide everything else from assistive tech and pointer input |
focusableWithin / focusSafely |
One definition of “can take focus”, instead of the three partial selector lists this codebase used to carry |
ensurePopoverClose(el, onClose, label, {prepend}) |
The visible × in a popover’s corner. Idempotent and re-callable, so it survives an innerHTML swap; prepend puts it first for a host that scrolls its own content |
window.gdAnnounce(msg, {assertive}) |
Say something to a screen reader without moving focus |
A new dialog or popover. Use installPopoverDismiss with trapFocus
and getReturnFocus, or call the primitives directly. Focus entry and
return stay EXPLICIT: a dialog also closes through paths the dismiss
handler never sees (a × button, Cancel, submit), and getAnchor is not a
safe stand-in — editor-secrets.js deliberately passes a neighbouring
popover there, and returning focus into a different dialog is worse than
doing nothing.
Anything that COVERS content owes a visible way out. Escape closes
every overlay in this editor, and outside-pointerdown closes every one
installPopoverDismiss touches — but neither is on screen, and the scrim
behind the .gd-pop family is a transparent click-catcher rather than a
dimmed backdrop, so it reads as nothing at all. So: a full-page management
surface is closed by the shared #gd-surface-exit control (one button for
all of them, revealed by body[data-surface] — a per-surface copy is the
thing that gets forgotten), and a popover gets a × from
ensurePopoverClose whenever it traps Tab, outlives the trigger that
opened it, or is a titled panel / form rather than a short menu anchored
to a chip that is still on screen. A dialog that traps Tab owes a
FOCUSABLE close in particular: tabbing out is exactly what the trap
prevents. Pinned by edit-overlay-close.test.js, which enumerates the
surfaces from the DOM so the next one added is covered without editing the
test.
A new keyboard shortcut. Register it in editor-shortcuts.js; do not
add a keydown listener. The registry is what Space and ? render
from, so a binding declared anywhere else is invisible and undiscoverable.
Prefer the leader (Space x) — bare keys are nearly exhausted and the
letter keys belong to canvas navigation. A registered binding is also what
the user can REBIND (Settings → Keyboard, MARKETPLACE.md § 6):
declare it with the registry and the user’s layout applies to it; a raw
listener is both undiscoverable and un-rebindable. The two deliberate
exceptions stay fixed — the canvas / tree navigation keys and the dialogs’
Escape / Enter — because a layout that moved Escape would break every
dismiss contract on this page.
Any state that changes without moving focus — a selection, a branch
switch, a filter chip toggle — calls gdAnnounce. A screen reader has no other
way to notice.
A new interactive element must be reachable and visible when focused.
If it appears on :hover, add :focus-within alongside — reachable by
Tab but invisible is worse than absent.
Sizes. font-size and anything sized to text goes in rem. A px box
around a rem glyph overflows the moment the user scales their font. Where
a px floor is a real requirement (WCAG 2.5.5 hit areas), use
max(28px, 1.75rem) so the floor holds and the target still grows.
Motion. CSS handles the declarative half through the
@media (prefers-reduced-motion: reduce) block at the END of
editor-styles.css (it must stay last — it overrides at equal
specificity; tools/runtime-test/css-reduced-motion-last.test.js fails
the build when a rule lands after it). JS-driven motion asks prefersReducedMotion(). Remove the
movement, keep the information: the tree-flash becomes a steady wash, the
busy spinner only slows down because it IS the progress signal.
| Surface | Pattern | Module |
|---|---|---|
| Explorer tree | ARIA tree — arrows, Right/Left expand/collapse, Enter opens, roving tabindex. A row’s own buttons are NOT tab stops (four per namespace header once made Tab walk the whole tree): . / m reach them, ← → walk them, Escape returns to the row. The filter field above it exits with ↓ / Escape onto the tree — every always-present text field owes a key out, since the bare keys type while it has focus |
editor-tree-keys.js |
| Graph canvas | Roving tabindex; arrows/hjkl follow EDGES (→ argument, ← consumer). Two levels: Enter steps INTO a card’s rows, Escape backs out; Shift+arrows move the node itself |
editor-canvas-keys.js |
| Pickers (fn, namespace) | Combobox — focus stays in the filter field, aria-activedescendant names the highlighted row |
editor-fn-picker.js, editor-namespace-picker.js |
| Explorer filters | The kind chips are a role=group of aria-pressed toggles; every dynamic chip (#gd-filter-chips) is a pressed toggle whose accessible name says Remove filter: … (and no longer exists when it names a deleted fn / view); ◍ all clears everything. The + filter menu and the view chip’s popover are non-modal dialogs (installPopoverDismiss + ensurePopoverClose, focus in on open, Escape / × out, focus back to the chip); the namespaces and graph-view rows are role=checkbox with aria-checked, the Name contains field adds its chip on Enter. Every change calls gdAnnounce — Only types — 12 of 40 shown, Only core, core.tests hidden, View on-const, N functions match, All functions. Leader: Space f f add a filter, Space f v views, Space f a all. |
editor-explorer-filters.js, editor-explorer-views-ui.js, editor-sidebar-lens.js |
| Inspector tabs | ARIA tabs — aria-controls, one tabpanel, ← → Home End |
editor-shell.js |
| Dialogs | Focus enters, Tab is trapped, Escape returns it | graphden-popover.js + each dialog |
| Account chip menu | ARIA menu — focus enters on open, ↑ ↓ Home End walk menuitems, Escape/Tab close and return focus to the chip (aria-expanded mirrors state) |
editor-auth.js |
| Management surfaces (Settings / Organization / Platform / Marketplace) | Dialog-like entry: gdAnnounce names the surface, focus moves to its section nav, the covered Build chrome inside #main-container goes inert (the top bar stays live — brand/org/chip work from any surface), Escape returns to Build (window-level, defaultPrevented-guarded so dialogs close first; from a text field on the surface the first Escape only leaves the field for the #gd-surface-exit button, the second — or Enter — leaves the surface), and the #gd-surface-exit button is the pointer counterpart — it lives in the bar, the one region that stays live, and is placed over the sheet’s top-right corner by CSS |
editor-shell.js |
| Undo toast | #gd-undo-toast (editor-undo.js): role="status" + aria-live="polite", so “Created foo · Undo · ×” (shown for 10 s, held while the pointer or focus is on it) is announced without moving focus — the reader is mid-gesture and must not be pulled to a toast. Its two buttons are ordinary focusable buttons (Tab reaches them; the Undo button’s aria-label names the gesture), and the same undo stays on the keyboard for the whole 30 s — Space u, or the Mod+z chord (inert inside a text field, where the browser’s own undo keeps it) — so no one has to catch a toast to undo |
editor-undo.js |
| Shortcuts | Registry + Space leader + ? cheatsheet; the Surfaces group (Space v …) reaches Settings / Organization / Platform / Build |
editor-shortcuts.js |
Two deliberate exceptions, both load-bearing:
aria-modal="false" is correct — steps
ask the reader to click targets OUTSIDE the popup, so trapping or
stealing focus would break the thing it exists to do. It announces each
step instead.toolbar, not a dialog (editor-row-actions.js),
which is why they take focus without trapping it.Rebuilds destroy focus. The Explorer tree does innerHTML = '' on
every updateEntityList — and selecting a fn calls it. The canvas rebuilds
its overlays on every render. So both remember the current item by a stable
KEY (fn id / namespace path / node id), never by element reference, and
restore it afterwards. The tree’s restore is guarded: it only reclaims
focus if focus was inside the tree beforehand, because plenty of rebuilds
are not user-initiated and grabbing focus then drags the keyboard away from
wherever the user actually was.
A key handler must not reach into a subtree it does not own. Both the
card level and the row level claim Escape and Enter — but only when the
card, or the row, ITSELF has focus. Claiming from anywhere in the subtree
steals the key from the popovers and controls living inside, and the
symptom shows up somewhere unrelated (the first time, in a tutorial test
about version history). edit-a11y-canvas.test.js fires Escape at a
control inside a card and requires it to arrive unconsumed.
The canvas has no scroll box. #graph-layer is positioned by a single
CSS transform, so scrollIntoView does nothing there. Bringing a node on
screen means writing viewport.pan yourself (ensureNodeVisible).
bb lint-web # biome + stylelint (design tokens)
node tools/browser-test/edit-a11y-dialogs.test.js # focus enters / stays / returns
node tools/browser-test/edit-a11y-tree.test.js # tree navigation, survives rebuild
node tools/browser-test/edit-a11y-canvas.test.js # edge-walking, viewport follows
node tools/browser-test/edit-shortcuts.test.js # leader, guards, cheatsheet
node tools/browser-test/edit-a11y-audit.test.js # structural sweep + contrast
node tools/browser-test/edit-overlay-close.test.js # every cover has a visible way out
The audit sweep runs in the landing gate with the rest of the e2e suite.
It walks the live DOM in four states — shell with a graph, expanded
Explorer, an open dialog, the cheatsheet — and fails on unnamed controls
and dialogs, aria-hidden over something focusable, unlabelled fields,
duplicate ids, missing alt, a missing main, and any text sample under
WCAG AA contrast.
It does not use axe-core: axe is MPL-2.0 and bb license-check allows
only the MIT/BSD/Apache/ISC family, so adding it would turn CI red. The
rules implemented here are the subset of axe that actually fires on an app
of this shape. The a11y MCP runs the real axe out of process, outside
the dependency tree, and stays the tool for ad-hoc scans.
Automated checks do not replace a real screen reader. Before shipping something that changes how a surface is announced, walk it once with NVDA (Windows) or VoiceOver (macOS): find a function, read its arguments, run it.
aria-live on the canvas itself. Node moves are announced by the
navigation module, which knows what the move MEANT; a live region on the
layer would read out layout churn.prefers-contrast: more is honoured
as a token overlay instead (the INCREASED CONTRAST block in
editor-styles.css): the OS setting re-picks the tokens that sat between
AA and AAA, and the audit suite re-runs its live contrast sweep at 7:1
with the media feature emulated — in both themes — so the overlay cannot
rot silently. forced-colors (Windows High Contrast) gets the minimal
companion block: states conveyed only by background are redrawn as
outlines in system colours.