Why page speed matters
A slow page costs people time and mobile data, and many give up before the page finishes loading. Government services must work for everyone, including people on older phones and weak mobile connections. Treat speed as part of the quality of a service, and test it before every release, not only at launch.
What to measure
Measure the three Core Web Vitals. A page passes when at least 75% of visits meet the "good" threshold.
| Metric | Measures | Good | Poor |
|---|---|---|---|
| Largest Contentful Paint (LCP) | How quickly the main content appears | 2.5 s or less | More than 4 s |
| Interaction to Next Paint (INP) | How quickly the page responds to taps, clicks and key presses | 200 ms or less | More than 500 ms |
| Cumulative Layout Shift (CLS) | How much the layout moves while loading | 0.1 or less | More than 0.25 |
Lab tools such as Lighthouse cannot measure INP, because it needs a real person interacting with the page. Use Total Blocking Time (TBT) as the lab stand-in: keep it under 200 ms.
Tools
| Tool | Data | Use it to |
|---|---|---|
| Lighthouse in Chrome DevTools | Lab | Test any page, including local and staging builds, and get a list of fixes. |
| PageSpeed Insights | Lab and field | Run Lighthouse on a public page, and see real-user Core Web Vitals from the Chrome UX Report when the site has enough traffic. |
| Chrome DevTools Performance panel | Lab | Record a page load or an interaction and find the long tasks, layout shifts and slow requests behind a poor score. |
| WebPageTest | Lab | Test from different locations, browsers and connection speeds, and compare runs as filmstrips. |
Lab data comes from one simulated load on a controlled device and network. It is repeatable, so use it to find and fix problems. Field data comes from real visitors on their own devices. It is what people actually experience, so use it to decide whether a page is fast enough.
Running a test
- Test a production build. Development servers skip minification and add hot-reload code, so their scores are meaningless.
- Open the page in a Chrome Incognito window, so browser extensions and cached files do not affect the result.
- In Lighthouse, choose Mobile, the Navigation mode and the Performance category. Mobile simulates a mid-range phone on a slow 4G connection, which is closer to many visitors than a desktop on office Wi-Fi.
- Run the test three to five times and use the median. Single runs vary.
- Test one page for each template, not only the home page: a content page, a listing page and a page with a form. Test both the English and Arabic versions, because they load different fonts.
- Save the report, so you can compare it with the next release.
What the design system already does
- Components load on demand.
defineCustomElements()registers everyaegov-*tag, but the code for each component is only downloaded when that tag appears on the page. A page with a button and an accordion does not download the date picker. - CSS contains only what you use. Tailwind CSS v4 scans your templates and generates only the utilities they use. Production builds are minified when Tailwind's optimisation is on (see Browser support).
- Fonts are split and swap in. The base stylesheet loads variable fonts in WOFF2 format, split by script with
unicode-range, so an English page does not download the Arabic fonts and the reverse.font-display: swapshows text immediately in a fallback font.
Common problems and fixes
Slow Largest Contentful Paint
The largest element is usually a hero image or a heading.
- Serve images in WebP or AVIF, sized for the space they fill, with
srcsetandsizesfor different screens. - Give the hero image
fetchpriority="high", and neverloading="lazy". - Give images further down the page
loading="lazy". - The fonts load from
fonts.gstatic.com. Add a preconnect so the browser opens that connection early:
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
Layout shift
- Set
widthandheighton every image and video, or useaegov-aspect-ratio, so the browser reserves the space before the file arrives. - Components are hidden until their code has loaded, then appear. If a component above the fold pushes content down when it appears, reserve its space with a
min-heighton its wrapper. - Do not insert banners, cookie notices or alerts above existing content after the page has loaded. Reserve their space or overlay them instead.
Slow interactions
- Load analytics, chat widgets and other third-party scripts with
deferorasync, and remove any you do not use. They are the most common cause of a high Total Blocking Time. - Break up long-running JavaScript, and avoid heavy work in
inputandscrollhandlers.
Slow server response
If the first byte takes more than about 800 ms to arrive, everything after it is late too. Cache pages at the server or a CDN and enable Brotli or gzip compression. How to effectively optimise your code: caching, compression and catalogue covers these in more depth.
Testing on every change
Run Lighthouse CI in your build pipeline, so a change that slows a page fails the build instead of reaching visitors. Add a lighthouserc.json to the project:
{
"ci": {
"collect": {
"url": ["http://localhost:8080/", "http://localhost:8080/ar/"],
"numberOfRuns": 3
},
"assert": {
"assertions": {
"largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
"total-blocking-time": ["error", { "maxNumericValue": 200 }]
}
},
"upload": {
"target": "filesystem",
"outputDir": ".lighthouseci"
}
}
}
Then serve the production build and run:
npx @lhci/cli autorun
The filesystem target keeps reports inside your pipeline. Lighthouse CI's temporary-public-storage target uploads them to a public server, so do not use it for services that are not yet public.