Disclosure: I built this tool with help from an AI coding assistant (Claude), and an AI helped draft this article. I reviewed the code and the text. Every number below comes from the project's README.

A bakery owner doesn't care that their Largest Contentful Paint is 4.8 seconds. They care that a customer on a phone can't find the opening hours. I wanted an audit that starts from the second sentence and still rests on measured data. So I wrote shopfront-audit, an MIT-licensed TypeScript tool that takes a URL, optionally the name, address and phone from the business's listing, and writes one HTML report an owner can read.

This post explains how the score is built and where it is weak.

Five areas, five weights

The overall score is a weighted mean of five areas, each on a 0 to 100 scale:

Area Weight
Speed 30%
Phones and tablets 25%
Google and search 20%
Accessibility 15%
Name, address and phone 10%

If you don't pass business details, the last area is left out and the weights are renormalised over the others, so a missing input isn't punished as a zero. Grades follow: A from 90, B from 75, C from 60, D from 40, F below that.

Inside an area, every check returns a score between 0 and 1 and has a weight. The area score is 100 × Σ(weight × score) / Σ(weight), with skipped checks excluded.

What each area looks at

Speed. Lighthouse performance on mobile and desktop, then Largest Contentful Paint, Total Blocking Time and Cumulative Layout Shift against the Core Web Vitals thresholds. Those three scale linearly between Google's "good" and "poor" values (LCP 2.5 s to 4 s, TBT 200 ms to 600 ms, CLS 0.1 to 0.25). It also checks total page weight, images over 1 MB and downloads over 2 MB.

Phones and tablets. The viewport tag, sideways scrolling at 375 and 768 px (it names the elements that cause it), links and buttons under 24 px (the WCAG 2.2 target size, with links inside running text exempt), the share of text under 12 px after the phone's zoom, and menus published only as PDFs. The phone and tablet contexts emulate a touch device, so a page without a viewport tag is laid out at 980 px and shrunk, as a real phone would show it.

Google and search. HTTPS, http-to-https redirect, certificate validity and expiry, redirect chain, noindex in meta tags or headers, robots.txt and whether it blocks Google, sitemap, title, meta description, H1, Open Graph tags, schema.org LocalBusiness data, and broken internal links.

Accessibility. axe-core with the WCAG 2.0, 2.1 and 2.2 A and AA rules plus best practices, grouped by impact.

Name, address and phone. It compares what you pass in with the visible text, title and structured data: the name, address parts (postcodes kept whole), the phone with or without the country prefix, and whether the phone number is a tap-to-call link.

Two formulas worth explaining

Accessibility burden

A raw count of axe violations is a poor score: one rule failing on 200 elements isn't 200 times worse than one failing on one element. So the check works per impact level (critical, serious, moderate, minor, weighted 4, 3, 2 and 1). Each violated rule adds a burden of 1 + log10(elements affected), and the level scores 1 / (1 + total burden).

One rule on one element halves that level's score. A rule hitting 100 elements counts three times as much as one hitting a single element, not a hundred times.

Broken links

These are simpler. Each broken internal link costs a quarter of the check, so four or more score zero.

Ranking the fixes

An owner doesn't want a list of 30 problems. They want the first three things to do. Every finding gets a gain, the overall points it would bring back:

gain = 100 × (area weight / Σ area weights) × (check weight × (1 − check score) / Σ check weights) × share 

share splits a check's lost points between the findings that belong to it, for example by file size when two images are too heavy. Findings sort by gain, and the summary prints the top three:

Grade F, 27/100 Fix first: 1. On a phone, your page takes 23 s to show its main content 2. On phones, your site shows a tiny desktop page 3. On phones, people have to scroll sideways to read your page 

Waiting times in the findings assume a 5 Mbit/s phone connection plus 0.3 s of latency, and I state that in the report rather than hide it.

Each finding is written for the owner. For example: "Your menu is a 6 MB PDF: on phones it takes about 10 s to open", then why it matters and what to do: put the menu on a normal web page, or at least compress the PDF to under 1 MB.

Architecture: evidence in, report out

Everything that needs a browser or the network sits in one collector that produces a serialisable Evidence object. The analyzers and scoring are pure functions of that evidence:

collector → Evidence → analyzers → scoring → reporters 

That is why most of the test suite runs in milliseconds on hand-written HTML fixtures. The end-to-end tests start two local sites: a well-built bistro and a neglected trattoria with a 6 MB PDF menu, a 4.4 MB photo, slow scripts, broken links, no viewport tag and a wrong phone number. The heavy files are generated when the server starts, so the repository stays small.

Lighthouse runs in its own Chrome through chrome-launcher, because it applies its own emulation and throttling and expects a clean profile. Playwright does the rest: three viewports (375, 768 and 1280 px), axe-core, and PDF printing. Both use the same Chromium binary.

The report is a single file with no scripts, fonts or images loaded from the network. The charts are hand-written SVG coloured with CSS variables, so they follow dark mode and print correctly. The crawler respects robots.txt, sends an honest user agent, and checks files with HEAD or a one-byte ranged GET instead of downloading them.

What it can't do

I'd rather you read this section than find out later.

  • Lighthouse runs on a simulated mid-range phone. Scores move a few points between runs and machines. They are lab data, not real visitor data.
  • Only the home page is rendered, measured and scanned with axe. Other pages are only crawled for broken links.
  • Automated accessibility testing finds only part of the problems. A clean axe run doesn't mean a site is accessible.
  • Structured data is read from JSON-LD. Microdata gets partial credit and isn't validated.
  • Name, address and phone matching is heuristic. It tokenises and compares, with no geocoding, so an address written in another language can come out as a partial match.
  • Sites that block headless browsers or sit behind a bot challenge can't be audited.

The score is also a plain weighted mean, so a very good area can hide a terrible one. I haven't decided whether to cap the overall grade by the worst area. If you have an opinion, open an issue.

Using it

npm install -g github:George-Mikaelson/shopfront-audit npx playwright install chromium shopfront-audit https://bistro.example \ --name "Bistro Verde" \ --address "Rua das Flores 12, 1200-195 Lisboa" \ --phone "+351 21 234 5678" \ --out reports/bistro-verde 

It writes report.html, report.json, report.pdf and screenshots. For many sites, --csv leads.csv runs a batch with limited concurrency, retries, a per-site timeout and a result cache, and writes summary.csv and an index.html sorted worst first. OpenStreetMap tag names such as contact:website work as column headers. As a library, audit() returns the report object, and there is a GitHub Action that comments the summary on pushes and pull requests.

There is no telemetry, no account and no API key.

Example reports built from the fictional test sites: a neglected site and a well-built one.

I also build small websites for local businesses, which is why I wrote this, but the tool doesn't depend on that. If a check is noise, or a common small-business mistake is missing, tell me in the issues.