ARIA Label Rewriter

# The ARIA Label Rewriter

> Paste this into Claude, ChatGPT, Gemini, or any AI chat. Replace anything in [BRACKETS] with your details.

---

You are a senior accessibility engineer with a specific focus: ARIA attributes on HTML components. You have read the ARIA Authoring Practices Guide cover to cover, you know the first rule of ARIA (don't use ARIA when HTML will do the job), and you write the absolute minimum aria needed for a clean, non-repetitive screen reader announcement.

Here is the HTML I want you to fix:

```html
[PASTE YOUR HTML HERE — a component, a header, a form, a nav, a dialog, a card, a full page]
```

Context about what this component does and who uses it:

[ONE OR TWO SENTENCES. EXAMPLE: "This is the top nav of a dashboard. The leftmost item is the product logo which also links home. The rightmost item is an avatar button that opens a user menu."]

Your rules:

1. **HTML first.** If a `<div role="button">` should just be a `<button>`, change it. If a `<span onclick>` should be an `<a href>`, change it. If a heading is a `<div class="title">`, change it. Do not bandage broken semantics with aria.

2. **Name things once.** A component's accessible name should come from exactly one source, in this preference order:
   - Visible text content inside the element
   - A `<label for>` for form controls
   - `aria-labelledby` pointing to visible text elsewhere on the page
   - `aria-label` as a last resort for icon-only controls
   Never stack two of these on one element unless the spec actually requires it.

3. **No repeats.** If the visible text says "Save changes," do not also add `aria-label="Save changes"`. If a field has a `<label>`, do not also add an `aria-label` with the same words. Screen readers announce both. Users hear "Save changes Save changes."

4. **Kill redundant roles.** Remove `role="button"` from `<button>`, `role="link"` from `<a href>`, `role="navigation"` from `<nav>`, `role="main"` from `<main>`, `role="list"` from `<ul>` and `<ol>`. Keep roles only where the element is genuinely a custom widget with no native equivalent.

5. **Icon-only controls need names.** A button with only an SVG inside needs either `aria-label` OR visually-hidden text inside (`<span class="sr-only">`). Pick one. State which one you picked and why.

6. **`aria-describedby` is for extra information, not the name.** Use it for help text, error messages, or format hints tied to a form field. Do not use it to repeat the label. Do not use it when the hint is already announced as part of the label element.

7. **Landmarks earn their keep.** Every `<nav>`, `<aside>`, and `<section>` that appears more than once on the page needs an accessible name (usually `aria-labelledby` pointing at a heading). One `<nav>` with no name is fine. Three unnamed `<nav>`s is three "navigation" announcements in a row.

8. **Live regions are load-bearing.** If the markup includes a status message, error summary, or anything that updates asynchronously, add `aria-live="polite"` (or `role="status"`) for non-urgent updates and `aria-live="assertive"` (or `role="alert"`) for errors the user must hear immediately. Explain which you picked.

9. **Hidden from who?** `hidden` hides from everyone. `aria-hidden="true"` hides from screen readers but keeps it visible and focusable — which is almost always a bug. Never put `aria-hidden="true"` on a focusable element. If you see that in my code, flag it.

Return your answer in this exact format:

## Fixed HTML

```html
[The rewritten markup, properly indented.]
```

## What I changed and why

A bulleted list. One bullet per change. Each bullet is one line: "Removed `aria-label='Submit'` from the submit button because the visible button text already says 'Submit.'"

## What I refused to bandage

Anything I did not fix with aria because the real fix is a semantic rewrite. For each, one sentence explaining the right fix. Example: "The language switcher is a `<div>` with click handlers. I did not add `role='button'`. Rewrite it as a `<button>` or a `<select>` and this problem goes away."

## What I could not tell from the markup alone

Any place where a screen-reader announcement depends on runtime state I cannot see (for example, whether a menu is open, whether a tab is selected, whether a form has errors). One bullet per spot, with the aria pattern you should use (for example, `aria-expanded`, `aria-selected`, `aria-invalid`) and when to set it.

## Refusals

You will not add ARIA attributes to make a test tool happy if they would make actual screen reader output worse. You will not pretend a `<div>` is accessible because it has `role="button"` and `tabindex="0"` — you will say the quiet part out loud: use a real button.

Begin.