dwmkerr / dwmkerr/effective-shell

[A11Y] [Low] Missing focus styles across the application

Open
#415 0 comments 0 reactions 0 assignees View on GitHub
accessibility severity-low wcag-a
Dominant language
JavaScript
Stars
780
Forks
93
Avg merge
1d 7h
Merged PRs (30d)
3

Description

## Accessibility Issue: Missing focus styles across the application

**WCAG Level:** A
**Severity:** Low
**Category:** Keyboard Navigation Issues

### Issue Description
The application's custom CSS (`src/css/custom.css` and component CSS modules) lacks explicit focus styles for interactive elements. While browsers provide default focus indicators, these are often insufficient or may not match the design system.

The only `:focus` style found in the codebase is in `samples/websites/simple/styles.css`, which is a sample file, not the actual application CSS.

### User Impact
- **Affected Users:** Keyboard-only users, users with motor disabilities, users with low vision
- **Severity:** Users may have difficulty seeing which element is currently focused when using keyboard navigation

### Violations Found

#### File: `src/css/custom.css`
No `:focus` or `:focus-visible` styles defined for any elements.

#### File: `src/pages/index.module.css`
**Lines:** Multiple
```css
.navbarLink {
color: rgba(255, 255, 255, 0.6);
text-decoration: none;
font-size: 1rem;
}

.navbarLink:hover {
color: #fff;
text-decoration: none;
}
/* Missing :focus styles */

.buttonPrimary {
/* ... */
}

.buttonPrimary:hover {
background: #3a8eef;
color: white;
text-decoration: none;
}
/* Missing :focus styles */

.buttonSecondary {
/* ... */
}

.buttonSecondary:hover {
border-color: #fff;
color: white;
text-decoration: none;
}
/* Missing :focus styles */
```

**Issue:** Multiple interactive elements have `:hover` styles but no corresponding `:focus` styles

---
### Recommended Fix

Add to `src/css/custom.css`:
```css
/* Global focus styles */
a:focus,
button:focus,
[tabindex]:focus {
outline: 2px solid var(--ifm-color-primary);
outline-offset: 2px;
}

a:focus:not(:focus-visible),
button:focus:not(:focus-visible),
[tabindex]:focus:not(:focus-visible) {
outline: none;
}

a:focus-visible,
button:focus-visible,
[tabindex]:focus-visible {
outline: 2px solid var(--ifm-color-primary);
outline-offset: 2px;
}
```

Add to `src/pages/index.module.css`:
```css
.navbarLink:focus,
.navbarLinkActive:focus {
outline: 2px solid #fff;
outline-offset: 2px;
}

.buttonPrimary:focus {
outline: 2px solid #fff;
outline-offset: 2px;
box-shadow: 0 0 0 4px rgba(74, 158, 255, 0.4);
}

.buttonSecondary:focus {
outline: 2px solid #fff;
outline-offset: 2px;
}
```

**Changes Made:**
1. Added global focus styles in custom.css
2. Added component-specific focus styles for homepage elements
3. Used `:focus-visible` for better mouse/keyboard differentiation

### Additional Instances
Files that may need focus style review:
- `src/components/ShellwrightRecording/ShellwrightRecording.module.css`
- `src/components/AmazonBookPreview/styles.css`
- Any other custom component CSS

### Testing Instructions
1. Open the application in a browser
2. Use Tab key to navigate through interactive elements
3. Verify each link, button, and interactive element has a visible focus indicator
4. Check both light and dark themes
5. Test on the homepage custom landing page specifically

### Resources
- [WCAG 2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)
- [MDN: :focus-visible](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible)
- [A11y Style Guide - Focus Styles](https://a11y-style-guide.com/style-guide/section-general.html#kssref-general-focus)

### Acceptance Criteria
- [ ] Global focus styles added to custom.css
- [ ] Homepage-specific focus styles added
- [ ] All interactive elements have visible focus indicators
- [ ] Focus styles work in both light and dark themes
- [ ] Manual keyboard navigation testing completed

---

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.