gilde

← All craftbooks

Accessibility Retrofit

Build: interactive and webevalv2.0.2released 2026-09-05workflow: build-loop

Audit real pages for concrete accessibility violations — alt text, labels, heading order, keyboard and focus, landmarks, contrast — then fix each one at its real site in the markup and verify it, with an enforced independent review that rejects accessibility theater.

Steps

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

  1. Audit the real pagesaccessibility reviewerentry

    Exercise the pages the project actually serves and inventory concrete violations, each with its file, issue, and priority.

    Show working prompt
    Audit the REAL pages before anything is repaired. Find the markup this project actually serves — HTML files, templates, components — and read every involved file with `read_file`. Inventory concrete violations by class: meaningful images with missing or empty alt text; form fields labeled only by placeholder text (no `label` element paired to the input's `id` via `for`); heading order that jumps levels; keyboard and focus failures (a `div` or `span` styled and clicked like a button with no `role`, `tabindex`, or key handling); missing or wrong landmark structure (`header`/`nav`/`main`/`footer`); and contrast problems where the colors are derivable from the code. Also classify genuinely decorative images — those must carry `alt=""`, not a description. Record every violation with the exact file, the concrete issue, and a priority (high/medium/low by user harm). Do not fix anything in this phase, and never pad the list — where an area is clean, say so honestly.

Write `{{workPath}}/audit.md` with exactly these sections: `## Scope` (which pages and files you exercised, with backtick paths), `## Violations` (a markdown table with columns `| File | Issue | Priority |`, one row per violation), `## Priorities` (the fix order and why). Every path you cite must be real.

Observable handoff: write the completed result to `{{workPath}}/audit.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  2. Fix each violation at its real sitefrontend engineer

    Repair every audited violation in the actual markup, styles, or components — semantic elements over ARIA bolt-ons.

    Show working prompt
    Read `{{workPath}}/audit.md` and repair every violation at its REAL site in the markup, styles, or components. There is no prescribed output path for the repairs — edit the actual files from the audit with `read_file` plus `write_file`/`replace_in_file`. Choose the semantic fix over the ARIA bolt-on: a real `button` element rather than `role` and `tabindex` sprayed on a `div` (where the surrounding code allows it), a real `label` paired to the input's `id` via `for` rather than placeholder text doing a label's job, corrected heading levels that restore monotonic order rather than CSS that fakes it. Write meaningful, specific alt text for images that carry content; give genuinely decorative images `alt=""` and state why each is decorative. Keep existing behavior working — handlers, ids, and styling hooks on elements you touch must still be wired afterwards. A violation you deliberately leave unfixed gets an honest deferral with a reason, never silence.

Then write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph), `## Change` (what you altered, per class of violation), `## Files touched` (backtick path per line), `## Per-violation disposition` (every audit row: fixed or deferred, with the reason), `## Risk` (what could still be wrong; be honest about anything unverified), `## How to verify` (concrete steps a person follows to confirm, keyboard included). Before working, open `{{workPath}}/audit.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/fix-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  3. Validate every fixaccessibility reviewer

    Re-inspect each fixed item against the current markup and walk the keyboard path, honest about inspected versus exercised.

    Show working prompt
    Verify with fresh eyes. Read `{{workPath}}/audit.md` and `{{workPath}}/fix-notes.md`, then re-open every touched file with `read_file` and check each audit row against the current markup: is the alt text present and specific, does each `label`'s `for` resolve to a real input `id`, is the heading sequence monotonic now, does the once-div control carry real button semantics and keyboard operability, are the landmarks in place. Walk the keyboard path as far as the code lets you: trace tab order, focusability, and key handlers through the markup and scripts. Say plainly which items you INSPECTED (read the code) versus EXERCISED (actually ran or interacted with) — anything that is neither is unverified, and you must say so rather than claim it.

Write `{{workPath}}/validation.md` with exactly these sections: `## Per-item verification` (each audit row and what you found in the current file), `## Keyboard walk` (the path a keyboard user takes and where focus goes), `## Result` (all clear, or what remains open and why). Before working, open `{{workPath}}/audit.md`, `{{workPath}}/fix-notes.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/validation.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  4. Evaluate the deliverableaccessibility reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. Every violation in audit.md is either fixed at its real site or honestly deferred with a stated reason — open the touched files and check the current markup; do not grade from fix-notes.md alone.
2. No accessibility theater: where a semantic element was the right fix (a real button, a real label), the markup uses it — aria-label sprayed over a non-semantic element does not pass.
3. Every label's for attribute resolves to a real input id in the current markup, and placeholder text no longer stands in for a label.
4. The heading sequence in the fixed markup is monotonic — no level is skipped on the way down.
5. Meaningful images carry specific, non-empty alt text; genuinely decorative images carry alt="" with the decorative call stated in the notes.
6. The dispositions reconcile across audit.md, fix-notes.md, and validation.md — the same items, none silently dropped — and validation.md separates inspected from exercised honestly.

Open `{{workPath}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`.

List the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet.
  5. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  6. Repair the deliverablefrontend engineer

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/validation.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  7. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license