TL;DR:
- Lighthouse scored my Org Chart 98%. A keyboard user could not reach a single node.
- I audited from three angles: automated tools, manual pass, LLM review.
- Fixes: landmarks, headings, focus styles,
role="tree"+ custom keyboard shortcuts, skip-link as documentation. - Tools score documents, not diagrams. They check what they can check.
- The biggest takeaway: try the app with the keyboard before the first commit.
Accessibility is getting harder to ignore, and that is mostly a good thing. The same markup that helps a screen reader user also lets web crawlers and LLM agents work from structure instead of screenshots. The catch is that the apps where the standard tools and articles say the least - diagrams, dashboards, data-heavy interfaces - are the ones where teams will increasingly need answers. The complexity is real, but it is not an excuse.
I built an Org Chart with ngDiagram a while back, and I want accessibility to be part of how I build rather than something I bolt on later. To audit it I picked the tools I had not used before on a real app: Lighthouse, WAVE, an accessibility linter, and an LLM-based review. What follows is a walkthrough of that audit rather than a guide.
The audit
The plan was to look at the app from three angles: automated tools, a manual pass, and an LLM review of the code itself.
What the automated tools said
Lighthouse went first. 98 out of 100, with one fix (a missing main landmark) and a manual checklist worth running through.
WAVE was more useful. Zero errors, but the warnings were the interesting part: node descriptions rendered below comfortable reading size and no heading structure on the page at all. The order tab was the only thing nagging me - something about the labels on the diagram's tab stops did not quite line up with what I expected, and that was enough to push me into trying the app manually.
The ESLint accessibility rules (angular-eslint's templateAccessibility ruleset) came in later as a habit rather than an audit. They do not catch the big things - those live in interactions, not markup. But they raise a hand when a label is missing or an aria attribute is wrong, every time you save. Next step is wiring them into CI so a missing label is a build failure rather than a reminder I might ignore.
What clicking and tabbing told me
I set the mouse aside and opened the browser's developer tools. The accessibility panel has an option to show the page as a full accessibility tree - a nice discovery on its own. The zoom level was rendered as a bare number, which a screen reader would read as "100" with no idea what it was 100 of. The minimap was technically hidden when collapsed, but the underlying image was still in the tree.
The keyboard pass was where the audit stopped feeling routine. Tabbing worked fine until I reached the diagram, and at first I thought it worked there too. What I was actually reaching were the expand/collapse buttons on each node. The nodes themselves had no focus, and the plus-buttons for adding new ones only appeared on mouse hover - which meant they did not exist for anyone not using one, and they did not exist for the audit tools either, because there is nothing in the DOM until the pointer event fires. Drag-and-drop reordering was the same story. Two of the most important things in the app were entirely mouse-only, and the previous tools had not flagged any of it. They were not wrong. They were checking what they can check, and they cannot check interactions that only exist while you hover.
What the LLM caught
For the third pass I used Claude with a custom skill based on the accessibility-review skill on MCPMarket. It agreed with the static tools on the obvious things. What it added was findings you can only get by reading the code: the specific input that auto-focused when the properties sidebar opened, the exact pointerdown handler that locked add-buttons to a mouse, and the missing keyboard entry on the diagram as a top finding rather than a footnote. Running it twice gave overlapping but not identical lists. Not every point was worth fixing, and saying no to a few of them ended up being part of the audit too.
Making the diagram keyboard-reachable
The first decision was what kind of thing the diagram actually is. An org chart is a tree, so the canvas got role="tree" and each node got role="treeitem". That changes how a screen reader narrates the structure: instead of "graphic, region" it reads as a hierarchical tree, which matches what the user is actually looking at. Picking the role is the application's job, not the library's - ngDiagram does not know whether you are rendering an org chart, a state machine, or a dependency graph, and each of those wants a different role.
The canvas gets the tree role:
<main aria-describedby="diagram-instructions" ...>
<div role="tree" aria-label="Organization tree">
<ng-diagram ... />
</div>
</main>
Each node component declares itself a treeitem through its host bindings, alongside the aria state it needs to expose:
@Component({
host: {
'[attr.role]': '"treeitem"',
'[attr.tabindex]': 'isFocusable() ? 0 : -1',
'[attr.aria-selected]': 'node().selected',
'[attr.aria-expanded]': 'ariaExpanded()',
'[attr.aria-label]': 'ariaLabel()',
},
})
export class NodeComponent { ... }
isFocusable() is a roving tabindex: only one node is in the tab order at a time, so Tab moves in and out of the canvas in one step rather than walking every node.
The interaction model:
| Keys | Action |
|---|---|
| Shift + arrows | Move focus between nodes |
| Arrows (when focused) | Move the node on the canvas |
| Space | Expand / collapse children |
| Enter / Esc | Open / close properties panel |
| Alt + arrows | Add a new node next to the focused one (child or sibling depending on layout direction) |
| Delete | Remove the focused node |
Adding all of this raised a question I had not been thinking about: how does the user know any of it exists? Implementing keyboard support is one job. Making sure people can find out it is there is another - a shortcut nobody is told about is a secret.
The skip-link as documentation
The answer ended up sitting next to the skip-link. The skip-link itself jumps focus to the diagram; right after it, a short paragraph lists every shortcut. The diagram's <main> references that paragraph via aria-describedby, so the instructions get announced when focus enters the canvas. The paragraph stays visible on the page too - sighted keyboard users need to know the shortcuts as much as screen reader users do, and the audit tools cannot tell them.
The side effect was the thing I did not see coming. Once there was a place to tell the user about a shortcut, the answer to "the plus-buttons only show on hover" stopped being "show them on focus too" and became "a custom shortcut, written down right next to the skip-link." Having somewhere to document a shortcut is what made them worth building at all.
The smaller fixes
The static-tool findings mostly translated to small fixes:
- The page got a
<main>landmark and a visually-hidden<h1>. - Styled spans pretending to be headings became real heading tags.
- Icon-only buttons (add, toggle, caret, sidebar, theme, zoom) picked up
aria-labels; the toggle-expand button gotaria-expanded. - "100" in the zoom widget became "Zoom level 100" - the kind of fix where a lot of accessibility work hides: rewriting a number to say what the number is of.
- Blanket
outline: nonecame out of the form styles;:focus-visiblerings went in. - The minimap, which duplicates content the keyboard user already navigates on the main canvas, got
aria-hidden="true"- along with the button that toggles it, since a control that opens a panel the user cannot perceive is no use to them either.
What I left alone (on purpose)
- Drag-and-drop hierarchy changes are still mouse-only. A real gap; a keyboard equivalent (cut/paste-style reparenting) was bigger than this round could absorb.
- No help dialog or shortcut overlay yet. The description next to the skip-link is enough to make the keyboard support discoverable for this pass.
- The properties sidebar is deliberately non-modal. No focus trap, no focus return on close, because a user editing a node's properties should still be able to move around the diagram underneath. That one is a feature, not a deferred fix.
Where this leaves me
The audit changed the app. What I did not expect was that it would also change how I look at apps. If I had spent any real time using my own work with the keyboard only, before I started building it, I would have built it differently from day one. That is the thing I am taking forward: not a list of fixes, but the habit of trying the app the way the user will, before the first commit.
Tools like Lighthouse, WAVE, and the LLM pass are useful starting points. They tell you where to look. They cannot tell you whether the app is actually usable. That part still needs a person, a keyboard, and a willingness to be honest with yourself about what you find.
Diagrams and other visual tools have a lot going on - many features, many interactions, many edge cases - and making them work for every user is harder than making a form work for every user. Most of the existing material does not help with the difference. If you are curious about how those problems play out in practice (and where some of them are still unsolved), come talk to us.
Where to look next
- Building Accessible Whiteboards and Diagrams - the GAAD 2026 webinar we are hosting
- ngDiagram Org Chart - the app the audit was on
- ngDiagram - the library the app is built on
- angular-eslint - the ESLint plugin with the templateAccessibility ruleset
- accessibility-review skill - the basis for the LLM audit skill I used
GAAD 2026 webinar - Thursday, 21 May, 14:00 CET
Anna Dulny-Leszczyńska and I are hosting Building Accessible Whiteboards and Diagrams: a free, 45-minute talk with real examples instead of theory.
Top comments (0)