feat(ui): Make CDS screenreader accessible (WCAG 2.2 AA, zero visual change)#7787
Open
behofer wants to merge 2 commits into
Open
feat(ui): Make CDS screenreader accessible (WCAG 2.2 AA, zero visual change)#7787behofer wants to merge 2 commits into
behofer wants to merge 2 commits into
Conversation
Make the CDS UI perceivable and operable with screenreaders (NVDA) and keyboard, as a strictly non-visual retrofit: default rendering is pixel identical; only attributes, announcements and tooling change. - document language, page-title announcements on navigation (cdk LiveAnnouncer), landmark roles (banner/navigation/main), skip link - form labels programmatically associated (nzFor + ids) across all views; aria-label fallbacks for placeholder-only inputs - accessible names for icon-only buttons; alt texts; status icons expose their state as text (aria-label "Status: ...") - keyboard/AT retrofit for non-interactive click targets via a new appClickable directive (role=button, tabindex, Enter/Space) - shared tabs expose APG tab semantics (tablist/tab, aria-selected, arrow-key navigation); data-table gains aria-sort + keyboard sort - run logs: step headers as disclosures (aria-expanded), role=log on streaming containers; run status changes announced politely - workflow graph (libs/workflow-graph): focusable container with arrow-key navigation moving real DOM focus, per-node accessible names, selection announcements, +/-/0 zoom keys; key handling no longer intercepts arrows while typing in unrelated inputs - toasts announced via ToastService (polite/assertive); nz-spin and banners exposed as role=status; Monaco editors labelled - tooling: @angular-eslint/template accessibility rules enabled as warnings (ratchet baseline, 0 errors); conventions documented in ui/docs/accessibility.md; audit and phased plan with remaining visual-impact items in ui/docs/accessibility-plan.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Benjamin Hofer <benjamin@gridscale.io>
behofer
changed the title
behofer
marked this pull request as ready for review
July 14, 2026 11:59
behofer
requested review from
fsamin,
richardlt,
sguiheux and
yesnault
as code owners
July 14, 2026 11:59
richardlt
requested changes
Jul 15, 2026
richardlt
left a comment
richardlt
left a comment
Member
There was a problem hiding this comment.
Can you please rework this PR to make it easier to review, for example in the specs remove non necessary technical details and also phasing informations. In other words the spec should describe how the project is working in the commit's codebase and guideline for future changes but not the history of the project.
Replace the historical audit/phasing plan with a single spec that describes how accessibility works in the current codebase and the rules to follow for future template changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Author
|
It should be much cleaner now, see first comment and ui/docs/accessibility.md for the changes. For questions, let's have a chat |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Large parts of CDS UI are a blackbox for a screenreader user, mainly due to unlabeled buttons, form fields and graphics, missing semantic roles (ARIA), and a workflow viewer that is fully invisible to assistive technology.
This PR fixes most of these problems with strictly zero visual change: only attributes, screenreader announcements, keyboard handling, docs and lint tooling are added. From a screenreader user's standpoint, this makes a huge(!!) difference.
How accessibility works in the UI and the rules for future template changes are documented in
ui/docs/accessibility.md.AI transparency note
The code changes in this repo were created with Claude Fable 5 model (high-effort level thinking).
I provided ideas, guidance, and proper prompting as well as some testing with NVDA screenreader.
Changes
Global
langon<html>, landmark roles (banner/navigation/main), skip link (off-screen, keyboard-only), page-title announcements on navigation via CDKLiveAnnouncerToastService(politefor success/info,assertivefor errors); spinners/banners exposed asrole="status"Forms & names (all views)
nzFor+idpairing for form labels;aria-labelwhere no visible label existsaltfixes; status icons announce their state (aria-label="Status: …")Interaction retrofit (attribute-only, no element swaps)
appClickabledirective addsrole="button",tabindex="0", Enter/Space to legacy click targets (fake links, clickable divs/rows)tablist/tab,aria-selected, arrow keys); data-table gainsaria-sort+ keyboard sortingaria-expanded,role="log"on streaming containers; run status changes announcedWorkflow graph (
libs/workflow-graph)+/-/0zoom/center; keyboard handling no longer intercepts arrows while typing in unrelated inputsTooling & docs
@angular-eslint/templateaccessibility rules enabled (warnon rules still triggered by legacy templates,erroronce clean)ui/docs/accessibility.md— how accessibility works in the UI, the rules to follow for new/changed templates, and known limitationsOut of scope
Fixes that require visible UI changes are deliberately excluded and listed under "Known limitations" in
ui/docs/accessibility.md(focus-visible styling, element swaps, graph list view, drag-and-drop keyboard alternative, CodeMirror migration). Each will come as its own PR with before/after screenshots.Verification
ng build(development configuration) compiles;ng lintpasses with 0 errorscds-sr-only, skip link) and invisible sr-only spansOpen
I will need to test the whole screenreader accessibility in a "real" development environment. Large parts were not testable e2e locally.