How to Configure Strict Document Policy for Unsized Media in Google Chrome

Cumulative Layout Shift (CLS) is one of Google Core Web Vitals’ most critical user experience metrics. Layout instability occurs most frequently when images, videos, and embedded canvases load without explicit width and height attributes, causing surrounding text and buttons to jump abruptly as resources render. While traditional CSS rules can enforce dimensions, developer oversights often reintroduce unsized media into production. Document Policy provides an HTTP-level enforcement mechanism that instructs Google Chrome to block or pad unsized media elements before layout calculations occur.

Understanding Document Policy vs Permissions Policy

While Permissions Policy controls access to hardware and device APIs (such as geolocation or microphone access), Document Policy configures structural rendering constraints and performance rules for the active document:

• unsized-media: Directs Chrome’s layout engine to require explicit dimensions or aspect ratios on all visual media (<img>, <video>, <canvas>).
• report-only mode: Allows engineering teams to measure compliance across production pages and collect JSON violation telemetry without breaking layout rendering for end users.
• Default Sizing Fallback: When strict enforcement is active, Chrome assigns a default 300×150 pixel box placeholder to unsized elements rather than allowing zero-height reflow shifts.

Configuring Document Policy Headers on Your Web Server

Configure your web server to deliver the Document-Policy header across all HTML documents:

# Nginx server configuration
add_header Document-Policy "unsized-media=?0" always;

# Apache HTTP Server (.htaccess / virtual host)
Header always set Document-Policy "unsized-media=?0"

Setting unsized-media=?0 instructs Google Chrome to disallow any media element that lacks explicit HTML attributes or CSS aspect ratios.

Authoring Resilient Media Markup

To comply with strict Document Policy rules, always specify both width and height attributes on media tags, pairing them with modern responsive CSS:

<!-- Fully compliant responsive image markup -->
<img src="hero-banner.webp" 
     width="1200" 
     height="630" 
     alt="Technical Architecture Guide" 
     loading="lazy" 
     decoding="async" 
     class="responsive-hero">

<style>
.responsive-hero {
    width: 100%;
    height: auto;
    aspect-ratio: 1200 / 630;
    display: block;
}
</style>

Auditing Document Policy Violations in Chrome DevTools

To inspect and troubleshoot Document Policy violations in Google Chrome:

1. Open Google Chrome and navigate to your application.
2. Open DevTools by pressing Ctrl + Shift + I (or Option + Command + I on macOS).
3. Switch to the Issues tab. Chrome highlights elements that trigger Document Policy violations, identifying the exact DOM node lacking dimension attributes.
4. Open the Console tab to view runtime enforcement warnings:

   [Document Policy] Unsized media violation: An <img> element was loaded without intrinsic or CSS size constraints.

5. Inspect the Performance tab and record a page reload. Verify that Cumulative Layout Shift remains safely below the 0.1 threshold.