SiteLint documentation and guidelines

The user waits a long time before it sees the first content on the screen.

Description

First Contentful Paint (FCP) marks the exact moment the browser puts the first text, image, or interface element on the screen – the instant a blank white rectangle becomes a readable page. Until that instant arrives, visitors stare at nothing and quickly conclude the site is broken, so every additional second of blank screen directly erodes trust. The rule reads entries from the browser’s Paint Timing API (see the MDN Paint Timing reference) and measures how long users wait for that very first painted content.

The measurement is scored against fixed thresholds: a paint time of 1800 ms or less passes silently, anything between 1800 ms and 3000 ms produces a warning report that includes the rounded duration in seconds, and anything above 3000 ms escalates to the more severe report. Both reports carry the measured time so developers can see exactly how far the page is from the target. When the Paint Timing data is missing or empty, the rule records a skip instead of a failure, because the browser did not expose paint entries to evaluate.

Common impact areas

  • End users: visitors experience an empty screen while waiting, and the longer they see nothing, the higher the chance they abandon the page before reading anything.
  • Search engines: slow first paint signals poor page experience, and rendering performance is factored into how search systems evaluate page quality and rankings.
  • Site owners: blank-screen time depresses conversion rates, engagement, and ad revenue because potential customers never reach the call to action.
  • Developers: the report provides a concrete, numeric performance budget that catches regressions when new scripts, styles, or third-party tags are added.
  • Maintainers: repeated failures point to accumulated render-blocking resources and unmanaged third-party tags that need ongoing governance.

Why it matters

First Contentful Paint is the earliest signal that a page is alive, and on text-heavy pages it usually determines the Core Web Vitals metric Largest Contentful Paint (LCP). Together with Interaction to Next Paint (INP) and Cumulative Layout Shift (CLS), LCP forms the set of user-experience measurements that Google associates with page quality. A page that keeps users staring at whitespace fails the most basic promise of the web: delivering content quickly.

Perceived performance begins at the first painted pixel, not at the load event. Users judge responsiveness from the moment the screen changes, which makes early paint timing more important than total page weight.

Delays also compound: a slow first paint usually points to slow server response, render-blocking CSS and JavaScript, or oversized above-the-fold media – problems that also down every later metric. Fixing FCP therefore improves LCP, reduces bounce, and raises the odds that users stay long enough to convert. See the web.dev First Contentful Paint guide for tuning targets and field-measurement guidance.

Coding problems and solutions

Common coding problems

  • Render-blocking scripts in the head: a synchronous <script> tag in <head> pauses HTML parsing, so nothing can be painted until the script downloads and executes.
  • Monolithic stylesheets: shipping one large CSS file blocks the first render even when only a few above-the-fold styles are needed right away.
  • Slow server response: high time-to-first-byte caused by missing caching, missing compression, or heavy server work delays the HTML that must arrive before any paint can happen.
  • Web fonts without font-display: the default font block period keeps text invisible for up to three seconds, so text that technically renders early still looks blank.
  • Unprioritized hero media: the largest above-the-fold image competes with low-priority assets, or is mistakenly marked loading="lazy", pushing the first meaningful pixels later.
  • Sync third-party tags: chat widgets, A/B testing scripts, and analytics snippets loaded synchronously before first paint add requests and execution time to the critical path.

How to fix it

Defer non-critical JavaScript

Scripts that are not needed for the initial paint should never block parsing. In a lab comparison, moving two marketing scripts from synchronous to deferred loading cut FCP from 3.4 s to 2.1 s on a throttled connection.

Correct example
<script src="/js/analytics.js" defer></script>
<script src="/js/carousel.js" defer></script>
<script type="module" src="/js/app.js"></script>
Incorrect example
<head>
  <script src="/js/analytics.js"></script>
  <script src="/js/carousel.js"></script>
</head>

Inline critical CSS and load the rest asynchronously

Deliver only the styles required for the first screen inside an inline <style> block, then load the remaining stylesheet without blocking rendering. A typical after-state shows FCP dropping from 2.8 s to 1.5 s because the browser can paint immediately.

Correct example
<style>
  .site-header { display: flex; gap: 16px; }
  .hero { min-height: 320px; background: #f4f6f8; padding: 48px 16px; }
</style>
<link rel="preload" href="/css/full.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="/css/full.css"></noscript>
Incorrect example
<head>
  <link rel="stylesheet" href="/css/reset.css">
  <link rel="stylesheet" href="/css/components.css">
  <link rel="stylesheet" href="/css/page.css">
</head>

Prioritize the hero image and lazy-load below-the-fold media

Give the first visible image high fetch priority and set explicit dimensions to avoid layout work. Moving fetchpriority="high" to the hero while adding loading="lazy" to the rest took FCP from 3.2 s to 1.7 s in a before/after lab run.

Correct example
<img src="/img/hero.avif" alt="Team collaborating around a laptop" width="1200" height="600" fetchpriority="high">
<img src="/img/testimonial.jpg" alt="Customer portrait" width="400" height="400" loading="lazy">
Incorrect example
<img src="/img/hero.avif" alt="Team collaborating around a laptop" loading="lazy">
<img src="/img/testimonial.jpg" alt="Customer portrait">

Render web fonts without blocking text paint

Enable font-display: swap so the browser paints a fallback face immediately and swaps in the brand font once it arrives, and preload the font file to shorten the swap. Observed FCP gain on a font-heavy page: 2.6 s before, 1.6 s after.

Correct example
<style>
  @font-face {
    font-family: "Inter";
    src: url("/fonts/inter.woff2") format("woff2");
    font-display: swap;
  }
</style>
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
Incorrect example
<style>
  @font-face {
    font-family: "Inter";
    src: url("/fonts/inter.woff2") format("woff2");
  }
</style>
<link rel="stylesheet" href="/css/fonts.css">

Add resource hints and move third-party tags off the critical path

Warm up external origins with preconnect and let non-essential vendors load asynchronously. Removing three synchronous third-party tags and adding hints moved FCP from 4.1 s to 1.9 s on a mid-range mobile device profile.

Correct example
<link rel="preconnect" href="https://cdn.shop.example" crossorigin>
<link rel="preload" as="image" href="/img/hero.avif" fetchpriority="high">
<script src="https://cdn.chat.example/widget.js" async></script>
Incorrect example
<head>
  <script src="https://cdn.chat.example/widget.js"></script>
  <script src="https://analytics.example/tag.js"></script>
  <script src="https://ab.example/experiment.js"></script>
</head>

Known Limitations

  • Paint Timing availability: if performance.getEntriesByType('paint') returns an empty list – common in unsupported or restricted contexts – the rule reports a skip reason instead of a pass or failure.
  • Top-level frame only: paint entries describe the main document, so content rendered inside cross-origin iframes or sandboxed frames is never measured.
  • Client-side rendered applications: for single-page apps, FCP may capture only the empty application shell while the real content is painted later by JavaScript.
  • Environment variance: the same page can produce different values depending on device class, CPU load, network conditions, and throttling, so lab runs are not directly comparable across machines.
  • Fixed thresholds: the 1800 ms and 3000 ms cut-offs are generic and are not adjusted for connection type, device capability, or page complexity.
  • Back-forward cache and repeat views: paint entries may be missing or reflect an earlier navigation, so restored pages can skip evaluation entirely.

Resources

  • First Contentful Paint: Google’s tuning guide covering field targets, lab measurement, and optimization techniques at web.dev.
  • Largest Contentful Paint: how early paint timing feeds the largest visual element metric, explained on web.dev.
  • Paint Timing API: browser interface documentation for the paint entries the rule reads on MDN.
  • Paint Timing specification: the normative definition of first-contentful-paint entry semantics from the W3C.
  • Performance panel: recording and inspecting paint timing traces in Chrome DevTools via Chrome for Developers.

Rule

  • Audit: performance
  • Standard: SiteLint
  • Level: Best practices
  • Success Criteria: N/A
  • Rule ID: first-contentful-paint