thinkhard.SI

Prompt repository Engineering & code

Brief a coding agent to fix accessibility problems on a page

An accessibility audit found problems on a page, and you want a coding agent to fix them and prove the page works with a keyboard.

Registry no.
ENG-043
Collection
Engineering & code
Laid out for
Coding agent
Score
10 out of 10
Blanks to fill
10
Added

Engineering & codeCode agent

The prompt

Score 10 of 10, Excellent

Use it when An accessibility audit found problems on a page, and you want a coding agent to fix them and prove the page works with a keyboard.

  • {{page}}
  • {{user_task}}
  • {{standard}}
  • {{files}}
  • {{findings}}
  • {{framework}}
  • {{tokens_file}}
  • {{a11y_command}}
  • {{test_command}}
  • {{off_limits}}
Full prompt and why it works
Prompt
Goal: Fix the accessibility findings below on {{page}}, so that people using a keyboard or a screen reader can {{user_task}}, meeting {{standard}} for these findings.

Context:
- Files for the page, as far as I know: {{files}} (for example src/pages/checkout/ and its components)
- Audit findings (tool or auditor, rule, element, description):
"""
{{findings}}
"""
- UI framework and component library: {{framework}}
- Where colors are defined, if the project uses design tokens: {{tokens_file}}
- Automated accessibility check command: {{a11y_command}}
- Test command: {{test_command}}

Constraints:
- Use native HTML first: button for actions, a for links, label for inputs, headings in order, and landmarks such as main and nav. Add ARIA only when no native element fits, and then follow the WAI-ARIA Authoring Practices pattern for that widget.
- Every form field has a visible label tied to it, and each error message is linked to its field with aria-describedby.
- Keep focus visible: do not remove outlines without a visible replacement. Keep the tab order in the visual order and do not use a positive tabindex. Dialogs move focus inside when they open, keep it there, close on Escape and return focus to the control that opened them.
- Fix color contrast (4.5:1 for normal text, 3:1 for large text and interface parts, under WCAG AA) in the design tokens, not with one-off colors. If a fix changes a brand color, stop and show me the before and after values first.
- For images, write alt text only from content I give, and use alt="" for decorative images. Where you cannot tell what an image shows, write [ALT NEEDED] and list it.
- Do not change the visual design beyond what the fixes need. Do not disable or suppress rules in the accessibility checker. Do not touch {{off_limits}}.

Done when:
- {{a11y_command}} reports no violations on the page for the rules in the findings.
- A keyboard test (for example in tests/a11y/, with Playwright) passes: from the top of the page, Tab reaches every interactive element in visual order with a visible focus indicator, Enter or Space activates each control, and any dialog opens, holds focus, closes on Escape and returns focus.
- {{test_command}} passes.

Verify: run the checks and tests, read the output and iterate until they pass. Then report a table with the columns Finding, Fix, File, Verified by (automated check, keyboard test, or needs a person), plus the commands you ran with the last 20 lines of their output. Automated checks find only part of the problems, so also list what still needs a person to test with a screen reader.

Variables

{{page}}
The page or screen, for example "the checkout page" or "the sign-up form".
{{user_task}}
What people must be able to do there, for example "enter an address and pay".
{{standard}}
The level you are aiming for, for example "WCAG 2.2 AA".
{{files}}
The page's files or folders, as far as you know.
{{findings}}
The audit findings as reported, with rule names, elements and descriptions.
{{framework}}
For example "React with our own component library" or "Vue 3 with Vuetify".
{{tokens_file}}
For example src/styles/tokens.css, or "no design tokens".
{{a11y_command}}
For example npx playwright test tests/a11y or an axe CLI command against the local server.
{{test_command}}
The command for the rest of the tests, for example npm test.
{{off_limits}}
Files that must not change, for example shared components used by other teams.

Why it works

  • What good looks like. Done means the automated check is clean for the audited rules and a keyboard test walks the page, two checks the agent can run itself.
  • What to avoid. Checker rules cannot be suppressed and contrast is fixed in the design tokens, so the page passes because it is fixed, not because the tool went quiet.
  • If unsure. Images the agent cannot describe get [ALT NEEDED], and changes to brand colors wait for your approval.

How to use it

  1. Press Fill in blanks and type your details into each blank. What you type stays in this browser.
  2. Copy the filled prompt into the AI tool you already use, such as ChatGPT, Claude or Gemini, or open it in the Grader or the Prompt Tester here.
  3. Before you rely on it, try it on three or four real examples. The Prompt Tester runs them all at once and shows which ones go wrong.
Use it from code

Get this prompt as JSON from the free REST API, with your own text in the blanks, or let an AI assistant fetch it through the MCP server. No key.

curl -s https://thinkhard.si/api/v1/prompts/coding-agent-accessibility-fix

With the MCP server added to Claude, ChatGPT, Cursor or VS Code, call get_prompt with {"prompt": "coding-agent-accessibility-fix"}, or just ask for it by name.