← All craftbooks

Alt-Text Pass

Media: imagesevalv1.0.0released 2026-06-05workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the passplannerentry

   list images, classify content vs decorative, set rules

   Show working prompt

   1) Find every image reference (img tags, CSS background images, picture/source) in the target file(s) or folder and list each with its current alt (if any) and surrounding context. 2) Classify each as CONTENT (conveys information → needs a description) or DECORATIVE (purely visual → must get alt=""). 3) Set the rules: alt text is concise (roughly under ~125 chars), describes purpose/content not 'image of', never duplicates adjacent caption text, and conveys any text embedded in the image. 4) Write an acceptance-criteria checklist: 'every content image has non-empty, purposeful alt', 'every decorative image has alt=""', 'no alt begins with "image of"/"picture of"', 'embedded text is transcribed', 'no alt is redundant with nearby visible text'. 5) Record the inventory + rules + checklist via write_task_note AND to notes/scope.md.

2. Caption content imagesdeveloper

   write alt text from what is actually visible

   Show working prompt

   1) Read scope.md's inventory and rules. 2) For each CONTENT image, use the vision capability to look at the actual image and write alt text that conveys its purpose in context (a chart's takeaway, a product's key detail, a screenshot's salient state) — not a literal pixel inventory. 3) Transcribe any meaningful text baked into the image. 4) Keep each under the length rule and avoid 'image of'/'photo of' openers. 5) For DECORATIVE images, record alt="" (intentional empty). 6) Produce a mapping of image → alt string. write_task_note the mapping. Good looks like: a blind user would understand each image's role from your text alone.

3. Apply to markupdeveloper

   write alt attributes back into the HTML

   Show working prompt

   1) Read the caption mapping. 2) Edit the source HTML so every img has the correct alt attribute (content → its description, decorative → alt=""). 3) For CSS background images that carry meaning, add an accessible equivalent (aria-label or a visually-hidden span) since they cannot take alt. 4) Do not alter layout, other attributes, or content — only the accessibility attributes. 5) Confirm the HTML still parses/renders. 6) On a loop-back, fix only the images the reviewer flagged. 7) write_task_note the edited file path and a count of images updated (content vs decorative). The deliverable is the updated index.html.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   1) Open index.html and enumerate every image. 2) Cross-check against scope.md: every content image has non-empty purposeful alt; every decorative image has alt="" (PASS/FAIL each class). 3) Verify no alt opens with 'image of'/'picture of' and none is over-long or redundant with adjacent text. 4) Spot-check 3 captions against the real images — accurate and purposeful? 5) Confirm CSS-background meaningful images got an aria equivalent. 6) Write PASS/FAIL per criterion. Any failure → loop back to apply (or caption if a description is wrong).
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "apply" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• add alt text
• generate alt text for images
• make images accessible
• alt text for my site
• wcag image descriptions

Source

View this craftbook on GitHub · MIT license