ai-friendly-web-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI-Friendly Web Design (AI Accessibility)

AI友好型Web设计（AI可访问性）

Original: @karminski-牙医 · Compiled by: @ianho7

Core principle: Treat AI agents the same way you'd treat a screen reader for a visually impaired user.

Getting AI Accessibility right is a win on three fronts simultaneously: future-proofing for agent traffic, improving human accessibility, and boosting SEO.

原文作者：@karminski-牙医 · 整理者：@ianho7

核心原则：对待AI Agent的方式，要和你对待视障用户使用的屏幕阅读器完全一致。

做好AI可访问性可以同时在三个方面获益：为未来的Agent流量做好适配、提升面向人类用户的可访问性，以及提高SEO效果。

Prime Directive

首要准则

Minimize modals and popups. They're bad for humans and bad for AI. When you must alert the user, use a banner instead.

尽量减少模态框和弹窗。 它们对人类用户和AI都不友好。当你必须向用户发出提醒时，请改用横幅。

Core Checklist

核心检查清单

DOM Structure & Semantics

DOM结构与语义

Use semantic HTML tags:
```
<main>
```
,
```
<article>
```
,
```
<nav>
```
,
```
<button>
```
, etc. Add
```
aria-label
```
to icon-only buttons
Hide decorative elements: Mark long SVGs, background layers, and visual noise with
```
aria-hidden="true"
```
or
```
data-ai-hidden="true"
```
to reduce irrelevant token consumption
Provide stable locators: Add
```
data-testid="submit-order"
```
or
```
data-ai-action="submit-order"
```
to key interactive nodes — never rely on volatile Tailwind-generated class names

使用语义化HTML标签：
```
<main>
```
、
```
<article>
```
、
```
<nav>
```
、
```
<button>
```
等。给仅含图标的按钮添加
```
aria-label
```
隐藏装饰性元素：给长SVG、背景层和视觉干扰元素标记
```
aria-hidden="true"
```
或
```
data-ai-hidden="true"
```
，以减少无关的token消耗
提供稳定的定位器：给关键交互节点添加
```
data-testid="submit-order"
```
或
```
data-ai-action="submit-order"
```
——永远不要依赖Tailwind生成的易变类名

Forms & Interactions

表单与交互

Use native form controls: Prefer
```
<select>
```
,
```
<input type="checkbox">
```
over div-based custom components — native controls have standard APIs that tools like Playwright can drive directly
Don't hide actions behind hover: Agents won't probe hover states; content that's only visible on hover may never be discovered
Listen to
input
/
change
events: Programmatic input doesn't fire
```
keydown
```
/
```
keyup
```
— relying solely on keyboard events will break validation
Error messages must be plain text: Use
```
aria-describedby
```
to surface readable error text; don't rely on color changes alone

使用原生表单控件：优先选择
```
<select>
```
、
```
<input type="checkbox">
```
而非基于div的自定义组件——原生控件有标准API，可被Playwright等工具直接驱动
不要将操作隐藏在hover触发逻辑后：Agent不会探测hover状态，仅在hover时可见的内容永远不会被发现
监听
input
/
change
事件：程序化输入不会触发
```
keydown
```
/
```
keyup
```
事件——仅依赖键盘事件会导致验证失效
错误提示必须为纯文本：使用
```
aria-describedby
```
展示可读的错误文本；不要仅依赖颜色变化提示错误

State & Navigation

状态与导航

Make loading states explicit: Disable buttons during loading and show text like "Saving..." or "Loading..."
Prefer pagination over infinite scroll: Pagination controls give agents a clear navigation target; infinite scroll has no definable end condition
Sync state to the URL: Write search terms, filters, categories, and page numbers into the URL to support deep linking and reproducibility

明确展示加载状态：加载期间禁用按钮，并展示「Saving...」或「Loading...」这类文本
优先选择分页而非无限滚动：分页控件为Agent提供了清晰的导航目标，而无限滚动没有可定义的结束条件
将状态同步到URL：把搜索词、筛选条件、分类和页码写入URL，以支持深度链接和可复现性

Context & Isolation

上下文与隔离

Use iframes and Shadow DOM sparingly: If unavoidable, keep enough context, status hints, and key summaries in the top-level DOM — many lightweight extraction tools can't pierce these boundaries
Complete critical flows in-page: Keep login, payment, and authorization in the current context; avoid opening new tabs or popup windows, which cause agents to lose focus

谨慎使用iframe和Shadow DOM：如果无法避免，请在顶层DOM中保留足够的上下文、状态提示和关键摘要——很多轻量提取工具无法穿透这些边界
在当前页面完成关键流程：将登录、支付和授权流程保留在当前上下文；避免打开新标签页或弹窗，这会导致Agent失去焦点

Advanced: Dual Entry Points

高级：双入口点

Expose an AI-consumable API manifest at
```
.well-known/ai.json
```
or a prominent location
Don't default to ReCAPTCHA — it's an impenetrable wall for AI agents; prefer rate limiting, honeypot fields, or behavioral analysis instead

在
```
.well-known/ai.json
```
或显眼位置提供可供AI消费的API清单
不要默认使用ReCAPTCHA——它对AI Agent来说是无法逾越的障碍；优先选择限流、蜜罐字段或行为分析等方案

Code Review Checklist

代码评审清单

When reviewing frontend code, check in order:

Do interactive elements have semantic tags or
```
aria-label
```
?
Are decorative elements marked with
```
aria-hidden
```
?
Do key buttons and forms have stable
```
data-testid
```
or
```
data-ai-action
```
attributes?
Are any actions only reachable via hover?
Are forms using native controls or div-based simulations?
Are error messages in readable text form, not just color changes?
Do loading states include
```
disabled
```
+ text feedback?
Do critical flows open new tabs or popup windows?

For full rationale and code examples, see
references/guidelines.md

评审前端代码时，按顺序检查以下项：

交互元素是否有语义标签或
```
aria-label
```
？
装饰性元素是否标记了
```
aria-hidden
```
？
关键按钮和表单是否有稳定的
```
data-testid
```
或
```
data-ai-action
```
属性？
是否有任何操作只能通过hover触发才能访问？
表单使用的是原生控件还是基于div的模拟组件？
错误提示是否为可读的文本形式，而非仅靠颜色变化展示？
加载状态是否包含
```
disabled
```
属性+文本反馈？
关键流程是否会打开新标签页或弹窗？

完整的原理说明和代码示例请查看
references/guidelines.md