Add icons at the top of all pages in the solutions index

[Rabia2219]

Overview

We need to add icons to the solution index pages that match the icons that are showing up in the WAVE evaluation tool so that when developers find a problem in their WAVE accessibility review they will see the same icon when the come to the page in the solution index

Details

See resource 1.0.2 for example of what each page should look like once icon is added

Action Items

• Go to Resource 1.0.1.
• Open the page where you want to add the icon.
  • Edit the page.
  • In the WAVE Guidance section, copy the URL under ??? Info "Click to see WAVE Tool Reference" at the end of Check for updated guidance at: and open it in your browser.
  • Copy the icon from the top of that page that opens up.
• Go back to the page in the repo and paste the icon after the single # in the page title.
  • Move the title back onto the same line, leaving one space between the icon and the title.
  • Preview the page to verify the formatting.
• Save and commit.

Resources/Instructions

• 1.0.1 https://github.com/hackforla/accessibility/tree/main/docs/known-issues-and-solutions/solutions-index
• 1.0.2 https://github.com/hackforla/accessibility/blob/main/docs/known-issues-and-solutions/solutions-index/error-empty-button.md
• 1.0.3 Spreadsheet: Accessibility: WAVE: Known Issues and Solutions DRAFTS

[rayneng]

While reviewing the solution index pages for this issue, I found two exceptions that may need decisions or corrections:

1. screen-reader-only-class.md does not contain a WAVE Guidance reference URL or bookmark suffix. Because the instructions for this issue rely on that reference to locate the matching icon, there is currently no specified WAVE icon source for this custom solution page. Should this page remain without an icon, or should a separate custom icon be selected?

2. error-multiple-form-labels.md currently links to #longdesc_invalid, which is the WAVE entry for “Invalid longdesc.” The WAVE entry for “Multiple form labels” is #label_multiple. I recommend correcting the WAVE Guidance URL to #label_multiple and using the icon from that entry.

[rayneng]

Found a 404 while testing this issue:

• https://hackforla.github.io/accessibility/known-issues-and-solutions/solutions-index/error-error-empty-table-header.md

Looks like the DRAFTS table has the error, but the page itself is fine:

• https://hackforla.github.io/accessibility/known-issues-and-solutions/solutions-index/error-empty-button/

[Rabia2219]

@rayneng I submitted this PR

• Update index.md #71

to address your comment

Found a 404 while testing this issue:

• https://hackforla.github.io/accessibility/known-issues-and-solutions/solutions-index/error-error-empty-table-header.md

Looks like the DRAFTS table has the error, but the page itself is fine:

• https://hackforla.github.io/accessibility/known-issues-and-solutions/solutions-index/error-empty-button/

Your comment mentioned one 404 from a link in the table. There were two more so the PR fixes all 3.

Bonnie mentioned a spreadsheet on your call last night, I added the following to the PR

Also changed spreadsheet rows 51 - 53 to fix where the problem originated in Accessibility: WAVE: Known Issues and Solutions DRAFTS

---

Please hide this comment as resolved once reviewed.

[Rabia2219]

@rayneng I submitted this PR

• Update error-multiple-form-labels.md #70

to address your comment

2. error-multiple-form-labels.md currently links to #longdesc_invalid, which is the WAVE entry for “Invalid longdesc.” The WAVE entry for “Multiple form labels” is #label_multiple. I recommend correcting the WAVE Guidance URL to #label_multiple and using the icon from that entry.

The PR fixes the link and adds the icon.

1. screen-reader-only-class.md does not contain a WAVE Guidance reference URL or bookmark suffix. Because the instructions for this issue rely on that reference to locate the matching icon, there is currently no specified WAVE icon source for this custom solution page. Should this page remain without an icon, or should a separate custom icon be selected?

There is no icon needed for this page.

---

Please hide this comment as resolved once reviewed.

[Rabia2219]

@rayneng Please document Codex steps that lead to submission of your PR.

[rayneng]

@Rabia2219 here are the main steps I used to complete the task:

Part 1: Audit and planning

Prompts include...

- Clone `hackforla/accessibility` into the local project, create Fork for contribution
- Review every Markdown file in `docs/known-issues-and-solutions/solutions-index/`, excluding `index.md`.
- Identify whether each page’s first H1 contained an icon.
- Produce a complete table containing the page, readable issue name, icon status, and WAVE documentation reference.
- Extract each WAVE reference from the page’s WAVE Guidance section and validate its bookmark suffix.
- Record exceptions separately instead of silently correcting them:
  - `screen-reader-only-class.md` had no WAVE reference.
  - `error-multiple-form-labels.md` contained a mismatched WAVE reference.

Part 2: Implementation and pull request

Prompts include...

- Add the corresponding WAVE icon to the H1 of every eligible solution page.
- Preserve the existing heading text and use a consistent icon size of 44 × 44 pixels.
- Commit and push the changes to the fork.
- Open a draft PR against `hackforla/accessibility:main`.
  - Keep the two identified exceptions out of the implementation so they could be resolved separately.
  - Remove an unintended change to the Multiple form labels reference and icon in a follow-up commit.
- Mark the PR ready for review after validation was complete.

Part 3: Workshopping visual validation process

Prompts include...

- Run the MkDocs development server locally.
- Open every rendered solution page beside its corresponding WAVE documentation entry.
- Wait 2–3 seconds before capturing screenshots so remotely hosted icons had time to load.
- Verify that each icon had loaded successfully before capture.
- Crop both views to their heading/icon areas.
- Create a neutral side-by-side image labeled `MkDocs` and `WAVE`.
- Skip making comparisons for known 2 exceptions
- Upload all 63 comparison images to one `<details>` dropdown in a single PR comment.
- Confirm that all 63 images rendered, that no additional comments were created, and that the repository worktree remained unchanged.

[rayneng]

RE: How to improve the prompt...

The two main areas of improvement would be...

1. Use plan mode to prevent it from making assumptions on how to handle edge-cases
2. Codex would repeatedly capture all screenshots, then validate those screenshots for correctness, rather than vetting the first few screenshots and then proceeding once a good process was established

This was the prompt used in plan mode...

Run the MkDocs site locally. For every page in docs/known-issues-and-solutions/solutions-index/ (excluding index.md), open the corresponding MkDocs page beside its WAVE documentation page. Crop both views to the H1/icon area and create a side-by-side screenshot for human comparison. Do not perform the comparison yourself.
Edit the single comment on PR #69 to be containing all of the screenshots. Do not create multiple comments.

A better series of prompts might have been...

1. Understand the screenshot cropping process, take screenshots of MkDocs and WAVE headers that vary in length, type (alert/error), and decide how to represent the 2 exceptions
2. Choose parameters for the screenshot's content formatting: alignment, padding, can it have neighboring content?
3. Complete the tasks in smaller batches, slowly grow the batch size when confidence increases

Providing a reference example would also have accomplished steps 1-2 above.

TL;DR

1. Use plan mode and always tell it to interview you to understand requirements
2. For any repeatable process, test end-to-end in small batches
3. provide reference examples that demonstrate acceptable quality (Codex might waste time being a perfectionist)