dwmkerr / dwmkerr/effective-shell

[A11Y] [Medium] Heading hierarchy issue on homepage

Open
#414 0 comments 0 reactions 0 assignees View on GitHub
accessibility severity-medium wcag-a
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

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.