dwmkerr / dwmkerr/effective-shell
[A11Y] [Medium] Heading hierarchy issue on homepage
- Dominant language
- JavaScript
- Stars
- 780
- Forks
- 93
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 3
Description
## Accessibility Issue: Heading hierarchy issue on homepage
**WCAG Level:** A
**Severity:** Medium
**Category:** Semantic HTML
### Issue Description
The homepage (`src/pages/index.tsx`) starts with an `
` heading ("Effective Shell") instead of an `
`. This violates the heading hierarchy best practice where pages should have exactly one `
` as the primary heading.
Similarly, the feature cards use `
` without a preceding `
` parent context on the page.
### User Impact
- **Affected Users:** Screen reader users, users who navigate by headings
- **Severity:** Users navigating by headings may be confused by the missing `
` and incorrect hierarchy
### Violations Found
#### File: `src/pages/index.tsx`
**Lines:** 12, 85
```tsx
// Line 12
Effective Shell
// Line 85
{feature.title}
```
**Issue:**
1. Main page title uses `
` instead of `
`
2. Feature cards use `
` without proper heading hierarchy
3. The page has no `
` element
---
### Recommended Fix
```tsx
function HeroSection() {
return (
Effective Shell
...
);
}
function FeatureSection() {
return (
Key Features
{features.map((feature, idx) => (
{feature.title}
...
))}
);
}
```
**Changes Made:**
1. Changed hero title from `
` to `
`
2. Added visually hidden `
` before feature cards for proper hierarchy
3. Feature `
` elements now have proper parent context
**CSS for visually hidden class:**
```css
.visually-hidden {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
```
### Testing Instructions
1. Use a screen reader or browser extension to list all headings on the page
2. Verify there is exactly one `
` element
3. Verify heading levels don't skip (h1 → h2 → h3)
4. Test with Chrome DevTools Accessibility tree
### Resources
- [WCAG 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)
- [WCAG 2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html)
- [MDN: Heading elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
### Acceptance Criteria
- [ ] Homepage has exactly one `
` element
- [ ] Heading hierarchy follows proper order (h1 → h2 → h3)
- [ ] Tested with screen reader heading navigation
- [ ] Manual testing completed
---
Contributor guide
Assessment
This issue has not been assessed yet.