# Buttons, links and forms agents can use: a checklist

> Browser agents navigate by the names and roles of controls. Fix icon-only buttons, fake buttons, unlabelled fields, blocking pop-ups and hover-only menus.

Published October 8, 2026 by Ghost Agent Labs · Navigability · https://ghostagentlab.com/articles/agent-friendly-buttons-forms/

## Key takeaways

- Browser agents find their way by the names and roles of buttons, links and fields, so accessibility work also makes your site agent-ready.
- Icon-only buttons, clickable boxes that aren't real buttons, unlabelled fields, covering pop-ups and hover-only menus are where agents most often get stuck.
- Try reaching the menu, search, a product and the cart with the keyboard alone, because anywhere you get stuck, an agent probably does too.

Browser agents don't see your page the way people do. They read its structure: what each button, link and form field is called, and what it does. A shopping-bag icon that a person recognizes instantly can be completely invisible to an agent. This checklist covers the fixes that matter most.

## How agents find their way around

Most browser agents work from the page's *accessibility tree*, the same structured view of the page that screen readers use, often alongside a screenshot. In that tree, every element has a role (button, link, text box, heading) and a name ("Add to cart", "Search", "Email address"). The agent decides what to do by reading those names.

That's good news: almost everything that makes a site work for agents also makes it work for people using screen readers and keyboards. If you've invested in accessibility, you're most of the way there.

What an agent reads

- `button` with no name (the search icon)
- `button` with no name (the cart icon)
- `heading` “Trail runner”
- `text` “$129”
- `generic`: the color swatches aren’t controls at all
- `button` “Add to cart”

*The same product page two ways. Icon-only buttons have no name, and swatches built from plain boxes aren’t controls, so the only thing an agent can use with confidence is the button with words on it.*

## 1. Give every button and link a name

The most common failure is the icon-only control: a cart, search, menu or close button that shows an icon and has no text.

```
<!-- An agent sees: button, no name -->
<button><svg>…</svg></button>

<!-- An agent sees: button "Cart, 2 items" -->
<button aria-label="Cart, 2 items"><svg aria-hidden="true">…</svg></button>
```

- Use visible text where you can. Use `aria-label` where the design calls for an icon alone.
- For a linked image, the image's `alt` text becomes the link's name.
- Make names specific. Ten links called "Learn more" or "Shop now" tell an agent nothing about where each goes; "Shop running shoes" does.

## 2. Use real buttons and links

A `<div>` with a click handler looks like a button to a person but isn't one to an agent: it has no role, can't be focused, and often isn't recognized as clickable at all.

```
<!-- Looks clickable, isn't recognized as clickable -->
<div class="btn" onclick="addToCart()">Add to cart</div>

<!-- Recognized as a button by every agent -->
<button type="button" onclick="addToCart()">Add to cart</button>
```

- Use `<a href>` for anything that goes to another page, and `<button>` for anything that does something on this page.
- If you truly can't change the element, add `role="button"` and `tabindex="0"`, and handle the Enter and Space keys.
- Make links real URLs. A link with `href="#"` and a script gives an agent nowhere to go if the script doesn't run.

## 3. Label every form field

Agents fill in forms by matching what they've been asked to enter ("my email", "ship to 10001") to the field's label. Placeholder text is a weak substitute: it disappears once someone types, and not every agent reads it.

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

- Connect each `<label>` to its field with `for` and `id`, or wrap the field in the label.
- Use the right `type` (`email`, `tel`, `number`) and `autocomplete` values (`given-name`, `postal-code`, `address-line1`). They tell an agent exactly what each field wants.
- Prefer native `<select>`, checkboxes and radio buttons over custom-built dropdowns. Custom size and color pickers are a frequent place agents get stuck.
- Show errors as text next to the field and link them with `aria-describedby`, so an agent knows what to fix. A red border alone isn't enough.

## 4. Get pop-ups and banners out of the way

Cookie banners, newsletter pop-ups and region selectors that cover the page on arrival are one of the biggest blockers. An agent has to work out how to dismiss them before it can do anything else, and if it can't, it's stuck.

- Close and accept controls must be real buttons with clear names: "Accept all", "Reject all", "Close".
- Keep consent banners small, at the edge of the screen, rather than covering the content.
- Don't show sign-up pop-ups on arrival. If you must, wait until someone has engaged with the page.

## 5. Make menus work without hover

Agents click; they don't hover. A menu that only opens when the mouse rests over it may never open for an agent, hiding every category inside it.

- Make the top-level menu item a button that opens the menu on click, with `aria-expanded` showing whether it's open.
- Make sure the top-level items are also real links to category pages, so there's always a route in.

## 6. Mark up the page's landmarks

Landmarks tell an agent where the main content is, and where the navigation is, so it can skip straight to what matters.

```
<header>…</header>
<nav aria-label="Main">…</nav>
<main>…</main>
<footer>…</footer>
```

Use one `<h1>` per page and headings in order, so the page has an outline an agent can follow.

## How to test it

1. **Tab through the page.** Use only the keyboard to reach the menu, search, a product, its options and the cart. Anywhere you get stuck, an agent probably does too.
2. **Look at the accessibility tree.** In Chrome's developer tools, the Accessibility pane shows each element's role and name. Look for buttons with no name.
3. **Run an accessibility checker**, such as Lighthouse in Chrome or axe, for a quick list of unnamed controls and unlabelled fields.
4. **Run [AgentScore](https://ghostagentlab.com/agentscore/).** It renders your home page in a browser and checks named buttons and links, real controls, form labels, landmarks and pop-ups that cover the page. To see where a real AI agent gets stuck on a journey, run a [Ghost Agent](https://ghostagentlab.com/ghost-agent/) test.

> **Test the journeys, not just the page.** A home page can pass every check while the size picker on a product page or the checkout button stops agents cold. [Ghost Agents](https://ghostagentlab.com/ghost-agent/) run your key journeys, such as search, add to cart and sign-up, on a schedule, and alert you when one breaks.

For the bigger picture, see [What is agent readiness?](https://ghostagentlab.com/articles/agent-readiness/)

## Sources and further reading

- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) (W3C)
- [Button pattern (ARIA Authoring Practices Guide)](https://www.w3.org/WAI/ARIA/apg/patterns/button/) (W3C)
- [HTML Standard: form control infrastructure (autofill)](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html) (WHATWG)