Skip to content

fix: add WCAG 2.1 AA accessibility compliance#24

Merged
corvid-agent merged 3 commits intomainfrom
fix/issue-20-aa-accessibility
Feb 25, 2026
Merged

fix: add WCAG 2.1 AA accessibility compliance#24
corvid-agent merged 3 commits intomainfrom
fix/issue-20-aa-accessibility

Conversation

@corvid-agent
Copy link
Owner

Summary

Adds comprehensive WCAG 2.1 AA accessibility support across all components. This addresses the accessibility gaps identified in #20.

Changes

Global (styles.scss, index.html)

  • Skip navigation link for keyboard users
  • Visible :focus-visible indicators on all interactive elements
  • Screen-reader-only utility class (.sr-only)
  • prefers-reduced-motion media query
  • Improved color contrast: --text-muted and --text-secondary now meet 4.5:1 contrast ratio
  • lang="en" added to 404.html

Semantic HTML

  • <nav> for spec list, <section> for editor panels, <article> for preview/features
  • <fieldset> + <legend> for list editor groups (files, db_tables, dependencies)
  • <form> wrappers with aria-label for GitHub connect forms

ARIA Attributes

  • role="tablist" / role="tab" / role="tabpanel" for Edit/Preview tabs
  • role="tree" / role="treeitem" with aria-expanded for collapsible suite groups
  • aria-selected, aria-current for active items
  • aria-label on all icon buttons, decorative content hidden with aria-hidden
  • aria-live="polite" for status updates, aria-live="assertive" for errors
  • aria-busy on loading buttons
  • aria-expanded on sidebar toggle and PAT form toggle

Form Accessibility

  • All inputs have associated <label> elements (visible or .sr-only)
  • List add-inputs have screen-reader labels
  • Remove buttons have descriptive aria-label (e.g., "Remove file server/path.ts")

Keyboard Navigation

  • Spec list items are keyboard-navigable (Enter/Space to select)
  • Focus styles replace all outline: none patterns

Focus Management

  • Replaced outline: none with focus-visible outlines (2px solid accent with offset)

Fixes #20

Test plan

  • Verify skip link appears on Tab from page load and navigates to main content
  • Tab through all interactive elements and verify visible focus rings
  • Test with screen reader (VoiceOver/NVDA): verify all buttons, inputs, and status changes are announced
  • Verify Edit/Preview tabs announce role and selection state
  • Verify spec list tree items announce expanded/collapsed state
  • Verify validation errors are announced via aria-live
  • Verify color contrast meets 4.5:1 for normal text in both dark and light themes
  • Test with prefers-reduced-motion: reduce — verify no animations
  • Run automated accessibility audit (axe, Lighthouse) and verify no AA violations

🤖 Generated with Claude Code

- Add skip navigation link for keyboard users
- Add visible focus indicators (focus-visible) across all interactive elements
- Replace outline:none with proper focus styles on inputs
- Add reduced-motion media query for users who prefer reduced animations
- Add screen-reader-only utility class (.sr-only)
- Improve color contrast ratios for text-muted and text-secondary
- Add semantic HTML: nav, section, article, fieldset/legend elements
- Add ARIA attributes: roles, aria-expanded, aria-selected, aria-live,
  aria-label, aria-labelledby, aria-current, aria-busy, aria-controls
- Add proper tablist/tab/tabpanel roles for editor view tabs
- Add tree/treeitem roles for spec list navigation
- Add keyboard event handlers (Enter/Space) for spec list items
- Add aria-label for delete buttons, form inputs, and icon buttons
- Mark decorative elements as aria-hidden
- Add role="alert" and aria-live="assertive" for error messages
- Add role="status" and aria-live="polite" for status updates
- Add proper form labels and fieldset/legend for list editors
- Add lang="en" to 404.html
- Wrap frontmatter list fields in fieldsets with legends
- Use <form> wrappers with aria-label for GitHub connect forms

Fixes #20

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
@corvid-agent corvid-agent mentioned this pull request Feb 25, 2026
@corvid-agent
Copy link
Owner Author

@corvid-agent resolve the CI.

…ection

The <form> element causes Angular's NgForm directive (from FormsModule) to
attach automatically, which interferes with signal-based change detection
in zoneless Angular 21. This prevented the spec-list sidebar collapse/expand
from updating the DOM despite the signal state changing correctly.

Adding ngNoForm prevents NgForm from attaching while keeping the semantic
<form> element for accessibility. The individual ngModel bindings continue
to work independently.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@corvid-agent
Copy link
Owner Author

Fixed in 1c40639.

Root cause: The <form> wrapper added to frontmatter-editor.html caused Angular's NgForm directive (auto-attached by FormsModule) to interfere with signal-based change detection in Angular 21's zoneless mode. The spec-list's collapsedSuites signal was updating correctly on click, but the DOM wasn't re-rendering.

Fix: Added ngNoForm to the <form> element to prevent NgForm from attaching, while keeping the semantic <form> for accessibility. All 11 e2e tests, 35 unit tests, and the build now pass.

@corvid-agent
Copy link
Owner Author

@corvid-agent there are still merge conflicts.

@corvid-agent
Copy link
Owner Author

Merge conflicts resolved in d590af7.

Two conflicts were present after merging main:

  • section-editor.html — main added arrow entities (/) to nav buttons while this branch added aria-label attributes. Kept both.
  • editor-page.html — main simplified the frontmatter panel closing tag while this branch added a <footer> with section navigation. Kept the accessibility footer and <section> wrapper.

The branch should be mergeable now.

@corvid-agent corvid-agent merged commit 92c4634 into main Feb 25, 2026
4 checks passed
@corvid-agent corvid-agent deleted the fix/issue-20-aa-accessibility branch February 25, 2026 01:21
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.

AA standards

1 participant