Agent Navigability

Why Agent Navigability?

AI agents (like Claude, GPT, and Cursor) navigate web pages by inspecting the accessibility tree — the same tree screen readers use. If your page has proper landmarks and headings, AI agents can understand and interact with it effectively.

Required Landmarks

The layer automatically injects these landmarks:

Heading Hierarchy

Every page must follow a logical heading structure:

• One h1 per page (the page title)
• h2 for section headings
• h3+ for subsections
• No skipped levels (e.g., h1 → h3 without h2)

The landing page h1 typically comes from the hero section. Other layouts auto-render the page title as h1.

Interactive Elements

• All form inputs must have descriptive <label> elements
• All buttons must have meaningful text (no icon-only buttons without aria-label)
• Navigation links must have descriptive text
• Use semantic <button> elements (not <div @click>)

Signal Capture Forms

Forms must be:

• Discoverable via data-testid (e.g., convert-form)
• Completable by agents: fill inputs → submit → verify success state
• Accessible: proper <form>, <label>, and <input> semantics

All ConvertForm components meet these requirements automatically.

Smoke Test Script

Run the automated navigability check:

bash scripts/agent-smoke-test.sh

This starts a dev server and validates:

1. Accessibility landmarks (banner, main, contentinfo, region)
2. Heading hierarchy (h1, h2)
3. Interactive elements (links, buttons)
4. Signal capture form discoverability

Manual Testing

agent-browser open http://localhost:3000
agent-browser snapshot           # Check landmarks + heading hierarchy
agent-browser snapshot -i        # Check interactive elements
agent-browser find role form     # Verify forms are discoverable

Best Practices

When creating custom sections or overriding components:

1. Use SectionWrapper to get automatic landmark and testid injection
2. Always include a heading (h2) in each section
3. Give buttons meaningful text or aria-label
4. Use <label> for all form inputs
5. Test with agent-browser snapshot after changes