agent-friendly-design

# agent-friendly design

how to build sites and apps that AI agents can actually use.

## why this exists

most design guidance is about agents *building* UI. this skill is about agents *consuming* UI. the audience for your site is no longer just humans — automated traffic surpassed human traffic in 2024 (51% of all web interactions). agents browse, compare, purchase, research, and interact on behalf of users.

if your site is invisible to agents, you're invisible to a growing majority of the web.

## the core insight

the accessibility tree — originally built for screen readers — is becoming the primary interface between AI agents and your website. OpenAI's Atlas explicitly uses ARIA tags to interpret page structure. Microsoft's Playwright MCP provides accessibility snapshots, not screenshots. even vision-first agents (Anthropic Computer Use, Google Mariner) are incorporating accessibility data for reliability.

**building for agents and building for accessibility are the same work.** every improvement you make for one benefits the other.

## the checklist

### 1. semantic HTML (non-negotiable)

agents can't "see" your layout. they read structure. div soup is invisible.

- use native elements: `<button>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<header>`, `<footer>`, `<aside>`
- proper heading hierarchy: `<h1>` through `<h6>`, no skipped levels
- `<label>` elements explicitly associated with form inputs (use `for` attribute)
- `<table>` for tabular data with `<thead>`, `<th>`, and `scope` attributes
- links are `<a>` elements, buttons are `<button>` elements. never `<div onclick>`
- use `<form>` for forms, with `<fieldset>` and `<legend>` for groups
- meaningful `<img alt>` text (not "image1.png")

**test:** disable CSS. can you still understand the page? if yes, agents can too.

### 2. ARIA: useful, not magic

ARIA supplements semantic HTML — it doesn't replace it. use it when native elements can't express the interaction.

- `aria-label` on buttons and links that lack visible text (icon buttons, close buttons)
- `aria-expanded` on toggles, dropdowns, accordions
- `aria-live` regions for dynamic content agents need to notice (status messages, notifications)
- `role` attributes only when there's no native element (e.g., `role="tablist"`, `role="dialog"`)
- `aria-describedby` for complex form fields that need additional context
- `aria-hidden="true"` on decorative elements agents should ignore

**don't do:** put ARIA on everything. over-labeling creates noise. if the native element already communicates the role, skip the ARIA.

### 3. machine-readable state

agents can't interpret visual cues. a grayed-out button means nothing if `disabled` isn't set.

- use `disabled` attribute on inactive controls
- use `aria-selected`, `aria-checked`, `aria-pressed` for toggle states
- loading states: `aria-busy="true"` on containers updating content
- error states: `aria-invalid="true"` on fields with validation errors, plus `aria-errormessage` linking to the error text
- empty states: render actual DOM content (not just CSS `::after` pseudo-elements)
- pagination: current page marked with `aria-current="page"`

**the rule:** if a human can tell the state by looking, an agent should be able to tell the state by reading the DOM.

### 4. structured data (JSON-LD + Schema.org)

helps agents understand *what* your content is, not just how it's structured.

- `Organization`, `Product`, `Article`, `BreadcrumbList`, `FAQPage`, `HowTo` schemas as appropriate
- JSON-LD in `<script type="application/ld+json">` (preferred over microdata or RDFa)
- keep structured data in sync with visible content — don't stuff keywords
- include `dateModified` and `datePublished` so agents know freshness
- product pages: price, availability, reviews, SKU
- articles: author, datePublished, headline, description

### 5. llms.txt

a markdown file at `/llms.txt` that gives LLMs a concise overview of your site. like robots.txt, but for language models.

```markdown
# Your Project Name

> Brief description of what this site/product does.

## Docs

- [Getting Started](https://yoursite.com/docs/getting-started): How to set up...
- [API Reference](https://yoursite.com/docs/api): Full API documentation...

## Optional

- [Changelog](https://yoursite.com/changelog): Recent updates...
```

- keep it under 2000 tokens for quick context loading
- link to detailed markdown versions of important pages (append `.md` to URLs if possible)
- update when content changes — stale llms.txt is worse than none
- spec: https://llmstxt.org

### 6. crawlability and rendering

agents can't all execute JavaScript. many rely on raw HTML.

- server-side render (SSR) or pre-render critical content
- don't hide key information behind client-side-only JavaScript
- update `robots.txt` to allow known AI user-agents (ChatGPT-User, OAI-SearchBot, Googlebot, etc.)
- maintain an up-to-date `sitemap.xml`
- fast response times (agents may time out at 10-30 seconds)
- important content should be high in the HTML source (agents may not scroll)

### 7. predictable interactions

agents automate by finding patterns. inconsistency breaks them.

- consistent naming: if "Add to Cart" is the button text on one page, don't make it "Buy Now" on another
- standard HTML form controls (not custom JavaScript widgets that look like inputs but aren't)
- predictable IDs and class names across similar pages
- avoid modals, popups, and interstitials that require complex dismissal sequences
- minimize login walls for browsing (allow guest checkout where possible)
- avoid CAPTCHAs on non-critical flows — they block agents completely

### 8. API-first patterns

if agents can get data without scraping HTML, everyone wins.

- REST or GraphQL endpoints for core data (products, content, status)
- OpenAPI spec published and linked from llms.txt
- MCP (Model Context Protocol) server for direct tool access — agents can call your API through MCP without browser automation
- NLWeb integration for natural language queries against your data
- A2UI for agent-driven native interfaces (Google's open project — agents send component blueprints that inherit host app styling)
- webhooks for state changes agents need to react to

### 9. content for agents, not just humans

- write clear, descriptive page titles (agents use `<title>` heavily)
- meta descriptions that actually describe the page content
- use descriptive link text ("View pricing details") not generic ("Click here")
- break long content into sections with headings
- provide summaries or TL;DRs for dense pages
- don't rely on images alone to convey information — always have text equivalents

### 10. test with agents

- use browser dev tools to inspect the accessibility tree (Chrome: Accessibility pane in Elements)
- test critical flows with AI browser agents (ChatGPT Atlas, Playwright MCP)
- run Lighthouse accessibility audit — most issues it catches affect agents too
- check that forms can be completed programmatically
- verify that dynamic content updates are reflected in the DOM, not just visually

## the dual-interface mental model

you're building two interfaces on one page:

**human interface:** visual hierarchy, color, typography, whitespace, motion, delight
**agent interface:** semantic structure, ARIA roles, JSON-LD, predictable controls, API endpoints

they don't conflict. a well-structured semantic page is easier for humans AND agents. the dual-interface is additive, not a trade-off.

## routing

- **every web project:** items 1-3 (semantic HTML, ARIA, machine-readable state) are non-negotiable
- **public-facing sites:** add items 4-6 (structured data, llms.txt, crawlability)
- **products/e-commerce/SaaS:** add items 7-9 (predictable interactions, API-first, content optimization)
- **full agent-readiness:** all 10 items

## emerging protocols to watch

| protocol | what it does | status |
|----------|-------------|--------|
| [llms.txt](https://llmstxt.org) | markdown site overview for LLMs | adopted by many, simple to implement |
| [MCP](https://modelcontextprotocol.io) | direct tool access for agents (no browser needed) | growing fast, Anthropic-led |
| [NLWeb](https://github.com/microsoft/nlweb) | natural language queries against your data | Microsoft open-source, early |
| [A2UI](https://developers.googleblog.com/introducing-a2ui-an-open-project-for-agent-driven-interfaces/) | agent-driven native UI components | Google, early spec |
| [AGENTS.md](https://docs.agentsmd.org) | project-level agent instructions | community adoption growing |

## compounding

after building or auditing a site for agent-friendliness:
- document which patterns agents struggled with → add to this skill's checklist
- note which ARIA patterns made the biggest difference → share with the team
- track agent traffic in analytics (user-agent strings) → understand actual usage
- test new protocols as they mature (MCP, A2UI) → update this guide

the web is shifting from page-driven to action-driven. designing for agents isn't future-proofing — it's building for today's traffic.