Content & Semantics
Fixes Category 3 (Content & Semantics, 20% weight) issues from IsAgentReady.com. AI agents use the accessibility tree — not visual rendering — to parse pages. Good semantic HTML and heading hierarchy directly improve AI comprehension.
When to Use
- IsAgentReady scan shows issues in Content & Semantics category
- Site has low scores on checkpoints 3.1–3.14
- User asks to fix semantic HTML, headings, SSR, alt text, ARIA, or link texts
- Building a new site and want AI agent readiness from the start
When NOT to Use
- Issues are in other categories (use
ai-content-discovery, structured-data, agent-protocols, or security-trust)
- Problem is purely visual styling (not semantic structure)
- Site already scores A+ on Content & Semantics
Checkpoints Overview
| ID |
Checkpoint |
Points |
Priority |
| 3.1 |
Server-side rendered content |
20 |
Critical |
| 3.2 |
Heading hierarchy |
20 |
Critical |
| 3.3 |
Semantic HTML elements |
20 |
Important |
| 3.4 |
ARIA landmarks |
10 |
Important |
| 3.5 |
Image alt text |
15 |
Important |
| 3.6 |
Language attribute |
5 |
Nice-to-have |
| 3.7 |
Descriptive link texts |
10 |
Nice-to-have |
| 3.8 |
Question-based headings |
10 |
Important |
| 3.9 |
Form label coverage |
10 |
Important |
| 3.10 |
Form field autocomplete |
10 |
Important |
| 3.11 |
Keyboard navigability |
5 |
Important |
| 3.12 |
Document title |
10 |
Important |
| 3.13 |
Button accessible names |
5 |
Important |
| 3.14 |
aria-hidden misuse |
10 |
Important |
Total: 160 points. Category weight: 20% of overall score.
Checkpoint 3.1: Server-Side Rendered Content (20 pts)
What the scanner checks: Whether <body> contains >200 characters of visible text in raw HTML (no JS execution). Detects SPA shells (<div id="root"></div>). Checks for <noscript> fallback.
Scoring:
- 20 pts — >200 chars visible text in raw HTML
- 10 pts — Limited text but
<noscript> fallback present
- 5 pts — Some visible text but under 200 chars
- 0 pts — Empty SPA shell or no visible text
Why it matters: AI agents cannot execute JavaScript. They parse raw HTML to understand page content. Without SSR, your content is invisible to most AI crawlers and assistants.
Fix Workflow
Test current state — check what AI agents see:
curl -s https://example.com | sed 's/<script[^>]*>.*<\/script>//g; s/<style[^>]*>.*<\/style>//g; s/<[^>]*>//g' | tr -s ' \n' | head -20
If this returns minimal text, your content relies on JavaScript.
Detect SPA shell — look for empty containers:
curl -s https://example.com | grep -E '<div id="(root|app|__next)"></div>'
Implement SSR — see references/ssr-strategies.md for framework-specific guides (Next.js, Nuxt, Astro, Remix, SvelteKit, Angular).
Add <noscript> fallback (partial credit if full SSR isn't feasible):
<noscript>
<p>This site requires JavaScript. Visit our <a href="/sitemap">sitemap</a> for a text-based overview.</p>
</noscript>
Verify — re-run the curl test and confirm >200 chars of visible text.
References:
Checkpoint 3.2: Heading Hierarchy (20 pts)
What the scanner checks: Exactly one <h1>, sequential heading levels (no h1→h3 skip), non-empty heading text.
Scoring:
- 20 pts — Single
<h1>, no level skips, all headings have text
- 15 pts — Good hierarchy but some headings have empty text
- 10 pts — Single
<h1> present but levels are skipped
- 5 pts — Multiple
<h1> tags
- 0 pts — No
<h1> found or no headings at all
Why it matters: AI agents use headings to build a content outline and determine topic hierarchy. A clear h1→h2→h3 structure helps AI systems extract and summarize your content accurately.
Fix Workflow
Audit current headings:
curl -s https://example.com | grep -oE '<h[1-6][^>]*>.*?</h[1-6]>' | head -30
Fix the hierarchy — ensure exactly one <h1> and sequential levels:
<h1>Page Title — One Per Page</h1>
<h2>Main Section</h2>
<h3>Subsection</h3>
<h3>Subsection</h3>
<h2>Another Section</h2>
<h3>Subsection</h3>
<h4>Detail</h4>
Common fixes:
- Multiple
<h1> tags → keep one, demote others to <h2>
<h1> → <h3> skip → add intermediate <h2>- Empty headings → add meaningful text or remove the tag
- Logo in
<h1> → move logo out, use text <h1> for page title
Verify — re-check that heading levels are sequential.
See references/gotchas.md for common heading hierarchy pitfalls (component-level <h1>, level resets).
References:
Checkpoint 3.3: Semantic HTML Elements (20 pts)
What the scanner checks: Presence of 5 semantic landmark elements: <header>, <nav>, <main>, <article> or <section>, <footer>. 4 points each.
Scoring:
- 20 pts (pass) — All 5 elements present
- 12–16 pts (partial) — 3–4 elements present
- 0–8 pts (fail) — Fewer than 3 elements
Why it matters: AI agents navigate pages using the accessibility tree, not visual layout. Semantic elements like <main>, <nav>, and <article> provide structural meaning that AI systems rely on to parse content.
Fix Workflow
Check which elements are present:
curl -s https://example.com | grep -oE '<(header|nav|main|article|section|footer)[\s>]' | sort -u
Implement the full semantic structure:
<body>
<header>
<nav>
<a href="/">Home</a>
<a href="/about">About</a>
<a href="/contact">Contact</a>
</nav>
</header>
<main>
<article>
<h1>Page Title</h1>
<section>
<h2>Introduction</h2>
<p>Content here...</p>
</section>
<section>
<h2>Details</h2>
<p>More content...</p>
</section>
</article>
</main>
<footer>
<nav aria-label="Footer">
<a href="/privacy">Privacy Policy</a>
<a href="/terms">Terms of Service</a>
</nav>
<p>© 2026 Example Inc.</p>
</footer>
</body>
Replace <div> wrappers with semantic equivalents:
<div class="header"> → <header><div class="nav"> → <nav><div class="main"> → <main><div class="footer"> → <footer><div class="sidebar"> → <aside>
See references/semantic-html-guide.md for the complete element reference and <article> vs <section> guidance.
References:
Checkpoint 3.4: ARIA Landmarks (10 pts)
What the scanner checks:
- Implicit landmarks from semantic elements (
<main> → main, <nav> → navigation, <header> → banner, <footer> → contentinfo, <aside> → complementary)
- Explicit ARIA roles (
role="navigation", role="main", etc.)
- Additive ARIA attributes:
aria-label, aria-labelledby, aria-describedby, aria-live, aria-expanded, aria-current, aria-hidden
Scoring:
- 10 pts — 3+ landmark regions AND at least 1 additive ARIA attribute
- 7 pts — 3+ landmark regions, no additive ARIA
- 5 pts — 1+ landmark AND 1+ additive ARIA attribute
- 3 pts — Any landmark or ARIA attribute present
- 0 pts — No landmarks or ARIA attributes found
Why it matters: ARIA landmarks help AI agents identify page regions (navigation, main content, footer). This is the same API used by screen readers and is increasingly used by AI browsing agents.
Fix Workflow
Use semantic HTML first — these provide implicit landmarks without extra attributes:
<header> <!-- implicit role="banner" -->
<nav> <!-- implicit role="navigation" -->
<main> <!-- implicit role="main" -->
<footer> <!-- implicit role="contentinfo" -->
<aside> <!-- implicit role="complementary" -->
Add ARIA attributes for disambiguation and state:
<nav aria-label="Primary">
<a href="/" aria-current="page">Home</a>
<a href="/about">About</a>
</nav>
<nav aria-label="Footer">
<a href="/privacy">Privacy</a>
</nav>
<div aria-live="polite" aria-label="Search results">
<!-- Dynamic content area -->
</div>
<button aria-expanded="false" aria-label="Toggle menu">Menu</button>
Do NOT add redundant roles to semantic elements:
<!-- WRONG — redundant, not recommended by W3C -->
<main role="main">
<!-- CORRECT — semantic element is sufficient -->
<main>
Verify — check for 3+ landmark types plus at least one aria-* attribute.
References:
Checkpoint 3.5: Image Alt Text (15 pts)
What the scanner checks: All <img> tags have non-empty alt attributes. Score = (images with alt / total images) * 15. No images on page = full score.
Why it matters: AI agents cannot see images. Alt text is the only way for AI systems to understand image content, context, and relevance to the surrounding text.
Fix Workflow
Find images missing alt text:
curl -s https://example.com | grep -oE '<img [^>]*>' | grep -v 'alt='
Add appropriate alt text:
<!-- Content images: describe what the image shows -->
<img src="team-photo.jpg" alt="Engineering team at the 2026 company offsite">
<img src="chart.png" alt="Revenue growth chart showing 40% increase in Q4 2025">
<img src="product.jpg" alt="Wireless noise-cancelling headphones in matte black">
<!-- Decorative images: use empty alt (NOT missing alt) -->
<img src="divider.svg" alt="">
<img src="bg-pattern.png" alt="">
<!-- Icons with adjacent text: use empty alt to avoid repetition -->
<img src="email-icon.svg" alt=""> <span>Email us</span>
<!-- Logos: use the company/brand name -->
<img src="logo.svg" alt="Acme Inc.">
Alt text guidelines:
- Be specific and concise (under 125 characters)
- Describe the content and function, not appearance
- Don't start with "Image of..." or "Picture of..."
- For charts/graphs, describe the key data point or trend
- For decorative images, use
alt="" (empty, not missing)
References:
Checkpoint 3.6: Language Attribute (5 pts)
What the scanner checks: <html> tag has a lang attribute with a valid BCP 47 language code.
Scoring:
- 5 pts — Valid BCP 47 code (e.g.,
en, nl, en-US)
- 2 pts —
lang attribute present but invalid value
- 0 pts — No
lang attribute
Why it matters: The lang attribute tells AI agents what language your content is in, enabling correct text processing, translation, and language-specific understanding.
Fix Workflow
Check current state:
curl -s https://example.com | grep -oE '<html[^>]*lang="[^"]*"'
Add or fix the lang attribute:
<!-- English -->
<html lang="en">
<!-- Regional variants -->
<html lang="en-US">
<html lang="en-GB">
<html lang="nl-NL">
<html lang="de-DE">
<html lang="fr-FR">
<html lang="ja">
<html lang="zh-Hans">
For multilingual content, use lang on specific elements:
<html lang="en">
<body>
<p>This is English text.</p>
<blockquote lang="fr">Ceci est en français.</blockquote>
</body>
</html>
References:
Checkpoint 3.7: Descriptive Link Texts (10 pts)
What the scanner checks: Samples up to 50 links. Flags generic text: "click here", "read more", "learn more", "here", "link", "more", "details", "info", "more details". Score = (descriptive links / total sampled) * 10.
Why it matters: AI agents use link text to understand navigation and discover related content. Generic text like "click here" provides no context about where the link leads.
Fix Workflow
Find generic links:
curl -s https://example.com | grep -oiE '<a [^>]*>([^<]*)<\/a>' | grep -iE '>(click here|read more|learn more|here|link|more|details|info|more details)<'
Replace with descriptive text:
<!-- WRONG -->
<a href="/pricing">Click here</a>
<a href="/blog/ai-trends">Read more</a>
<a href="/docs">Learn more</a>
To sign up, <a href="/register">click here</a>.
<!-- CORRECT -->
<a href="/pricing">View pricing plans</a>
<a href="/blog/ai-trends">Read our AI trends analysis</a>
<a href="/docs">Explore the documentation</a>
<a href="/register">Create your free account</a>.
Patterns for common cases:
- Blog posts: "Read [article title]" instead of "Read more"
- CTAs: describe the action — "Start free trial", "Download the report"
- Navigation: use the destination name — "About us", "API documentation"
- Lists: "[Item name] details" instead of "Details"
For "Read more" in card layouts, make the entire card clickable or use aria-label:
<!-- Option A: descriptive visible text -->
<a href="/blog/ai-trends">Read AI trends analysis</a>
<!-- Option B: aria-label when visual design requires short text -->
<a href="/blog/ai-trends" aria-label="Read AI trends analysis">Read more</a>
References:
Checkpoint 3.8: Question-Based Headings (10 pts)
What the scanner checks: H2 headings that use question format — ending with ? or starting with a question word (how, what, why, when, where, which, who, can, does, do, is, are, will, should, would, could, shall).
Scoring:
- 10 pts — 2+ question-format H2 headings, or (3 or fewer total H2s and at least 30% are questions)
- 5 pts — At least 1 question-format H2
- 0 pts — H2 headings exist but none are questions
- Skip (0/0) — No H2 headings present
Why it matters: 78.4% of ChatGPT citations come from pages with question-based H2 headings. Question headings match how users query AI systems, making your content more likely to be selected as a source for AI-generated answers.
Fix Workflow
Audit current H2 headings:
curl -s https://example.com | grep -oE '<h2[^>]*>.*?</h2>'
Rewrite H2 headings as questions:
<!-- WRONG -->
<h2>AI Agent Readiness</h2>
<h2>Content Discovery by AI Systems</h2>
<!-- CORRECT -->
<h2>What Is AI Agent Readiness?</h2>
<h2>How Do AI Systems Discover Your Content?</h2>
<h2>Why Does Structured Data Matter for AI?</h2>
Recognized question starters: how, what, why, when, where, which, who, can, does, do, is, are, will, should, would, could, shall — or any heading ending with ?.
Not all headings need to be questions — aim for 2+ question H2s on pages with 4+ H2s, or 30%+ on pages with 3 or fewer.
Pair with FAQPage schema (checkpoint 2.7) for maximum AI citation potential — match H2 questions with JSON-LD Question/Answer pairs.
Verify:
curl -s https://example.com | grep -oE '<h2[^>]*>.*?</h2>' | grep -iE '(\?|>(How|What|Why|When|Where|Which|Who|Can|Does|Do|Is|Are|Will|Should|Would|Could|Shall) )'
References:
Quick Wins Checklist
For the fastest score improvement, fix in this order:
- Add
<html lang="en"> — 5 pts, one line (checkpoint 3.6)
- Add semantic elements — wrap existing
<div>s with <header>, <nav>, <main>, <footer> (checkpoint 3.3)
- Fix heading hierarchy — ensure one
<h1>, sequential levels (checkpoint 3.2)
- Add ARIA attributes —
aria-label on duplicate navs, aria-current="page" (checkpoint 3.4)
- Add alt text to all images (checkpoint 3.5)
- Fix generic link texts — replace "click here" and "read more" (checkpoint 3.7)
- Rewrite H2s as questions — match how users query AI systems (checkpoint 3.8)
- Add form labels — associate every input with a label (checkpoint 3.9)
- Add autocomplete — help agents fill forms correctly (checkpoint 3.10)
- Fix document title — descriptive, 10-70 chars (checkpoint 3.12)
- Fix aria-hidden misuse — never on focusable elements (checkpoint 3.14)
- Add button names — every button needs an accessible name (checkpoint 3.13)
- Fix keyboard navigation — no positive tabindex, proper roles on clickable divs (checkpoint 3.11)
- Implement SSR — largest effort but highest single-checkpoint score (checkpoint 3.1)
Key Gotchas
Common mistakes that cause checkpoint failures:
- Multiple
<h1> tags — Components that each add their own <h1> break hierarchy
- Heading level skips — Going from
<h1> directly to <h3> without <h2>
- SPA with empty shell —
<div id="root"></div> scores 0 without SSR
- Missing alt vs empty alt —
<img src="..."> (no alt) fails; <img src="..." alt=""> (empty) is valid for decorative images
- Generic link text — "Click here" and "Read more" provide no context for AI agents
- Statement headings instead of questions — "AI Agent Readiness" scores 0; "What Is AI Agent Readiness?" scores points
See references/gotchas.md for detailed correct vs incorrect examples of each.
References
- references/semantic-html-guide.md — Semantic elements, ARIA mapping, heading patterns, link text patterns
- references/ssr-strategies.md — Framework-specific SSR implementation guides
- references/gotchas.md — Common pitfalls with correct vs incorrect examples
Instructions
- Identify failing checkpoints from the IsAgentReady.com scan results
- Follow the fix workflow for each failing checkpoint above
- Apply the code examples — adapt HTML structure and content to the user's site
- Verify each fix using the curl commands provided in each workflow
- Re-scan at isagentready.com to confirm improvements
If $ARGUMENTS is provided, interpret it as the URL to fix or the specific checkpoint to address.
1---2name: content-semantics3description: Fixes content and semantic HTML issues — implements server-side rendering, heading hierarchy, semantic HTML elements, ARIA landmarks, image alt text, language attributes, descriptive link texts, question-based headings, form labels, autocomplete hints, keyboard navigability, document titles, button accessible names, and aria-hidden misuse so AI agents can navigate and understand page content via the accessibility tree. Use when asked to "fix semantic HTML", "add SSR", "fix heading hierarchy", "add alt text", "improve semantics score", "fix accessibility for AI", "add ARIA landmarks", "fix language attribute", "add question headings", "fix form labels", "add autocomplete", "fix keyboard navigation", "fix document title", "fix button names", "fix aria-hidden", or any semantic HTML task.4---56# Content & Semantics78Fixes Category 3 (Content & Semantics, 20% weight) issues from [IsAgentReady.com](https://isagentready.com). AI agents use the accessibility tree — not visual rendering — to parse pages. Good semantic HTML and heading hierarchy directly improve AI comprehension.910## When to Use1112- IsAgentReady scan shows issues in **Content & Semantics** category13- Site has low scores on checkpoints 3.1–3.1414- User asks to fix semantic HTML, headings, SSR, alt text, ARIA, or link texts15- Building a new site and want AI agent readiness from the start1617## When NOT to Use1819- Issues are in other categories (use `ai-content-discovery`, `structured-data`, `agent-protocols`, or `security-trust`)20- Problem is purely visual styling (not semantic structure)21- Site already scores A+ on Content & Semantics2223## Checkpoints Overview2425| ID | Checkpoint | Points | Priority |26|-----|-----------------------------|--------|-------------|27| 3.1 | Server-side rendered content | 20 | Critical |28| 3.2 | Heading hierarchy | 20 | Critical |29| 3.3 | Semantic HTML elements | 20 | Important |30| 3.4 | ARIA landmarks | 10 | Important |31| 3.5 | Image alt text | 15 | Important |32| 3.6 | Language attribute | 5 | Nice-to-have|33| 3.7 | Descriptive link texts | 10 | Nice-to-have|34| 3.8 | Question-based headings | 10 | Important |35| 3.9 | Form label coverage | 10 | Important |36| 3.10| Form field autocomplete | 10 | Important |37| 3.11| Keyboard navigability | 5 | Important |38| 3.12| Document title | 10 | Important |39| 3.13| Button accessible names | 5 | Important |40| 3.14| aria-hidden misuse | 10 | Important |4142Total: 160 points. Category weight: 20% of overall score.4344---4546## Checkpoint 3.1: Server-Side Rendered Content (20 pts)4748**What the scanner checks:** Whether `<body>` contains >200 characters of visible text in raw HTML (no JS execution). Detects SPA shells (`<div id="root"></div>`). Checks for `<noscript>` fallback.4950**Scoring:**51- 20 pts — >200 chars visible text in raw HTML52- 10 pts — Limited text but `<noscript>` fallback present53- 5 pts — Some visible text but under 200 chars54- 0 pts — Empty SPA shell or no visible text5556**Why it matters:** AI agents cannot execute JavaScript. They parse raw HTML to understand page content. Without SSR, your content is invisible to most AI crawlers and assistants.5758### Fix Workflow59601. **Test current state** — check what AI agents see:61 ```bash62 curl -s https://example.com | sed 's/<script[^>]*>.*<\/script>//g; s/<style[^>]*>.*<\/style>//g; s/<[^>]*>//g' | tr -s ' \n' | head -2063 ```64 If this returns minimal text, your content relies on JavaScript.65662. **Detect SPA shell** — look for empty containers:67 ```bash68 curl -s https://example.com | grep -E '<div id="(root|app|__next)"></div>'69 ```70713. **Implement SSR** — see [references/ssr-strategies.md](references/ssr-strategies.md) for framework-specific guides (Next.js, Nuxt, Astro, Remix, SvelteKit, Angular).72734. **Add `<noscript>` fallback** (partial credit if full SSR isn't feasible):74 ```html75 <noscript>76 <p>This site requires JavaScript. Visit our <a href="/sitemap">sitemap</a> for a text-based overview.</p>77 </noscript>78 ```79805. **Verify** — re-run the curl test and confirm >200 chars of visible text.8182**References:**83- [Rendering on the Web](https://web.dev/articles/rendering-on-the-web)84- [Google JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics)8586---8788## Checkpoint 3.2: Heading Hierarchy (20 pts)8990**What the scanner checks:** Exactly one `<h1>`, sequential heading levels (no h1→h3 skip), non-empty heading text.9192**Scoring:**93- 20 pts — Single `<h1>`, no level skips, all headings have text94- 15 pts — Good hierarchy but some headings have empty text95- 10 pts — Single `<h1>` present but levels are skipped96- 5 pts — Multiple `<h1>` tags97- 0 pts — No `<h1>` found or no headings at all9899**Why it matters:** AI agents use headings to build a content outline and determine topic hierarchy. A clear h1→h2→h3 structure helps AI systems extract and summarize your content accurately.100101### Fix Workflow1021031. **Audit current headings:**104 ```bash105 curl -s https://example.com | grep -oE '<h[1-6][^>]*>.*?</h[1-6]>' | head -30106 ```1071082. **Fix the hierarchy** — ensure exactly one `<h1>` and sequential levels:109 ```html110 <h1>Page Title — One Per Page</h1>111 <h2>Main Section</h2>112 <h3>Subsection</h3>113 <h3>Subsection</h3>114 <h2>Another Section</h2>115 <h3>Subsection</h3>116 <h4>Detail</h4>117 ```1181193. **Common fixes:**120 - Multiple `<h1>` tags → keep one, demote others to `<h2>`121 - `<h1>` → `<h3>` skip → add intermediate `<h2>`122 - Empty headings → add meaningful text or remove the tag123 - Logo in `<h1>` → move logo out, use text `<h1>` for page title1241254. **Verify** — re-check that heading levels are sequential.126127See [references/gotchas.md](references/gotchas.md) for common heading hierarchy pitfalls (component-level `<h1>`, level resets).128129**References:**130- [MDN Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)131- [W3C Using h1-h6 to identify headings](https://www.w3.org/WAI/WCAG22/Techniques/html/H42)132133---134135## Checkpoint 3.3: Semantic HTML Elements (20 pts)136137**What the scanner checks:** Presence of 5 semantic landmark elements: `<header>`, `<nav>`, `<main>`, `<article>` or `<section>`, `<footer>`. 4 points each.138139**Scoring:**140- 20 pts (pass) — All 5 elements present141- 12–16 pts (partial) — 3–4 elements present142- 0–8 pts (fail) — Fewer than 3 elements143144**Why it matters:** AI agents navigate pages using the accessibility tree, not visual layout. Semantic elements like `<main>`, `<nav>`, and `<article>` provide structural meaning that AI systems rely on to parse content.145146### Fix Workflow1471481. **Check which elements are present:**149 ```bash150 curl -s https://example.com | grep -oE '<(header|nav|main|article|section|footer)[\s>]' | sort -u151 ```1521532. **Implement the full semantic structure:**154 ```html155 <body>156 <header>157 <nav>158 <a href="/">Home</a>159 <a href="/about">About</a>160 <a href="/contact">Contact</a>161 </nav>162 </header>163164 <main>165 <article>166 <h1>Page Title</h1>167 <section>168 <h2>Introduction</h2>169 <p>Content here...</p>170 </section>171 <section>172 <h2>Details</h2>173 <p>More content...</p>174 </section>175 </article>176 </main>177178 <footer>179 <nav aria-label="Footer">180 <a href="/privacy">Privacy Policy</a>181 <a href="/terms">Terms of Service</a>182 </nav>183 <p>© 2026 Example Inc.</p>184 </footer>185 </body>186 ```1871883. **Replace `<div>` wrappers** with semantic equivalents:189 - `<div class="header">` → `<header>`190 - `<div class="nav">` → `<nav>`191 - `<div class="main">` → `<main>`192 - `<div class="footer">` → `<footer>`193 - `<div class="sidebar">` → `<aside>`194195See [references/semantic-html-guide.md](references/semantic-html-guide.md) for the complete element reference and `<article>` vs `<section>` guidance.196197**References:**198- [MDN Semantics in HTML](https://developer.mozilla.org/en-US/docs/Glossary/Semantics#semantics_in_html)199- [W3C HTML5 Document Sections](https://www.w3.org/TR/html52/sections.html)200201---202203## Checkpoint 3.4: ARIA Landmarks (10 pts)204205**What the scanner checks:**206- Implicit landmarks from semantic elements (`<main>` → main, `<nav>` → navigation, `<header>` → banner, `<footer>` → contentinfo, `<aside>` → complementary)207- Explicit ARIA roles (`role="navigation"`, `role="main"`, etc.)208- Additive ARIA attributes: `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-live`, `aria-expanded`, `aria-current`, `aria-hidden`209210**Scoring:**211- 10 pts — 3+ landmark regions AND at least 1 additive ARIA attribute212- 7 pts — 3+ landmark regions, no additive ARIA213- 5 pts — 1+ landmark AND 1+ additive ARIA attribute214- 3 pts — Any landmark or ARIA attribute present215- 0 pts — No landmarks or ARIA attributes found216217**Why it matters:** ARIA landmarks help AI agents identify page regions (navigation, main content, footer). This is the same API used by screen readers and is increasingly used by AI browsing agents.218219### Fix Workflow2202211. **Use semantic HTML first** — these provide implicit landmarks without extra attributes:222 ```html223 <header> <!-- implicit role="banner" -->224 <nav> <!-- implicit role="navigation" -->225 <main> <!-- implicit role="main" -->226 <footer> <!-- implicit role="contentinfo" -->227 <aside> <!-- implicit role="complementary" -->228 ```2292302. **Add ARIA attributes for disambiguation and state:**231 ```html232 <nav aria-label="Primary">233 <a href="/" aria-current="page">Home</a>234 <a href="/about">About</a>235 </nav>236237 <nav aria-label="Footer">238 <a href="/privacy">Privacy</a>239 </nav>240241 <div aria-live="polite" aria-label="Search results">242 <!-- Dynamic content area -->243 </div>244245 <button aria-expanded="false" aria-label="Toggle menu">Menu</button>246 ```2472483. **Do NOT add redundant roles** to semantic elements:249 ```html250 <!-- WRONG — redundant, not recommended by W3C -->251 <main role="main">252253 <!-- CORRECT — semantic element is sufficient -->254 <main>255 ```2562574. **Verify** — check for 3+ landmark types plus at least one `aria-*` attribute.258259**References:**260- [W3C Landmarks Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/)261- [MDN ARIA Roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles)262263---264265## Checkpoint 3.5: Image Alt Text (15 pts)266267**What the scanner checks:** All `<img>` tags have non-empty `alt` attributes. Score = (images with alt / total images) * 15. No images on page = full score.268269**Why it matters:** AI agents cannot see images. Alt text is the only way for AI systems to understand image content, context, and relevance to the surrounding text.270271### Fix Workflow2722731. **Find images missing alt text:**274 ```bash275 curl -s https://example.com | grep -oE '<img [^>]*>' | grep -v 'alt='276 ```2772782. **Add appropriate alt text:**279 ```html280 <!-- Content images: describe what the image shows -->281 <img src="team-photo.jpg" alt="Engineering team at the 2026 company offsite">282 <img src="chart.png" alt="Revenue growth chart showing 40% increase in Q4 2025">283 <img src="product.jpg" alt="Wireless noise-cancelling headphones in matte black">284285 <!-- Decorative images: use empty alt (NOT missing alt) -->286 <img src="divider.svg" alt="">287 <img src="bg-pattern.png" alt="">288289 <!-- Icons with adjacent text: use empty alt to avoid repetition -->290 <img src="email-icon.svg" alt=""> <span>Email us</span>291292 <!-- Logos: use the company/brand name -->293 <img src="logo.svg" alt="Acme Inc.">294 ```2952963. **Alt text guidelines:**297 - Be specific and concise (under 125 characters)298 - Describe the content and function, not appearance299 - Don't start with "Image of..." or "Picture of..."300 - For charts/graphs, describe the key data point or trend301 - For decorative images, use `alt=""` (empty, not missing)302303**References:**304- [WCAG Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html)305- [MDN img alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt)306307---308309## Checkpoint 3.6: Language Attribute (5 pts)310311**What the scanner checks:** `<html>` tag has a `lang` attribute with a valid BCP 47 language code.312313**Scoring:**314- 5 pts — Valid BCP 47 code (e.g., `en`, `nl`, `en-US`)315- 2 pts — `lang` attribute present but invalid value316- 0 pts — No `lang` attribute317318**Why it matters:** The `lang` attribute tells AI agents what language your content is in, enabling correct text processing, translation, and language-specific understanding.319320### Fix Workflow3213221. **Check current state:**323 ```bash324 curl -s https://example.com | grep -oE '<html[^>]*lang="[^"]*"'325 ```3263272. **Add or fix the lang attribute:**328 ```html329 <!-- English -->330 <html lang="en">331332 <!-- Regional variants -->333 <html lang="en-US">334 <html lang="en-GB">335 <html lang="nl-NL">336 <html lang="de-DE">337 <html lang="fr-FR">338 <html lang="ja">339 <html lang="zh-Hans">340 ```3413423. **For multilingual content**, use `lang` on specific elements:343 ```html344 <html lang="en">345 <body>346 <p>This is English text.</p>347 <blockquote lang="fr">Ceci est en français.</blockquote>348 </body>349 </html>350 ```351352**References:**353- [MDN lang attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)354- [W3C Declaring language in HTML](https://www.w3.org/International/questions/qa-html-language-declarations)355356---357358## Checkpoint 3.7: Descriptive Link Texts (10 pts)359360**What the scanner checks:** Samples up to 50 links. Flags generic text: "click here", "read more", "learn more", "here", "link", "more", "details", "info", "more details". Score = (descriptive links / total sampled) * 10.361362**Why it matters:** AI agents use link text to understand navigation and discover related content. Generic text like "click here" provides no context about where the link leads.363364### Fix Workflow3653661. **Find generic links:**367 ```bash368 curl -s https://example.com | grep -oiE '<a [^>]*>([^<]*)<\/a>' | grep -iE '>(click here|read more|learn more|here|link|more|details|info|more details)<'369 ```3703712. **Replace with descriptive text:**372 ```html373 <!-- WRONG -->374 <a href="/pricing">Click here</a>375 <a href="/blog/ai-trends">Read more</a>376 <a href="/docs">Learn more</a>377 To sign up, <a href="/register">click here</a>.378379 <!-- CORRECT -->380 <a href="/pricing">View pricing plans</a>381 <a href="/blog/ai-trends">Read our AI trends analysis</a>382 <a href="/docs">Explore the documentation</a>383 <a href="/register">Create your free account</a>.384 ```3853863. **Patterns for common cases:**387 - Blog posts: "Read [article title]" instead of "Read more"388 - CTAs: describe the action — "Start free trial", "Download the report"389 - Navigation: use the destination name — "About us", "API documentation"390 - Lists: "[Item name] details" instead of "Details"3913924. **For "Read more" in card layouts**, make the entire card clickable or use `aria-label`:393 ```html394 <!-- Option A: descriptive visible text -->395 <a href="/blog/ai-trends">Read AI trends analysis</a>396397 <!-- Option B: aria-label when visual design requires short text -->398 <a href="/blog/ai-trends" aria-label="Read AI trends analysis">Read more</a>399 ```400401**References:**402- [WCAG Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html)403- [MDN Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)404405---406407## Checkpoint 3.8: Question-Based Headings (10 pts)408409**What the scanner checks:** H2 headings that use question format — ending with `?` or starting with a question word (how, what, why, when, where, which, who, can, does, do, is, are, will, should, would, could, shall).410411**Scoring:**412- 10 pts — 2+ question-format H2 headings, or (3 or fewer total H2s and at least 30% are questions)413- 5 pts — At least 1 question-format H2414- 0 pts — H2 headings exist but none are questions415- Skip (0/0) — No H2 headings present416417**Why it matters:** 78.4% of ChatGPT citations come from pages with question-based H2 headings. Question headings match how users query AI systems, making your content more likely to be selected as a source for AI-generated answers.418419### Fix Workflow4204211. **Audit current H2 headings:**422 ```bash423 curl -s https://example.com | grep -oE '<h2[^>]*>.*?</h2>'424 ```4254262. **Rewrite H2 headings as questions:**427 ```html428 <!-- WRONG -->429 <h2>AI Agent Readiness</h2>430 <h2>Content Discovery by AI Systems</h2>431432 <!-- CORRECT -->433 <h2>What Is AI Agent Readiness?</h2>434 <h2>How Do AI Systems Discover Your Content?</h2>435 <h2>Why Does Structured Data Matter for AI?</h2>436 ```4374383. **Recognized question starters:** how, what, why, when, where, which, who, can, does, do, is, are, will, should, would, could, shall — or any heading ending with `?`.4394404. **Not all headings need to be questions** — aim for 2+ question H2s on pages with 4+ H2s, or 30%+ on pages with 3 or fewer.4414425. **Pair with FAQPage schema** (checkpoint 2.7) for maximum AI citation potential — match H2 questions with JSON-LD Question/Answer pairs.4434446. **Verify:**445 ```bash446 curl -s https://example.com | grep -oE '<h2[^>]*>.*?</h2>' | grep -iE '(\?|>(How|What|Why|When|Where|Which|Who|Can|Does|Do|Is|Are|Will|Should|Would|Could|Shall) )'447 ```448449**References:**450- [MDN Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)451452---453454## Quick Wins Checklist455456For the fastest score improvement, fix in this order:4574581. **Add `<html lang="en">`** — 5 pts, one line (checkpoint 3.6)4592. **Add semantic elements** — wrap existing `<div>`s with `<header>`, `<nav>`, `<main>`, `<footer>` (checkpoint 3.3)4603. **Fix heading hierarchy** — ensure one `<h1>`, sequential levels (checkpoint 3.2)4614. **Add ARIA attributes** — `aria-label` on duplicate navs, `aria-current="page"` (checkpoint 3.4)4625. **Add alt text** to all images (checkpoint 3.5)4636. **Fix generic link texts** — replace "click here" and "read more" (checkpoint 3.7)4647. **Rewrite H2s as questions** — match how users query AI systems (checkpoint 3.8)4658. **Add form labels** — associate every input with a label (checkpoint 3.9)4669. **Add autocomplete** — help agents fill forms correctly (checkpoint 3.10)46710. **Fix document title** — descriptive, 10-70 chars (checkpoint 3.12)46811. **Fix aria-hidden misuse** — never on focusable elements (checkpoint 3.14)46912. **Add button names** — every button needs an accessible name (checkpoint 3.13)47013. **Fix keyboard navigation** — no positive tabindex, proper roles on clickable divs (checkpoint 3.11)47114. **Implement SSR** — largest effort but highest single-checkpoint score (checkpoint 3.1)472473## Key Gotchas474475Common mistakes that cause checkpoint failures:4764771. **Multiple `<h1>` tags** — Components that each add their own `<h1>` break hierarchy4782. **Heading level skips** — Going from `<h1>` directly to `<h3>` without `<h2>`4793. **SPA with empty shell** — `<div id="root"></div>` scores 0 without SSR4804. **Missing alt vs empty alt** — `<img src="...">` (no alt) fails; `<img src="..." alt="">` (empty) is valid for decorative images4815. **Generic link text** — "Click here" and "Read more" provide no context for AI agents4826. **Statement headings instead of questions** — "AI Agent Readiness" scores 0; "What Is AI Agent Readiness?" scores points483484> See [references/gotchas.md](references/gotchas.md) for detailed correct vs incorrect examples of each.485486## References487488- [references/semantic-html-guide.md](references/semantic-html-guide.md) — Semantic elements, ARIA mapping, heading patterns, link text patterns489- [references/ssr-strategies.md](references/ssr-strategies.md) — Framework-specific SSR implementation guides490- [references/gotchas.md](references/gotchas.md) — Common pitfalls with correct vs incorrect examples491492## Instructions4934941. **Identify failing checkpoints** from the IsAgentReady.com scan results4952. **Follow the fix workflow** for each failing checkpoint above4963. **Apply the code examples** — adapt HTML structure and content to the user's site4974. **Verify each fix** using the curl commands provided in each workflow4985. **Re-scan** at [isagentready.com](https://isagentready.com) to confirm improvements499500If `$ARGUMENTS` is provided, interpret it as the URL to fix or the specific checkpoint to address.
bartwaardenburg