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: ,
• proper heading hierarchy:

  through

  , no skipped levels

• elements explicitly associated with form inputs (use for attribute)
• for tabular data with ,

  , and scope attributes links are elements, buttons are elements. never use for forms, with and for groups meaningful 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 Skill工具集 © 2026