Methodology · Scoring model v3 · Last updated June 13, 2026

20 checks. Published scoring model. No mystery.

Each check is named. Each failure has a severity. Every failure maps to a concrete fix.

Every Legibility Score can be reconstructed from the checks, weights, and grade bands below — and this page is generated from the same code the scanner runs, so it cannot drift from the product.

What Legible does not measure: search rankings, traffic, brand visibility, or whether an AI assistant will recommend you. It measures the layer upstream of all of those — whether your site exposes the structure, labels, and machine-readable meaning agents need to understand it at all.

The scoring model

In plain terms: Legible checks 20 things that help AI agents read, navigate, and understand a page. Critical failures cost more than medium ones, and the final score is the percentage of weighted checks passed — normalized to 100 so every site is comparable. Formally:

score = 100 × (weight of checks passed ÷ total weight)

A check passes or fails as a whole. Every flagged element is shown in the report, but instance counts don't multiply penalties — that keeps the score stable, comparable between sites, and impossible to bottom out on a single widespread issue.

Severity	Weight	What it means
critical	5	Decides whether agents can see and identify the site at all — content reachability and identity metadata
high	3	Machine-followable paths and machine-readable facts — links agents can follow, entities they can cite
medium	1	Robustness and clarity margin — costs agents retries and risks misreads, and matters for assistive technology

Total weight across all 20 checks: 2 critical × 5 + 3 high × 3 + 15 medium × 1 = 34.

Worked example

A page passes 14 of 20 checks, failing 2 critical, 1 high, and 3 medium. Failed weight: 2×5 + 1×3 + 3×1 = 16. Score: 100 × (34 − 16) ÷ 34 = 53 — Needs Work. Fixing just the two criticals and the high recovers 38 points: 100 × (34 − 3) ÷ 34 = 91 — Agent-Ready. This is the same arithmetic behind every “+N pts” in a Legible report.

The grades

Score	Grade	Reading
90–100	Agent-Ready	Agents can read, navigate, and act with confidence
70–89	Mostly Legible	A good foundation with fixable friction
50–69	Needs Work	Key signals missing — agents will guess or skip
0–49	Agent-Hostile	Most of the site does not come through to machine readers
—	Agent-Blocked	Bot protection turns automated readers away entirely

The 20 checks

Three layers, in the order an agent experiences them.

Interaction clarity

Can an agent operate the page's controls?

Grounded in WAI-ARIA and WCAG interaction principles — the same name/role/state model assistive technology relies on.

Ghost Buttons

high

Flags: div/span with onclick but no role="button". Passes when nothing is flagged.
Why it matters: AI assistants can't press them, so anything behind them — menus, sign-ups, bookings — is out of reach.
The fix: Replace clickable div/span elements with real <button> elements, or add role="button" and keyboard handling.

Icon-Only Actions

medium

Flags: Buttons containing only svg/img with no aria-label. Passes when nothing is flagged.
Why it matters: An assistant has to guess what an unnamed button does — guesses cost retries and mistakes, and screen-reader users get no guess at all.
The fix: Add an aria-label describing the action to every icon-only button or link.

Duplicate Labels

medium

Flags: Multiple buttons/links with identical text. Passes when nothing is flagged.
Why it matters: Assistants can't tell them apart, and may send a customer to the wrong one.
The fix: Differentiate repeated button/link text with aria-label (e.g. "Read more about pricing").

Orphaned Inputs

medium

Flags: Form inputs with no label or aria-label. Passes when nothing is flagged.
Why it matters: Capable assistants usually work unlabeled fields out — after wasted attempts. Weaker tools and screen readers don't, and every retry is a chance to fill your form wrong.
The fix: Associate every input with a <label for=...>, or add an aria-label. Placeholders are not labels.

Div Links

high

Flags: div/span used for navigation instead of anchor tags. Passes when nothing is flagged.
Why it matters: Assistants and search engines can't follow them, so the pages behind them go unvisited.
The fix: Use a real <a href> for navigation so agents can follow it without executing JavaScript.

Ambiguous Links

medium

Flags: Links with vague text like "click here" or under 4 characters. Passes when nothing is flagged.
Why it matters: Tools that read your page aloud or quote it can only repeat the link text — “click here” tells their user nothing about what you're offering behind it.
The fix: Rewrite link text to describe the destination — "View pricing", not "click here".

Identical Links, Different Targets

medium

Flags: Links with same text but different href values. Passes when nothing is flagged.
Why it matters: Assistants may take a customer to the wrong page and trust in the site drops.
The fix: Make link text unique per destination, or add aria-labels that distinguish them.

State Blindness

medium

Flags: Interactive elements (dropdown, accordion, modal, tab) lacking ARIA state. Passes when nothing is flagged.
Why it matters: Humans see it; machines have to be told. Assistants burn extra steps working out what's open, and screen-reader users hear nothing at all.
The fix: Add aria-expanded, aria-selected, or aria-hidden so agents can read component state.

Dynamic IDs

medium

Flags: Element IDs with random hex strings or framework prefixes. Passes when nothing is flagged.
Why it matters: An assistant that found your booking button yesterday can't find it again today.
The fix: Give interactive elements stable, semantic id or data attributes that survive rebuilds.

Structure

Can an agent navigate the page's anatomy?

Grounded in semantic HTML and ARIA landmark practice: headings, regions, and elements that mean what they say.

Missing Landmarks

medium

Flags: No nav, main, header, or footer elements. Passes when nothing is flagged.
Why it matters: Landmarks are the map machine readers navigate by. Without them, assistants and assistive tech work through the page the slow way.
The fix: Wrap page regions in <nav>, <main>, <header>, and <footer> landmark elements.

Heading Chaos

medium

Flags: Skipped heading levels or multiple h1s. Passes when nothing is flagged.
Why it matters: Headings are the table of contents a machine reads first. When they're scrambled, the whole page is harder to summarize correctly.
The fix: Use exactly one <h1> per page and never skip heading levels.

Semantic Soup

medium

Flags: div/span to semantic element ratio exceeds 15:1. Passes when nothing is flagged.
Why it matters: To a machine reader, everything looks the same — nothing stands out as a menu, an article, or a product.
The fix: Replace generic div/span wrappers with semantic elements: <section>, <article>, <nav>, <button>, <ul>.

Table Misuse

medium

Flags: Tables used for layout or data tables missing th headers. Passes when nothing is flagged.
Why it matters: Prices, schedules, and comparisons in them can't be read or quoted accurately by AI tools.
The fix: Give data tables <th> headers inside <thead>; use CSS for layout instead of tables.

Invisible Content

medium

Flags: Hidden elements with meaningful text content. Passes when nothing is flagged.
Why it matters: Assistants may quote content your visitors never see — or miss content they should.
The fix: Remove meaningful text from hidden elements, or expose its state with aria-expanded.

Meaning

Does the site state what it offers in machine-readable form?

Grounded in Schema.org / JSON-LD structured data and emerging agent conventions (agents.md, llms.txt).

Structured Data Depth

high

Flags: JSON-LD that describes the site's actual entities, not just its existence. Passes when nothing is flagged.
Why it matters: AI tools and search engines have to guess what you sell, what it costs, and when you're open. Guesses lose customers; structured facts win recommendations.
The fix: Add JSON-LD describing your core entities — products, articles, events, your organization. Legible generates a scaffold for you.

Unlabeled Images

medium

Flags: Images missing an alt attribute entirely. Passes when nothing is flagged.
Why it matters: Your photography — rooms, products, food, people — is invisible to AI assistants. They can only recommend what they can read.
The fix: Add descriptive alt text to informative images; use alt="" for purely decorative ones.

Title & Description Quality

critical

Flags: Descriptive <title> and meta description. Passes when nothing is flagged.
Why it matters: Most AI tools meet your business as a title and description in a results list — before any of them load your page. In our published twin experiment, this alone decided whether four out of four AI assistants could identify and recommend the business, or had nothing to go on.
The fix: Write a specific <title> and a 50–160 character meta description — they are the first thing agents read.

JS-Gated Content

critical

Flags: Content requires JavaScript to render. Passes when nothing is flagged.
Why it matters: Many machine readers never run those scripts. To them, your site is an empty page.
The fix: Server-render or statically generate your primary content so it exists in the initial HTML response.

Missing agents.md

medium

Flags: No /agents.md file to guide AI agents. Passes when nothing is flagged.
Why it matters: It's a free concierge note for machine visitors — what you do, what they may use, where things are. Sites that have one get understood; sites that don't get guessed at.
The fix: Add an agents.md file at your site root describing what your site does and how agents should use it — Legible generates one for you.

Missing llms.txt

medium

Flags: No /llms.txt summary for language models. Passes when nothing is flagged.
Why it matters: A one-page summary AI tools check first. Cheap to add, and it shapes how every AI describes your business.
The fix: Add an llms.txt file at your site root: a plain-language summary of the site with links to your key pages.

Known limitations

Legible analyzes the page's served HTML. It does not execute JavaScript; instead, a heuristic flags pages whose content only exists client-side. Sites that render meaningful content into their initial HTML are measured accurately; pure client-side apps are flagged rather than partially scored.
A scan reads one page — the URL you submit — plus root discovery probes (robots.txt, agents.md, agent.md, llms.txt). Multi-page scanning is on the roadmap.
Checks are deterministic heuristics, not judgment calls. That makes scores reproducible and explainable, and it means rare false positives are possible on unusual markup — every flagged element is shown so you can verify.
Legible measures legibility — whether agents can read, navigate, and understand a site. It does not measure rankings, traffic, or how often AI tools cite a site.
Scans respect robots.txt and require the person scanning to confirm they have permission.

Changelog

June 13, 2026

Scoring model v3 — recalibrated against our own controlled experiment. We built two pixel-identical versions of a hotel site (legibility scores 54 and 100), pre-registered six predictions, and ran four AI assistants plus 30 logged browser-agent sessions against both. The comprehension and task-completion predictions missed: capable agents read and operated both twins nearly identically. The metadata prediction hit decisively: from title and description alone, all four assistants identified and recommended the fixed site and found the flawed one unidentifiable. Full data in the repo (validation/).
Consequence: Title & Description Quality is now critical (was medium) — the one check our experiment proved decisive. Interaction-polish checks (icon-only actions, orphaned inputs, state blindness, ambiguous links, duplicate labels, landmarks) moved down to medium: tested agents recovered from all of them, at the cost of wasted retries rather than failure. JS-gated content stays critical (reader-mode agents consume only extracted text — several never saw page forms at all). Ghost buttons and div links stay high: without a real role or href there is nothing in the accessibility tree to recover from.
What the score now means: can an agent that never renders your JavaScript — and often never reads past your metadata — still tell who you are, what you offer, and how to act.

June 12, 2026

Scoring model v2: score = weighted share of checks passed (critical 5 / high 3 / medium 1). Replaced the per-instance penalty model, which saturated at 0 for large JS-heavy sites.
Checks expanded 16 → 20: structured data depth, image alt coverage, title & description quality, llms.txt. JS-gated detection repaired; agents.md accepted alongside agent.md.
Grades relabeled: Mostly Legible (70–89) and Needs Work (50–69) replace the former Needs Work / Hazardous bands. Ring colors now track grade bands.
Dynamic ID detection fixed to never flag plain hyphenated ids (found by scanning ourselves).

Disagree with a weight, or want a standard covered? Email a methodology suggestion — the changelog above records what changes and why.