Accessibility Fixes and Minimized Music Player Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Improve Lighthouse accessibility/SEO low-hanging issues and add a theme-aware minimized music player mode that persists across instant navigation within the current browsing session.
Architecture: Keep the existing music player component and UI structure intact, adding only the minimal metadata and state hooks required for accessibility fixes and a new compact/minimized display state. Use session-scoped state (not long-term persistence) so minimized status survives page transitions but resets on full refresh.
Tech Stack: MkDocs Material, vanilla JavaScript, CSS, HTML template overrides, ARIA attributes, sessionStorage or session-scoped runtime state
Task 1: Fix Lighthouse metadata and accessibility attributes
Files:
- Modify: mkdocs.yml
- Modify: overrides/main.html
- Modify: docs/javascripts/music-player.js
- Verify: generated search dialog, progressbar, and music player slider in rendered pages
Step 1: Write the failing test
Manual failing criteria from current Lighthouse JSON:
- meta-description score is 0
- search dialog lacks accessible name
- progressbar lacks accessible name
- music player seek slider lacks label/aria-label
Step 2: Run verification to confirm failure
Confirm in current rendered output that:
- page head lacks meta description
- .md-search[role="dialog"] lacks aria-label or equivalent name
- .md-progress[role="progressbar"] lacks aria-label
- #tcy-seek-slider lacks accessible labeling
Expected: FAIL.
Step 3: Write minimal implementation
- Add a concise site-wide meta description in MkDocs config or head override
- Add search dialog accessible name in override/template layer
- Add progressbar accessible name in override/template layer
- Add
aria-labelto the music seek slider when player markup is created
Do not change search behavior, progress behavior, or player logic beyond metadata.
Step 4: Run verification to confirm it passes
Expected: - meta description present - search dialog has accessible name - progressbar has accessible name - seek slider has accessible name
Step 5: Commit
git add mkdocs.yml overrides/main.html docs/javascripts/music-player.js
git commit -m "fix: improve metadata and accessibility labels"
Task 2: Fix Minecraft-theme contrast issues in music player
Files:
- Modify: docs/stylesheets/music-player.css
- Possibly modify: docs/stylesheets/minecraft-theme.css
- Verify: music player in minecraft mode only
Step 1: Write the failing test
Manual failing criteria from Lighthouse JSON: - player title color contrast too low in minecraft mode - track name contrast too low in minecraft mode - current/total time contrast too low in minecraft mode
Step 2: Run verification to confirm failure
Check the minecraft-mode player selectors identified by Lighthouse and confirm their effective foreground/background colors still fall below target contrast.
Expected: FAIL.
Step 3: Write minimal implementation
- Adjust only the problematic minecraft-theme player colors
- Preserve current theme style direction and overall aesthetic
- Do not redesign the player or alter other themes unnecessarily
Step 4: Run verification to confirm it passes
Expected: - improved contrast for the identified title/track/time text - player still visually matches minecraft theme
Step 5: Commit
git add docs/stylesheets/music-player.css docs/stylesheets/minecraft-theme.css
git commit -m "fix: improve music player contrast in minecraft mode"
Task 3: Add minimized music player state and compact bar UI
Files:
- Modify: docs/javascripts/music-player.js
- Modify: docs/stylesheets/music-player.css
- Verify: all themes, page transitions, refresh behavior
Step 1: Write the failing test
Manual failing criteria: - no minimize button exists - player cannot collapse into a compact bar - minimized state does not persist across instant-navigation page transitions - refresh behavior cannot reset to default expanded state
Step 2: Run verification to confirm failure
Expected: FAIL.
Step 3: Write minimal implementation
- Add one minimize/restore toggle button to player chrome
- Add a compact horizontal mini-bar state that keeps the player discoverable
- Preserve playback logic and controls when restored
- Store minimized state only for current browsing session:
- survives instant-navigation page transitions
- resets after full refresh
- Ensure styles work in default, flashlight, and minecraft themes
Do not add extra configuration, extra player modes, or long-term persistence.
Step 4: Run verification to confirm it passes
Check: - player minimizes and restores correctly - current session page transitions preserve minimized state - full page refresh resets to expanded state - player remains readable and clickable in all themes
Step 5: Commit
git add docs/javascripts/music-player.js docs/stylesheets/music-player.css
git commit -m "feat: add minimized music player mode"
Task 4: Verify no regression in player behavior or site UI
Files: - Verify only unless regression found
Step 1: Write failing verification checklist
Failure conditions: - player no longer plays or switches tracks correctly - minimize mode breaks layout or overlaps badly - theme switching breaks minimized bar styling - search dialog/progress metadata changes alter behavior
Step 2: Run verification
Check manually: - open site - play music - minimize / restore - switch pages with instant navigation - switch theme modes - refresh page and confirm default expanded state returns
Step 3: Minimal implementation if needed
Only fix regressions caused by Tasks 1-3. No unrelated cleanup.
Step 4: Re-run verification
Expected: all behavior remains correct and new compact mode works as designed.
Step 5: Commit
git add <only files changed during regression fix>
git commit -m "fix: preserve player behavior after accessibility and compact mode updates"
Plan complete and saved to docs/plans/2026-03-07-accessibility-and-mini-player-plan.md. Two execution options:
1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints
Which approach?