Improve accessibility navigation and controls

[plx]

Summary

• add a skip link, focus management, and main landmark focus styling to improve keyboard navigation
• enhance header navigation semantics, external link handling, and decorative icon markup
• tighten theme toggle accessibility, upgrade astro JSX a11y linting to the strict preset, and improve related scripts

Testing

• npm run lint

---

https://chatgpt.com/codex/tasks/task_e_6907dab108b88327913259d4669f9f56

[github-actions]

PR Validation ✅

All checks passed! Ready for review.

Checks Performed:

✓ Linting
✓ Spell check (source)
✓ Type checking & Build
✓ Spell check (HTML)
✓ Internal link validation
✓ Artifact upload

This is a complete dry-run of the deployment process, ensuring your changes will deploy successfully when merged.

[plx]

@claude please review

[plx]

@claude please review

[claude]

Claude finished @plx's task —— View job

---

Review: Improve accessibility navigation and controls

I've reviewed all the changes in this PR. Overall, this is an excellent accessibility improvement that demonstrates thoughtful attention to keyboard navigation, screen readers, and WCAG compliance. The upgrade to strict a11y linting is particularly commendable. Here are my findings:

---

✅ Strengths

1. Skip Link Implementation (PageLayout.astro:25, global.css:26-49)

• Properly positioned with position: absolute and hidden off-screen until focused
• Smooth keyboard-only reveal with top: 1rem on focus
• Good contrast and visible focus indicator (2px blue outline)
• Correctly targets #main-content with programmatic focus management

2. Focus Management (Head.astro:172-179)

• Excellent use of requestAnimationFrame to ensure DOM is ready
• Main content properly receives focus after skip link activation
• Correctly uses tabindex="-1" on main (PageLayout.astro:27) to allow programmatic focus without adding to tab order

3. Main Landmark Focus Styling (global.css:61-64)

• Clear visual feedback when main receives focus (2px solid #2563eb)
• Appropriate offset (0.5rem) prevents overlap with content

4. Navigation Semantics (Header.astro:17-50)

• Proper <nav> landmark
• Excellent use of aria-current="page" for active navigation items
• Decorative separators correctly marked with aria-hidden="true" (lines 27, 38)
• Semantic list structure maintained

5. External Link Handling (Link.astro:15-16)

• Proper target="_blank" only when external prop is true
• Security-conscious: includes rel="noopener noreferrer"

6. Decorative Icons (BackToPrev.astro:13-14, BackToTop.astro:5-6)

• SVG icons correctly marked with aria-hidden="true" and focusable="false"
• Text content provides accessible label

7. Theme Toggle Improvements (Footer.astro:18, Head.astro:222-234)

• Proper role="group" with aria-label="Theme selection"
• Dynamic aria-pressed state management (lines 227)
• Correct button types and accessible labels

8. ESLint Configuration (eslint.config.js:94)

• Upgrade to jsx-a11y-strict preset is excellent—enforces stricter accessibility rules

---

🔍 Minor Observations & Suggestions

1. Main Focus Style Color Consistency

• The main focus outline uses #2563eb (blue-600), while skip-link uses the same
• Consider: Should this color adapt to dark mode? Currently it's a fixed blue in both themes
• File: global.css:62 and global.css:47
• Recommendation: While the current implementation works, you might consider using a CSS custom property or Tailwind's ring-blue-500 utility for better dark mode contrast. Not blocking—just something to consider.

2. BackToTop Button Label

• Currently has hardcoded text "Back to top" (BackToTop.astro:12)
• No aria-label since the text is visible—this is correct
• Just noting: This button appears conditionally via CSS (global.css:109-115), which is good UX

3. Skip Link Dark Mode Colors

• Uses specific hex values: #f5f5f5, #1f2937, #111827 (global.css:33-42)
• Suggestion: Consider using Tailwind utilities or CSS custom properties for consistency with the rest of the theme system. Example:

  .skip-link {
    @apply bg-stone-100 text-stone-900 dark:bg-stone-800 dark:text-stone-100;
  }

• Not critical—current implementation works fine

4. Theme Button Focus Styles

• The theme toggle buttons have hover styles but no explicit focus styles defined
• They'll get browser default focus indicators, which may work fine
• Consider: Adding explicit focus ring styles for consistency with the skip link:

  [data-theme-button]:focus-visible {
    outline: 2px solid #2563eb;
    outline-offset: 2px;
  }

• File: Footer.astro:25-26, 56, 79

5. Link Component Accessibility

• External links have proper rel but no visual or screen-reader indication they open in new window
• Consider: WCAG 3.2.5 (AAA) suggests warning users about new windows
• Could add: aria-describedby pointing to a hidden description, or append "(opens in new window)" text
• File: Link.astro:15-16
• Not required for AA compliance, but could enhance UX

---

📋 Code Quality

Excellent work on:

• Consistent code style throughout
• Proper TypeScript typing on Props interfaces
• Clean separation of concerns (CSS, markup, behavior)
• No console errors or warnings evident in the code
• Good use of Astro's slot mechanism

Script organization (Head.astro:90-252):

• Well-structured with clear function separation
• Proper event listener cleanup and re-initialization for Astro transitions
• Good defensive programming (e.g., backToTop?.removeEventListener)

---

🎯 Testing Recommendations

Since you've made significant a11y improvements, consider testing:

1. Keyboard navigation: Tab through entire page, verify focus order
2. Screen reader: Test with NVDA/JAWS/VoiceOver to verify announcements
3. Skip link: Verify it appears on Tab and correctly focuses main
4. Theme toggles: Verify aria-pressed states announce correctly
5. Dark mode: Check all focus indicators have sufficient contrast in dark mode

---

✨ Summary

This PR represents a significant accessibility improvement to the site. The implementation quality is high, with proper ARIA usage, semantic HTML, and thoughtful keyboard navigation. The strict a11y linting upgrade will help prevent regressions.

Recommendation: ✅ Approve with minor suggestions

The suggestions above are enhancements, not blockers. The current implementation already provides excellent accessibility support and passes all validation checks. Great work!

---

[claude]

PR Review: Improve accessibility navigation and controls

This is a solid set of accessibility improvements. The changes are well-structured and address real a11y gaps. A few issues worth addressing before merging, plus some minor suggestions.

---

Issues

1. main:focus should be main:focus-visible (medium)

/* global.css */
main:focus {
  @apply outline-2 outline-blue-600 dark:outline-blue-400 outline-offset-2;
}

Using :focus here will show an outline whenever main is programmatically focused — including when users click anywhere that causes #main-content to receive focus. Modern browsers propagate :focus-visible for programmatic .focus() calls when the user's previous interaction was keyboard-based, so a keyboard user activating the skip link will still see the outline with :focus-visible. This avoids the visual noise for mouse users.

main:focus-visible {
  @apply outline-2 outline-blue-600 dark:outline-blue-400 outline-offset-2;
}

---

2. Missing role="list" on the nav <ul> (minor but relevant given the PR's a11y focus)

<ul class="flex items-center gap-3 list-none">

VoiceOver on Safari strips the list semantics from a <ul> when list-style: none is applied (a longstanding WebKit quirk). Since the PR adds proper nav semantics everywhere else, this is worth fixing:

<ul role="list" class="flex items-center gap-3 list-none">

---

3. Missing outline style alongside outline-2 (minor)

In .skip-link:focus and the Footer button classes, only outline-2 (which sets outline-width) is applied without outline (which sets outline-style: solid). Browsers may supply a default outline-style: auto, so this likely works in practice, but it's fragile. Consider adding outline alongside outline-2 for explicit styling — or verify your Tailwind config supplies a default outline style.

---

Suggestions

4. role="radiogroup" vs role="group" for theme buttons

The three theme buttons are mutually exclusive (only one can be "pressed" at a time), which maps semantically to a radio group rather than a generic group. Using role="radiogroup" with role="radio" on each button (or leaving them as button with aria-pressed) is a valid debate — but if you keep aria-pressed + role="group", consider noting why in a comment since auditors sometimes flag this.

---

5. Skip link revealed on hover

.skip-link:focus,
.skip-link:hover {
  top: 1rem;
}

Showing the skip link on mouse hover is unusual — skip links are a keyboard navigation aid and appearing for mouse users can be surprising. Consider dropping the :hover rule and keeping :focus only (or :focus-visible).

---

6. colorSchemeMedia listener added at module scope (FYI, no action needed)

The colorSchemeMedia.addEventListener is outside init(), which is correct — it avoids duplicate registrations across astro:after-swap calls. Just noting it's intentional in case a future reader wonders why it's structured differently from the other listeners.

---

What's great

• rel="noopener noreferrer" on external links — good security fix that was missing
• aria-hidden="true" + focusable="false" on decorative SVGs — correct for both modern and legacy browsers
• aria-current on active nav links — well-implemented
• aria-pressed state syncing for theme buttons — correct pattern and properly initialized
• Named event handler functions with removeEventListener before addEventListener — clean solution to the duplicate-listener problem
• type="button" on all buttons — prevents accidental form submission
• Skip link implementation is clean and standard
• Upgrading to jsx-a11y-strict is a good long-term investment

Overall: two things worth fixing before merge (items 1 and 2), the rest are optional.

[github-actions]

PR Validation ✅

All checks passed! Ready for review.

Checks Performed:

✓ Linting
✓ Spell check (source)
✓ Type checking & Build
✓ Spell check (HTML)
✓ Internal link validation
✓ Artifact upload

This is a complete dry-run of the deployment process, ensuring your changes will deploy successfully when merged.