Semantic HTML & Accessibility Tree Audit
When to Use
Execute this skill during a brand discoverability and engagement audit to evaluate whether an AI assistant, business agent (UCP), or RAG crawler can parse text hierarchies and interact with page controls.
Inputs
html_content: The raw DOM string of the audited page.url: Target webpage URL.
Procedure
- Read the provided raw HTML document strictly in-memory to minimize I/O overhead.
- Execute the bundled audit script by piping the HTML content into it via standard input. Run the exact following bash command:
echo "$html_content" | python3 scripts/a11y_extractor_check.py - The script will scan the document
<head>for UCP/ACP agentic commerce feeds, compute static accessible names for interactive nodes, and verify structural landmarks (<main>,<article>, heading monotonicity). - Do not alter or summarize the script's output.
- Output the exact findings mathematically as generated by the script.
Deterministic Grading Rubric
You must assign severities and generate findings strictly according to this matrix based on the JSON output from a11y_extractor_check.py.
| Condition from Script Output | Finding Title | Severity | Priority |
|---|---|---|---|
Interactive controls (buttons, links, inputs) lack an accessible name (no aria-label, visible text, or alt) |
Nameless Interactive Controls (Agent Blockers) | critical (if no commerce feed) / high | critical / high |
Document lacks <main> or <article> tags |
Missing Core Semantic Container (<main> or <article>) |
high | high |
Document has exactly 0 <h1> tags |
Missing Entity Anchor (<h1>) |
high | high |
Document has more than 1 <h1> tag |
Multiple Entity Anchors (Ambiguous <h1>) |
medium | medium |
Heading levels skip ranks (e.g., h2 followed directly by h4) |
Fragmented Heading Hierarchy | medium | medium |
Allowed Tools
bash(executing bundled scriptscripts/a11y_extractor_check.py)
Output
Emit only a valid JSON array matching the exact structure dictated in references/finding_schema.json.