# Accessible names for AI agents: buttons, links and form labels

> Accessible names are the text labels browsers expose for buttons, links and form fields in the accessibility tree. AI browser agents read that tree to decide what to click, so an icon-only cart button with no name looks identical to the wishlist button. Agent-friendly stores name at least 95% of controls.

- Source: https://is-agentic-storefront.com/checks/accessible-names
- Updated: 2026-10-15
- Category: Operability (20% of score)
- Impact: High
- Spec: [Lighthouse accessibility for agents](https://developer.chrome.com/docs/lighthouse/agentic-browsing/accessibility-for-agents)
- Scanner check: Buttons, links and form fields have accessible names

## Why it matters for AI agents

Browser agents don't see your design; they read the **accessibility tree**, where every interactive element has a role and a name. Chrome's Lighthouse added an [accessibility for agents](https://developer.chrome.com/docs/lighthouse/agentic-browsing/accessibility-for-agents) audit to its Agentic Browsing category for this reason. Anthropic's browser tool returns elements in the form `button "Search"` ([browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool)), and OpenAI asks developers to follow WAI-ARIA practices with "descriptive roles, labels, and states" so its Atlas agent can operate pages ([OpenAI FAQ](https://help.openai.com/en/articles/12627856)).

A store header typically has five or six icon buttons: search, account, wishlist, cart, menu. Without names, an agent sees `button ""` five times and has to guess. The same applies to quantity steppers (`+` / `−`), carousel arrows, close buttons on dialogs, and links wrapping a product image with no `alt`.

Form fields follow the same logic. Agents fill in search boxes, quantity inputs, newsletter forms and checkout fields by label. A field with no label is a field the agent can't map to the user's data.

## What the scanner checks

The scanner inspects the server HTML of the homepage and the first sampled product page.

- **Controls:** every `button`, `a[href]` and `[role="button"]`, excluding elements with `hidden` or `aria-hidden="true"`. A control is named if it has `aria-label`, text from `aria-labelledby`, its own text content, `alt` on an image inside it (or an SVG `<title>`), or a `title` or `value` attribute.
- **Fields:** every `input`, `select` and `textarea`, except hidden, submit, button, reset and image inputs. A field is labelled by `aria-label`, `aria-labelledby`, `title`, `placeholder`, a `<label for>` pointing to its `id`, or a wrapping `<label>`.

The score weights controls at 70% and fields at 30%:

| Result           | Weighted named share |
| ---------------- | -------------------- |
| **Pass**         | 95% or more          |
| **Partial**      | 80% to under 95%     |
| **Fail**         | under 80%            |
| **Inconclusive** | no page loaded       |

Findings list up to three unnamed controls and three unlabelled fields, so you can find them in your templates.

## How to fix it

Name icon-only buttons and links:

```html
<button type="button" aria-label="Open cart (2 items)">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

<a href="/account" aria-label="Account">
  <svg aria-hidden="true">…</svg>
</a>
```

Or include visually hidden text inside the button:

```html
<button type="button">
  <svg aria-hidden="true">…</svg>
  <span class="visually-hidden">Search</span>
</button>
```

Label every field:

```html
<label for="newsletter-email">Email address</label>
<input id="newsletter-email" type="email" name="email" autocomplete="email" />
```

Give product images inside links a meaningful `alt`, such as `alt="Merino crew sock in navy"`, so the link takes its name from the image.

Then run Lighthouse's Accessibility and Agentic Browsing audits and fix any "Buttons do not have an accessible name", "Links do not have a discernible name" or "Form elements do not have associated labels" failures.

## Common mistakes

- **`aria-hidden="true"` on the SVG but no label on the button**, which leaves the button completely nameless.
- **Generic names** like "Click here" or several links named "Shop now". They pass this check but tell an agent little; WCAG's [link purpose](https://www.w3.org/TR/WCAG22/#link-purpose-in-context) criterion asks for descriptive text.
- **Labels that don't match the visible text.** WCAG's [label in name](https://www.w3.org/TR/WCAG22/#label-in-name) criterion expects the accessible name to contain the visible label.

The single most important control to name is add-to-cart; see [add-to-cart](https://is-agentic-storefront.com/checks/add-to-cart).

## Sources

- [Lighthouse: accessibility for agents](https://developer.chrome.com/docs/lighthouse/agentic-browsing/accessibility-for-agents)
- [W3C Accessible Name and Description Computation 1.2](https://www.w3.org/TR/accname-1.2/)
- [WCAG 2.2 SC 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)
- [WCAG 2.2 SC 3.3.2 Labels or Instructions](https://www.w3.org/TR/WCAG22/#labels-or-instructions)
- [Anthropic: browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool)
- [OpenAI: Publishers and Developers FAQ](https://help.openai.com/en/articles/12627856)

## Frequently asked questions

### What is an accessible name?

It is the text a browser computes for an element from its content, aria-label, aria-labelledby, alt text of images inside it, or title. Screen readers announce it, and AI browser agents use it to identify controls.

### How do I give an icon-only button an accessible name?

Add aria-label to the button, for example aria-label="Open cart", or include visually hidden text inside it. An SVG icon alone gives the button no name.

### Is a placeholder a valid label for an input?

Browsers use the placeholder as a fallback name, and the scanner accepts it, but it disappears when the user types and WCAG guidance prefers a real label element. Use a label for every field.

## Run your store on a platform built for agentic commerce

Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.

### Deploy on Medusa Cloud

Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.

- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Faccessible-names)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Faccessible-names)

### Storefront skills for coding agents

Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.

```bash
npx skills add medusajs/medusa-agent-skills
```

[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)

---

Scan your store for free at https://is-agentic-storefront.com/