Skip to content

fix(a11y): give the graph and its controls accessible names - #110

Open
Ravi chandu Edru (RaviChanduEdru) wants to merge 1 commit into
microsoft:mainfrom
RaviChanduEdru:fix/a11y-graph-labels
Open

fix(a11y): give the graph and its controls accessible names#110
Ravi chandu Edru (RaviChanduEdru) wants to merge 1 commit into
microsoft:mainfrom
RaviChanduEdru:fix/a11y-graph-labels

Conversation

@RaviChanduEdru

Copy link
Copy Markdown
Contributor

Picks up the unchecked "Add ARIA labels to the graph visualization" item from TODO.md, continuing the recent accessibility work (#75, #77, #78).

The problem

Cytoscape paints the ontology into <canvas> elements, which expose nothing to assistive technology. The container is a bare div:

<div ref={containerRef} className="graph-canvas" data-testid="ontology-graph-canvas" />

No role, no label, no text alternative — a screen reader announces nothing at all for the app's central feature.

The change

The graph canvas gets role="img" and an accessible name built from the loaded ontology — name, entity-type count, relationship count:

"Fourth Coffee ontology graph: 6 entity types, 7 relationships. Interactive diagram."

Two deliberate choices there:

  • The role goes on .graph-canvas, not .graph-container. role="img" prunes descendants from the accessibility tree, and the container also holds the legend and the control buttons — putting it there would have hidden them.
  • Entity and relationship names are not folded into the label. They're already reachable as real DOM in the search panel and the legend, and a paragraph-long accessible name reads badly.

The summary lives in src/lib/graphA11y.ts as a pure function, so it's testable without mounting cytoscape in jsdom.

The five control buttons are icon-only and carried only a title. To be precise: title does supply an accessible name for an icon-only button, so this wasn't a violation — but it's the fragile option, announced inconsistently across screen readers and invisible on touch. They now carry explicit aria-labels, with title kept for the mouse tooltip.

Verification

5 unit tests cover the summary: counts, singular/plural agreement, an empty ontology, and the unnamed/whitespace-name fallback.

Driven against the running app with Playwright:

Check Result
Canvas exposes role="img" yes, 1 match
Accessible name "Fourth Coffee ontology graph: 6 entity types, 7 relationships. Interactive diagram."
Label tracks the loaded ontology switches to "E-Commerce Platform ontology graph: 5 entity types, 6 relationships."
All 5 controls resolvable by accessible name yes — and they activate correctly when clicked by name

No console errors. Only existing theme tokens are involved, so the contrast suite is untouched.

Scope

Cytoscape paints the ontology into <canvas>, which exposes nothing to
assistive technology. The container was a bare <div> with no role, no label,
and no text alternative, so a screen reader announced nothing at all for the
app's central feature - TODO.md's "Add ARIA labels to the graph
visualization".

Mark the canvas container role="img" and label it with a summary built from
the loaded ontology: name, entity type count, relationship count. The role
goes on .graph-canvas rather than .graph-container so the legend and the
control buttons stay exposed as their own elements. Entity and relationship
names are not folded into the label - they are already reachable as real DOM
in the search panel and the legend, and a paragraph-long accessible name
reads badly.

The summary lives in lib/graphA11y.ts as a pure function so it can be tested
without mounting cytoscape in jsdom.

The five graph control buttons are icon-only and carried only a title. A
title does supply an accessible name, but it is the fragile option - not
announced consistently across screen readers and invisible on touch. Add
explicit aria-labels and keep title for the mouse tooltip.

Verified against the running app: the canvas exposes role="img" named
"Fourth Coffee ontology graph: 6 entity types, 7 relationships. Interactive
diagram.", the label tracks the loaded ontology when switching to E-Commerce
Platform, and all five controls resolve and activate by their accessible
names. No console errors.

Keyboard navigation of the graph itself is a separate TODO item and is not
addressed here.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant