Accessibility Alt Text Updates Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add meaningful, user-approved alt text and related accessibility metadata to image/iframe content without changing layout, styling, or browsing behavior.

Architecture: Apply targeted content edits in Markdown and HTML files only. Reuse the user's approved naming rules for grouped image sets, preserve existing accurate alt text, and only update ambiguous or missing labels.

Tech Stack: MkDocs Material, Markdown, HTML, accessibility attributes (alt, title)

Task 1: Update grouped image alt text in homepage and gallery content

Files: - Modify: docs/index.md - Modify: docs/gallery/gallery.md - Modify: docs/gallery/2026newyear.md

Step 1: Write the failing test

Manual failing criteria: - C (1-20) image sets still use generic alt like 新地形预览 - Viewmap-2026 (1-25) still use generic alt like Viewmap - Fireworks-2026 (1-10) images lack descriptive numbered alt text - DLC-2026newyear (1-10) still use repeated generic alt text - TCYserver (1-14) images on homepage lack descriptive alt text

Step 2: Run verification to confirm failure

Check manually in source files and confirm grouped image alt text is generic or missing.

Expected: FAIL because alt text does not yet follow user-approved naming rules.

Step 3: Write minimal implementation

Apply the exact user-approved rules: - C (1-20) → 新地形预览 1 ... 新地形预览 20 - Viewmap-2026 (1-25) → 2026 新年活动 Viewmap 截图 1 ... 25 - Fireworks-2026 (1-10) → 2026 新年烟花截图 1 ... 10 - DLC-2026newyear (1-10) → 2026 新年 DLC 道具展示 1 ... 10 - TCYserver (1-14) → 服务器图标预览 1 ... 14

Preserve existing alt text that is already specific and useful.

Step 4: Run verification to confirm success

Manual checks: - Open each modified file and confirm grouped image labels follow the approved numbering format. - Confirm no path changes or layout markup changes were introduced.

Expected: PASS.

Step 5: Commit

git add docs/index.md docs/gallery/gallery.md docs/gallery/2026newyear.md
git commit -m "fix: add descriptive alt text for grouped gallery images"

Task 2: Update ambiguous guide image alt text and iframe titles

Files: - Modify: docs/guide/tcymods.md - Modify: docs/index.md - Modify: docs/portal.html - Modify: docs/guide/serverip.md - Modify: docs/tools/imguruploader.md - Modify: docs/update/Cloudflare-TCYmkdocs-stats.md

Step 1: Write the failing test

Manual failing criteria: - tcymods.md still contains numeric alt text like ![1] - iframe elements in listed files are missing title

Step 2: Run verification to confirm failure

Check source and confirm: - Numeric alt placeholders remain - iframe title attributes are absent

Expected: FAIL.

Step 3: Write minimal implementation

Replace numeric alt placeholders in docs/guide/tcymods.md with short, descriptive labels based on visible nearby context.
Add concise iframe title values:
Bilibili player iframes → title describing embedded video player
img uploader iframe → title describing embedded image uploader
stats iframe → title describing embedded Cloudflare statistics panel
serverip iframe → title based on actual embedded content context in file

Do not alter iframe source URLs, styles, or behavior.

Step 4: Run verification to confirm success

Manual checks: - No ![1] or similarly meaningless alt remains in modified guide file - Each listed iframe has a title - Rendered behavior remains unchanged

Expected: PASS.

Step 5: Commit

git add docs/guide/tcymods.md docs/index.md docs/portal.html docs/guide/serverip.md docs/tools/imguruploader.md docs/update/Cloudflare-TCYmkdocs-stats.md
git commit -m "fix: improve iframe titles and guide image alt text"

Task 3: Verify accessibility metadata changes did not alter behavior

Files: - Verify only (no code expected unless regression found)

Step 1: Write failing verification checklist

Define failure conditions: - Any modified image path changed accidentally - Any iframe source or sizing changed unintentionally - Markdown rendering broken by attribute edits

Step 2: Run verification

Open local preview and check representative pages: - home page - gallery page - 2026 new year gallery - tcymods guide - image uploader page - stats page

Expected before verification: possible regressions unknown.

Step 3: Minimal implementation if needed

Only fix metadata-formatting regressions if found. No extra improvements.

Step 4: Re-run verification

Expected: all pages render exactly as before, with only accessibility metadata improved.

Step 5: Commit

git add <only files changed during regression fix>
git commit -m "fix: preserve rendering after accessibility metadata updates"

Plan complete and saved to docs/plans/2026-03-07-accessibility-alt-text-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?