{"id":"2a45ca84-bbee-40d3-9bd9-ac6beb28c911","shortId":"9xeKCd","kind":"skill","title":"ai-friendly-web-design","tagline":"Guidelines for building AI-accessible web interfaces that work well with AI agents, automation tools, and screen readers. Use this skill whenever the user is building or reviewing a webpage, UI component, form, or frontend feature and any of these apply: they mention AI agents, a","description":"# AI-Friendly Web Design (AI Accessibility)\n\n> Original: [@karminski-牙医](https://weibo.com/2169039837/QxmP8bEIS) · Compiled by: [@ianho7](https://github.com/ianho7)\n\nCore principle: **Treat AI agents the same way you'd treat a screen reader for a visually impaired user.**\n\nGetting AI Accessibility right is a win on three fronts simultaneously: future-proofing for agent traffic, improving human accessibility, and boosting SEO.\n\n---\n\n## Prime Directive\n\n**Minimize modals and popups.** They're bad for humans and bad for AI. When you must alert the user, use a banner instead.\n\n---\n\n## Core Checklist\n\n### DOM Structure & Semantics\n\n- **Use semantic HTML tags**: `<main>`, `<article>`, `<nav>`, `<button>`, etc. Add `aria-label` to icon-only buttons\n- **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\n- **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\n\n### Forms & Interactions\n\n- **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\n- **Don't hide actions behind hover**: Agents won't probe hover states; content that's only visible on hover may never be discovered\n- **Listen to `input`/`change` events**: Programmatic input doesn't fire `keydown`/`keyup` — relying solely on keyboard events will break validation\n- **Error messages must be plain text**: Use `aria-describedby` to surface readable error text; don't rely on color changes alone\n\n### State & Navigation\n\n- **Make loading states explicit**: Disable buttons during loading and show text like \"Saving...\" or \"Loading...\"\n- **Prefer pagination over infinite scroll**: Pagination controls give agents a clear navigation target; infinite scroll has no definable end condition\n- **Sync state to the URL**: Write search terms, filters, categories, and page numbers into the URL to support deep linking and reproducibility\n\n### Context & Isolation\n\n- **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\n- **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\n\n### Advanced: Dual Entry Points\n\n- Expose an AI-consumable API manifest at `.well-known/ai.json` or a prominent location\n- Don't default to ReCAPTCHA — it's an impenetrable wall for AI agents; prefer rate limiting, honeypot fields, or behavioral analysis instead\n\n---\n\n## Code Review Checklist\n\nWhen reviewing frontend code, check in order:\n\n1. Do interactive elements have semantic tags or `aria-label`?\n2. Are decorative elements marked with `aria-hidden`?\n3. Do key buttons and forms have stable `data-testid` or `data-ai-action` attributes?\n4. Are any actions only reachable via hover?\n5. Are forms using native controls or div-based simulations?\n6. Are error messages in readable text form, not just color changes?\n7. Do loading states include `disabled` + text feedback?\n8. Do critical flows open new tabs or popup windows?\n\n> For full rationale and code examples, see `references/guidelines.md`","tags":["friendly","web","design","skill","ianho7","agent","agent-skills","claude","claude-code","claude-skills","skills"],"capabilities":["skill","source-ianho7","skill-ai-friendly-web-design","topic-agent","topic-agent-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-skills"],"categories":["ai-friendly-web-design-skill"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/ianho7/ai-friendly-web-design-skill/ai-friendly-web-design","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add ianho7/ai-friendly-web-design-skill","source_repo":"https://github.com/ianho7/ai-friendly-web-design-skill","install_from":"skills.sh"}},"qualityScore":"0.479","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 59 github stars · SKILL.md body (3,479 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T06:55:52.408Z","embedding":null,"createdAt":"2026-04-18T22:14:56.293Z","updatedAt":"2026-05-02T06:55:52.408Z","lastSeenAt":"2026-05-02T06:55:52.408Z","tsv":"'/2169039837/qxmp8beis)':66 '/ai.json':442 '/ianho7)':72 '1':479 '2':490 '3':499 '4':516 '5':524 '6':535 '7':547 '8':555 'access':11,59,94,111 'action':200,245,514,519 'add':150,189 'advanc':427 'agent':19,51,77,107,248,332,423,459 'ai':2,10,18,50,54,58,76,93,129,178,199,434,458,513 'ai-access':9 'ai-consum':433 'ai-friend':53 'ai-friendly-web-design':1 'alert':133 'alon':306 'analysi':467 'api':234,436 'appli':47 'aria':152,172,293,488,497 'aria-describedbi':292 'aria-hidden':171,496 'aria-label':151,487 'attribut':515 'author':409 'autom':20 'avoid':414 'background':165 'bad':123,127 'banner':138 'base':227,533 'behavior':466 'behind':246 'boost':113 'boundari':398 'break':283 'build':8,32 'button':158,314,502 'categori':353 'caus':422 'chang':268,305,546 'check':476 'checklist':141,471 'class':215 'clear':334 'code':469,475,569 'color':304,545 'compil':67 'complet':399 'compon':38,229 'condit':343 'consum':435 'consumpt':185 'content':254 'context':366,378,413 'control':222,231,330,529 'core':73,140 'critic':400,557 'current':412 'custom':228 'd':82 'data':177,191,198,508,512 'data-ai-act':197,511 'data-ai-hidden':176 'data-testid':190,507 'decor':160,492 'deep':362 'default':449 'defin':341 'describedbi':294 'design':5,57 'direct':116,241 'disabl':313,552 'discov':264 'div':226,532 'div-bas':225,531 'doesn':272 'dom':142,372,389 'drive':240 'dual':428 'element':161,482,493 'end':342 'enough':377 'entri':429 'error':285,298,537 'etc':149 'event':269,281 'exampl':570 'explicit':312 'expos':431 'extract':392 'featur':42 'feedback':554 'field':464 'filter':352 'fire':274 'flow':401,558 'focus':426 'form':39,217,221,504,526,542 'friend':3,55 'front':101 'frontend':41,474 'full':566 'futur':104 'future-proof':103 'generat':214 'get':92 'github.com':71 'github.com/ianho7)':70 'give':331 'guidelin':6 'hidden':173,179,498 'hide':159,244 'hint':380 'honeypot':463 'hover':247,252,260,523 'html':147 'human':110,125 'ianho7':69 'icon':156 'icon-on':155 'ifram':369 'impair':90 'impenetr':455 'improv':109 'in-pag':402 'includ':551 'infinit':327,337 'input':267,271 'instead':139,468 'interact':206,218,481 'interfac':13 'irrelev':183 'isol':367 'karminski':62 'karminski-牙医':61 'keep':376,405 'key':205,382,501 'keyboard':280 'keydown':275 'keyup':276 'known':441 'label':153,489 'layer':166 'level':388 'lightweight':391 'like':237,320 'limit':462 'link':363 'listen':265 'load':310,316,323,549 'locat':188,446 'login':406 'long':163 'lose':425 'make':309 'mani':390 'manifest':437 'mark':162,494 'may':261 'mention':49 'messag':286,538 'minim':117 'modal':118 'must':132,287 'name':216 'nativ':220,230,528 'navig':308,335 'never':208,262 'new':416,560 'node':207 'nois':169 'number':356 'open':415,559 'order':195,203,478 'origin':60 'page':355,404 'pagin':325,329 'payment':407 'pierc':396 'plain':289 'playwright':238 'point':430 'popup':120,419,563 'prefer':223,324,460 'prime':115 'principl':74 'probe':251 'programmat':270 'promin':445 'proof':105 'provid':186 'rate':461 'rational':567 're':122 'reachabl':521 'readabl':297,540 'reader':24,86 'recaptcha':451 'reduc':182 'references/guidelines.md':572 'reli':209,277,302 'reproduc':365 'review':34,470,473 'right':95 'save':321 'screen':23,85 'scroll':328,338 'search':350 'see':571 'semant':144,146,484 'seo':114 'shadow':371 'show':318 'simul':534 'simultan':102 'skill':27 'skill-ai-friendly-web-design' 'sole':278 'source-ianho7' 'spare':373 'stabl':187,506 'standard':233 'state':253,307,311,345,550 'status':379 'structur':143 'submit':194,202 'submit-ord':193,201 'summari':383 'support':361 'surfac':296 'svgs':164 'sync':344 'tab':417,561 'tag':148,485 'tailwind':213 'tailwind-gener':212 'target':336 'term':351 'testid':192,509 'text':290,299,319,541,553 'three':100 'token':184 'tool':21,236,393 'top':387 'top-level':386 'topic-agent' 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-skills' 'traffic':108 'treat':75,83 'true':174,180 'ui':37 'unavoid':375 'url':348,359 'use':25,136,145,219,291,368,527 'user':30,91,135 'valid':284 'via':522 'visibl':258 'visual':89,168 'volatil':211 'wall':456 'way':80 'web':4,12,56 'webpag':36 'weibo.com':65 'weibo.com/2169039837/qxmp8beis)':64 'well':16,440 'well-known':439 'whenev':28 'win':98 'window':420,564 'won':249 'work':15 'write':349 '牙医':63","prices":[{"id":"f7c5a3e6-ba7d-40cc-8a01-71d75c147c24","listingId":"2a45ca84-bbee-40d3-9bd9-ac6beb28c911","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"ianho7","category":"ai-friendly-web-design-skill","install_from":"skills.sh"},"createdAt":"2026-04-18T22:14:56.293Z"}],"sources":[{"listingId":"2a45ca84-bbee-40d3-9bd9-ac6beb28c911","source":"github","sourceId":"ianho7/ai-friendly-web-design-skill/ai-friendly-web-design","sourceUrl":"https://github.com/ianho7/ai-friendly-web-design-skill/tree/main/skills/ai-friendly-web-design","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:56.293Z","lastSeenAt":"2026-05-02T06:55:52.408Z"}],"details":{"listingId":"2a45ca84-bbee-40d3-9bd9-ac6beb28c911","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"ianho7","slug":"ai-friendly-web-design","github":{"repo":"ianho7/ai-friendly-web-design-skill","stars":59,"topics":["agent","agent-skills","ai","claude","claude-code","claude-skills","skills"],"license":null,"html_url":"https://github.com/ianho7/ai-friendly-web-design-skill","pushed_at":"2026-03-23T04:29:17Z","description":"A Claude Code Skill that helps you build web interfaces friendly to both AI agents and human users — covering semantic HTML, ARIA attributes, stable locators, form best practices, and more.","skill_md_sha":"368b76d369bb26988c298f507ecf1fd04b0f77dc","skill_md_path":"skills/ai-friendly-web-design/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/ianho7/ai-friendly-web-design-skill/tree/main/skills/ai-friendly-web-design"},"layout":"multi","source":"github","category":"ai-friendly-web-design-skill","frontmatter":{"name":"ai-friendly-web-design","description":"Guidelines for building AI-accessible web interfaces that work well with AI agents, automation tools, and screen readers. Use this skill whenever the user is building or reviewing a webpage, UI component, form, or frontend feature and any of these apply: they mention AI agents, automation, Playwright, web scraping, accessibility, a11y, aria, semantic HTML, or ask how to make their UI \"agent-friendly\", \"AI-friendly\", or \"machine-readable\". Also trigger when reviewing existing frontend code for accessibility or automation compatibility issues, even if the user doesn't explicitly mention AI."},"skills_sh_url":"https://skills.sh/ianho7/ai-friendly-web-design-skill/ai-friendly-web-design"},"updatedAt":"2026-05-02T06:55:52.408Z"}}