asgardeo / asgardeo/javascript

feat: add `WCAG 2.2` Compliance and Accessibility Testing to `@asgardeo/react` & `@asgardeo/nextjs` UI Components

Open
#143 11 comments 0 reactions 0 assignees View on GitHub
@asgardeo/nextjs @asgardeo/react accessibility Complexity/Low good first issue Type/Improvement
Dominant language
TypeScript
Stars
18
Forks
67
Avg merge
4h 6m
Merged PRs (30d)
13

Description

### Current Limitation

The `@asgardeo/react` & `@asgardeo/nextjs` UI components lack comprehensive accessibility features and WCAG 2.2 compliance:

**WCAG 2.2 Compliance Issues:**
- Missing support for new WCAG 2.2 success criteria (Focus Appearance, Dragging Movements, Target Size)
- Non-compliant focus indicators and target sizes
- Lack of proper keyboard navigation patterns

**Keyboard Navigation Issues:**
- Organization switcher dropdown cannot be navigated with keyboard
- Modals lack proper focus management and keyboard shortcuts
- No Escape/Enter key handling

**ARIA Support Gaps:**
- Missing ARIA labels for interactive elements
- Dropdown menus lack aria-expanded, aria-haspopup attributes
- Modal dialogs missing aria-modal, aria-labelledby
- No screen reader announcements for organization switches

**Focus Management:**
- Modals don't trap focus
- Focus not restored when modals close
- Missing visual focus indicators that meet WCAG 2.2 standards

**Testing:**
- No automated WCAG 2.2 accessibility testing
- Missing keyboard navigation tests
- No screen reader compatibility verification

### Suggested Improvement

Add comprehensive WCAG 2.2 AA accessibility support with proper testing:

## Implementation Areas

### 1. WCAG 2.2 Compliance
- **Focus Appearance (2.4.11)**: Enhanced focus indicators with proper contrast
- **Target Size (2.5.8)**: Ensure interactive elements meet 24x24px minimum
- **Dragging Movements (2.5.7)**: Provide keyboard alternatives for any drag interactions
- **Fixed Reference Points (2.4.12)**: Consistent navigation patterns

### 2. ARIA Enhancements
- Add proper ARIA attributes to dropdowns and modals
- Implement live regions for dynamic announcements
- Add descriptive labels for all interactive elements

### 3. Keyboard Navigation
- Arrow keys for dropdown navigation
- Enter/Space for selection, Escape to close
- Focus trapping in modals with Tab/Shift+Tab
- Focus restoration when closing modals

### 4. Screen Reader Support
- Live announcements for organization switches
- Loading state announcements
- Error message announcements

### 5. Custom Accessibility Hooks
```tsx
// WCAG 2.2 compliant hooks
useFocusTrap(isActive: boolean)
useFocusRestore()
useAnnouncement()
useKeyboardNavigation()
useWCAGCompliantFocus()
```

### 6. Testing with Vitest + WCAG 2.2
```tsx
// WCAG 2.2 automated testing
test('meets WCAG 2.2 AA standards', async () => {
// axe-core with WCAG 2.2 rules
});

// Focus appearance testing
test('focus indicators meet WCAG 2.2 standards', () => {
// Focus visibility and contrast testing
});

// Target size validation
test('interactive elements meet 24x24px minimum', () => {
// Target size compliance testing
});
```

## Benefits
- **WCAG 2.2 AA compliance** for legal requirements
- **Enhanced focus indicators** for better visibility
- **Improved target sizes** for touch and motor accessibility
- **Better keyboard-only navigation**
- **Screen reader compatibility**
- **Automated accessibility regression prevention**

## Key Files to Update
- OrganizationSwitcher components (ARIA + keyboard + WCAG 2.2)
- Modal components (focus management + target sizes)
- New accessibility hooks with WCAG 2.2 compliance
- CSS for WCAG 2.2 compliant focus indicators
- Vitest setup for axe-core with WCAG 2.2 rules
- ESLint jsx-a11y rules updated for WCAG 2.2

### Please select the package issue is related to

@asgardeo/react, @asgardeo/nextjs

### Version

current

### Reporter Checklist

- [x] I have searched the existing issues and this is not a duplicate.
- [x] I have provided all the necessary information.
- [x] I have verified the improvement is not available in the latest version of the package.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.