Skip to content

Implement comprehensive accessibility improvements (WCAG 2.1)#332

Closed
yshmarov wants to merge 1 commit into
mainfrom
claude/improve-app-accessibility-3adA4
Closed

Implement comprehensive accessibility improvements (WCAG 2.1)#332
yshmarov wants to merge 1 commit into
mainfrom
claude/improve-app-accessibility-3adA4

Conversation

@yshmarov
Copy link
Copy Markdown
Owner

@yshmarov yshmarov commented Feb 6, 2026

Summary

This PR implements comprehensive accessibility improvements across the application to meet WCAG 2.1 standards. Changes include semantic HTML fixes, proper ARIA attributes, keyboard navigation support, focus management, and motion preferences handling.

Key Changes

Documentation & Guidelines

  • Added detailed accessibility guidelines to CLAUDE.md covering semantic HTML, images/icons, focus management, ARIA, forms, motion, and JavaScript best practices

Semantic HTML & Structure

  • Fixed notification table rows: replaced onclick handler with proper <a> link wrapper for keyboard accessibility
  • Fixed feature list: changed from misused <dl> to proper <ul>/<li> structure
  • Added id="main-content" anchors to all layout templates for skip navigation links
  • Added skip-to-main-content links in all layouts (application, centered, static) with proper styling

Images & Icons

  • Added alt attributes to all logo images with site name fallback
  • Added aria-hidden="true" to all decorative SVG icons and images throughout components and views
  • Fixed privacy_setting_icon helper: changed from invalid alt on <span> to proper role="img" and aria-label

Forms & Interaction

  • Converted language picker from inline onchange handler to Stimulus controller (locale_picker_controller.js)
  • Added <label class="sr-only"> for language picker accessibility
  • Added role="alert" to error messages for screen reader announcements

Focus & Keyboard Navigation

  • Enhanced dialog_controller.js to restore focus to trigger element when modal closes (WCAG 2.4.3)
  • Removed automatic blur of focused elements in modals
  • Added aria-label to user menu button

Motion & Zoom

  • Added global prefers-reduced-motion: reduce media query to disable animations for users with motion sensitivity
  • Fixed viewport meta tag: removed user-scalable=0 restriction for regular mobile browsers (only restrict in native app shells per WCAG 1.4.4)

Component Updates

  • Updated empty_state_component.rb to add aria-hidden="true" to decorative icons
  • Updated tabs_component.html.erb to add aria-hidden="true" to tab icons
  • Updated nav_link helper to properly handle emoji icons with aria-hidden wrapper

Implementation Details

  • All decorative SVGs and images now have aria-hidden="true" to prevent screen reader clutter
  • Meaningful emoji icons use role="img" with aria-label for proper semantic meaning
  • Focus restoration in modals uses event listener cleanup to prevent memory leaks
  • Stimulus controllers replace inline event handlers for better maintainability and accessibility
  • Skip navigation links use Tailwind's sr-only and focus:not-sr-only utilities for keyboard-only visibility

https://claude.ai/code/session_016dLbGjCok7srCAqX5uH6pt

- Add skip navigation links to application, centered, and static layouts
- Replace onclick handler on notification rows with proper <a> links
- Replace inline onchange on language picker with Stimulus controller
- Add alt text to all logo images (navbar, footer, centered layout)
- Add role="alert" to error explanation partial for screen readers
- Fix features list: change misused <dl> to proper <ul>/<li>
- Fix dialog controller: store/restore focus instead of blurring,
  and properly clean up event listeners
- Add aria-label to user avatar dropdown button
- Add aria-hidden="true" to decorative SVGs/icons across nav_link
  helper, TabsComponent, EmptyStateComponent, sidebar, navbar, modal
- Fix privacy_setting_icon: replace invalid alt on <span> with
  role="img" and aria-label
- Add prefers-reduced-motion support to disable animations/transitions
- Remove viewport zoom restriction on mobile browsers (WCAG 1.4.4),
  keep only for native app shells
- Update CLAUDE.md with accessibility guidelines section

https://claude.ai/code/session_016dLbGjCok7srCAqX5uH6pt
@yshmarov yshmarov closed this Feb 6, 2026
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.

2 participants