Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams Dropdowns
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Concepts Page speed testing

Page speed testing

How to measure the speed of a website built with the UAE Design System, which numbers to aim for, and how to fix the most common causes of slow pages.

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

You must test this from a laptop or desktop, running Google Chrome in Incognito Mode, where your laptop or desktop is physically connected to an internet connection from within the United Arab Emirates. You cannot simulate the connection using a VPN.
  1. Test a production build. Development servers skip minification and add hot-reload code, so their scores are meaningless.
  2. Open the page in a Chrome Incognito window, so browser extensions and cached files do not affect the result.
  3. 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.
  4. Run the test three to five times and use the median. Single runs vary.
  5. 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.
  6. Save the report, so you can compare it with the next release.

What the design system already does

  • Components load on demand. defineCustomElements() registers every aegov-* 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: swap shows text immediately in a fallback font.
Your code decides how fast your pages load. The design system gives you a fast starting point, but it cannot make a page fast on its own. The quality of your templates and code, and how you use images, video and other media, decide how quickly each page loads. Large unoptimised images, autoplaying video, unused scripts and third-party widgets will make a page slow, however efficiently the components load.

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 srcset and sizes for different screens.
  • Give the hero image fetchpriority="high", and never loading="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 width and height on every image and video, or use aegov-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-height on 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 defer or async, 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 input and scroll handlers.

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.

Where to next

Responsive design Back to Concepts