[A11Y] [Medium] Heading hierarchy issue on homepage

[continue]

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 <h2> heading ("Effective Shell") instead of an <h1>. This violates the heading hierarchy best practice where pages should have exactly one <h1> as the primary heading.

Similarly, the feature cards use <h3> without a preceding <h2> 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 <h1> and incorrect hierarchy

Violations Found

File: src/pages/index.tsx

Lines: 12, 85

// Line 12
<h2 className={styles.heroTitle}>Effective Shell</h2>

// Line 85
<h3 className={styles.featureTitle}>{feature.title}</h3>

Issue:

1. Main page title uses <h2> instead of <h1>
2. Feature cards use <h3> without proper heading hierarchy
3. The page has no <h1> element

---

Recommended Fix

function HeroSection() {
  return (
    <header className={styles.heroBanner}>
      <div className={styles.heroContent}>
        <div className={styles.heroText}>
          <h1 className={styles.heroTitle}>Effective Shell</h1>
          ...
        </div>
      </div>
    </header>
  );
}

function FeatureSection() {
  return (
    <section className={styles.features}>
      <div className={styles.featuresContainer}>
        <h2 className="visually-hidden">Key Features</h2>
        <div className={styles.featureGrid}>
          {features.map((feature, idx) => (
            <div key={idx} className={styles.featureCard}>
              <h3 className={styles.featureTitle}>{feature.title}</h3>
              ...
            </div>
          ))}
        </div>
      </div>
    </section>
  );
}

Changes Made:

1. Changed hero title from <h2> to <h1>
2. Added visually hidden <h2> before feature cards for proper hierarchy
3. Feature <h3> elements now have proper parent context

CSS for visually hidden class:

.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 <h1> 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
• WCAG 2.4.6 Headings and Labels
• MDN: Heading elements

Acceptance Criteria

• Homepage has exactly one <h1> element
• Heading hierarchy follows proper order (h1 → h2 → h3)
• Tested with screen reader heading navigation
• Manual testing completed

---