Buttons, links and forms agents can use: a checklist

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.

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. 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 test.

For the bigger picture, see What is agent readiness?