Page title

# The Website Specification > A platform-agnostic, full specification of the technical features a good website should have. Built in the open under an MIT licence. Source: https://specification.website · Repository: https://github.com/jdevalk/specification.website · Content licence: CC BY 4.0 --- # Foundations The HTML, head, and document basics every page needs. ## The HTML doctype Status: required · Source page: https://specification.website/spec/foundations/doctype/ Every HTML document must start with as its first line. This opts the browser into standards mode; without it, you get quirks mode and broken layout. ## What it is The doctype is a short declaration at the very top of an HTML document that tells the browser which rendering mode to use. In modern HTML, there is exactly one correct form: ```html ``` It is case-insensitive, so `` is equally valid. It must be the first thing in the document, before ``, with no whitespace, comments, or byte-order mark trickery in front of it. ## Why it matters Without a doctype, browsers fall back to **quirks mode** — a compatibility layer that emulates the buggy behaviour of browsers from the late 1990s. In quirks mode: - The CSS box model changes (widths include padding and border, like the old IE5 model). - Inline elements behave differently around whitespace. - Many modern CSS features are unreliable or disabled. - Table cell heights, image alignment, and font sizing all shift. With `` you get **standards mode**, where the browser follows current specifications. There is also a "limited-quirks" (almost-standards) mode triggered by some legacy doctypes, but you should never need it. In short: one missing line at the top of the document silently changes how every CSS rule on the page is interpreted. It is the cheapest correctness fix on the web. ## How to implement Put the doctype on line one of every HTML response. No XML prolog, no comment, no blank line: ```html Page title ... ``` The old HTML 4 and XHTML doctypes (`HTML 4.01 Transitional`, `XHTML 1.0 Strict`, etc.) are obsolete. Replace them with ``. The short form is part of the HTML Living Standard and works in every browser back to IE6. For XML-serialised HTML (XHTML served as `application/xhtml+xml`), the doctype is optional, but the document must still parse as XML. Almost no public sites need this — serve HTML. ## Common mistakes - A blank line, comment, or BOM before ``. Anything before the doctype can trigger quirks mode. - Using a legacy HTML 4 or XHTML doctype copied from a 2005 tutorial. - Sending the doctype only on some pages — error pages, print views, and embedded iframes need it too. - Letting a templating engine strip it during minification. ## Verification - View source on the page. The very first bytes must be ``. - In DevTools, run `document.compatMode` in the console. It should return `"CSS1Compat"` (standards mode), not `"BackCompat"` (quirks). - Check error pages (404, 500), redirect destinations, and any HTML fragments returned by APIs. ### Sources - HTML Living Standard — The DOCTYPE (WHATWG) — https://html.spec.whatwg.org/multipage/syntax.html#the-doctype - MDN — Doctype (MDN) — https://developer.mozilla.org/en-US/docs/Glossary/Doctype - MDN — Quirks Mode and Standards Mode (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode --- ## The lang attribute on Status: required · Source page: https://specification.website/spec/foundations/html-lang/ Set a valid BCP 47 language tag on the element so screen readers, translators, search engines, and browsers know what language the page is in. ## What it is Every HTML document should declare its primary language on the root element using the `lang` attribute: ```html ``` The value is a **BCP 47 language tag** — a short, standardised string that identifies a language and, optionally, a region or script. Examples: `en`, `en-GB`, `nl`, `pt-BR`, `zh-Hant`, `de-AT`. ## Why it matters The language of the page is metadata that many systems rely on: - **Screen readers** switch pronunciation engines based on `lang`. Without it, VoiceOver and NVDA read English text with a Dutch accent, or vice versa, making content unintelligible. - **Browsers** offer translation prompts ("Translate this page from French?") only when they know the source language. - **Search engines** use it as one signal for which audience to show the page to. - **Spell checkers** in `

` and `contenteditable` fields use the document language as their default.
- **CSS** can match `:lang(en-GB)` to apply locale-specific typography (quotation marks, hyphenation).
- **WCAG 3.1.1 Level A** requires the human language of every page to be programmatically determinable.

A missing `lang` is one of the most common accessibility failures, and one of the easiest to fix.

## How to implement

Use a valid BCP 47 tag. The simplest form is just the two-letter ISO 639-1 language code:

```html
<html lang="en">
<html lang="fr">
<html lang="ja">
```

Add a region only when it changes meaning — currency, spelling, or pronunciation:

```html
<html lang="en-GB">   
<html lang="en-US">   
<html lang="pt-BR">   
<html lang="zh-Hant"> 
```

For sections of a page in a different language, use `lang` on a child element:

```html
<p>The French call it <span lang="fr">pamplemousse</span>.</p>
```

For right-to-left scripts (Arabic, Hebrew), pair `lang` with `dir`:

```html
<html lang="ar" dir="rtl">
```

## Common mistakes

- Omitting the attribute entirely. Many CMS templates ship without it.
- Using made-up codes like `lang="english"` or `lang="us"`. Only BCP 47 tags are valid.
- Setting `lang="en"` on a Dutch site because the template was copied from an English boilerplate.
- Over-specifying the region (`lang="en-US"` on a generic global English site is fine but rarely needed).
- Forgetting to update `lang` on translated pages — every locale needs its own value.

## Verification

- View source: confirm `<html lang="...">` is present and matches the actual content language.
- Run `document.documentElement.lang` in DevTools.
- Use an accessibility checker (axe, Lighthouse). Both flag missing or invalid `lang`.
- Listen to the page with a screen reader and confirm pronunciation matches the language.

### Sources
- HTML Living Standard — The lang and xml:lang attributes (WHATWG) — https://html.spec.whatwg.org/multipage/dom.html#the-lang-and-xml:lang-attributes
- MDN — HTML lang global attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang
- BCP 47 — Tags for Identifying Languages (IETF) — https://www.rfc-editor.org/info/bcp47
- WCAG 3.1.1 — Language of Page (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html

---

## <meta charset>

Status: required  ·  Source page: https://specification.website/spec/foundations/meta-charset/

Declare UTF-8 as the document character encoding in the first 1024 bytes of the HTML, so browsers parse text correctly before they hit any non-ASCII content.

## What it is

`<meta charset>` tells the browser how to decode the bytes of the HTML document into characters. In 2026 there is only one correct value:

```html
<meta charset="utf-8" />
```

It must appear inside `<head>`, and the entire `<meta>` element must fit within the **first 1024 bytes** of the response. Browsers stop sniffing after that point; anything declared later is ignored.

## Why it matters

Before the browser can parse a single character of your page, it has to decide which encoding to apply to the byte stream. Without an explicit declaration, it guesses — based on the `Content-Type` HTTP header, a byte-order mark, or heuristics over the first chunk of bytes. Guessing goes wrong:

- A page with a curly apostrophe (`'`) shows mojibake (`â€™`) when the browser picks Windows-1252.
- Form submissions get encoded in the wrong charset, corrupting non-ASCII input.
- Right-to-left text reorders incorrectly.
- Search engines index garbled strings.

**UTF-8 is the only encoding you should use.** It is a superset of ASCII, supports every script (Latin, Cyrillic, Arabic, Chinese, emoji), is the default for JSON and XML, and is what every modern build tool produces. Legacy encodings (`iso-8859-1`, `windows-1252`, `shift_jis`) exist only as compatibility for old documents — do not create new content in them.

## How to implement

Put the charset declaration as the very first child of `<head>`, before `<title>` or any other tag that could contain non-ASCII text:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>The Website Specification</title>
    ...
  </head>
</html>
```

Save the file itself as UTF-8 (most editors do this by default). The declaration in the HTML and the actual bytes on disk must match.

Also set the HTTP `Content-Type` header on the response. The header takes precedence over the meta tag, so if they conflict, the header wins:

```http
Content-Type: text/html; charset=utf-8
```

If both agree on UTF-8, you are covered for every loader: browsers, scrapers, RSS readers, and crawlers that read the bytes directly.

The older XHTML form `<meta http-equiv="Content-Type" content="text/html; charset=utf-8">` still works but is verbose and unnecessary. Use the short form.

## Common mistakes

- Declaring the charset after `<title>` so a non-ASCII character in the title is parsed wrongly before the meta tag is reached.
- Saving the file as Windows-1252 or Latin-1 while declaring `utf-8`.
- Adding a byte-order mark to a UTF-8 file. It is allowed but can break server-side includes and PHP headers.
- Different charsets in the HTTP header and the meta tag.
- Using `utf8` without the hyphen — browsers accept it, but `utf-8` is the canonical spelling.

## Verification

- View source. `<meta charset="utf-8" />` should be the first or second line inside `<head>`.
- Run `document.characterSet` in DevTools. It must return `"UTF-8"`.
- Check the `Content-Type` response header in the Network tab.
- Add a non-ASCII test string (`café — 日本語 — 🌍`) to a page and confirm it renders correctly.

### Sources
- HTML Living Standard — Specifying the document's character encoding (WHATWG) — https://html.spec.whatwg.org/multipage/semantics.html#charset
- MDN — <meta>: charset (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#charset
- WHATWG Encoding Standard (WHATWG) — https://encoding.spec.whatwg.org/

---

## <meta viewport>

Status: required  ·  Source page: https://specification.website/spec/foundations/meta-viewport/

Tell mobile browsers to render the page at the device's actual width instead of pretending to be a 980-pixel desktop. One line, and never disable user scaling.

## What it is

The viewport meta tag controls how mobile browsers size and scale the page. The correct value for almost every website is:

```html
<meta name="viewport" content="width=device-width, initial-scale=1" />
```

It belongs in `<head>`, alongside the charset and title.

## Why it matters

When mobile browsers first appeared, almost every website on the web was designed for desktop. To avoid showing tiny squashed columns, Safari on iPhone decided to render pages as if the screen were 980 CSS pixels wide and zoom out to fit. That behaviour persists today: without a viewport meta tag, your responsive site is rendered at 980 pixels, then scaled down. The result on a phone is a postage-stamp version of the desktop layout, with text too small to read and tap targets the user has to pinch-zoom to hit.

Setting `width=device-width` tells the browser: "Use the device's actual width as the viewport." `initial-scale=1` sets the initial zoom level to 1:1, so CSS pixels match the browser's idea of a pixel. Together they make responsive CSS (`@media (max-width: 600px)`) work as designed.

This single line is the difference between a site that works on mobile and one that does not. Google has used "mobile-friendliness" as a ranking signal since 2015, and Search uses the mobile version of pages for indexing.

## How to implement

The standard, correct value:

```html
<meta name="viewport" content="width=device-width, initial-scale=1" />
```

That is it. Do not add anything else unless you have a specific reason.

You may occasionally see additional keys:

- `viewport-fit=cover` — required for iOS Safari to draw into the safe-area insets (the notch). Add it only if you handle the insets in CSS with `env(safe-area-inset-*)`.
- `interactive-widget=resizes-content` — controls how the on-screen keyboard interacts with the viewport.

What you must **never** do is disable user zooming:

```html

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
```

`user-scalable=no` and `maximum-scale=1` prevent users from pinch-zooming. For anyone with low vision who needs to magnify text — and that is a significant fraction of users — this turns a usable page into an unusable one. It also fails WCAG 1.4.4. There is no good reason to disable zoom on a content site.

## Common mistakes

- Omitting the tag and assuming the site is "responsive enough" — mobile browsers will still render at 980 pixels.
- Copying old snippets that include `user-scalable=no`. Remove it.
- Setting `width=1024` or a fixed pixel value to force a layout. Build a responsive layout instead.
- Using `initial-scale=1.0` (with the trailing zero) — harmless, but `1` is canonical.
- Adding the tag only to some templates. Every HTML page needs it.

## Verification

- View source: confirm the tag is present and contains `width=device-width, initial-scale=1`.
- Open Chrome DevTools, toggle device emulation, and check the layout is not 980 pixels wide and scaled down.
- Try pinch-to-zoom on a real phone. If it does not zoom, you have a `user-scalable=no` somewhere.
- Run Lighthouse — it flags both missing viewport tags and ones that disable zooming.

### Sources
- MDN — Viewport meta tag (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag
- CSS Device Adaptation Module — viewport meta (W3C) — https://drafts.csswg.org/css-device-adapt/#viewport-meta
- WCAG 1.4.4 — Resize Text (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html

---

## The <title> element

Status: required  ·  Source page: https://specification.website/spec/foundations/title/

Every HTML document must have exactly one non-empty <title> element inside <head>. It is used by browsers, search engines, screen readers, social previews, and AI agents.

## What it is

The `<title>` element is a required child of `<head>` that names the document. It is the only HTML element with no markup inside it — only text. There must be exactly one per page.

```html
<title>Setting up CSP · The Website Specification</title>
```

## Why it matters

- **Browsers** show the title in the tab, the window, the bookmark, and the history entry.
- **Search engines** use it as the default link text in results (Google may rewrite it, but a good `<title>` is rewritten less).
- **Screen readers** announce the title when the page loads, so it is the first thing a non-sighted user hears.
- **Social platforms** fall back to it when no `<meta property="og:title">` is set.
- **AI agents** use it as the canonical short description of the page.

Missing or empty titles are a WCAG 2.4.2 Level A failure — the lowest accessibility bar there is.

## How to implement

Write the title for the page, not for the site:

- **Page-specific first, site name second**, separated by a delimiter such as `·`, `—`, or `|`.
- **Front-load the unique part.** Truncation in search results and tabs hides the end of the string.
- **50–60 characters** is a reasonable target. Google typically displays around 600 pixels of width.
- **One per page, unique per page.** Two pages with the same title is a quality signal that they are duplicates.
- **No keyword stuffing.** Write what the page is about.

The order matters when the tab is narrow:

```html

<title>HSTS · Security · The Website Specification</title>

<title>The Website Specification — Security — HSTS</title>
```

For the homepage, the site name on its own is fine:

```html
<title>The Website Specification</title>
```

## Common mistakes

- Empty `<title></title>`. Browsers show the URL; screen readers announce nothing useful.
- Identical titles across many pages (often the site name only).
- Titles set in JavaScript after first paint — search crawlers and social scrapers may not run JS.
- Putting the title in `<body>` instead of `<head>`.

## Verification

- View source. `<title>` must be inside `<head>` and contain non-whitespace text.
- Open the page in a narrow tab. Check the unique part is visible.
- Run [`curl -s https://example.com | grep -i '<title'`](https://curl.se) and confirm it is set without JavaScript.
- Test with a screen reader (VoiceOver, NVDA). It should announce the title on load.

### Sources
- HTML Living Standard — The title element (WHATWG) — https://html.spec.whatwg.org/multipage/semantics.html#the-title-element
- MDN — <title>: The Document Title element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
- WCAG 2.4.2 — Page Titled (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html
- Google — Influencing your title links in search results (Google Search Central) — https://developers.google.com/search/docs/appearance/title-link

---

## <meta name="description">

Status: recommended  ·  Source page: https://specification.website/spec/foundations/meta-description/

A short, unique summary of the page used by search engines and social platforms as a snippet. Google may rewrite it, but a good one is rewritten less often.

## What it is

A meta description is a short summary of the page, declared in `<head>`:

```html
<meta name="description" content="The Website Specification is a platform-agnostic spec of what a good website must do, from doctype to security headers." />
```

The browser does not render it. It is metadata for crawlers, social platforms, and AI agents that fetch the page.

## Why it matters

The meta description does not directly affect search ranking, but it strongly affects whether the user clicks. Search engines often use it as the snippet shown beneath the title in results:

- A good description that matches the user's query gives them a reason to click.
- A missing description forces the engine to invent one from the page body, which is often less compelling.
- Google rewrites the description for about 70% of results, but matches the source more often when it is high quality.

Social platforms (Slack, Discord, iMessage, LinkedIn) use it as the preview text when no Open Graph description is set. AI agents and answer engines use it as a short canonical summary.

A description that is missing, duplicated across pages, or stuffed with keywords is a wasted asset on every result and every share.

## How to implement

Write one description per page, specific to that page:

- **120–160 characters** is the sweet spot. Google typically truncates around 920 pixels on desktop, roughly 155–160 characters.
- **Front-load the unique value.** Truncation eats the end.
- **Describe what the page is about, not the site.** A reader skimming SERPs should be able to predict what they will find.
- **Plain language.** No keyword lists, no marketing slogans, no all-caps.
- **One per page.** Two pages with the same description is a duplicate-content signal.

```html

<meta name="description" content="The lang attribute on <html> tells screen readers, browsers, and search engines what language the page is written in. Use a valid BCP 47 tag." />

<meta name="description" content="Welcome to our website. We are the best in the industry, providing world-class solutions for all your needs. Contact us today to learn more about what we do and how we can help your business grow in 2026." />
```

For the homepage, summarise the site as a whole. For article pages, summarise the article. For category or archive pages, describe what is in the category. Do not leave the description empty and do not auto-generate it from the first 160 characters of the body — that almost always picks up navigation or boilerplate.

If the page also sets `<meta property="og:description">`, write each separately. Social platforms prefer the OG version; search engines prefer the plain meta description. They can be similar but rarely identical, because the audience and the truncation length differ.

## Common mistakes

- Reusing the same description on every page (often pulled from a site-wide template field).
- Stuffing keywords: "cheap shoes, buy shoes, shoes online, shoe shop". Search engines ignore this and users distrust it.
- Including the page title verbatim. The snippet shows both — repeating wastes space.
- Going to 300+ characters. Anything past the truncation line is invisible.
- Ending mid-sentence because the CMS truncates blindly. Write to fit.

## Verification

- View source. `<meta name="description" content="...">` must be in `<head>` and non-empty.
- Run `document.querySelector('meta[name="description"]').content` in DevTools.
- Crawl the site and check for duplicate descriptions. Any duplication is worth fixing.
- Use a SERP preview tool to see how the snippet looks at the truncation length.

### Sources
- MDN — <meta>: the metadata element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
- Google — Create good meta descriptions (Google Search Central) — https://developers.google.com/search/docs/appearance/snippet
- HTML Living Standard — Standard metadata names (WHATWG) — https://html.spec.whatwg.org/multipage/semantics.html#standard-metadata-names

---

## Canonical URL (rel="canonical")

Status: recommended  ·  Source page: https://specification.website/spec/foundations/canonical-url/

Declare the preferred URL for a page so search engines and crawlers consolidate ranking signals on one address, even when several URLs serve the same content.

## What it is

The canonical link tells crawlers which URL is the authoritative version of a page when the same content is reachable through several addresses:

```html
<link rel="canonical" href="https://example.com/articles/lang-attribute" />
```

It belongs in `<head>` and was standardised in [RFC 6596](https://www.rfc-editor.org/rfc/rfc6596). All major search engines honour it.

## Why it matters

The same content often lives at multiple URLs without anyone meaning it to:

- `https://example.com/page` and `https://www.example.com/page`
- `http://` and `https://` versions of the same path
- `/page` and `/page/` (with and without trailing slash)
- `/page?utm_source=newsletter` and `/page` (tracking parameters)
- `/page?sort=date` and `/page?sort=name` (filter and sort variants)
- Paginated archives, printer-friendly views, AMP versions

Without a canonical, crawlers may index every variant separately, splitting ranking signals and backlinks across duplicates. With a canonical, those signals consolidate on one URL. The result is a stronger ranking for the page you actually want to rank, and a cleaner index.

A canonical is a **strong hint**, not an absolute directive. Search engines can override it if other signals (sitemaps, redirects, internal links) point elsewhere. Make all your signals agree.

## How to implement

Put a **self-referencing canonical** on every public HTML page. Even pages without duplicates benefit: it removes ambiguity for query-string variants and short-circuits any scraper that copies the page.

```html
<link rel="canonical" href="https://example.com/articles/lang-attribute" />
```

Rules:

- **Use absolute URLs.** Include the scheme (`https://`) and host. Relative canonicals are allowed by the spec but more error-prone; absolute is the safer default.
- **Match the scheme you actually serve.** If the site is HTTPS everywhere, canonicals must say `https://`.
- **Pick one host and stick to it.** Either `example.com` or `www.example.com`, never both. Redirect the other.
- **Be consistent about trailing slashes.** If `/articles/` and `/articles` resolve to the same content, pick one and canonicalise to it. Mixed is the worst case.
- **Strip tracking parameters** from the canonical. The canonical of `/page?utm_source=newsletter` is `/page`.
- **Avoid loops.** Page A canonical to B, B canonical to A is a contradiction.
- **One per page.** Multiple canonicals are ignored.

Cross-domain canonicals are valid when content is syndicated. If you republish an article on a partner site, the partner can canonical back to your original:

```html

<link rel="canonical" href="https://yoursite.example/articles/the-original" />
```

For pages that exist in multiple languages, use `hreflang` in addition to `canonical`. Each language version is its own canonical; `hreflang` ties them together.

The canonical can also be sent as an HTTP header, which is useful for non-HTML resources like PDFs:

```http
Link: <https://example.com/whitepaper.pdf>; rel="canonical"
```

## Common mistakes

- Pointing every page's canonical at the homepage. This tells crawlers your inner pages are duplicates of the homepage and de-indexes them.
- Canonicalising paginated archives (`?page=2`) to page 1. Each pagination page is distinct content; let them index normally.
- Setting a canonical on `https://` that points to `http://`, or vice versa.
- Forgetting to update the canonical when the site moves domain.
- Generating canonicals from `window.location` in client-side JS only. Crawlers may not run JS; render server-side.

## Verification

- View source on a few pages with query parameters. The canonical should ignore the parameters and point to the clean URL.
- Run `document.querySelector('link[rel=canonical]').href` in DevTools.
- Crawl the site and list canonical targets. Every target should return 200 OK, not a redirect.
- In Google Search Console, the "URL Inspection" tool shows the user-declared canonical and the Google-selected canonical. When they differ, something else is overriding your hint.

### Sources
- RFC 6596 — The Canonical Link Relation (IETF) — https://www.rfc-editor.org/rfc/rfc6596
- MDN — rel=canonical (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/canonical
- Google — Consolidate duplicate URLs with canonicals (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls
- HTML Living Standard — Link types: canonical (WHATWG) — https://html.spec.whatwg.org/multipage/links.html#link-type-canonical

---

## Favicons and app icons

Status: recommended  ·  Source page: https://specification.website/spec/foundations/favicons/

Ship an SVG favicon, an ICO fallback at /favicon.ico, an apple-touch-icon, and a maskable PWA icon. Five files cover every browser and home-screen surface.

## What it is

A favicon is the small icon that represents your site in browser tabs, bookmarks, history, home-screen shortcuts, and OS task switchers. Modern sites need a small set of icons in different formats to cover every surface that displays them.

```html
<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
<link rel="icon" href="/favicon.ico" sizes="32x32" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />
```

## Why it matters

The favicon is one of the most visible pieces of branding on the web. Tab strips, bookmark bars, and history menus are full of them, and a missing or broken icon looks unfinished. It also affects:

- **Recognition** — users scan tab strips visually, not by reading title text.
- **Home-screen installs** — when a user adds your site to their phone, the icon is what they see every day.
- **Search results** — Google shows a favicon next to mobile search results.
- **OS surfaces** — pinned tabs, recent apps, share sheets, and notification icons all pull from the icon set.

A single 16×16 ICO from 2008 still works, but looks terrible on a high-DPI screen, and is wrong on a phone home screen.

## How to implement

Aim for five files. They cover every browser, every platform, and every density:

1. **`/favicon.svg`** — the modern default. One vector file, infinitely scalable, supports light- and dark-mode variants via CSS inside the SVG. Most browsers since 2021 prefer it.
2. **`/favicon.ico`** — a multi-resolution ICO containing 16×16, 32×32, and 48×48 PNGs. Older browsers and crawlers expect this at the root path.
3. **`/apple-touch-icon.png`** — 180×180 PNG used by iOS when the user adds the site to their home screen. iOS does not honour the SVG favicon for home screens.
4. **`/icon-192.png` and `/icon-512.png`** — referenced from the web app manifest, used by Android and PWA installs.
5. **A maskable variant** — a 512×512 PNG with the important content inside an 80% safe zone, so platforms can crop it to round, squircle, or other masks without clipping your logo.

Wire them up in the head:

And declare the maskable icons in the manifest:

```json
{
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}
```

Even with explicit `<link rel="icon">` tags, browsers and crawlers still request `/favicon.ico` from the site root. Always serve a real ICO at that path. A 404 there shows up in every server log forever.

Design the icon to read at 16×16. Logos with thin text or fine detail disappear; bold marks survive. Test in both light and dark browser themes.

## Common mistakes

- Only shipping a 16×16 PNG. Looks blurry on every modern screen.
- No `/favicon.ico` at the root, so crawlers and old browsers 404 endlessly.
- An apple-touch-icon with transparency. iOS used to add its own rounded background; modern iOS does not, and transparent gaps look broken.
- A maskable icon with the logo at the very edge. The platform crops it; design for an 80% safe zone.
- Forgetting to update the icon when rebranding. Stale icons cached by browsers persist for months.

## Verification

- Open the site in a browser. The tab should show a sharp icon, not a blank page.
- Visit `https://yoursite.example/favicon.ico` directly — it should return 200.
- On iOS Safari, use "Add to Home Screen" and check the icon is crisp and well-cropped.
- On Android Chrome, install the PWA and confirm the launcher icon uses the maskable variant.
- Check server logs for `/favicon.ico` 404s.

### Sources
- MDN — Link types: icon (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/icon
- HTML Living Standard — Link type: icon (WHATWG) — https://html.spec.whatwg.org/multipage/links.html#rel-icon
- W3C — Web App Manifest, maskable icons (W3C) — https://www.w3.org/TR/appmanifest/#icons-member

---

## <meta name="theme-color">

Status: recommended  ·  Source page: https://specification.website/spec/foundations/theme-color/

Tints the browser chrome and OS surfaces to match your brand. Use the media attribute to ship one colour for light mode and another for dark mode.

## What it is

`theme-color` suggests a colour for the browser or OS to use when rendering surfaces around the page — the address bar on mobile, the title bar of an installed PWA, the task switcher card, and notification accents.

```html
<meta name="theme-color" content="#0b1020" />
```

The value is any valid CSS colour: hex, `rgb()`, `hsl()`, or a named colour.

## Why it matters

Mobile browsers render a thin strip above the page — the URL bar in Safari and Chrome on iOS and Android. By default it is grey or white. With `theme-color`, that strip can match your brand, so the page and the chrome around it look like one continuous surface.

The same value is used by:

- **iOS Safari** to tint the status bar area when scrolled.
- **Chrome on Android** for the address bar and the task switcher card.
- **PWAs and installed web apps** for the system title bar.
- **macOS Safari 15+** to tint the tab bar of the focused tab.

A page without `theme-color` is not broken, but the visual seam between page content and browser chrome is more obvious. With it, the page feels polished and "native-ish" on mobile.

## How to implement

Set one value for light mode and one for dark mode using the `media` attribute:

```html
<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)" />
<meta name="theme-color" content="#0b1020" media="(prefers-color-scheme: dark)" />
```

Browsers pick the value whose `media` query matches the user's current colour scheme. If only one tag is present, it is used in every mode — fine for sites with a single fixed palette.

Pick colours that match the **edges** of your page, not the centre. The strip sits flush against your `<body>` background; if your header is dark and the rest of the page is light, the theme colour should match the header.

For an installed PWA, the manifest's `theme_color` and `background_color` are used at launch. Set both for a smooth splash:

```json
{
  "name": "The Website Specification",
  "theme_color": "#0b1020",
  "background_color": "#0b1020"
}
```

The manifest value is used once at install/launch time; the meta tag is consulted on every page load. They can differ if you want a different colour during the splash than during normal browsing, but matching them avoids a visible jump.

If your site updates colour scheme based on user choice (a theme switcher independent of OS), update the meta tag dynamically:

```js
document.querySelector('meta[name="theme-color"]').setAttribute('content', '#0b1020');
```

Some browsers re-read the tag on change; others cache it per navigation. Either way, server-rendering the correct initial value is the most reliable approach.

## Common mistakes

- A theme colour with low contrast against the address-bar text. Safari and Chrome render the URL in dark or light text based on the luminance of `theme-color`; an unreadable URL is a real bug.
- Setting only the dark-mode value, so light-mode users see the default grey.
- Forgetting to update the value when redesigning. The address bar starts looking off-brand months before anyone notices.
- Animating it on scroll. It is metadata, not a paint surface — leave it static.
- Putting hex values with alpha (`#0b1020aa`). Browsers ignore the alpha channel; use an opaque colour.

## Verification

- Open the site on iOS Safari or Chrome on Android. The address bar should be tinted to match your site.
- Toggle the OS between light and dark mode. The strip should change.
- Install the site as a PWA and check the title bar and splash screen colours.
- In DevTools, run `document.querySelector('meta[name="theme-color"]').content` and confirm the value.

### Sources
- MDN — <meta name="theme-color"> (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color
- HTML Living Standard — Other metadata names: theme-color (WHATWG) — https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color
- W3C — Web App Manifest, theme_color (W3C) — https://www.w3.org/TR/appmanifest/#theme_color-member

---

## <meta name="color-scheme">

Status: recommended  ·  Source page: https://specification.website/spec/foundations/color-scheme/

Tells the browser which colour schemes your page is designed for. Prevents the white flash that dark-mode users see before your CSS loads, and lets the browser style scrollbars, form controls, and the page background to match.

## What it is

`color-scheme` declares which colour schemes your page is designed for — light, dark, or both. The browser uses that information to pick sensible defaults for things you didn't style yourself: the canvas background it paints before your CSS loads, scrollbars, native form controls, and the white-space around `<input>` and `<textarea>` elements.

There are two places to set it. The HTML meta tag sets the document-level default:

```html
<meta name="color-scheme" content="light dark" />
```

The CSS property sets it on any element (and is the only form that participates in the cascade):

```css
:root { color-scheme: light dark; }
```

Ship both. The meta tag takes effect before any stylesheet parses, so it prevents the white flash dark-mode users would otherwise see during page load. The CSS property is the authoritative source once styles arrive, and lets you scope schemes to subtrees if you ever need to.

**This site ships it.** [`HeadMeta.astro`](https://github.com/jdevalk/specification.website/blob/main/src/components/HeadMeta.astro) emits `<meta name="color-scheme" content="light dark">` plus a matched pair of `theme-color` tags with `media="(prefers-color-scheme: ...)"`, and [`global.css`](https://github.com/jdevalk/specification.website/blob/main/src/styles/global.css) flips the `--color-ink-*` token scale inside `@media (prefers-color-scheme: dark)` so every utility that references those tokens — backgrounds, borders, body text, code blocks — switches with the user's OS preference. Accent green is held constant and lifted for text contrast on dark surfaces.

## Why it matters

Without `color-scheme`, the browser assumes the page is light-only. A dark-mode user opening your site sees a blink of white background before your CSS paints — even if your stylesheet is perfectly dark-mode-ready. Native form controls, date pickers, and scrollbars also stay in their light defaults until you restyle every one by hand.

With `color-scheme: light dark` (or just `dark` if your site is dark-only), the browser:

- paints the initial canvas in a colour matching the user's preference;
- renders `<input type="date">`, `<select>`, file pickers, and other form controls in the right scheme;
- gives scrollbars the right contrast against your background;
- treats `currentColor` defaults sensibly for things you forgot to style.

It is distinct from [`<meta name="theme-color">`](/spec/foundations/theme-color/). `theme-color` paints the **browser chrome around** the page (address bar, task switcher, PWA title bar). `color-scheme` styles the **page surface itself** and its native controls. Both should ship; neither replaces the other.

## How to implement

The valid values for the `content` attribute are `normal`, `light`, `dark`, `light dark`, `dark light`, and `only light`. List the preferred scheme first; the others are acceptable fallbacks. `only dark` is explicitly not allowed by the HTML spec — there is no way to forbid light mode, because forcing a page into dark mode the page wasn't built for produces unreadable contrast.

```html
<head>
  <meta name="color-scheme" content="light dark" />
  <link rel="stylesheet" href="/styles.css" />
</head>
```

```css
:root {
  color-scheme: light dark;
  --bg: light-dark(#ffffff, #0b1020);
  --fg: light-dark(#0b1020, #ffffff);
}

body { background: var(--bg); color: var(--fg); }
```

CSS's `light-dark()` function reads the *used* colour scheme from `color-scheme` and picks the matching value. It replaces most cases where you would have reached for `@media (prefers-color-scheme: dark)`.

If your site has a theme switcher independent of the OS preference, update both the meta tag and the root CSS dynamically — or use a CSS custom property for the scheme and toggle it.

## Common mistakes

- Setting `<meta name="theme-color">` for dark mode but forgetting `color-scheme`. The browser chrome is dark; the page underneath still flashes white on load.
- Using `only dark` — invalid; pick `dark` and accept the light fallback.
- Setting `color-scheme: dark` on a site that has not been audited in dark mode. Form controls and scrollbars will recolour and you will discover broken contrast in production.
- Forgetting `light dark` order matters. The first value is the *preferred* scheme when the user has no preference set.

## Verification

- `curl -s https://example.com/ | grep -i 'name="color-scheme"'` returns the meta tag.
- In Chrome DevTools → Rendering, toggle "Emulate CSS prefers-color-scheme: dark" and reload. The page background should switch immediately, with no white flash.
- View a page with a native form control (`<input type="date">`) in both schemes — the picker UI itself should match.
- Run `getComputedStyle(document.documentElement).colorScheme` in the console — it should return the value you set, not `normal`.

### Sources
- HTML Living Standard — Standard metadata names: color-scheme (WHATWG) — https://html.spec.whatwg.org/multipage/semantics.html#meta-color-scheme
- CSS Color Adjustment Module Level 1 — the color-scheme property (W3C) — https://www.w3.org/TR/css-color-adjust-1/#color-scheme-prop
- MDN — <meta name="color-scheme"> (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/color-scheme
- web.dev — Improve dark mode default with color-scheme (web.dev) — https://web.dev/articles/color-scheme

---

## Open Graph protocol

Status: recommended  ·  Source page: https://specification.website/spec/foundations/open-graph/

Open Graph tags control how pages look when shared on social platforms and chat apps. Set og:title, og:description, og:image, og:url, and og:type on every page.

## What it is

Open Graph (OG) is a set of `<meta>` tags, originally introduced by Facebook in 2010 and now supported by virtually every social platform, chat app, and link-preview tool. They tell the platform how to display your page when someone pastes the URL.

```html
<meta property="og:title" content="The lang attribute on <html>" />
<meta property="og:description" content="Set a valid BCP 47 language tag on <html> so screen readers, translators, and search engines know what language the page is in." />
<meta property="og:image" content="https://example.com/og/html-lang.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="675" />
<meta property="og:url" content="https://example.com/foundations/html-lang" />
<meta property="og:type" content="article" />
```

Note `property=` (not `name=`) — Open Graph predates the standard `meta name` registry and uses the RDFa attribute.

## Why it matters

When a link is pasted into Slack, Discord, iMessage, WhatsApp, LinkedIn, Mastodon, Bluesky, or X, the platform fetches the page and reads the OG tags to build a preview card. Without them, the platform falls back to whatever it can scrape — sometimes the `<title>` and meta description, sometimes the first image it can find, sometimes nothing. The result is unpredictable and often unflattering.

A good preview card gives the link a thumbnail, a headline, and a one-line description. Posts with card previews get measurably more clicks than bare URLs. For any content you want shared, OG tags are the difference between a polished preview and a naked URL.

## How to implement

Six tags do most of the work:

- **`og:title`** — the headline. Usually shorter than the HTML `<title>` (no site suffix needed; the platform shows the domain separately).
- **`og:description`** — the snippet under the title. 60–200 characters reads well on most platforms.
- **`og:image`** — an absolute URL to the preview image.
- **`og:url`** — the canonical absolute URL of the page. Match your `<link rel="canonical">`.
- **`og:type`** — the kind of object: `website` for the homepage, `article` for posts, `product` for shop items.
- **`og:site_name`** — the human-readable site name. Slack renders it as the small label above the title; Facebook and LinkedIn also use it when present.

For the image, there are two sensible sizes:

- **1200 × 630** (1.91:1) — the historical Open Graph default. Works on Facebook, LinkedIn, Slack, Discord, iMessage, Bluesky, and Mastodon.
- **1200 × 675** (16:9) — also works on every OG platform, *and* satisfies [Google Discover](https://developers.google.com/search/docs/appearance/google-discover), which only surfaces large-format cards when the image is at least 1200 px wide and roughly 16:9. If you care about appearing in Discover (and you should, if your content is Discover-eligible), 1200 × 675 is the more portable choice — and you also need `<meta name="robots" content="max-image-preview:large">` for Google to use the full-width version.

Other constraints, regardless of which size you pick:

- File size under 5 MB across most platforms, but **WhatsApp drops the preview entirely if the image is over 300 KB** — and WhatsApp is one of the most-used unfurlers on the planet. Treat 300 KB as the real ceiling.
- **Format: PNG or JPEG is the safe universal choice.** WebP is now accepted by virtually every modern unfurler (Facebook, LinkedIn, Discord, iMessage, Slack, Mastodon, Bluesky, X, WhatsApp) and is a good pick when you need to stay under WhatsApp's 300 KB cap on a denser image. AVIF is *not* yet safe — only Facebook, Threads, Pinterest, and WhatsApp render AVIF previews today; the rest will silently drop them. If your CMS auto-converts uploads to AVIF, force the `og:image` URL to stay PNG/JPEG/WebP.
- No critical content within 60 pixels of any edge — platforms crop differently.
- Declare `og:image:width` and `og:image:height`. Some platforms refuse to use images they cannot pre-size.
- Serve over HTTPS. HTTP images are rejected.
- Use absolute URLs. Relative `og:image` paths are not portable.

For X (Twitter), add Twitter Card tags as a fallback. X prefers them when present:

```html
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="The lang attribute on <html>" />
<meta name="twitter:description" content="Set a valid BCP 47 language tag on <html>..." />
<meta name="twitter:image" content="https://example.com/og/html-lang.png" />
```

If you skip the Twitter Card tags, X will fall back to your OG tags, which is fine. The one extra value worth adding is `twitter:card` set to `summary_large_image` so the preview shows the full-width image instead of a small thumbnail.

Two more Twitter Card tags are worth setting because **Slack** renders them as extra key–value rows below the description in the unfurl card:

```html
<meta name="twitter:label1" content="Reading time" />
<meta name="twitter:data1" content="6 min" />
<meta name="twitter:label2" content="Written by" />
<meta name="twitter:data2" content="Jane Doe" />
```

Up to two pairs are shown. Keep each value short — roughly 25 characters fits without truncation. Good uses are reading time, author, price, publication date, category, or rating. Slack is currently the main consumer of these tags; X used to render them on a now-deprecated card type, and most other platforms ignore them, so treat them as a Slack-specific bonus, not a replacement for `og:description`.

Slack also checks for **[oEmbed](https://oembed.com/) discovery** before falling back to OG/Twitter Card tags — either a `<link rel="alternate" type="application/json+oembed">` in the head or an `application/json+oembed` link in the HTTP `Link` header. If you ship oEmbed (most CMSes do for video and rich embeds), Slack uses it first; OG tags are the fallback. The two should describe the same page.

Generate the image per page when you can. A unique illustration or screenshot per article is more engaging than a single site-wide card. Many sites generate them on-demand at build time or with an edge function.

**Locale tags for multilingual sites.** If your page has translated versions, declare them with `og:locale` (this page) and `og:locale:alternate` (every other locale). Use the underscored `language_TERRITORY` form, not the BCP 47 hyphenated form used by `lang` and `hreflang`:

```html
<meta property="og:locale" content="en_GB" />
<meta property="og:locale:alternate" content="fr_FR" />
<meta property="og:locale:alternate" content="de_DE" />
```

Without `og:locale`, social platforms guess from the crawler's `Accept-Language` and may render the wrong-language card. The full set of head changes for a translated page — title, description, OG, JSON-LD `inLanguage`, image alt — is covered in [localised-metadata](/i18n/localised-metadata).

## Common mistakes

- Using `name="og:title"` instead of `property="og:title"`. The protocol requires `property`.
- Relative URLs in `og:image` or `og:url`. Always absolute, always HTTPS.
- Image dimensions that drift from 1.91:1 or 16:9 — cropped badly on every platform.
- Shipping a 1200 × 630 image *and* wanting Google Discover traffic. Discover wants 16:9 at ≥ 1200 px wide; 1200 × 675 satisfies both worlds.
- A beautiful 600 KB PNG that WhatsApp silently refuses to preview. Compress, downscale, or switch to WebP until you are under 300 KB.
- Serving `og:image` as AVIF. Most platforms cannot render it and will skip the card entirely.
- Missing `og:image:width` and `og:image:height`. Some platforms skip the image entirely without them.
- One generic OG image reused on every page. Works, but missing an opportunity.
- `og:url` that does not match the canonical URL. The two should agree.
- Missing `og:site_name`. Slack and Facebook fall back to the bare domain, which looks unbranded.
- Stuffing a sentence into `twitter:data1`. The field is for a short value, not a description — long strings get truncated in the Slack card.
- Burying OG tags below 32 KB of inline CSS or scripts in the `<head>`. Slackbot only fetches the first 32 KB with a `Range` request; meta tags past that cut-off are never seen and the link silently fails to unfurl. Put OG tags near the top of `<head>`, above any large inline blocks.

## Verification

- View source and check the five core tags are present and absolute.
- Paste the URL into a debugger (Facebook Sharing Debugger, LinkedIn Post Inspector, Slack's link unfurler, or a direct paste into a chat).
- Confirm the image renders at full width, the title is correct, and the description matches.
- After updating tags, re-scrape on platforms that cache previews aggressively (Facebook, LinkedIn) so they pick up the new values.

### Sources
- The Open Graph protocol (ogp.me) — https://ogp.me/
- MDN — The Open Graph protocol (MDN) — https://developer.mozilla.org/en-US/docs/Web/OpenGraph
- X — About Cards (X) — https://developer.x.com/en/docs/x-for-websites/cards/overview/abouts-cards
- Google Search Central — Google Discover and your website (Google) — https://developers.google.com/search/docs/appearance/google-discover
- WhatsApp — Link previews (Meta) — https://developers.facebook.com/documentation/business-messaging/whatsapp/link-previews/
- Slack — Unfurling links in messages (Slack) — https://docs.slack.dev/messaging/unfurling-links-in-messages/
- Open Graph Plus — Slack unfurl tags (Open Graph Plus) — https://opengraphplus.com/consumers/slack/tags
- Open Graph Plus — How Slack crawls your page (Open Graph Plus) — https://opengraphplus.com/consumers/slack/crawling

---

## Feed discovery with rel="alternate"

Status: recommended  ·  Source page: https://specification.website/spec/foundations/feed-discovery/

If your site publishes a feed — RSS, Atom, or JSON Feed — announce it in <head> with <link rel="alternate">. Feed readers, agents, and browsers discover it without guessing the URL.

## What it is

`<link rel="alternate">` in `<head>` declares an alternative representation of the current page or site — most commonly a syndication feed, but also a translated version, a print stylesheet, or, increasingly, the page's Markdown source. Feed readers, browsers, and a growing number of AI agents look for these links to subscribe, switch language, or fetch a machine-friendly version.

For feeds specifically:

```html
<head>
  <link rel="alternate" type="application/rss+xml"
        title="Example — Posts" href="/feed.xml">
  <link rel="alternate" type="application/atom+xml"
        title="Example — Posts (Atom)" href="/atom.xml">
  <link rel="alternate" type="application/feed+json"
        title="Example — Posts (JSON Feed)" href="/feed.json">
</head>
```

The browser, [feed readers](https://en.wikipedia.org/wiki/Comparison_of_feed_aggregators), and tools like the [W3C Feed Validation Service](https://validator.w3.org/feed/) pick these up automatically. The `title` attribute is what the user sees in the subscribe UI — make it specific.

## Why it matters

- **Feed readers cannot subscribe to what they cannot find.** Without `<link rel="alternate">`, the user has to know the URL. With it, every modern reader auto-discovers from the homepage or any article.
- **Browsers and OS-level readers (Safari, NetNewsWire, Reeder) use the same discovery hook.**
- **Search engines and aggregators** treat `rel="alternate"` as the canonical signal for syndication.
- **`rel="alternate"` is a multi-purpose link relation.** Pair the same pattern with `hreflang` for translated URLs (see [hreflang](/spec/i18n/hreflang/)), with `type="text/markdown"` for [Markdown source endpoints](/spec/agent-readiness/markdown-source-endpoints/), and with `media` for print or mobile alternates. Using it consistently teaches every tool that reads your site what to look for.

## How to implement

**Pick the right MIME type.** Browsers and readers branch on it.

| Format | MIME type |
|---|---|
| RSS 2.0 | `application/rss+xml` |
| Atom 1.0 | `application/atom+xml` |
| JSON Feed | `application/feed+json` |
| Markdown source | `text/markdown` |

**Include `title`** for every alternate. A reader's subscribe dialog shows the title verbatim. "RSS Feed" tells the user nothing; "Example — Engineering blog" does.

**Put the most-preferred feed first.** Some readers offer the first alternate by default if there are several.

**Use absolute URLs in the feed itself**, even if the `href` here is relative — see [machine-readable formats](/spec/agent-readiness/machine-readable-formats/).

**Site-wide vs page-specific.** A blog index links to the main feed. An individual category page can additionally link to that category's feed. An individual post does not need its own feed.

**Don't forget HTTP discovery.** Some readers also honour `Link` headers:

```http
Link: </feed.xml>; rel="alternate"; type="application/rss+xml"; title="Example — Posts"
```

Useful for non-HTML responses (e.g. an API root) where there is no `<head>`.

## Common mistakes

- Using `type="text/xml"` or `application/xml` for an RSS feed. Some readers ignore it.
- Linking to a feed that 404s, redirects, or fails validation. Run `https://validator.w3.org/feed/` on every feed URL before shipping.
- Pointing all `<link rel="alternate">` entries at the same URL "to be safe". Each entry must describe a distinct representation.
- Omitting `title` and letting the reader guess.
- Putting `rel="alternate"` on an `<a>` link in the body. It only carries discovery semantics inside `<head>`.

## Verification

- `curl -s https://example.com/ | grep -i 'rel="alternate"'` returns each declared alternate.
- Paste the homepage URL into a feed reader's "Add subscription" dialog — it should resolve to the correct feed without you typing the feed URL.
- The W3C [feed validator](https://validator.w3.org/feed/) returns no errors on the linked feed.
- View source on a per-language page and confirm `rel="alternate" hreflang="…"` siblings sit alongside any feed alternates without conflicting.

### Sources
- HTML Living Standard — Link types: alternate (WHATWG) — https://html.spec.whatwg.org/multipage/links.html#link-type-alternate
- MDN — rel=alternate (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/alternate
- RSS 2.0 Specification (RSS Advisory Board) — https://www.rssboard.org/rss-specification
- RFC 4287 — The Atom Syndication Format (IETF) — https://www.rfc-editor.org/rfc/rfc4287
- JSON Feed 1.1 (JSON Feed) — https://www.jsonfeed.org/version/1.1/

---

## Feed content hygiene

Status: recommended  ·  Source page: https://specification.website/spec/foundations/feed-hygiene/

If you publish a feed, ship it well-formed. Identify the feed inside itself with atom:link rel="self", give every item a stable guid, declare an update cadence with the Syndication module, and validate before deploy.

## What it is

[`Feed discovery`](/spec/foundations/feed-discovery/) tells the world *where* your feed is. Feed hygiene is about whether the feed itself is well-formed once they fetch it. Aggregators, feed readers, and AI agents all behave better — and waste fewer of your bytes — when the channel identifies itself, every item has a stable identifier, and the publishing cadence is declared.

The conventions are old and stable. The base specs are RSS 2.0 (RSS Advisory Board), RFC 4287 (Atom), and JSON Feed 1.1. The practical layer — what makes a feed actually portable — lives in the *RSS Best Practices Profile*, which both the [W3C Feed Validation Service](https://validator.w3.org/feed/) and the RSS Validator use to flag warnings.

## Why it matters

- **Self-identification (`atom:link rel="self"`)** makes a feed portable. If the feed is mirrored, cached, or sent to you by a friend, every reader can still find the canonical subscription URL.
- **Stable, unique `<guid>`** lets aggregators detect updates without re-displaying old items. Get this wrong and every refresh re-floods subscribers with duplicates.
- **`sy:updatePeriod` and `sy:updateFrequency`** tell polite aggregators how often to poll. A weekly blog declaring `daily` cadence wastes bandwidth on both sides; declaring `hourly` invites unnecessary load.
- **`<lastBuildDate>`** lets a reader skip parsing when nothing has changed.
- **Paging headers (RFC 5005)** keep archive feeds usable. Without `rel="next"`/`rel="prev"`, anything past the first page is invisible to readers that follow links.

The cost of getting these right is one-time and small. The cost of getting them wrong shows up as duplicate posts in every reader, weeks of stale entries, or 100× more polling traffic than you intended.

## How to implement

Declare the Atom and Syndication namespaces on the `<rss>` root, then ship a self-link, channel metadata, and per-item GUIDs:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:sy="http://purl.org/rss/1.0/modules/syndication/">
  <channel>
    <title>Example — Posts</title>
    <link>https://example.com/</link>
    <description>Engineering writing from the Example team.</description>
    <language>en-GB</language>

<atom:link href="https://example.com/feed.xml"
               rel="self" type="application/rss+xml" />
    <lastBuildDate>Mon, 27 May 2026 09:00:00 GMT</lastBuildDate>
    <sy:updatePeriod>daily</sy:updatePeriod>
    <sy:updateFrequency>1</sy:updateFrequency>

<item>
      <title>Shipping the new search</title>
      <link>https://example.com/blog/new-search/</link>
      <guid isPermaLink="true">https://example.com/blog/new-search/</guid>
      <pubDate>Mon, 27 May 2026 09:00:00 GMT</pubDate>
      <description>Why we rebuilt search on Pagefind.</description>
    </item>
  </channel>
</rss>
```

Key points:

- **`atom:link rel="self"`** must point at the canonical URL of the feed itself. Both feed validators flag its absence as a warning.
- **`<guid isPermaLink="true">`** is the simplest correct form when the URL never changes. If the URL is unstable, use `isPermaLink="false"` with a tag URI: `<guid isPermaLink="false">tag:example.com,2026:post/123</guid>`. Once chosen, **the GUID for an item must never change** — that is the identifier readers key off.
- **`sy:updatePeriod`** accepts `hourly`, `daily`, `weekly`, `monthly`, `yearly`. `sy:updateFrequency` is a positive integer (count per period). A site updating twice a day declares `<sy:updatePeriod>daily</sy:updatePeriod><sy:updateFrequency>2</sy:updateFrequency>`.
- **Dates** use RFC 822 format (`Mon, 27 May 2026 09:00:00 GMT`). Atom uses RFC 3339.
- **For archive feeds**, add RFC 5005 paging:

```xml
<atom:link rel="next" href="https://example.com/feed.xml?page=2" />
<atom:link rel="last" href="https://example.com/feed.xml?page=14" />
```

Atom and JSON Feed have direct equivalents for all of the above — JSON Feed's `feed_url` is the self-link, and its `id` per item is the GUID.

## Common mistakes

- Missing `atom:link rel="self"`. Both validators warn on it, and most production feeds in the wild still don't ship it.
- Generating a fresh GUID per build instead of per item. Every reader re-floods subscribers on every deploy.
- Mismatched dates — `pubDate` newer than `lastBuildDate`, or per-item timestamps in the future. Some aggregators silently drop the item.
- Declaring a cadence (`<sy:updatePeriod>hourly</sy:updatePeriod>`) the site does not actually meet. Aggregators back off if the feed is stale relative to the declared cadence.
- Putting absolute URLs in `<link>` but relative URLs in `<atom:link rel="self">`. Both should be absolute.
- Forgetting `xmlns:atom` or `xmlns:sy` namespace declarations. The elements are then technically invalid in RSS 2.0.

## Verification

- Paste the feed URL into [validator.w3.org/feed](https://validator.w3.org/feed/) — expect a clean pass.
- Paste it into [rssboard.org/rss-validator](https://www.rssboard.org/rss-validator/) — the second-opinion validator catches things the W3C one misses.
- `curl -s https://example.com/feed.xml | grep -i 'rel="self"'` should return your self-link.
- Subscribe in two different readers (NetNewsWire and a web reader). Trigger a deploy that does not change content. Confirm no item duplicates appear in either reader.
- Inspect a few items: each `<guid>` should be stable across builds for the same post.

### Sources
- RSS 2.0 Specification (RSS Advisory Board) — https://www.rssboard.org/rss-specification
- RSS Best Practices Profile (RSS Advisory Board) — https://www.rssboard.org/rss-profile
- RFC 4287 — The Atom Syndication Format (IETF) — https://www.rfc-editor.org/rfc/rfc4287
- RDF Site Summary 1.0 Modules: Syndication (RSS-DEV Working Group) — https://web.resource.org/rss/1.0/modules/syndication/
- RFC 5005 — Feed Paging and Archiving (IETF) — https://www.rfc-editor.org/rfc/rfc5005
- W3C Feed Validation Service (W3C) — https://validator.w3.org/feed/

---

## Popover API

Status: recommended  ·  Source page: https://specification.website/spec/foundations/popover-api/

Replace ARIA-puzzled JavaScript modals, menus, and tooltips with a native top-layer primitive that the browser opens, closes, and accessibility-wires for you.

## What it is

The Popover API turns any element into a top-layer overlay using three HTML attributes. The browser handles opening, closing, stacking, focus, and keyboard behaviour — no JavaScript and no ARIA juggling.

- `popover` on the overlay element. Values: `auto` (default), `manual`, or `hint`.
- `popovertarget` on a `<button>` that controls the overlay, referencing the popover's `id`.
- `popovertargetaction` to force `"show"`, `"hide"`, or the default `"toggle"`.

```html
<button popovertarget="menu">Open menu</button>

<div id="menu" popover>
  <p>Menu contents.</p>
  <button popovertarget="menu" popovertargetaction="hide">Close</button>
</div>
```

The `auto` value gives you light-dismiss (click outside to close) and auto-close on Escape. `manual` requires an explicit dismiss control. `hint` is for tooltip-style transient overlays that close when another `hint` opens.

CSS hooks: `:popover-open` matches an open popover, `::backdrop` styles the layer behind it, and `popover-position` (where supported) declaratively anchors a popover to its trigger.

## Why it matters

- **Native top-layer rendering.** The popover sits above every `z-index`, every `overflow: hidden` ancestor, and every transformed container — the perennial CSS bugs of hand-rolled overlays disappear.
- **Built-in accessibility.** Focus moves into the popover on open, Escape closes `auto` popovers, click-outside dismisses them, and the trigger-to-popover relationship is wired automatically. No `aria-expanded`, `aria-controls`, focus-trap library, or outside-click listener required.
- **Less JavaScript.** Menus, disclosure widgets, and lightweight overlays become pure HTML. No state hook, no portal component, no event plumbing.
- **Composes with `<dialog>`.** `<dialog>` remains the right choice for blocking modal flows (forms that need a decision); `popover` covers everything else.

## How to implement

Use `popover` (`auto`) for menus, share sheets, command palettes, and any overlay where clicking outside should dismiss. Use `popover="manual"` only when you have an explicit close affordance and a reason the user shouldn't dismiss by clicking away. Use `hint` for tooltips.

```html
<button popovertarget="share">Share</button>
<div id="share" popover>
  <ul>
    <li><a href="...">Copy link</a></li>
    <li><a href="...">Email</a></li>
  </ul>
</div>

For programmatic control, the element exposes `showPopover()`, `hidePopover()`, and `togglePopover()`, and fires `beforetoggle` / `toggle` events.

## Common mistakes

- **`popover="manual"` without a dismiss control.** The user has no way out. Auto is the default for a reason.
- **Reaching for `popover` when you mean `<dialog>`.** Confirmations, sign-in flows, and anything that must block the rest of the page belong in `<dialog showModal()>`. Popovers are non-blocking.
- **Not testing focus return.** When a popover closes, focus must return to the trigger. The browser does this for you — but only if your trigger is a real `<button>`, not a `<div>` with an onClick.
- **Duplicating ARIA.** Don't add `role="dialog"` or `aria-modal` to a popover. The accessibility tree already reflects the right semantics.

## Verification

- DevTools accessibility tree shows the popover as an exposed overlay tied to its trigger.
- Pressing Escape closes an `auto` popover; clicking outside dismisses it; focus returns to the trigger.
- The popover renders above every transformed and `overflow: hidden` ancestor — proof it is in the top layer.
- `caniuse.com/mdn-html_global_attributes_popover` — supported in all major browsers since 2024.

### Sources
- HTML Standard — Popover (WHATWG) — https://html.spec.whatwg.org/multipage/popover.html
- MDN — Popover API (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/Popover_API
- Introducing the Popover API (web.dev) — https://web.dev/blog/popover-api
- Open UI — Popover explainer (Open UI) — https://open-ui.org/components/popover.research.explainer/

---

# SEO

Search visibility — robots.txt, sitemaps, canonicals, structured data.

## robots.txt

Status: recommended  ·  Source page: https://specification.website/spec/seo/robots-txt/

A plain-text file at the site root that tells crawlers which paths they may or may not fetch. Standardised in RFC 9309 and supported by every major search engine.

## What it is

`robots.txt` is a plain-text file served at the root of a host that tells automated crawlers which URL paths they are allowed to fetch. The format was finalised as a standard in 2022 as RFC 9309.

It must be reachable at exactly `/robots.txt` on the host, served as `text/plain`, and returned with a `200 OK`. A `404` is interpreted as "no restrictions"; a `5xx` is interpreted as "crawl nothing" by most crawlers.

```txt
User-agent: *
Disallow: /admin/
Disallow: /cart
Allow: /admin/public-policy

Sitemap: https://example.com/sitemap.xml
```

## Why it matters

- Saves crawl budget on URLs that have no value in search (faceted filters, internal search, login, cart).
- Keeps staging paths and admin areas out of crawler logs.
- The `Sitemap:` directive is the canonical way to point crawlers at your sitemap when they have not been told another way.
- AI crawlers and SEO tools also honour it — it is the broadest signal you have for "do not fetch this".

It is not a security mechanism. Anything you do not want public must be behind authentication. Disallowed URLs can still appear in search results if they are linked from elsewhere.

## How to implement

Group rules by user-agent. The most specific user-agent wins per RFC 9309.

```txt
User-agent: Googlebot
Disallow: /private/

User-agent: *
Disallow: /admin/
Allow: /

Sitemap: https://example.com/sitemap_index.xml
```

Rules to follow:

- One host per file. `robots.txt` only applies to the host it is served from, including the scheme and port.
- Paths are case-sensitive and treated as URL prefixes. `/Admin` and `/admin` are different.
- Wildcards (`*`) and end-of-URL anchors (`$`) are supported by Google, Bing, and most other major crawlers, but they are not in RFC 9309. Use them carefully.
- `Crawl-delay` is non-standard. Google ignores it; Bing and Yandex honour it. Prefer per-crawler rate settings in their dashboards.
- Keep the file under 500 KiB. Google truncates above that.

## Common mistakes

- `Disallow: /` accidentally left over from staging. This blocks the entire site.
- Disallowing a URL that you also want deindexed. Crawlers cannot read a `noindex` they are not allowed to fetch.
- Blocking CSS and JS. Google needs to render the page to rank it.
- Serving `robots.txt` from a CDN that returns `5xx` during incidents — crawlers stop fetching the whole site.

## Verification

- Fetch `https://example.com/robots.txt` directly. Confirm `Content-Type: text/plain` and a `200`.
- Use Google Search Console's robots.txt report to see the parsed rules and any warnings.

### Sources
- RFC 9309 — Robots Exclusion Protocol (IETF) — https://www.rfc-editor.org/rfc/rfc9309.html
- Introduction to robots.txt (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/robots/intro
- How Google interprets the robots.txt specification (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/robots/robots_txt

---

## XML sitemaps

Status: recommended  ·  Source page: https://specification.website/spec/seo/xml-sitemaps/

An XML file listing the canonical URLs of a site, with optional metadata about when each was last changed. The fastest way to tell a search engine what exists.

## What it is

An XML sitemap is a structured list of the URLs a site wants search engines to know about. The format is defined by sitemaps.org and supported by Google, Bing, Yandex, and others. Each entry is a `<url>` element with a required `<loc>` and optional `<lastmod>`, `<changefreq>`, and `<priority>`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/articles/hsts</loc>
    <lastmod>2026-05-12</lastmod>
  </url>
  <url>
    <loc>https://example.com/articles/csp</loc>
    <lastmod>2026-04-30</lastmod>
  </url>
</urlset>
```

## Why it matters

Crawlers find URLs by following links. A sitemap is a shortcut: it lists every canonical URL, even those that are only weakly linked, and tells the crawler when they last changed. Without one, new pages can take days or weeks to be discovered.

A sitemap is also the cleanest way to surface translation pairs, image and video metadata, and large archives. It is the main signal that powers crawl scheduling on Bing and the IndexNow protocol.

## How to implement

Follow the spec:

- **URL must be absolute.** Include the scheme and host. The sitemap must live on the same host as the URLs it lists, with limited exceptions.
- **One sitemap, 50,000 URLs and 50 MB uncompressed maximum.** Past that, split into multiple sitemaps and add a sitemap index.
- **List canonical URLs only.** A URL that redirects, returns 404, or has a different canonical confuses crawlers.
- **Set `<lastmod>` honestly.** Use ISO 8601 / W3C date format. Google uses it as a hint when scheduling recrawls; touching it on every deploy degrades that signal.
- **`<changefreq>` and `<priority>` are ignored by Google.** Other crawlers may use them, but do not spend effort tuning them.
- **Gzip is allowed.** Serve as `application/xml` (`.xml`) or `application/x-gzip` (`.xml.gz`).
- **Reference it from `robots.txt`** with `Sitemap: https://example.com/sitemap.xml` and submit it in Search Console / Bing Webmaster Tools.

Generate sitemaps dynamically from your content source, not by crawling your own site — that way you cannot accidentally include orphaned or redirected URLs.

**This site ships it.** `specification.website` generates [`/sitemap-index.xml`](/sitemap-index.xml) at build time from the content collection, and sets each `<lastmod>` from the entry's `updated` front matter — the same field the [RSS feed](/rss.xml) uses — rather than the build timestamp, so the date only moves when the content actually changes.

## Common mistakes

- Listing non-canonical URLs (parameters, session IDs, alternate-case paths).
- Including URLs that return 3xx, 4xx, or 5xx — crawlers will drop trust in the whole sitemap.
- Updating `<lastmod>` on every build even when content has not changed.
- Splitting by URL hash for no reason. Split by content type or section so each sitemap is meaningful on its own.

## Verification

- Fetch the sitemap directly. Confirm `Content-Type: application/xml` and a `200 OK`.
- Validate against the sitemaps.org XSD.
- Check Search Console's Sitemaps report for parse errors and discovered-vs-indexed counts.

### Sources
- Sitemaps XML format (sitemaps.org) — https://www.sitemaps.org/protocol.html
- Build and submit a sitemap (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap
- XML sitemaps: the most important SEO tool (Yoast) — https://yoast.com/what-is-an-xml-sitemap-and-why-should-you-have-one/

---

## Sitemap index files

Status: recommended  ·  Source page: https://specification.website/spec/seo/sitemap-index/

A sitemap of sitemaps. Used when a site has more than 50,000 URLs or wants to split sitemaps by content type for cleaner reporting.

## What it is

A sitemap index is an XML file that lists other sitemap files. Its root element is `<sitemapindex>` and each child `<sitemap>` has a `<loc>` pointing at a child sitemap, with an optional `<lastmod>`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-articles.xml</loc>
    <lastmod>2026-05-29</lastmod>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-products.xml</loc>
    <lastmod>2026-05-28</lastmod>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-images.xml</loc>
    <lastmod>2026-05-29</lastmod>
  </sitemap>
</sitemapindex>
```

Submit the index URL to Search Console. Crawlers will fetch the index, then each child sitemap, then each URL.

## Why it matters

Two reasons to use an index:

1. **Scale.** A single sitemap is capped at 50,000 URLs and 50 MB uncompressed. Once a site exceeds either, the only standard-compliant option is to split into multiple sitemaps and reference them from an index.
2. **Reporting.** Search Console reports submitted-vs-indexed counts per sitemap. Splitting by content type (articles, products, categories, images) lets you see at a glance which section has indexing problems instead of one big number for the whole site.

A site with 500 URLs does not need an index. Adding one anyway is harmless but adds a layer of fetching that gains you nothing.

## How to implement

Split sitemaps by something meaningful:

- **By content type** — `sitemap-posts.xml`, `sitemap-pages.xml`, `sitemap-products.xml`.
- **By language or region** — `sitemap-en.xml`, `sitemap-nl.xml`. Pairs well with `hreflang`.
- **By date** — `sitemap-2025.xml`, `sitemap-2026.xml` for archive-heavy sites.

Rules:

- Up to **50,000 child sitemaps** per index, and the index itself is capped at 50 MB uncompressed.
- Every child sitemap must be on the same host as the index, with limited cross-host exceptions.
- `<lastmod>` on the index entry should reflect the newest `<lastmod>` inside the child sitemap. This lets crawlers skip refetching unchanged sections.
- Reference the index from `robots.txt` and submit only the index in Search Console — do not also submit each child individually.

## Common mistakes

- Pointing the index at child sitemaps on a different host.
- Stale `<lastmod>` on the index while the child sitemap has fresh URLs.
- Splitting arbitrarily (sitemap-1, sitemap-2) so the reporting buckets are meaningless.
- Submitting both the index and each child sitemap, causing duplicate reports.

## Verification

- Fetch the index URL. Confirm the root element is `<sitemapindex>` and each child resolves to a valid sitemap.
- Validate against the sitemaps.org XSD.
- In Search Console, confirm the index shows the expected number of child sitemaps and their per-sitemap indexing stats.

### Sources
- Sitemaps XML format — sitemap index files (sitemaps.org) — https://www.sitemaps.org/protocol.html#index
- Manage sitemaps for large sites (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/sitemaps/large-sitemaps

---

## Image and video sitemap extensions

Status: optional  ·  Source page: https://specification.website/spec/seo/image-sitemaps/

Optional XML extensions that add image and video metadata to sitemap entries. Useful when media is loaded by JavaScript or hosted on a CDN that crawlers cannot reach by following links.

## What it is

Sitemaps support extensions for declaring images and videos associated with each page. They use additional XML namespaces alongside the standard `urlset`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
  <url>
    <loc>https://example.com/articles/csp</loc>
    <image:image>
      <image:loc>https://cdn.example.com/csp-hero.jpg</image:loc>
    </image:image>
    <image:image>
      <image:loc>https://cdn.example.com/csp-diagram.png</image:loc>
    </image:image>
  </url>
</urlset>
```

The video extension is similar (`xmlns:video`) and supports more metadata: `title`, `description`, `thumbnail_loc`, `content_loc`, and `player_loc`.

## Why it matters

Crawlers normally find images by parsing the HTML of pages they fetch. That is usually enough. The extensions only earn their keep when:

- **Media is loaded by JavaScript** and not in the initial HTML.
- **Media lives on a different host** (a CDN or media subdomain) that crawlers do not visit independently.
- **You publish a lot of original photography or video** and want crawlers to discover updates quickly.

For most marketing sites, plain `<img>` and `<video>` elements with good `alt` text and `<source>` declarations are enough. The extensions are an optimisation, not a baseline.

## How to implement

For images:

- Up to **1,000 images per `<url>` entry**.
- Each `<image:image>` needs only `<image:loc>`. Other fields (`caption`, `title`, `geo_location`, `license`) are accepted by some crawlers but are not widely used.
- Use the canonical image URL — the one the page actually loads. CDN URLs are fine.

For videos:

- Each `<video:video>` needs `thumbnail_loc`, `title`, `description`, and one of `content_loc` or `player_loc`.
- Keep titles under 100 characters and descriptions under 2,048.
- Add `duration` in seconds where possible.

For both, prefer to **add them to existing page sitemaps** rather than create a separate image or video sitemap. That keeps the relationship between page and media explicit. If volume is too high, split into a dedicated `sitemap-images.xml` and reference it from your sitemap index.

## Common mistakes

- Listing images that are not actually used on the page in `<loc>`. Crawlers cross-check.
- Pointing `<image:loc>` at a redirect or a 404.
- Forgetting the `xmlns:image` or `xmlns:video` namespace declaration on `<urlset>`.
- Treating these as a ranking lever. They help discovery, not ranking.

## Verification

- Validate the sitemap against the extension XSDs.
- In Search Console, check the Sitemaps report for parsed image and video counts.
- Test that each `<image:loc>` returns `200 OK` with an image `Content-Type`.

### Sources
- Image sitemaps (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/sitemaps/image-sitemaps
- Video sitemaps and alternatives (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/sitemaps/video-sitemaps
- Sitemaps XML format (sitemaps.org) — https://www.sitemaps.org/protocol.html

---

## URL structure

Status: recommended  ·  Source page: https://specification.website/spec/seo/url-structure/

URLs are the most stable identifier on the web. Keep them lowercase, hyphenated, descriptive, and shallow. Treat them as a public API for your content.

## What it is

A URL is the canonical name for a resource on the web. Its syntax is defined by RFC 3986 and refined for the browser by the WHATWG URL Living Standard. The path component — everything after the host — is where structure choices have the most impact on SEO and usability.

```
https://example.com/articles/web-security/csp
            ^host       ^path
```

## Why it matters

URLs are quoted in chat, pasted into documents, printed on slides, and saved in bookmarks for years. Once a URL is public, it is effectively forever — changing it requires a redirect, and chains of redirects degrade. They also appear under the page title in search results, so a clean, readable URL is a small but real signal of quality to both users and crawlers.

A consistent URL structure also makes analytics, A/B testing, redirect rules, and access controls dramatically simpler.

## How to implement

Treat URLs as a public API:

- **Lowercase only.** RFC 3986 says the path is case-sensitive, so `/About` and `/about` are different URLs. Pick lowercase and enforce a 301 redirect for any uppercase variant.
- **Hyphens, not underscores.** Search engines tokenise on hyphens but not underscores. `web-security` reads as two words; `web_security` reads as one.
- **No trailing whitespace, no encoded spaces.** Replace spaces with hyphens before the URL is ever generated.
- **Descriptive slugs.** `/articles/csp` beats `/articles/12345`. Both work, but the readable one survives social sharing better.
- **Avoid deep nesting.** Aim for three or fewer path segments after the host. Deep URLs (`/section/sub/sub/sub/post`) signal low priority and are hard to refactor.
- **Pick trailing-slash or no-trailing-slash and stick with it.** Both work; mixing creates duplicate-content risk. Use a 301 to enforce the chosen form.
- **Query parameters are for filters, not content.** Canonical content should have a clean path. Parameters are fine for sort order, pagination, and tracking, but the canonical link should strip them.
- **ASCII where possible.** Modern browsers handle IDNs and percent-encoded UTF-8 fine, but non-ASCII URLs break in older tooling, copy-paste, and email clients.

```
Good:  https://example.com/articles/web-security/csp
Bad:   https://example.com/Articles/Web_Security/CSP/?id=12345&utm_source=x
```

## Common mistakes

- Mixed case across the site, with no canonical enforcement.
- Including dates that go stale: `/2023/10/csp` looks outdated by 2026 even if the content has been kept current.
- Session IDs or tracking parameters baked into canonical URLs.
- Renaming URLs every CMS migration. Each rename costs link equity even with redirects.

## Verification

- Crawl the site with a tool like Screaming Frog or a sitemap fetcher. Check for mixed-case duplicates and trailing-slash inconsistencies.
- Confirm 301 redirects enforce the canonical form.
- Check Search Console's Pages report for "Duplicate, Google chose different canonical" — that often points at URL-structure problems.

### Sources
- RFC 3986 — Uniform Resource Identifier (URI): Generic Syntax (IETF) — https://www.rfc-editor.org/rfc/rfc3986
- URL structure best practices (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/url-structure
- URL — Living Standard (WHATWG) — https://url.spec.whatwg.org/

---

## Redirects (301/302/308)

Status: required  ·  Source page: https://specification.website/spec/seo/redirects/

HTTP redirects send a client from one URL to another. Use 301 or 308 for permanent moves, 302 or 307 for temporary ones, and never chain more than necessary.

## What it is

A redirect is a `3xx` HTTP response that tells the client to fetch a different URL, named in the `Location` header. RFC 9110 defines the semantics of each status code.

```http
HTTP/1.1 301 Moved Permanently
Location: https://example.com/articles/csp
```

The four codes that matter in practice:

- **301 Moved Permanently** — the canonical URL has changed. Search engines transfer ranking signals to the target.
- **302 Found** — temporary redirect. The browser may switch the request method (a `POST` can become a `GET`). Use only for short-lived redirects.
- **307 Temporary Redirect** — like 302, but the method and body must be preserved. Safer for APIs.
- **308 Permanent Redirect** — like 301, but the method and body must be preserved.

For SEO, treat 301 and 308 as equivalent ("permanent"), and 302 and 307 as equivalent ("temporary").

## Why it matters

When you move a page, every link, bookmark, and search result pointing at the old URL becomes a problem. A permanent redirect tells crawlers to forget the old URL and consolidate ranking signals onto the new one. A temporary redirect tells them the old URL is the canonical one and will return.

Getting this wrong is one of the most common SEO mistakes. A 302 on a URL that has actually moved permanently can take months to be reinterpreted as a 301, during which the site loses traffic.

## How to implement

Rules of thumb:

- **URL has moved for good → 301 (or 308 if the method matters).**
- **Site is in maintenance, A/B test, or geo-redirect → 302 (or 307).**
- **HTTPS upgrade → 301** from `http://` to `https://`.
- **Trailing-slash or case canonicalisation → 301.**
- **Old domain → new domain → 301.** Keep the old domain registered indefinitely so the redirect keeps working.

Keep chains short. Each hop is a fresh request, costs latency, and risks a crawler giving up. `A → B → C` should be flattened to `A → C` and `B → C` wherever you control both rules.

```
Bad:  /old-name  → 301 → /new-name  → 301 → /new-name/
Good: /old-name  → 301 → /new-name/
      /new-name  → 301 → /new-name/
```

Other practical points:

- Redirect at the edge (web server, CDN, or origin) — not with `<meta http-equiv="refresh">` or JavaScript. Crawlers handle HTTP redirects reliably; meta-refresh and JS redirects are slower and ambiguous.
- For 301 chains across a migration, write the redirect map from your old URL inventory, not by guessing.
- Preserve query strings if the destination needs them.

## Common mistakes

- Using 302 for a permanent move.
- Redirecting every removed page to the home page. That hides the loss and confuses crawlers — return 410 or 404 instead.
- Redirect loops (`A → B → A`).
- Chains longer than three hops. Google stops following after about ten; users feel the latency long before that.

## Verification

- `curl -sI https://example.com/old-url` and check the status code and `Location` header.
- Use Search Console's URL inspection tool. It reports the redirect chain Google followed.
- Crawl the site to find chains and loops.

### Sources
- RFC 9110 — HTTP Semantics, redirection 3xx (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-redirection-3xx
- Redirects and Google Search (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/301-redirects
- MDN — Redirections in HTTP (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections

---

## Soft 404s

Status: avoid  ·  Source page: https://specification.website/spec/seo/soft-404/

A page that looks like a 'not found' message to a user but returns 200 OK to a crawler. Search engines treat soft 404s as a quality problem and often refuse to index them.

## What it is

A soft 404 is a URL that **returns `200 OK`** but **renders a page indicating the content is missing**. The classic examples:

- An empty search results page that says "no results found" but returns 200.
- A category page with zero products that renders the chrome and a "nothing here" message.
- A single-page app that routes every unknown URL to a generic "page not found" component without changing the status code.
- A CMS that, when a slug is missing, redirects to the home page (a different bug, but classified by Google in the same family).

The HTTP semantics and the human-readable content disagree. RFC 9110 is explicit: `404 Not Found` is the correct status for a missing target. A page that says "not found" with `200` is lying to the protocol.

## Why it matters

Crawlers use the status code as the source of truth. When they see `200`, they assume the content is valid, index it, and may rank it for queries it should never appear for. When the user clicks through, they land on an empty page and bounce.

Once Google's quality systems notice the pattern, they reclassify the URL as a soft 404 and drop it from the index, often along with similar URLs across the site. Search Console's "Soft 404" report exists specifically to surface these. A site with many soft 404s gets crawled less, because the crawler stops trusting the status codes.

It is also an accessibility and user-experience problem. Screen readers and browser back-button behaviour rely on status codes being accurate.

## How to detect

- **Search Console → Pages → Why pages aren't indexed → Soft 404.** This is the authoritative list of URLs Google has reclassified.
- **Server logs.** Look for `200` responses on URLs that match patterns like `/search`, `/category/<id>`, or known SPA fallback routes, especially with very low time-on-page.
- **Crawl with a status-aware tool.** Compare the rendered DOM (for phrases like "no results", "page not found", "this product is no longer available") against the HTTP status.

## How to fix

- **Return the right status.** A missing page returns `404`. A removed page that will never come back returns `410 Gone` — both signal "do not index" and are correct.
- **For SPAs**, configure the server or edge to return the correct status before serving the fallback HTML. The same shell can render, but the response must be `404`.
- **For empty category and search pages**, decide whether the URL should exist at all. If it should, return a useful page (suggestions, related products) but keep `200`. If it should not, return `404`.
- **Do not redirect missing pages to the home page.** That is the worst of both worlds — Google treats it as a soft 404 anyway, and users get no signal about what went wrong.

## Verification

- `curl -sI https://example.com/this-does-not-exist` should return `404` or `410`, not `200` and not `302`.
- After deploying the fix, request reindexing for affected URLs in Search Console and watch the Soft 404 count fall on the next crawl cycle.

### Sources
- Soft 404 errors (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/http-network-errors#soft-404-errors
- RFC 9110 — 404 Not Found (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found
- MDN — HTTP response status codes (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

---

## Meta robots and X-Robots-Tag

Status: required  ·  Source page: https://specification.website/spec/seo/meta-robots/

Every page must have an explicit, correct indexing policy — either implicit (default index, follow) on public pages, or an explicit noindex / X-Robots-Tag on staging, admin, thin, or private content. Get this wrong and you either disappear from search or expose what you didn't mean to.

## What it is

The robots meta tag and the equivalent `X-Robots-Tag` HTTP header tell search engines and other compliant crawlers whether they may index a page, follow its links, and how to render it in results. Together they are the per-page complement to [robots.txt](/spec/seo/robots-txt/) — robots.txt controls *crawling*, robots meta controls *indexing*.

```html
<meta name="robots" content="index, follow">
<meta name="robots" content="noindex, nofollow">
<meta name="robots" content="noindex, max-image-preview:large">
```

```http
X-Robots-Tag: noindex, nofollow
X-Robots-Tag: googlebot: noindex
```

The HTTP header form is the only way to control indexing for non-HTML resources — PDFs, images, JSON endpoints, downloads.

## Why it matters

Every URL a search engine fetches has a policy, whether you set one or not. The default is `index, follow` — every fetched page becomes a candidate for the index, and every link is a discovery hop. That is right for your homepage and your articles; it is wrong for:

- **Staging and preview environments.** Forgetting `noindex` on a `staging.example.com` is a top-five SEO mistake. Once Google indexes a staging URL, it competes with production.
- **Internal search results, filtered listings, faceted-search permutations.** Infinite combinations of low-value pages dilute the site's crawl budget.
- **Thin, duplicate, or transactional pages.** Thank-you pages, cart pages, password-reset pages, account screens.
- **Pages waiting for content.** Empty category pages, "coming soon" pages.
- **Sensitive resources.** Print-only versions, internal exports, machine-readable feeds you don't want surfacing as snippets.

Public pages are required to be indexable; non-public pages are required to be non-indexable. Either way, the policy must be explicit and correct.

## How to implement

**Add the meta tag in `<head>`** for every HTML page that needs a non-default policy:

```html
<meta name="robots" content="noindex, follow">
```

`follow` keeps link equity flowing to the destinations even when the host page is not indexed. Pair it with `noindex` for staging, internal search, faceted listings.

**Use directives precisely.** The most useful ones, with the values search engines respect:

| Directive | Effect |
|---|---|
| `index` / `noindex` | Allow / disallow indexing of this page |
| `follow` / `nofollow` | Allow / disallow following links on this page |
| `noarchive` | Don't show a cached copy in results |
| `nosnippet` | Don't show a text snippet in results |
| `max-snippet:[n]` | Cap the snippet at *n* characters; `-1` means no limit |
| `max-image-preview:[none\|standard\|large]` | Control image-preview size |
| `max-video-preview:[n]` | Cap video preview at *n* seconds |
| `noimageindex` | Don't index images on this page |
| `unavailable_after:[date]` | Drop from the index after this RFC 822 / ISO 8601 date |

**Target a specific crawler when you need to.** Replace `robots` with `googlebot`, `bingbot`, `applebot`, or another user-agent token. A `robots` directive applies to all; a named-bot directive overrides it for that bot.

```html
<meta name="robots" content="noindex">
<meta name="googlebot-news" content="noindex, nofollow">
```

**Use `X-Robots-Tag` for non-HTML.** Cloudflare, Nginx, Apache, and CDN edge config can all set it per-path. Required for PDFs you don't want indexed.

```http
X-Robots-Tag: noindex, nofollow
```

**Don't combine `robots.txt: Disallow` with `noindex`.** If a URL is disallowed in robots.txt, crawlers never fetch it — and therefore never see the `noindex`. The page can still be indexed from external links, with no snippet. To truly de-index, allow crawl and serve `noindex`.

**Default policy is implicit.** A public page with no robots meta tag is `index, follow`. You do not need to add `<meta name="robots" content="index, follow">` — it's the default, and shipping it on every page is noise. Add the tag only when the policy differs.

## Common mistakes

- Staging site indexed because someone forgot to set `noindex`. Block it at the server with `X-Robots-Tag: noindex` site-wide on the staging host.
- `Disallow: /` in robots.txt on a staging site instead of `noindex`. The page may still appear in results with the URL but no snippet. Use `noindex` and let the crawler fetch and see it.
- Shipping a launch with `<meta name="robots" content="noindex, nofollow">` left over from staging. Diff every deploy.
- Conflicting directives: `<meta name="robots" content="index">` paired with `X-Robots-Tag: noindex`. The most restrictive wins; the result is usually not what was intended.
- Using `nofollow` to "save crawl budget" by stopping internal link discovery. It does not save budget; it just throws away signals.
- Relying on `noindex` to protect sensitive data. It is a request, not an access control. Use authentication.

## Verification

- View source on every key URL — confirm the `<meta name="robots">` value matches intent.
- `curl -I https://example.com/private/` — confirm `X-Robots-Tag` is set as expected.
- Google Search Console → URL Inspection. The "Indexing allowed" line is authoritative.
- After a staging deploy, search `site:staging.example.com` in Google. Zero results is the only acceptable answer.
- Audit tools (Screaming Frog, Sitebulb) export every URL's `robots` directive — review the list before launch and after major releases.

### Sources
- HTML Living Standard — Standard metadata names: robots (WHATWG) — https://html.spec.whatwg.org/multipage/semantics.html#meta-robots
- Google Search Central — Robots meta tag, data-nosnippet, and X-Robots-Tag (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag
- Bing Webmaster — Robots meta tag (Bing) — https://www.bing.com/webmasters/help/which-robots-metatags-does-bing-support-5198d240
- MDN — <meta name="robots"> (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name

---

## Heading hierarchy

Status: required  ·  Source page: https://specification.website/spec/seo/heading-hierarchy/

Headings describe the sections of a page. They must form a nested outline, never be used for visual styling alone, and never skip levels.

## What it is

HTML defines six heading levels, `<h1>` through `<h6>`. They are the spine of a document's outline. Screen readers expose them as a navigable list, search engines weight them when working out what a page is about, and AI agents use them to chunk content.

```html
<h1>HSTS</h1>
<h2>What it is</h2>
<h2>Why it matters</h2>
<h3>For users on public Wi-Fi</h3>
<h2>How to implement</h2>
```

## Why it matters

Headings are the only structural signal that is consistent across browsers, screen readers, search engines, and AI tools. Get them right and the page becomes:

- **Navigable** for users of assistive technology, who jump heading-by-heading instead of scrolling.
- **Indexable** in chunks, so search engines and AI agents can quote a section without needing the whole page.
- **Maintainable**, because the outline matches the writing.

WCAG 2.4.6 (Level AA) requires headings and labels to describe the topic or purpose. Skipping levels or using a heading for its visual weight is a direct failure.

## How to implement

The rules are simple and rarely controversial:

- **One `<h1>` per page.** The HTML spec technically allows multiple in sectioning roots, but no major screen reader or search engine implements the document-outline algorithm. Stick to one `<h1>` per page — it should match the page title.
- **Do not skip levels.** Go `h1 → h2 → h3`, never `h1 → h3`. Levels can decrease by any amount on the way back up (`h3 → h2` is fine).
- **Headings describe sections, not styling.** If you want bigger text, use CSS. Never pick a heading level for its font size.
- **No heading without a section under it.** Every heading should have content. An `<h2>` followed immediately by another `<h2>` with nothing between them is a smell.
- **Keep headings short.** They are anchors, not paragraphs. Aim for under 70 characters.
- **Headings are unique within a page.** Two `<h2>` elements with the same text are confusing in a screen-reader rotor.
- **Visual headings need real heading tags.** A `<div class="heading">` is invisible to assistive tech. A `<p>` styled to look like an `<h2>` is invisible to search engines.

For component-driven design systems, expose the heading level as a prop (`<Heading level={2}>...</Heading>`) so the same component can render at the right level for its context.

## Common mistakes

- Using an `<h1>` per section because a designer wanted "big titles everywhere".
- Wrapping the site logo in `<h1>` on every page, so every page has the same H1.
- Skipping levels to get a smaller default size (use CSS).
- Hiding headings visually but leaving them in the DOM as the only outline — fine if intentional, broken if it becomes a maintenance burden.
- Putting interactive elements inside headings (buttons, dropdowns). Keep headings text-only.

## Verification

- Use the browser dev tools accessibility panel to view the heading outline.
- Run an automated check (axe, Lighthouse, WAVE). Skipped levels and empty headings are flagged immediately.
- Tab through the page with a screen reader's heading shortcut (`H` in NVDA, `VO+Cmd+H` in VoiceOver). Does the outline read like a table of contents?

### Sources
- HTML Living Standard — Headings and sections (WHATWG) — https://html.spec.whatwg.org/multipage/sections.html#headings-and-sections
- WCAG — Headings and Labels (2.4.6) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html
- Section Headings — ARIA Authoring Practices (W3C WAI) — https://www.w3.org/WAI/tutorials/page-structure/headings/
- MDN — Heading elements (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements

---

## Internal linking

Status: recommended  ·  Source page: https://specification.website/spec/seo/internal-linking/

Links from one page on a site to another. The strongest signal you control for telling crawlers and AI agents what a page is about and how important it is.

## What it is

An internal link is an `<a href>` from one URL on a site to another URL on the same site. Internal links form the graph that crawlers walk, that screen-reader users navigate, and that AI agents follow to gather context.

```html
<p>
  Read the <a href="/seo/xml-sitemaps">XML sitemap spec</a>
  to see how this page is discovered.
</p>
```

## Why it matters

Three audiences read internal links differently:

- **Crawlers** use them to discover pages and to weight importance. A page linked from the home page is considered more important than one linked only from a deep archive.
- **AI agents and answer engines** use anchor text as a strong signal for what the destination is about, often stronger than the destination's own `<title>`.
- **Humans** scan link text to decide whether the click is worth it.

Internal links are also the easiest SEO lever you fully control. External backlinks are won; internal links are decided.

## How to implement

Anchor text is the single most important variable.

- **Use descriptive anchor text.** "XML sitemap spec" is good. "Click here" tells the user and the crawler nothing.
- **Vary anchor text naturally.** Link the same destination from different pages using slightly different phrasings. Identical anchors on every link looks templated.
- **Link to the canonical URL** of the destination, not a redirect. Every link to a redirect costs a hop.
- **Link to topically related content.** Each article should link to two to five other relevant pages on the site. A page with zero outbound internal links is an orphan from the crawler's perspective even if it links inwards.
- **Avoid orphan pages.** Every URL in the sitemap should be reachable from at least one other page through normal navigation, not just from the sitemap itself.
- **Keep link depth shallow.** Pages more than three clicks from the home page get crawled and updated less often.
- **Cross-link from breadcrumbs.** They give crawlers a clean hierarchical view and let users escape upwards.
- **Open in the same tab unless there is a reason.** `target="_blank"` is for downloads and third-party flows, not internal navigation.

Avoid linking inside long lists of navigation that repeat on every page. Those count, but contextual links inside body content carry more weight per link.

## Common mistakes

- "Click here" or "read more" used as the only anchor text in the body.
- Hundreds of footer links to every page on the site. Dilutes the signal and clutters screen-reader rotors.
- Linking to staging or preview URLs by accident.
- Building the entire navigation in JavaScript with no `<a href>` fallback. Crawlers and screen readers cannot follow it.
- Pointing internal links at redirect chains created by an old migration.

## Verification

- Crawl the site and check the orphan-pages report. Anything in the sitemap but not reachable through links needs a contextual link added.
- Use Search Console's Links report to see the top linked-to pages. The list should match your idea of what is important.
- Check that anchor text varies and is descriptive — a crawler that exports a list of `(anchor, target)` pairs tells you a lot in one read.

### Sources
- Yoast — Internal linking for SEO (Yoast) — https://yoast.com/internal-linking-for-seo-why-and-how/
- Google — Links and link building (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/links-crawlable
- MDN — Creating hyperlinks (MDN) — https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links

---

## Structured data (JSON-LD)

Status: recommended  ·  Source page: https://specification.website/spec/seo/structured-data/

Machine-readable annotations that describe the content of a page using the schema.org vocabulary. JSON-LD is the format search engines and AI agents expect.

## What it is

Structured data is a set of machine-readable statements that describe what a page is about, using the shared vocabulary at [schema.org](https://schema.org/). The recommended serialisation is JSON-LD: a `<script type="application/ld+json">` block inside `<head>` (or, less commonly, `<body>`).

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "What is HSTS?",
  "datePublished": "2026-05-29",
  "author": {
    "@type": "Person",
    "name": "Jane Doe"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example",
    "url": "https://example.com"
  }
}
</script>
```

Microdata and RDFa are also accepted, but JSON-LD is the de facto standard because it sits separate from the visible markup.

## Why it matters

Two audiences read it heavily:

- **Search engines** use structured data to power rich results (article cards, breadcrumbs, FAQ accordions, product carousels, knowledge-panel facts). Without it, you get a plain blue link.
- **AI agents and answer engines** rely on it as the ground truth for facts they may quote. A `Person` schema with a `sameAs` linking to your verified profiles is the cleanest way to assert identity.

It is also the most stable contract between a publisher and the rest of the web. The HTML can change; the JSON-LD describes meaning.

## How to implement

Stick to a small set of well-supported types:

- **`WebSite`** — site-wide, on the home page. Include `url` and `name`, and `potentialAction` for sitelinks search if appropriate.
- **`Organization`** or **`Person`** — for the publisher and authors. Include `sameAs` arrays pointing at verified profiles.
- **`BreadcrumbList`** — on every page that has a breadcrumb trail.
- **`Article`** or **`BlogPosting`** — for articles, with `headline`, `datePublished`, `dateModified`, `author`, `image`.
- **`Product`**, **`Offer`**, **`AggregateRating`** — for e-commerce, where eligibility is strict.
- **`FAQPage`** — only when the page genuinely has a Q-and-A list visible to users. Google has restricted FAQ rich results to authoritative publishers; do not stuff fake FAQs.

Rules:

- **Mirror what is visible on the page.** Do not declare facts in JSON-LD that the page does not state. Google calls this "out of sync" data and ignores or penalises it.
- **One graph per page is cleaner than many fragments.** Use `@graph` to nest related entities and `@id` URIs to cross-reference them.
- **Use absolute URLs** in `@id`, `url`, `image`, and `sameAs`.
- **Keep dates in ISO 8601.**
- **Validate.** Schema.org evolves; what is valid one year may be deprecated the next.

## Common mistakes

- Fabricating `aggregateRating` or `Review` to win stars. Google detects this and removes the rich result, sometimes the whole site's eligibility.
- Marking up navigation, footers, or sidebars as if they were the main content.
- Forgetting to update structured data when the page content changes.
- Multiple disagreeing `@type` declarations across plugins or templates on the same page.

## Verification

- Use the [Schema.org validator](https://validator.schema.org/) for spec conformance.
- Use Google's [Rich Results Test](https://search.google.com/test/rich-results) for eligibility.
- Check Search Console's "Enhancements" reports after deployment.

### Sources
- Schema.org (schema.org) — https://schema.org/
- Introduction to structured data markup in Google Search (Google Search Central) — https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data
- JSON-LD 1.1 Specification (W3C) — https://www.w3.org/TR/json-ld11/
- Yoast — What is structured data? (Yoast) — https://yoast.com/what-is-structured-data/

---

## Breadcrumbs

Status: recommended  ·  Source page: https://specification.website/spec/seo/breadcrumbs/

A short trail showing the page's position in the site hierarchy. Visible in the UI for users, marked up as BreadcrumbList JSON-LD for search engines.

## What it is

Breadcrumbs are a short, one-line navigation trail showing the path from the site root to the current page. They serve users (an at-a-glance "where am I"), assistive technology (a labelled landmark to skip to or escape from), and search engines (a hierarchy signal that often replaces the URL in search results).

The visible markup is a `<nav>` containing an ordered list of links, with the current page marked using `aria-current`. The same trail is also serialised as JSON-LD `BreadcrumbList` for search engines.

```html
<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/seo">SEO</a></li>
    <li><a href="/seo/breadcrumbs" aria-current="page">Breadcrumbs</a></li>
  </ol>
</nav>
```

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home",        "item": "https://example.com/" },
    { "@type": "ListItem", "position": 2, "name": "SEO",         "item": "https://example.com/seo" },
    { "@type": "ListItem", "position": 3, "name": "Breadcrumbs", "item": "https://example.com/seo/breadcrumbs" }
  ]
}
</script>
```

## Why it matters

- **Search engines** display breadcrumb trails under the page title in results instead of the raw URL. A clean `Home › SEO › Breadcrumbs` reads better than `example.com/seo/breadcrumbs/`.
- **Screen-reader users** rely on the labelled `<nav>` landmark to find the trail in one keystroke.
- **Sighted users** use breadcrumbs to escape upwards, especially when they arrived from a search result deep in the site.
- **AI agents** parse the JSON-LD to understand the site's taxonomy, which helps them answer questions like "what is the parent topic of this page".

## How to implement

The pattern is small and stable; do it once and reuse it.

- **Wrap the trail in `<nav aria-label="Breadcrumb">`.** The label is what screen readers announce. "Breadcrumb" is the conventional value.
- **Use an ordered list (`<ol>`).** Order is part of the meaning.
- **Each item except the last is a link to its level.** The last item is the current page, marked `aria-current="page"`. It should not be a link.
- **Match the visible trail to the JSON-LD exactly.** Same items, same order, same names, same URLs.
- **Use a CSS separator (`::before`), not a literal `›` character in the markup.** Avoids the separator being announced as part of the link.
- **Anchor breadcrumbs at "Home".** Some sites omit Home, but including it makes the JSON-LD more useful and matches what Google displays.
- **Keep them short.** Three to five levels is normal; ten levels suggests the URL structure is too deep.

For dynamic sites, derive the trail from the URL or the page's place in the navigation tree, not from a hand-maintained per-page list.

## Common mistakes

- Visible trail and JSON-LD list disagree.
- The current-page item is a link to itself.
- `aria-label` missing or set to something unhelpful like "Navigation".
- Breadcrumbs based on the user's click path ("you came from Search") rather than the site hierarchy. That is "history", not "breadcrumbs".
- Adding a separator character inside the `<a>` text, so the link reads "Home ›".

## Verification

- Tab through with a screen reader. The trail should be announced as "Breadcrumb navigation, list with 3 items".
- Use the Rich Results Test to confirm Google recognises the `BreadcrumbList`.
- Visually check that the current-page item is not clickable.

### Sources
- Schema.org — BreadcrumbList (schema.org) — https://schema.org/BreadcrumbList
- Breadcrumb structured data (Google Search Central) — https://developers.google.com/search/docs/appearance/structured-data/breadcrumb
- ARIA Authoring Practices — Breadcrumb (W3C WAI) — https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/
- MDN — aria-current (MDN) — https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current

---

## IndexNow

Status: optional  ·  Source page: https://specification.website/spec/seo/indexnow/

An open protocol for telling participating search engines that a URL has changed. One HTTP request pushes Bing, Yandex, Naver, and Seznam to recrawl — Google does not participate.

## What it is

IndexNow is a simple push protocol that lets a site tell search engines a URL has been added, updated, or deleted. The publisher hosts a key file at the site root and sends an HTTP request to a participating endpoint listing the changed URLs. Bing, Yandex, Naver, Seznam, and Yep all consume the same feed; one submission propagates to all of them. Google does **not** participate.

The submission is a single GET or POST:

```http
POST /indexnow HTTP/1.1
Host: api.indexnow.org
Content-Type: application/json

{
  "host": "example.com",
  "key": "abc123...xyz",
  "keyLocation": "https://example.com/abc123xyz.txt",
  "urlList": [
    "https://example.com/articles/csp",
    "https://example.com/articles/hsts"
  ]
}
```

The key file at `https://example.com/abc123xyz.txt` must contain the same key as plain text — that proves you control the host.

## Why it matters

Discovery is the slowest part of indexing. A sitemap tells crawlers what exists; IndexNow tells them what just changed. For news, e-commerce stock changes, and price updates, that gap matters — Bing typically recrawls within minutes of an IndexNow ping versus hours or days from sitemap-only discovery.

It is also a low-effort improvement. A single endpoint covers every participating engine, no per-engine integrations needed.

Google's absence is the limiting factor. If most of your traffic is from Google, IndexNow is a nice-to-have. For markets where Bing, Yandex, or Naver have meaningful share (Russia, South Korea, the Czech Republic, US Bing-driven verticals), the impact is real.

## How to implement

The shape is straightforward:

1. **Generate a key.** 8 to 128 characters, `[a-zA-Z0-9-]`. Pick one and reuse it indefinitely.
2. **Host the key file at the site root.** `https://example.com/<key>.txt`, served as `text/plain`, body equal to the key.
3. **Submit URLs on change.** Fire a request to `https://api.indexnow.org/indexnow` (or directly to Bing's or Yandex's endpoint) after every publish, update, or unpublish event.
4. **Limit volume.** Up to 10,000 URLs per request. Do not send the entire sitemap on every cron tick — submit only what changed since the last call.
5. **Send deletions too.** A 404 or 410 should also be submitted; that is how participating engines learn to drop URLs quickly.

A small wrapper around your CMS publish hook is usually enough. Many SEO plugins (including Yoast) submit automatically.

## Common mistakes

- Submitting URLs that return non-200 statuses you did not mean to publish.
- Re-submitting on every page view rather than only on change.
- Hosting the key file at the wrong path or behind redirects. The key file must return 200 directly.
- Treating IndexNow as a Google signal. Google ignores the protocol — use Search Console's URL Inspection tool for one-off Google submissions.

## Verification

- `curl https://example.com/<key>.txt` should return the key as plain text.
- The endpoint returns `200 OK` on accepted submissions, `202` if quarantined, and `400`/`403`/`422` on errors. Log the response.
- Bing Webmaster Tools shows IndexNow activity under "URL Submission" — confirm the URLs appear there.

### Sources
- IndexNow protocol (IndexNow) — https://www.indexnow.org/documentation
- Bing — IndexNow (Bing) — https://www.bing.com/indexnow
- Yandex — IndexNow (Yandex) — https://yandex.com/support/webmaster/indexnow/key.html

---

# Accessibility

WCAG-aligned rules so people of all abilities can use the site.

## Colour contrast

Status: required  ·  Source page: https://specification.website/spec/accessibility/color-contrast/

Text and meaningful non-text elements must have enough contrast against their background so people with low vision and people in harsh light can read them.

## What it is

Contrast is the difference in luminance between the foreground (text, icons, control borders) and the background behind them. WCAG defines minimum ratios that pages must meet so that text remains legible for users with low vision, age-related sight loss, or colour vision deficiencies, and for everyone reading on a glare-filled screen.

## Why it matters

Low contrast is consistently the single most common automated accessibility failure on the web. It locks out users with low vision, makes content unreadable in bright sunlight, and degrades comprehension even for users with average vision. Meeting the contrast minimum is the cheapest, highest-impact accessibility fix you can make to a site.

## How to implement

WCAG 2.2 sets three thresholds you should know:

- **1.4.3 Contrast (Minimum) — AA.** Body text needs at least **4.5:1**. Large text (18pt, or 14pt bold) needs **3:1**.
- **1.4.6 Contrast (Enhanced) — AAA.** Body text **7:1**, large text **4.5:1**.
- **1.4.11 Non-text Contrast — AA.** Meaningful UI components (input borders, focus rings, icon-only buttons) and graphics needed to understand the content need at least **3:1** against adjacent colours.

Pick colour pairs from a palette that has been checked against these ratios. Use design tokens, not one-off hex values, so a single fix propagates.

```css
:root {
  --text: #1a1a1a;       /* 16.1:1 on white — comfortable */
  --text-muted: #595959; /* 7.0:1 on white — passes AAA */
  --link: #0b5fff;       /* 6.4:1 on white */
}
```

APCA (the contrast algorithm being prototyped for WCAG 3) gives a more perceptually accurate score, especially for dark mode. Treat it as a useful second opinion, not a replacement — conformance today is still measured against WCAG 2 ratios.

## Common mistakes

- Light grey body text on white ("#aaa on #fff" is 2.3:1 — a clear fail).
- Placeholder text used as the only label, set in a low-contrast grey.
- Brand-coloured buttons where the label sits below 4.5:1 on the button fill.
- Disabled states styled so low that sighted keyboard users cannot see which control has focus.
- Text laid over a busy image with no scrim or solid block behind it.

## Verification

- Run an automated checker (axe DevTools, WAVE, Lighthouse, Equalize Digital) on every template.
- Spot-check the reported failures by hand — automation can miss text on gradients or images.
- Test the page in greyscale and in a high-glare environment.

### Sources
- WCAG 2.4.3 — Contrast (Minimum) (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
- WCAG 1.4.6 — Contrast (Enhanced) (Level AAA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/contrast-enhanced.html
- WCAG 1.4.11 — Non-text Contrast (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html
- Accessibility Checker — Low Contrast (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/low-contrast/

---

## Image alt text

Status: required  ·  Source page: https://specification.website/spec/accessibility/image-alt-text/

Every <img> element must have an alt attribute. The value describes the image's purpose to screen readers, search engines, and anyone whose image fails to load.

## What it is

The `alt` attribute on `<img>` provides a text alternative for an image. Screen readers announce it, browsers display it when the image fails to load, and crawlers use it to understand the content. An `alt` is required on every `<img>`; the *value* depends on what the image does on the page.

## Why it matters

Images carry meaning. A product photo, a chart, an icon-only button, a decorative flourish — each plays a different role. Without an alt attribute, a screen-reader user hears the file name, or nothing at all, and loses that meaning. WCAG 1.1.1 is a Level A success criterion, which means failing it puts the page below the minimum bar.

## How to implement

Choose the alt value by asking what the image is doing on this page.

**Informative images** — convey content. Describe what is shown, in the context of the surrounding copy.

```html
<img src="bar-chart.png"
     alt="Sales by quarter: Q1 12k, Q2 18k, Q3 22k, Q4 30k.">
```

**Functional images** — act as a link or button. Describe the action, not the picture.

```html
<a href="/cart"><img src="cart.svg" alt="View basket"></a>
```

**Decorative images** — purely visual, add no information. Use an empty alt so assistive tech skips them.

```html
<img src="swirl.svg" alt="">
```

**Complex images** — charts, maps, infographics. Use a short alt plus a longer description nearby (a caption, a paragraph, or a `<figure>`/`<figcaption>` pair).

Two further rules:

- **Don't say "image of"** or "photo of". The screen reader already announces "graphic".
- **Don't use the file name.** "DSC_0142.jpg" is worse than no alt at all because users can't skip past it cleanly.

## Common mistakes

- Missing `alt` attribute entirely (different from `alt=""`).
- Decorative images with descriptive alts that interrupt the reading flow.
- Functional icon-only buttons with `alt=""`, leaving the button nameless.
- Duplicating the adjacent caption verbatim in the alt.
- Stuffing keywords into alt text for SEO.

## Verification

- Run an automated checker — Equalize Digital and axe both flag missing and suspicious alts.
- Disable images in the browser and read the page top to bottom. Does it still make sense?
- Listen to the page with a screen reader; decorative images should be silent.

### Sources
- WCAG 1.1.1 — Non-text Content (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html
- Accessibility Checker — Image Missing Alternative Text (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/image-missing-alternative-text/
- W3C WAI — Alt Decision Tree (W3C WAI) — https://www.w3.org/WAI/tutorials/images/decision-tree/

---

## Form labels

Status: required  ·  Source page: https://specification.website/spec/accessibility/form-labels/

Every form control needs a programmatically associated label. A placeholder is not a label, and an unlabelled input is unusable for screen-reader and voice-control users.

## What it is

A label is the human-readable name of a form control. It must be associated with the control in the accessibility tree so that assistive technologies announce it, click targets are extended to the label text, and voice-control users can say the field's name to focus it.

## Why it matters

An input without a label is a black box. A screen-reader user hears "edit, blank"; a voice-control user has nothing to say to reach it; a sighted user with a cognitive impairment can lose track of which field they are in when the placeholder disappears on focus. WCAG 3.3.2 (Level A) requires labels or instructions; 1.3.1 (Level A) requires that the relationship between label and field be programmatically determinable.

## How to implement

Prefer a visible `<label>` element associated by `for`/`id`:

```html
<label for="email">Email address</label>
<input type="email" id="email" name="email" autocomplete="email">
```

Wrapping the input inside the label works too:

```html
<label>
  Email address
  <input type="email" name="email" autocomplete="email">
</label>
```

When the visual design genuinely cannot show a label (an icon-only search field, for example), use `aria-label` or `aria-labelledby` — but only as a last resort:

```html
<input type="search" aria-label="Search the site">
```

A few hard rules:

- **Placeholder is not a label.** It disappears on focus, has poor contrast by default, and is invisible to many assistive tools.
- **Every checkbox and radio button** needs its own label, and the group needs a name from `<fieldset>`/`<legend>` or `role="group"` with `aria-labelledby`.
- **Required fields** should say so in the label (or in instructions), not only with an asterisk and colour.
- **Hidden labels** (`.visually-hidden`) are acceptable; `display: none` strips them from the accessibility tree.

## Common mistakes

- `<input placeholder="Email">` with no `<label>`.
- A label that sits next to the input but is not associated with it.
- An icon-only button with no `aria-label`.
- Reusing the same `id` for several inputs, so `for` points at the wrong one.
- A `<legend>` that names the form section but no labels on the individual radio buttons.

## Verification

- Tab through the form with a screen reader. Each control must announce a meaningful name.
- Inspect each input in the browser's accessibility panel — the "Name" must be set.
- Run an automated checker; "Missing Form Label" is a standard rule.

### Sources
- WCAG 3.3.2 — Labels or Instructions (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html
- WCAG 1.3.1 — Info and Relationships (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html
- Accessibility Checker — Missing Form Label (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/missing-form-label/
- WP Accessibility — Web Forms (WP Accessibility) — https://wpaccessibility.org/

---

## Keyboard navigation

Status: required  ·  Source page: https://specification.website/spec/accessibility/keyboard-navigation/

Every interactive element on the page must be reachable and operable with a keyboard alone, in a logical order, with no traps that hold focus.

## What it is

Keyboard navigation is the ability to reach and operate every control on a page using only a keyboard — Tab and Shift+Tab to move, Enter and Space to activate, arrow keys inside composite widgets, Escape to dismiss. Many users never touch a mouse: people using switch devices, screen readers, voice control, or just a laptop trackpad they find painful.

## Why it matters

If a control can be clicked but not focused, it does not exist for a large share of disabled users. WCAG 2.1.1 (Level A) requires all functionality to be operable from a keyboard. 2.1.2 (Level A) requires that focus is never trapped — the user must always be able to move on. 2.4.3 (Level A) requires the focus order to preserve meaning and operability.

## How to implement

The cheapest way to get keyboard support right is to use the right HTML element:

```html
<button type="button">Open menu</button>
<a href="/about">About</a>
<input type="checkbox" id="news"><label for="news">Subscribe</label>
```

Native `<button>`, `<a href>`, and form controls are focusable, operable, and announce their role for free. A `<div onclick>` gets none of that.

When you build a custom widget, you must add it back yourself:

- **`tabindex="0"`** to put a non-interactive element into the natural tab order.
- **`tabindex="-1"`** to make an element focusable only by script (useful for moving focus after a dialog opens).
- **Never use positive `tabindex`** — it overrides DOM order and creates surprises.
- **Key handlers** for the keys the role implies (Space and Enter on a button, arrows on a tab list, Escape on a dialog).
- **A visible focus style** so the user can see where they are.

Manage focus on view changes. When a dialog opens, move focus into it and trap it inside until it closes; then return focus to the element that opened it. Single-page navigations should move focus to the main heading of the new view.

## Common mistakes

- Click handlers attached to `<div>` or `<span>` with no role, tabindex, or key handlers.
- Modal dialogs that let Tab leak to the page underneath.
- Custom dropdowns that open on click but cannot be opened or operated from the keyboard.
- Positive `tabindex` values used to "fix" focus order, which then desynchronises with the visual layout.
- Hover-only menus that never receive focus.

## Verification

- Unplug the mouse. Walk through every interactive feature.
- Check that the focus order matches the visual reading order.
- Open every dialog, menu, and dropdown — press Escape and Tab to confirm focus is managed and never trapped.

### Sources
- WCAG 2.1.1 — Keyboard (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html
- WCAG 2.1.2 — No Keyboard Trap (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html
- WCAG 2.4.3 — Focus Order (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html

---

## Visible focus indicators

Status: required  ·  Source page: https://specification.website/spec/accessibility/focus-indicators/

Whenever a control receives keyboard focus, the page must show a clear, high-contrast indicator. Removing focus outlines without a replacement is a top accessibility failure.

## What it is

A focus indicator is the visible cue that tells a keyboard user which control will receive their next keystroke. Browsers ship one by default — usually a thin outline ring. WCAG 2.4.7 (Level AA) requires the active focus location to be visible at all times when navigating by keyboard.

WCAG 2.2 added two more rules. 2.4.11 (AA) requires that the focused element is not entirely hidden behind sticky headers or cookie banners. 2.4.13 (AAA) sets minimum size and contrast for the focus indicator itself.

## Why it matters

Without a focus ring, a keyboard user is navigating blind — they tab three times, do not know where they are, and give up. The single most common cause is a stylesheet that hides the default ring to "tidy up the design":

```css
/* Don't ship this. */
*:focus { outline: none; }
```

This is a Level AA failure. If you remove the default style, you must replace it with something equal or better.

## How to implement

Use `:focus-visible` so the focus style appears for keyboard users but not for every mouse click on a button:

```css
button:focus-visible,
a:focus-visible,
[role="button"]:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: 3px solid #0b5fff;
  outline-offset: 2px;
  border-radius: 4px;
}
```

Guidelines:

- **Contrast at least 3:1** against the adjacent colour, both focused and unfocused (1.4.11).
- **At least 2 CSS pixels thick** to meet 2.4.13's enclosed-area minimum.
- **Offset the outline** away from the control so it never disappears into the border.
- **Two-tone rings** (a light ring and a dark ring) work on any background.
- **Keep focus visible across sticky UI.** Use `scroll-margin` so anchor jumps land below sticky headers, and avoid full-viewport modals that overlay the focused element below.

`:focus-visible` is supported in every current browser. If you need to support older engines, pair it with `:focus` as a fallback.

## Common mistakes

- `outline: none` with no replacement.
- A focus style that only changes the text colour by a small amount.
- A focus ring drawn inside the button so the button's own background hides it.
- Sticky headers covering the focused control after Tab scrolls it into view.
- Custom widgets (cards, tab lists) that never style their focused state.

## Verification

- Tab through every page template; the focused control must be obvious from across the room.
- Check the contrast of the focus ring against its background.
- Resize the viewport and test with sticky headers in place — focus must stay visible.

### Sources
- WCAG 2.4.7 — Focus Visible (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html
- WCAG 2.4.11 — Focus Not Obscured (Minimum) (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html
- WCAG 2.4.13 — Focus Appearance (Level AAA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
- MDN — :focus-visible (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible

---

## Skip links

Status: recommended  ·  Source page: https://specification.website/spec/accessibility/skip-links/

A 'skip to main content' link as the first focusable element lets keyboard and screen-reader users jump past repeated navigation on every page.

## What it is

A skip link is an in-page anchor — usually the first focusable element in `<body>` — that jumps to the start of the main content. It is hidden until it receives focus, so it stays out of the sighted user's way but is the first thing a keyboard or screen-reader user hits.

## Why it matters

Every page on a site usually starts with the same header, navigation, search box, and notification bar. Without a skip link, a keyboard user tabs through twenty controls before reaching the article they came for, on every single page. Screen-reader users have heading and landmark shortcuts, but switch-device and Tab-only users have nothing. WCAG 2.4.1 (Level A) requires a mechanism to bypass blocks of repeated content; a skip link is the most widely supported way to satisfy it.

## How to implement

Put the link first in the document order and target the main content container:

```html
<body>
  <a class="skip-link" href="#main">Skip to main content</a>
  <header>…</header>
  <nav>…</nav>
  <main id="main" tabindex="-1">
    
  </main>
</body>
```

Style it so it is invisible by default and visible on focus:

```css
.skip-link {
  position: absolute;
  inset-inline-start: 1rem;
  inset-block-start: -3rem;
  background: #000;
  color: #fff;
  padding: 0.5rem 1rem;
  border-radius: 4px;
  z-index: 1000;
  transition: inset-block-start 0.15s;
}

.skip-link:focus {
  inset-block-start: 1rem;
}
```

Notes:

- **Use `display: none` is wrong.** It removes the link from the accessibility tree. Use offscreen positioning instead.
- **`tabindex="-1"`** on `<main>` ensures focus actually moves to it when the link is followed; some browsers otherwise just scroll the page.
- **One link is usually enough.** A second link to the navigation is fine if the nav is also long.
- **Keep the text plain.** "Skip to main content" is well understood.

## Common mistakes

- Skip link present but never visible on focus (no `:focus` style).
- Skip link points to a `<div>` with no `id`, or the target has been renamed.
- Skip link hidden with `display: none`, so it never receives focus.
- Decorative banners or cookie modals sit between the skip link and the main content and steal focus.

## Verification

- Load the page and press Tab once. The skip link must appear.
- Press Enter. Focus must move into the main content, not just scroll the page.
- Confirm the link is reachable on every template, not only on the homepage.

### Sources
- WCAG 2.4.1 — Bypass Blocks (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html
- W3C WAI — Skip Links (W3C WAI) — https://www.w3.org/WAI/WCAG22/Techniques/general/G1
- WebAIM — Skip Navigation Links (WebAIM) — https://webaim.org/techniques/skipnav/

---

## Semantic HTML and landmarks

Status: required  ·  Source page: https://specification.website/spec/accessibility/semantic-html/

Use the right HTML element for the job. Landmarks like <header>, <nav>, <main>, and <footer> let assistive technologies announce structure and skip between regions.

## What it is

Semantic HTML is the practice of using the element whose name matches its meaning — a heading is `<h1>` to `<h6>`, a list is `<ul>` or `<ol>`, a button is `<button>`, a navigation block is `<nav>`. Landmarks are the small set of elements (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`, `<section>` with a name, `<form>` with a name, `<search>`) that screen readers expose as a skippable region list.

## Why it matters

Assistive technology builds its model of the page from the tags. A screen-reader user presses a key to jump from heading to heading, from landmark to landmark, from form to form. None of that works on a page made of `<div>` soup. WCAG 1.3.1 (Level A) requires that information, structure, and relationships conveyed visually are also available programmatically — which in practice means using the right element.

## How to implement

A typical page skeleton:

```html
<body>
  <a class="skip-link" href="#main">Skip to main content</a>

<header>
    <a href="/" aria-label="Home">…logo…</a>
    <nav aria-label="Primary">
      <ul><li><a href="/about">About</a></li>…</ul>
    </nav>
  </header>

<main id="main">
    <article>
      <h1>Page title</h1>
      <p>…</p>
      <h2>Section heading</h2>
      <p>…</p>
    </article>

<aside aria-labelledby="related">
      <h2 id="related">Related</h2>
      …
    </aside>
  </main>

<footer>
    <nav aria-label="Footer"><ul>…</ul></nav>
  </footer>
</body>
```

Key rules:

- **Exactly one `<main>` per page.** Two mains break the landmark list.
- **Name every duplicate landmark** with `aria-label` or `aria-labelledby`. A page with two `<nav>` blocks needs each one named ("Primary", "Footer", "In page").
- **Headings form an outline.** Use one `<h1>`, then `<h2>` for sections, `<h3>` for sub-sections. Do not skip levels.
- **Lists are lists.** Wrap navigation items in `<ul>`; screen readers announce "list, six items".
- **ARIA roles only when no semantic equivalent exists.** Prefer `<nav>` over `role="navigation"`.

## Common mistakes

- A whole page of `<div>` and `<span>`, with no landmarks at all.
- Two `<main>` elements, or no `<main>`.
- Multiple unnamed `<nav>` elements — the landmark list shows "navigation, navigation, navigation".
- Headings used for size rather than structure (`<h4>` because "I wanted it smaller").
- A `<button>` that is actually a `<div role="button" onclick>` with no keyboard support.

## Verification

- Open the accessibility tree in the browser devtools and look at the landmark list.
- Use a screen reader's landmark and heading shortcuts to navigate the page.
- Run an automated checker; missing landmarks and skipped heading levels are standard rules.

### Sources
- WCAG 1.3.1 — Info and Relationships (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html
- MDN — HTML elements reference (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element
- W3C WAI — ARIA Landmarks (W3C WAI) — https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/
- WP Accessibility — Frontend code (WP Accessibility) — https://wpaccessibility.org/

---

## ARIA — first rule of ARIA

Status: recommended  ·  Source page: https://specification.website/spec/accessibility/aria-usage/

ARIA can make custom widgets accessible, but the first rule of ARIA is don't use ARIA. Reach for a native HTML element first; add ARIA only when nothing native fits.

## What it is

ARIA — Accessible Rich Internet Applications — is a set of HTML attributes (`role`, and the many `aria-*` attributes) that tell assistive technologies what a custom element is, what state it is in, and how it relates to other elements. ARIA never changes how something looks or behaves; it only affects the accessibility tree.

## Why it matters

ARIA is a sharp tool. Used well, it lets you describe widgets the HTML spec does not cover. Used badly, it overrides the real semantics of an element and makes the page *less* accessible than the unstyled HTML would have been. The W3C's own guide leads with five rules — and the first is the most important.

## How to implement

The five rules of ARIA, in plain English:

1. **Don't use ARIA if a native HTML element will do.** `<button>`, `<a href>`, `<input type="checkbox">`, `<details>` — these come with role, focus, and keyboard support for free.
2. **Don't change native semantics.** Never write `<h1 role="button">`. If you need a button, use a `<button>`.
3. **All interactive ARIA controls must be keyboard-operable.** A `role="button"` div without Space/Enter handlers is broken.
4. **Don't set `role="presentation"` or `aria-hidden="true"` on focusable elements.** You will hide controls from the very users who need them.
5. **Every interactive element needs an accessible name.** Use a visible label, `aria-label`, or `aria-labelledby`.

Common, useful ARIA attributes:

```html

<button aria-label="Close">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

<label for="pw">Password</label>
<input id="pw" type="password" aria-describedby="pw-hint">
<p id="pw-hint">At least 12 characters.</p>

<div role="group" aria-labelledby="format">
  <h3 id="format">Text format</h3>
  <button aria-pressed="true">Bold</button>
  <button aria-pressed="false">Italic</button>
</div>
```

- `aria-label` overrides the element's text — use only when there is no visible label.
- `aria-labelledby` points at the id of one or more existing elements; it takes precedence over `aria-label` and `<label>`.
- `aria-describedby` adds a description in addition to the name — for hints, errors, format examples.

## Common mistakes

- `role="button"` on a `<div>` with no `tabindex`, no key handlers, no focus style.
- Redundant roles: `<button role="button">`, `<nav role="navigation">`.
- `aria-label` written for SEO, in language different from the visible text — voice control users cannot say the visible text.
- `aria-hidden="true"` on a wrapper that contains a focusable button.
- ARIA states (`aria-expanded`, `aria-checked`) never updated by JavaScript when the UI changes.

## Verification

- Inspect every custom widget in the accessibility tree; the role, name, and state must match what is on screen.
- Run an automated checker for ARIA misuse.
- Test with a screen reader — the announcement must match how the control behaves.

### Sources
- ARIA Authoring Practices Guide — Read Me First (W3C WAI) — https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/
- Using ARIA (W3C) — https://www.w3.org/TR/using-aria/
- MDN — ARIA (MDN) — https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
- WCAG 4.1.2 — Name, Role, Value (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html

---

## Descriptive link text

Status: required  ·  Source page: https://specification.website/spec/accessibility/link-text/

Every link's text must describe where it goes. 'Click here' and 'read more' fail screen-reader users who scan a page by jumping from link to link.

## What it is

Link text is the visible (or accessible) name of a link — the bit screen readers announce and the bit a sighted user scans for. WCAG 2.4.4 (Level A) requires that the purpose of each link is determinable from the link text together with its immediate context. The stricter 2.4.9 (AAA) requires the link text alone to be enough.

## Why it matters

Screen-reader users routinely call up a list of all links on the page to navigate. If that list is "click here, click here, read more, read more, learn more", the page has no usable structure. Sighted users skim links too — descriptive link text helps everyone. Search engines also use link text as one of the strongest signals of what the target page is about.

## How to implement

Write link text that names the destination or the action:

```html

<p>To read our refund policy, <a href="/refunds">click here</a>.</p>

<p>Read our <a href="/refunds">refund policy</a>.</p>
```

For repeated "Read more" patterns on a card list, give each link a unique accessible name — the card heading is the easiest source:

```html
<article>
  <h2 id="post-42">How we cut bundle size by 60%</h2>
  <p>…</p>
  <a href="/blog/bundle-size" aria-labelledby="post-42">Read more</a>
</article>
```

Or include the title visually-hidden inside the link:

```html
<a href="/blog/bundle-size">
  Read more
  <span class="visually-hidden"> about cutting bundle size by 60%</span>
</a>
```

Further rules:

- **Don't put the URL in the link text** ("visit https://example.com/very/long/path") — screen readers spell it out character by character.
- **Don't repeat the destination twice** in the same paragraph with two different links.
- **Different link text for different destinations.** Two links named "Documentation" pointing at different pages are a fail.
- **Same link text for the same destination.** Two different names for the same URL is confusing.
- **Indicate file type and language changes** when relevant: "Annual report (PDF, 2.4 MB)".

## Common mistakes

- "Click here", "read more", "learn more", "here", with no context in the link itself.
- Image links with no alt text — the screen reader falls back to the URL.
- Identical link text on every card in a list, with no `aria-label` to disambiguate.
- A long sentence wrapped in `<a>` so the entire paragraph becomes the link text.
- Whitespace-only links produced by CSS background images.

## Verification

- Use a screen reader's link-list shortcut. Every entry should make sense out of context.
- Run an automated checker; "Ambiguous Anchor Text" is a standard rule.
- Read the page through a print stylesheet that lists every link — it should still be navigable.

### Sources
- WCAG 2.4.4 — Link Purpose (In Context) (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html
- WCAG 2.4.9 — Link Purpose (Link Only) (Level AAA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html
- Accessibility Checker — Ambiguous Anchor Text (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/ambiguous-anchor-text/
- WP Accessibility — Content and images: Links (WP Accessibility) — https://wpaccessibility.org/

---

## Empty links and buttons

Status: avoid  ·  Source page: https://specification.website/spec/accessibility/empty-links-buttons/

A link or button with no accessible name is invisible to screen readers and unreachable for voice control. Icon-only controls without a label are the usual culprit.

## What it is

An empty link or button is one where the accessibility tree records no name. Visually it might be a clear icon — a magnifying glass, a hamburger, an X — but the screen reader announces "link" or "button" with no further information. The user has no idea what it does.

This fails WCAG 2.4.4 (Level A, link purpose) and 4.1.2 (Level A, name role value) at the same time.

## Why it matters

Empty controls are at the top of every accessibility scanner's findings because they are easy to detect and ship in huge numbers. Icon-only buttons and image-only links are the usual sources: a designer placed an SVG inside a `<button>`, nobody added a label, and the control becomes a guessing game.

Voice-control users are hit hardest. Their software lets them say "click search" — but if the search button has no name, there is nothing to say.

## How to implement

Give every link and button an accessible name. Pick whichever fits the design:

**Icon plus visible text** (the easiest case):

```html
<button type="button">
  <svg aria-hidden="true" focusable="false">…</svg>
  Search
</button>
```

**Icon only — use `aria-label`**:

```html
<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>
```

**Image link** — give the `<img>` a useful `alt`:

```html
<a href="/"><img src="logo.svg" alt="Acme home"></a>
```

**Tooltip-only labelling is not enough.** A `title` attribute does not produce a reliable accessible name in every browser and assistive tech combination. Use `aria-label` or visible text instead.

Rules of thumb:

- Mark the SVG inside the button `aria-hidden="true"` and `focusable="false"` so the icon is not double-announced.
- If two controls do the same thing on the page (a top and a footer search), give them the same name.
- Never use a button as a styled wrapper around an empty span — the button has no name and no purpose.

## Common mistakes

- `<button><svg>…</svg></button>` with no label.
- `<a href="/"><img src="logo.svg"></a>` — image link with no alt text. The screen reader reads the URL.
- Empty `<a href="/path"></a>` left behind by a templating bug.
- Icon font glyphs (Font Awesome and similar) used as the only content with no label — the Unicode private-use character is announced as random nonsense.
- A label hidden with `display: none` instead of a visually-hidden utility, removing it from the accessibility tree.

## Verification

- Run an automated checker; "Empty Link" and "Empty Button" are direct, high-confidence findings.
- Inspect each icon-only control in the browser's accessibility panel — the Name field must be populated.
- Tab through the page with a screen reader and confirm every control announces something useful.

### Sources
- WCAG 2.4.4 — Link Purpose (In Context) (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html
- WCAG 4.1.2 — Name, Role, Value (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html
- Accessibility Checker — Empty Link (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/empty-link/
- Accessibility Checker — Empty Button (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/empty-button/

---

## Accessible form errors

Status: required  ·  Source page: https://specification.website/spec/accessibility/form-errors/

When a form submission fails, errors must be identified in text, associated with the input that caused them, and announced to assistive technology.

## What it is

An accessible form error tells the user three things, in text and in the accessibility tree: which field is wrong, what is wrong with it, and how to fix it. WCAG 3.3.1 (Level A) requires the field and the problem to be identified. 3.3.3 (Level AA) requires a fix to be suggested when known. 1.4.1 (Level A) forbids using colour as the only indicator.

## Why it matters

A red border alone is invisible to a screen-reader user, to a user with colour vision deficiency, and to a user reading on a sunlit phone. An error summary above the form helps everyone, but only if each error is also wired to its input — otherwise a screen-reader user reading the field on its own hears nothing wrong.

## How to implement

Associate each error message with its input using `aria-describedby` and mark the field invalid:

```html
<label for="email">Email address</label>
<input
  id="email"
  name="email"
  type="email"
  autocomplete="email"
  aria-invalid="true"
  aria-describedby="email-error"
  required>
<p id="email-error" class="error">
  Enter an email address in the format name@example.com.
</p>
```

For an error summary at the top of the form after submission, render it server-side or move focus to it with JavaScript:

```html
<div role="alert" aria-labelledby="error-heading">
  <h2 id="error-heading">There are 2 problems with your submission</h2>
  <ul>
    <li><a href="#email">Email address is not valid</a></li>
    <li><a href="#postcode">Postcode is required</a></li>
  </ul>
</div>
```

Rules:

- **Identify the error in text.** "Email is required" — not just a red border.
- **Tell the user how to fix it.** "Enter a date in the format DD/MM/YYYY", not "Invalid date".
- **Announce dynamically inserted errors.** Use `role="alert"` (assertive) or a live region (`aria-live="polite"`) so screen readers hear the change.
- **Set `aria-invalid="true"`** on the field — and remove it when the user corrects the value.
- **Don't rely on colour alone.** Pair red with an icon, a word ("Error"), or a heavier border.
- **Don't validate every keystroke.** Validate on blur or on submit; constant interruptions are unusable with a screen reader.

## Common mistakes

- Red outline as the only signal.
- Error text that appears in the DOM but is never associated with the input.
- A live region inserted *after* the message, so the message is never announced.
- Server-side errors that move the user back to the top of the page with no focus management.
- Generic messages: "Invalid input".

## Verification

- Submit a form with deliberately bad data using a screen reader. The error must be announced and reachable.
- Tab to each invalid field; the error text must be read along with the label.
- Test in grayscale to confirm the error state is visible without colour.

### Sources
- WCAG 3.3.1 — Error Identification (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html
- WCAG 3.3.3 — Error Suggestion (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html
- WCAG 1.4.1 — Use of Color (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html
- MDN — ARIA live regions (MDN) — https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions

---

## Document and parts language

Status: required  ·  Source page: https://specification.website/spec/accessibility/document-language/

Set the page's primary language on <html lang> and mark any inline content in a different language with its own lang attribute, so screen readers pronounce it correctly.

## What it is

The `lang` attribute tells browsers, screen readers, search engines, translation tools, and AI agents what language a piece of content is written in. WCAG 3.1.1 (Level A) requires the page's primary language to be set on the root `<html>` element. WCAG 3.1.2 (Level AA) requires any inline passage in a different language to be marked too.

The value is a BCP 47 language tag — `en`, `nl`, `de`, `pt-BR`, `zh-Hant` — not a free-text string.

## Why it matters

Screen readers switch their pronunciation and accent based on `lang`. Without it, a Dutch screen reader will sing English words like Dutch, and an English one will mangle French. Translation tools and AI agents use it to decide whether to translate the text. Spell-checkers, hyphenation, and quotation marks all depend on it.

A missing `lang` is a Level A failure — the lowest possible bar — and one of the easiest accessibility findings for an automated scanner to catch.

## How to implement

Set the page language on `<html>`:

```html
<!doctype html>
<html lang="en-GB">
  <head>…</head>
  <body>…</body>
</html>
```

For a French quotation inside an English page, wrap it and mark the language:

```html
<p>
  As Antoine de Saint-Exupéry wrote,
  <q lang="fr">on ne voit bien qu'avec le cœur</q> —
  one sees clearly only with the heart.
</p>
```

A few rules:

- **Use BCP 47 tags.** `en`, `en-GB`, `pt-BR` — not `english` or `EN_GB`.
- **Match the actual content language.** A site delivered in Dutch with `lang="en"` is worse than no lang at all.
- **Set the directionality too** when needed: `<html lang="ar" dir="rtl">`.
- **Loanwords don't count.** "Café" in an English sentence does not need `lang="fr"`. Mark whole quotations or passages, not individual borrowed words.
- **Update the attribute on language switches.** A single-page app that changes language in the navigation must update `document.documentElement.lang`.

Related: see the [foundations/html-lang](/spec/foundations/html-lang) page for the underlying HTML requirement.

## Common mistakes

- Template ships with `<html lang="en">` and never changes, regardless of which language the page is rendered in.
- `lang=""` (empty) — counts as missing.
- Full-language names ("english") instead of BCP 47 codes.
- Inline quotations in another language with no marker, mispronounced by every screen reader.
- Right-to-left content without `dir="rtl"`, breaking layout.

## Verification

- View source. `<html>` must have a non-empty `lang` matching the page's actual language.
- Listen to a sample with a screen reader and confirm pronunciation matches the language.
- Run an automated checker; missing or invalid `lang` is a standard high-confidence rule.

### Sources
- WCAG 3.1.1 — Language of Page (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html
- WCAG 3.1.2 — Language of Parts (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html
- Accessibility Checker — Missing Language Declaration (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/missing-language-declaration/
- MDN — The lang global attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang

---

## Reduced motion

Status: required  ·  Source page: https://specification.website/spec/accessibility/reduced-motion/

Respect the user's `prefers-reduced-motion` setting. Decorative animation, parallax, and autoplay can trigger vestibular distress, migraines, and seizures.

## What it is

Some users have signalled at the operating-system level that they want motion on screen reduced. The browser exposes that signal through the `prefers-reduced-motion` media query. When the value is `reduce`, the user is asking you to remove or shorten non-essential animation.

```css
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}
```

## Why it matters

Uncontrolled motion is not a taste issue. It causes real harm:

- **Vestibular disorders.** Parallax, zooming transitions, and long slide-ins can trigger nausea, dizziness, and disorientation that lasts for hours.
- **Migraine and photosensitivity.** Looping background video and flashing transitions are common triggers.
- **Seizure risk.** Anything flashing more than three times per second is a WCAG Level A failure (2.3.1).

WCAG 2.2.2 Pause, Stop, Hide (Level A) requires that any moving, blinking, scrolling, or auto-updating content lasting more than five seconds can be paused or stopped. WCAG 2.3.3 (Level AAA) goes further: motion triggered by interaction must be disableable unless essential to the function.

## How to implement

Cover both CSS animations and JavaScript-driven motion.

```js
const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
if (!reduce.matches) {
  startCarousel();
}
reduce.addEventListener('change', (e) => {
  e.matches ? stopCarousel() : startCarousel();
});
```

Apply the same logic to native media:

```html
<video autoplay muted loop playsinline>...</video>
```

Autoplaying background video should be gated on `prefers-reduced-motion: no-preference`, or shipped as a static poster image by default.

Distinguish decorative motion from meaningful motion. A spinner that says "loading" still needs to communicate; replace the spin with a static "Loading…" label or a very slow pulse. A tutorial transition that shows where a panel came from can be shortened to a fade rather than removed.

The worst offenders to audit first:

- Parallax scrolling.
- Large zoom or slide-in transitions on scroll.
- Autoplay carousels and sliders.
- Looping background video.
- Confetti, particle effects, and infinite marquees.

Browser support is universal across Chrome, Edge, Safari, and Firefox.

## Common mistakes

- Treating reduced motion as optional polish. It is a required accessibility behaviour.
- Removing transitions but leaving autoplay video running.
- Hiding the pause control behind a hover state on a touch device.
- Animating in JavaScript with no `matchMedia` check, so CSS overrides do nothing.

## Verification

- In macOS System Settings, enable **Accessibility → Display → Reduce motion**. Reload the page. Decorative animation should stop.
- In Chrome DevTools, open the command menu and run **Emulate CSS prefers-reduced-motion: reduce**.
- Confirm any motion longer than five seconds has a visible pause, stop, or hide control (WCAG 2.2.2).
- Confirm no content flashes more than three times in any one-second window.

### Sources
- WCAG 2.3.3 — Animation from Interactions (Level AAA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html
- WCAG 2.2.2 — Pause, Stop, Hide (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html
- MDN — prefers-reduced-motion (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
- WP Accessibility (WP Accessibility) — https://wpaccessibility.org/
- web.dev — prefers-reduced-motion: Sometimes less movement is more (web.dev) — https://web.dev/articles/prefers-reduced-motion

---

## Accessibility overlays

Status: avoid  ·  Source page: https://specification.website/spec/accessibility/accessibility-overlays/

Third-party JavaScript widgets that claim to make a site WCAG-compliant at runtime. They do not work, often harm screen-reader users, and attract lawsuits.

## What it is

Accessibility overlays are third-party JavaScript widgets — AccessiBe, UserWay, EqualWeb, AudioEye, and similar — that you paste into a page with a single script tag. They promise to detect accessibility problems and fix them automatically at runtime, usually with a floating button that opens a panel of toggles for font size, contrast, and similar controls.

```html

<script src="https://acsbapp.com/apps/app/dist/js/app.js"></script>
```

The marketing claim is that one line of code makes a site WCAG-compliant. It does not.

## Why it matters

Overlays do not fix accessibility. They frequently make it worse:

- They override native semantics with injected ARIA, which confuses screen readers that already understood the original markup.
- They cannot generate meaningful alt text, correct heading order, or sensible link names from nothing — the underlying HTML still has to be right.
- They ship visitor data, including assistive-technology fingerprints, to a third-party server, raising privacy and GDPR concerns.
- They are now a litigation magnet. More than 1,000 ADA web-accessibility lawsuits in the US in 2023 named sites that used an overlay; some named the overlay vendor as a co-defendant.
- Under the EU Web Accessibility Directive and the European Accessibility Act, public-sector bodies and many private services must publish an accessibility statement based on the real state of the site. An overlay does not change that state.

The Overlay Fact Sheet, signed by more than 800 accessibility professionals including most of the field's recognised experts, recommends against them outright. WebAIM's survey of users with disabilities found that the large majority who had encountered overlays rated them as unhelpful or actively harmful.

## What to do instead

Fix the underlying site. There is no shortcut, but the work is well-scoped:

- Start with [semantic HTML](/spec/accessibility/semantic-html/) — correct landmarks, headings, lists, buttons, and links.
- Use [ARIA](/spec/accessibility/aria-usage/) only where native HTML cannot express the role, and never to paper over broken markup.
- Make every interactive control reachable and operable with the [keyboard](/spec/accessibility/keyboard-navigation/), with visible [focus indicators](/spec/accessibility/focus-indicators/).
- Meet [colour contrast](/spec/accessibility/color-contrast/) minimums in your design tokens, not in a user-toggled overlay.
- Give every form control a real [label](/spec/accessibility/form-labels/).

Audit with a combination of automated and manual tools: axe DevTools, Lighthouse, WAVE, and the Equalize Digital Accessibility Checker for WordPress sites all catch a useful subset of issues. None of them replace manual testing with a real screen reader (VoiceOver on macOS or iOS, NVDA on Windows) and keyboard-only navigation. Fix issues incrementally and track them like any other defect.

## Common mistakes

- Installing an overlay because a vendor email warned of "ADA risk". The overlay increases that risk.
- Treating an overlay's compliance badge as a legal defence. Courts have repeatedly rejected it.
- Leaving an overlay in place "while we work on the real fixes". It interferes with the audit and with users.
- Disabling browser or OS accessibility settings the user already configured by overriding them in the widget.

## Verification

- Search the page source for known overlay scripts (`acsbapp.com`, `userway.org`, `equalweb.com`, `audioeye.com`). Remove them.
- Run axe DevTools, Lighthouse, and WAVE against representative pages and triage the findings.
- Navigate the site using only the Tab, Shift+Tab, Enter, and arrow keys. Every action must be reachable and visible.
- Test the main user journeys with VoiceOver or NVDA. The page should be usable without the widget.

### Sources
- Overlay Fact Sheet (Overlay Fact Sheet) — https://overlayfactsheet.com/
- WP Accessibility Knowledge Base (WP Accessibility) — https://wpaccessibility.org/
- WebAIM — Survey of Users with Disabilities on Accessibility Overlays (WebAIM) — https://webaim.org/projects/overlaysurvey/
- Equalize Digital — Accessibility Checker documentation (Equalize Digital) — https://equalizedigital.com/accessibility-checker/documentation/
- EU Web Accessibility Directive (European Commission) — https://digital-strategy.ec.europa.eu/en/policies/web-accessibility

---

## Captions and transcripts

Status: required  ·  Source page: https://specification.website/spec/accessibility/captions-and-transcripts/

Video needs synchronised captions, audio-only content needs a transcript, and visuals that carry meaning need audio description. Auto-captions alone are not enough.

## What it is

Any time-based media a page plays — a video, a podcast episode, a recorded talk — must come with a text alternative that conveys the same information. In practice this means three things:

- **Captions** for video with sound (WCAG 1.2.2, Level A).
- **A transcript** for audio-only content such as podcasts (WCAG 1.2.1, Level A).
- **Audio description** — or a full text alternative — when the visuals carry meaning the soundtrack does not (WCAG 1.2.3, Level A).

Captions are not the same as subtitles. Subtitles translate dialogue for hearing viewers. Captions are written for deaf and hard-of-hearing viewers and include speaker identification, laughter, music cues, and other non-speech sound.

## Why it matters

Without captions and transcripts, a video or podcast simply does not exist for a large part of the audience. Deaf and hard-of-hearing users need captions. Blind users need either a soundtrack that already describes the visuals, or a separate audio description track. People in noisy or quiet environments, second-language speakers, and search engines all benefit from the same text layer.

WCAG 1.2.1, 1.2.2, and 1.2.3 are all Level A — the minimum legal accessibility bar in most jurisdictions, including the European Accessibility Act and the US Section 508.

## How to implement

For self-hosted video, attach a WebVTT caption file using the HTML5 `<track>` element with `kind="captions"`:

```html
<video controls>
  <source src="/media/intro.mp4" type="video/mp4" />
  <track
    kind="captions"
    src="/media/intro.en.vtt"
    srclang="en"
    label="English"
    default
  />
  <track
    kind="descriptions"
    src="/media/intro.en.desc.vtt"
    srclang="en"
    label="English audio description"
  />
</video>
```

A WebVTT file is a plain `.vtt` text file starting with `WEBVTT`, followed by cue blocks:

```
WEBVTT

00:00:01.000 --> 00:00:04.500
[upbeat music]

00:00:04.600 --> 00:00:07.000
ANNA: Welcome to the show.
```

For audio-only content, publish a full transcript on the same page as the player — not behind a download link.

If visuals carry meaning the dialogue does not (an unspoken demo, a chart, an on-screen face), either record a version with descriptive narration baked in, add a `kind="descriptions"` track, or provide a media alternative in text.

For embedded video on YouTube or Vimeo, the responsibility still sits with you as the publisher: upload a corrected caption file, do not rely on auto-captions.

**Open captions** are burned into the video frame and always visible. **Closed captions** can be toggled. Closed is preferred — users can resize, restyle, and translate them.

## Common mistakes

- Shipping YouTube auto-captions unedited. They miss punctuation, mishear names, and are not WCAG-compliant.
- Treating subtitles as captions: dialogue only, no speaker labels, no sound effects.
- Putting the transcript on a separate page that is hard to find.
- Forgetting audio description on tutorial or demo videos where the screen carries the message.
- Setting `kind="subtitles"` when you mean `kind="captions"`.

## Verification

- Play the video with the sound off. Can you follow it from the captions alone?
- Play it with the screen off. Can you follow it from the soundtrack alone? If not, you need audio description.
- Validate the `.vtt` file at a WebVTT validator and confirm cues sync within 100 ms of speech.
- Run an automated accessibility scan (axe, Lighthouse) and confirm media elements have a `<track>` child.
- Test with a screen reader on the player page and confirm the transcript is reachable in the reading order.

### Sources
- WCAG 1.2.2 — Captions (Prerecorded) Level A (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/captions-prerecorded.html
- WCAG 1.2.3 — Audio Description or Media Alternative (Prerecorded) Level A (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/audio-description-or-media-alternative-prerecorded.html
- WCAG 1.2.1 — Audio-only and Video-only (Prerecorded) Level A (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/audio-only-and-video-only-prerecorded.html
- MDN — <track>: The Embed Text Track element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track
- WP Accessibility — Accessible media (WP Accessibility) — https://wpaccessibility.org/
- Media Accessibility User Requirements (W3C) — https://www.w3.org/TR/media-accessibility-reqs/

---

## Accessible data tables

Status: required  ·  Source page: https://specification.website/spec/accessibility/data-tables/

Tabular data must use real <table> markup with a caption, header cells, and scope attributes so screen readers can announce row and column relationships.

## What it is

A data table presents information where each cell only makes sense in the context of its row and its column. The `<table>` element, together with `<caption>`, `<thead>`, `<tbody>`, `<tfoot>` and `<th>`, encodes those relationships so that assistive technology can announce them as the user moves between cells.

## Why it matters

Sighted users scan a table visually — they see the column heading above a number and the row label to its left at the same time. Screen reader users cannot. They rely on the markup to be told, when they land on `£42`, that this is the **Price** column of the **Hardback** row. Without `<th>` and `scope`, that announcement does not happen and the table becomes a grid of disconnected values.

WCAG 1.3.1 Level A requires that information and relationships conveyed visually are also available in the markup. A layout `<table>` or a table built from `<div>`s fails this criterion.

## How to implement

A simple table needs a caption and one row of column headers:

```html
<table>
  <caption>Book prices, May 2026</caption>
  <thead>
    <tr><th scope="col">Format</th><th scope="col">Price</th></tr>
  </thead>
  <tbody>
    <tr><th scope="row">Hardback</th><td>£42</td></tr>
    <tr><th scope="row">Paperback</th><td>£18</td></tr>
  </tbody>
</table>
```

When headers span groups of rows or columns, use `scope="rowgroup"` and `scope="colgroup"`. When the structure is genuinely complex — multiple levels of headers, headers that don't line up — switch to the `id` and `headers` pattern:

```html
<table>
  <caption>Quarterly revenue by region</caption>
  <thead>
    <tr><td></td><th id="q1" scope="col">Q1</th><th id="q2" scope="col">Q2</th></tr>
  </thead>
  <tbody>
    <tr><th id="eu" scope="row">EU</th>
        <td headers="eu q1">€1.2m</td><td headers="eu q2">€1.4m</td></tr>
  </tbody>
</table>
```

For long extra context that won't fit in the caption, use `aria-describedby` pointing to a paragraph nearby.

Wide tables on narrow screens should scroll horizontally as a focusable region, so keyboard users can reach the off-screen columns:

```html
<div role="region" aria-label="Quarterly revenue" tabindex="0" style="overflow-x:auto">
  <table>…</table>
</div>
```

## Common mistakes

- Using `<table>` for page layout or for form field alignment. Use CSS Grid or Flexbox instead.
- `<td>` cells with bold text standing in for headers, with no `<th>`.
- A header row with no `scope` attribute — ambiguous for nested tables and complex headers.
- Hiding the caption with `display: none`; it is then also removed from the accessibility tree. Use a visually hidden class if you must.
- Setting `overflow-x: auto` on a `<div>` with no `tabindex` — mouse users can scroll, keyboard users cannot.

## Verification

- Tab through the table with a screen reader (VoiceOver, NVDA). Each data cell should be announced with its row and column header.
- Check the accessibility tree in DevTools. Headers should appear as `columnheader` or `rowheader`, not `cell`.
- Run an automated checker (axe, Lighthouse). It will flag missing `<th>`, missing `scope`, and layout tables.
- Disable CSS. The table should still read top-to-bottom in a sensible order.

### Sources
- WCAG 2.2 — 1.3.1 Info and Relationships (Level A) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html
- HTML Living Standard — Tabular data (WHATWG) — https://html.spec.whatwg.org/multipage/tables.html
- MDN — <table>: The Table element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table
- Web Accessibility Tutorials — Tables (W3C WAI) — https://www.w3.org/WAI/tutorials/tables/
- WP Accessibility (WP Accessibility) — https://wpaccessibility.org/

---

## Touch target size

Status: required  ·  Source page: https://specification.website/spec/accessibility/touch-target-size/

Interactive controls must be large enough to tap or click reliably. WCAG 2.2 sets a 24×24 CSS px minimum, with 44×44 CSS px as the enhanced target.

## What it is

A touch target is the area a user can tap, click, or otherwise activate to trigger a control — a button, a link, a checkbox, an icon. The target is not just the visible glyph; it is the full hit area the browser registers as activating the control.

WCAG 2.2 introduced a new Level AA success criterion, **2.5.8 Target Size (Minimum)**, that requires interactive targets to be at least **24×24 CSS pixels**. The older Level AAA criterion, **2.5.5 Target Size (Enhanced)**, asks for **44×44 CSS pixels**. Apple's Human Interface Guidelines recommend **44pt**, and Material Design recommends **48dp**.

## Why it matters

Small targets are easy to miss. That penalises:

- Users with motor impairments — Parkinson's, tremors, arthritis, limited fine-motor control.
- Users on small phones, or holding a phone one-handed on a commute.
- Older users, whose pointing precision declines with age.
- Anyone tapping while walking, in a moving vehicle, or wearing gloves.

Mis-taps are not just annoying. They can submit the wrong form, open the wrong link, or trigger destructive actions like "delete".

## How to implement

Set a minimum size on every interactive element:

```css
button,
a.button,
[role="button"] {
  min-height: 44px;
  min-width: 44px;
}
```

For icon-only buttons that must look small, expand the hit area with padding rather than shrinking the target:

```css
.icon-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-height: 44px;
  min-width: 44px;
  padding: 10px; /* hit area extends past the 24px icon */
  background: transparent;
  border: 0;
}
```

```html
<button class="icon-button" aria-label="Close dialog">
  <svg width="24" height="24" aria-hidden="true">…</svg>
</button>
```

If a target genuinely must be smaller than 24 CSS px — for example, a dense data table — WCAG 2.5.8 allows it as long as a **24 px diameter circle around the target's centre does not overlap any other target**. The spacing alone satisfies the criterion.

**Inline links inside running prose are exempt** from both criteria. A link in a sentence is sized by the line-height of the paragraph, and forcing 44 px around each one would wreck typography.

## Common mistakes

- Setting `font-size` but no `min-height` on a button, so its hit area collapses on short labels.
- Tiny close (×) icons in dialogs and toasts, 16 px or less, with no padding.
- Stacking small icon buttons (share, like, bookmark) directly next to each other with no spacing.
- Wrapping a small icon in a link without giving the `<a>` a block-level layout — the link only hits the glyph.
- Removing `padding` "to make the design tighter" and shipping a button you can only tap with a stylus.

## Verification

- Inspect the element in DevTools. Read the computed `width` and `height` (or the bounding box). Both must be at least 24 CSS px; aim for 44.
- On a real phone, try tapping every primary control with a thumb, one-handed. If you miss, it is too small.
- Run axe DevTools or Lighthouse — both flag WCAG 2.5.8 failures.
- For dense UIs, draw a 24 px circle around each target's centre and check no two circles overlap.

### Sources
- WCAG 2.5.8 — Target Size (Minimum) Level AA (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
- WCAG 2.5.5 — Target Size (Enhanced) Level AAA (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html
- Human Interface Guidelines — Layout (Apple) — https://developer.apple.com/design/human-interface-guidelines/layout
- Material Design — Accessibility: Layout and typography (Google) — https://m2.material.io/design/usability/accessibility.html#layout-and-typography
- WP Accessibility (WP Accessibility) — https://wpaccessibility.org/

---

## Hidden until found

Status: recommended  ·  Source page: https://specification.website/spec/accessibility/hidden-until-found/

Use hidden="until-found" (or content-visibility: hidden) for collapsible content so that browser find-in-page, assistive tech, and search engines can still reach the text and auto-expand it.

## What it is

`hidden="until-found"` is a value of the global `hidden` attribute defined in the HTML Standard. An element marked this way renders as if hidden — it takes up no visible space — but the browser's find-in-page (Ctrl/Cmd+F), the fragment-directive scroll-to-text, and `scrollIntoView()` still walk through it. When a match is found inside, the browser fires a `beforematch` event on the element, removes the `hidden` attribute, and scrolls the match into view.

Under the hood it is implemented through `content-visibility: hidden`, which behaves the same way: skipped for rendering, still reachable for find-in-page. Anything you can do with the attribute you can do with the CSS property — pick whichever fits your component.

## Why it matters

- `display: none` removes content from the accessibility tree and from find-in-page entirely. Accordion or tab patterns that hide panels with `display: none` are invisible to a user who knows the exact phrase they want.
- Find-in-page is a primary accessibility tool. Keyboard users, screen-reader users, users with cognitive disabilities, and anyone skimming a long document rely on it to locate content directly.
- Search engines and AI crawlers vary in how they treat content hidden with `display: none`. `hidden="until-found"` keeps the text in the DOM and reachable, which is the honest signal: this is real content, just collapsed by default.

## How to implement

Mark each collapsed panel and listen for `beforematch` so your widget state stays in sync:

```html
<button aria-expanded="false" aria-controls="panel-1">Shipping</button>
<div id="panel-1" hidden="until-found">
  We ship worldwide within 48 hours…
</div>
```

```js
const panel = document.getElementById('panel-1');
panel.addEventListener('beforematch', () => {
  const button = document.querySelector('[aria-controls="panel-1"]');
  button.setAttribute('aria-expanded', 'true');
  // remove any matching collapsed class on the button or panel
});
```

The CSS equivalent, for components that already have their own toggle class:

```css
.accordion-panel[data-collapsed] {
  content-visibility: hidden;
}
```

**Prefer `<details>/<summary>` where you can.** For the everyday "click a heading to expand a panel" pattern, the native disclosure element gives you focus management, keyboard handling, and find-in-page reachability with zero JavaScript. Reach for `hidden="until-found"` when you need a custom widget that `<details>` cannot model — a search-driven FAQ, a complex tab strip, an off-screen mega-menu that must still be findable.

## Common mistakes

- Using `display: none` on accordion panels and then wondering why users cannot find the content they remember reading. Switch the closed state to `hidden="until-found"`.
- Using `hidden="until-found"` for content that should be permanently hidden — error messages, off-screen utility nodes, suppressed admin tools. Use plain `hidden` or `display: none` instead.
- Forgetting to update `aria-expanded` and the visual chevron state in the `beforematch` handler. The panel opens but the button still claims it is collapsed.
- Treating it as a layout primitive. The element still participates in DOM order and document outline — it is hidden, not removed.

## Verification

- Open the page in Chrome or Edge. Press Ctrl/Cmd+F and search for a phrase that lives inside a collapsed panel. The browser should auto-scroll and reveal it.
- Repeat with a panel that uses `display: none`. The search should fail, confirming the regression you are avoiding.
- Tab through the widget with a screen reader (VoiceOver, NVDA, JAWS) and confirm the panel announces correctly once expanded.
- Inspect the element in DevTools after a match — the `hidden` attribute should be gone, the `beforematch` listener should have fired, and `aria-expanded` should read `true`.

### Sources
- HTML Standard — The hidden attribute (WHATWG) — https://html.spec.whatwg.org/multipage/interaction.html#the-hidden-attribute
- MDN — hidden global attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden
- Chrome for Developers — hidden=until-found and the beforematch event (Google) — https://developer.chrome.com/articles/hidden-until-found

---

## Native interactive elements

Status: recommended  ·  Source page: https://specification.website/spec/accessibility/native-interactive-elements/

Prefer native HTML interactive elements — <button>, <a>, <details>/<summary>, <dialog> — over divs with click handlers. You get keyboard support, focus management, and assistive-tech semantics for free.

## What it is

HTML ships a small set of interactive primitives — `<button>`, `<a href>`, `<details>`/`<summary>`, `<dialog>` — that come pre-wired with keyboard handling, focus management, ARIA roles, and browser behaviours. Reach for those first; reach for `<div role="button" tabindex="0">` only when the platform genuinely has no element for what you are building. The broader principle of "use the right tag" lives on [Semantic HTML](/spec/accessibility/semantic-html/); this page is about the interactive ones specifically.

## Why it matters

Replacing `<div onclick>` with `<button>` is not cosmetic. The native element gives you, with zero code:

- **Keyboard semantics.** `<button>` activates on ENTER and SPACE. `<a>` activates on ENTER. `<dialog>` closes on ESC. `<details>` toggles on ENTER or SPACE when `<summary>` has focus. Tab order is correct by default.
- **Focus management.** `<dialog>` traps focus inside the modal while open, returns focus to the opener on close, and renders in the top layer above other content.
- **Assistive-tech announcement.** Screen readers expose the right role ("button", "link", "dialog", "disclosure") and state ("expanded", "modal") without an `aria-*` attribute in sight.
- **Browser plumbing.** Open `<details>` state survives back/forward navigation. `<a>` populates history, supports middle-click and "open in new tab", honours `target` and `rel`.
- **Free maintenance.** Every browser ships fixes and refinements (animatable `<details>`, `::backdrop`, ESC-dismiss policy) without you changing a line.

Re-implement any of this in JavaScript and you have signed up to maintain it forever, with bugs.

## How to implement

**Disclosure / FAQ / accordion** — `<details>` and `<summary>`:

```html
<details>
  <summary>What is the return policy?</summary>
  <p>Returns are accepted within 30 days of delivery.</p>
</details>
```

Animate with modern CSS — no JavaScript needed:

```css
details::details-content {
  block-size: 0;
  overflow: hidden;
  transition: block-size 200ms, content-visibility 200ms allow-discrete;
  interpolate-size: allow-keywords;
}
details[open]::details-content { block-size: auto; }
```

**Modal dialog** — `<dialog>` with `showModal()`:

```html
<dialog id="confirm">
  <form method="dialog">
    <p>Delete this entry?</p>
    <button value="cancel">Cancel</button>
    <button value="confirm">Delete</button>
  </form>
</dialog>

<button type="button" onclick="confirm.showModal()">Delete</button>
```

`showModal()` opens it modally — focus is trapped, ESC dismisses, `::backdrop` styles the dim layer. Use `show()` for non-modal. For transient, non-blocking overlays (menus, tooltips, toasts) use the [Popover API](/spec/accessibility/popover-api/) instead.

**Buttons and links.** A `<button>` does something on the current page; an `<a href>` goes somewhere. Inside a `<form>`, always set `type="button"` on buttons that are not the submit:

```html
<button type="button" onclick="reset()">Reset</button>
```

## Common mistakes

- **`<div onclick>` as a button.** No keyboard activation, no focus, no accessible name, no role.
- **`<a href="#" onclick>` as a button.** Pollutes browser history, breaks middle-click and "open in new tab", and announces as a link in screen readers.
- **Rebuilding `<details>` in JavaScript "to control the animation".** Modern CSS — `interpolate-size`, `transition-behavior: allow-discrete`, `::details-content` — animates the native element.
- **Using `<dialog>` for transient, non-blocking UI.** Reserve `<dialog>` for modal flows that require a decision. For menus, popovers, and toasts, use the [Popover API](/spec/accessibility/popover-api/).
- **Forgetting `type="button"` inside a `<form>`.** A bare `<button>` defaults to `type="submit"` and submits the form on click.

## Verification

- Tab through the page. Every interactive thing must be reachable, in a sensible order, with a visible focus ring.
- Open Chrome DevTools → Elements → Accessibility tree. Confirm `details`, `dialog`, and `button` are exposed with the correct roles and states.
- Activate `<details>`, `<button>`, and `<dialog>` triggers using only the keyboard (ENTER, SPACE, ESC).
- In VoiceOver, open the Web Item Rotor — disclosure widgets and dialogs appear with the right labels.
- Search the codebase for `role="button"` and `onclick` on non-button elements. Each hit is a candidate for replacement.

### Sources
- WHATWG HTML — The details element (WHATWG) — https://html.spec.whatwg.org/multipage/interactive-elements.html#the-details-element
- WHATWG HTML — The dialog element (WHATWG) — https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
- MDN — <dialog> (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
- WAI-ARIA Authoring Practices (W3C WAI) — https://www.w3.org/WAI/ARIA/apg/

---

## CSS state and relational selectors

Status: recommended  ·  Source page: https://specification.website/spec/accessibility/css-state-selectors/

Use `:has()` together with `:user-invalid`, `:user-valid`, `:placeholder-shown` and `:focus-within` to express form and component state in CSS, removing the JavaScript class-toggling pattern and the race conditions it brings.

## What it is

Two related primitives let CSS describe state that previously needed JavaScript.

**`:has()`** is the relational pseudo-class. A parent matches based on what it contains, so an ancestor can style itself from a descendant's state. It is the missing "parent selector" that the platform spent two decades without.

**The `:user-*` form-state pseudo-classes** — `:user-invalid` and `:user-valid` — only apply *after* the user has interacted with a field. They sit on top of the HTML constraint-validation model alongside the older `:invalid` / `:valid`, `:required` / `:optional`, `:in-range` / `:out-of-range`, `:placeholder-shown`, `:focus-within`, and `:focus-visible`.

Together they let the stylesheet, not a `classList.toggle()` call, hold the truth about what is focused, filled, valid, or hovered.

## Why it matters

The pattern this replaces is everywhere:

```js
input.addEventListener('input', () => {
  field.classList.toggle('has-error', !input.checkValidity());
  field.classList.toggle('is-empty', input.value === '');
});
```

That code has to exist on every field, runs on every keystroke, races with framework re-renders, and silently drifts out of sync when an attribute changes outside the listener. Moving the same logic into CSS removes the listener, removes the drift, and respects the browser's own constraint-validation timing — which is what assistive technology already listens to.

This page covers the *visual state* layer. Accessible *messaging* — labels, live regions, error summaries, `aria-invalid` — belongs with [accessible form errors](/spec/accessibility/form-errors/) and [form labels](/spec/accessibility/form-labels/). Both layers are needed; neither replaces the other.

## How to implement

**Style a form from its contents with `:has()`.** The submit button dims while any field is invalid; the field row highlights while its input is focused:

```css
form:has(:user-invalid) button[type="submit"] {
  opacity: 0.5;
  pointer-events: none;
}

.field:has(input:focus) label {
  color: var(--accent);
}

.field:has(input:placeholder-shown) label {
  /* float-label pattern, no JS */
  transform: translateY(0.75rem);
}
```

**Prefer `:user-invalid` over `:invalid`.** `:invalid` matches the moment the page loads, so every required-but-empty field renders red before the user has typed a character. `:user-invalid` waits for interaction or submission:

```css
/* Wrong: red on first paint */
input:invalid { border-color: red; }

/* Right: red only after the user has tried */
input:user-invalid { border-color: red; }
input:user-valid   { border-color: green; }
```

Pair the colour with text and an icon — colour alone is not enough (see [form errors](/spec/accessibility/form-errors/)).

## Common mistakes

- Using `:invalid` instead of `:user-invalid`, so a fresh form looks broken before anyone interacts with it.
- Nesting `:has()` selectors so deeply that selector matching regresses on large DOMs. Keep depth shallow and the inner selector specific.
- Forgetting `:has()` can reach siblings via combinators inside the argument — `.field:has(+ .field input:user-invalid)` lets one row react to the next.
- Relying on colour alone for invalid state. Add an icon or text; the visual state must not be the only signal.
- Re-implementing `:focus-within` with JS focus/blur listeners. The pseudo-class already exists and stays in sync.

## Verification

- Reload a form with required fields. Nothing should be red until the user interacts — if it is, you are still using `:invalid`.
- Focus an empty required input and tab away. The field should turn red and the submit button should dim.
- In Chrome DevTools, the Styles pane has "Force element state" with `:user-invalid`, `:focus-within`, and `:placeholder-shown` — use it to verify each rule fires.
- Run a screen reader through the form and confirm the visual state does not stand in for the accessible error message. `aria-invalid` and the announced text still need to be there.

### Sources
- W3C Selectors Level 4 — Relational selector `:has()` (W3C) — https://www.w3.org/TR/selectors-4/#relational
- MDN — `:has()` (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/:has
- MDN — `:user-invalid` (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/:user-invalid
- HTML Living Standard — Constraint validation (WHATWG) — https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#constraint-validation

---

# Security

Headers, transport, and policies that keep visitors safe.

## HTTPS and TLS

Status: required  ·  Source page: https://specification.website/spec/security/https-tls/

Serve every page over HTTPS using TLS 1.2 or 1.3, redirect plain HTTP to HTTPS, and disable obsolete SSL and early TLS versions on every host you control.

## What it is

HTTPS is HTTP carried over TLS, a protocol that encrypts and authenticates the connection between the browser and the server. TLS 1.3 (RFC 8446) is the current version; TLS 1.2 remains acceptable. Everything earlier — TLS 1.0, TLS 1.1, and all versions of SSL — is broken and must be disabled.

## Why it matters

- **Confidentiality.** Without TLS, anyone on the path can read form data, cookies, and page content.
- **Integrity.** Network operators and middleboxes routinely inject ads, trackers, and malware into plain HTTP.
- **Authentication.** The certificate proves the visitor is talking to the right host, not a captive portal or attacker.
- **Modern web features.** Service workers, HTTP/2, HTTP/3, geolocation, camera, and most powerful browser APIs require a secure context.
- **SEO and trust.** Browsers mark HTTP pages as "Not Secure". Search engines prefer HTTPS.

## How to implement

Get a certificate from an ACME-supported certificate authority — Let's Encrypt and ZeroSSL are free, automated, and well supported. Most hosting platforms issue and renew certificates automatically.

Configure your server using the Mozilla SSL Configuration Generator. The "Intermediate" profile is the right default for public sites in 2026 — it supports TLS 1.2 and 1.3 and works on every browser still in use.

Redirect every HTTP request to HTTPS with a 301:

```http
HTTP/1.1 301 Moved Permanently
Location: https://example.com/path
```

Serve the same redirect on every hostname you own, including the apex, `www`, and any legacy subdomains. After HTTPS works, add [HSTS](/security/hsts/) so browsers stop trying HTTP at all.

Cipher and protocol checklist:

- TLS 1.3 enabled, TLS 1.2 enabled, everything older disabled.
- OCSP stapling on.
- Forward-secret cipher suites only (ECDHE).
- A complete certificate chain — serve the intermediate, not just the leaf.

## Common mistakes

- Mixed content: an HTTPS page that loads a script, image, or iframe over HTTP. Browsers block it.
- Self-signed certificates on production. Use a real CA.
- A valid certificate on `www.example.com` but not the apex `example.com`, or vice versa.
- Leaving TLS 1.0 or 1.1 enabled "for old clients" that no longer exist.
- Forgetting to renew. Automate it.

## Verification

- Run the [Qualys SSL Labs test](https://www.ssllabs.com/ssltest/) and aim for an A or A+.
- `curl -vI https://example.com` should report `TLS 1.3` or `TLS 1.2` and a valid chain.
- Visit `http://example.com` and confirm it 301s to `https://`.
- Check the browser console for mixed-content warnings.

### Sources
- RFC 8446 — The Transport Layer Security (TLS) Protocol Version 1.3 (IETF) — https://www.rfc-editor.org/rfc/rfc8446
- Mozilla SSL Configuration Generator (Mozilla) — https://ssl-config.mozilla.org/
- MDN — Transport Layer Security (MDN) — https://developer.mozilla.org/en-US/docs/Web/Security/Transport_Layer_Security
- Qualys SSL Labs Server Test (Qualys) — https://www.ssllabs.com/ssltest/

---

## HSTS (Strict-Transport-Security)

Status: required  ·  Source page: https://specification.website/spec/security/hsts/

HSTS tells browsers to use HTTPS for your domain only, for a long time. Add max-age, includeSubDomains, and preload — but understand it is an irreversible commitment.

## What it is

HTTP Strict Transport Security, defined in RFC 6797, is a response header that tells the browser: from now on, never speak HTTP to this host — only HTTPS. The browser remembers the instruction for the duration of `max-age` and refuses plain HTTP even if the user types it, clicks a stale link, or has DNS hijacked.

```http
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
```

## Why it matters

A 301 redirect from HTTP to HTTPS only protects the second request. The first request — and any cookies sent with it — already left the device in plain text. HSTS closes that gap. It also defends against active downgrade attacks where a network attacker strips the redirect and proxies the connection.

Without HSTS, every typed URL, bookmark, and external link to `http://example.com` is a moment when an attacker on the network can intercept the session.

## How to implement

Send the header on every HTTPS response. Browsers ignore it on plain HTTP.

Directives:

- **`max-age=<seconds>`** — required. How long the browser remembers. Start short (a few hours) to verify, then raise to two years (`63072000`) before preloading.
- **`includeSubDomains`** — applies the policy to every subdomain. Required for preload.
- **`preload`** — opts in to the browser preload list. Required for preload submission, and a commitment that you intend to stay on HTTPS.

Recommended production header:

```http
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
```

After running this header reliably for at least a few weeks, submit the domain at [hstspreload.org](https://hstspreload.org/). Preloaded domains are hard-coded into Chrome, Firefox, Safari, and Edge, so even the first visit on a fresh device uses HTTPS.

## Common mistakes

- **Sending HSTS over HTTP.** Browsers must ignore it. Send it on HTTPS responses only.
- **Setting `includeSubDomains` without auditing subdomains.** Every subdomain — including internal tools, staging, and legacy services — must work over HTTPS. If `dev.example.com` is HTTP-only, you have just broken it.
- **Setting `max-age=0` by accident.** That removes HSTS. Useful when rolling back, dangerous when copied from a tutorial.
- **Preloading too early.** Removal from the preload list takes months. Test thoroughly first.

## Verification

- `curl -sI https://example.com | grep -i strict-transport-security` should return the header.
- Check the preload status at [hstspreload.org](https://hstspreload.org/?domain=example.com).
- In Chrome DevTools, the Security panel shows HSTS state.
- After preload, `chrome://net-internals/#hsts` lists the domain as `static_sts_domain`.

HSTS is a commitment, not a switch. Plan the rollback path before you ship.

### Sources
- RFC 6797 — HTTP Strict Transport Security (HSTS) (IETF) — https://www.rfc-editor.org/rfc/rfc6797
- MDN — Strict-Transport-Security (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
- HSTS Preload List Submission (Google Chrome) — https://hstspreload.org/
- OWASP — HTTP Strict Transport Security Cheat Sheet (OWASP) — https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Strict_Transport_Security_Cheat_Sheet.html

---

## Content Security Policy (CSP)

Status: recommended  ·  Source page: https://specification.website/spec/security/content-security-policy/

A CSP tells browsers which sources of script, style, image, and frame content to trust. A good policy stops most XSS and data-exfiltration attacks dead.

## What it is

Content Security Policy is a response header that restricts which resources a page may load and execute. Level 3 is the current specification. The browser enforces the policy; any script, style, image, frame, or fetch from a source the policy does not allow is blocked, and a report is sent if a reporting endpoint is configured.

```http
Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-r4nd0m' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; report-to csp-endpoint
```

## Why it matters

The single biggest class of web vulnerabilities is cross-site scripting. A solid CSP turns a successful XSS injection from "attacker runs JavaScript in your origin" into "browser blocks the script and logs a violation". CSP also limits where data can be exfiltrated to, prevents your site from being framed, and disables dangerous legacy features like inline event handlers.

## How to implement

Build a strict, nonce-based policy. The recommended pattern from Google's strict CSP guidance:

```http
Content-Security-Policy:
  default-src 'self';
  script-src 'nonce-{random}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';
  frame-ancestors 'none';
  require-trusted-types-for 'script';
  report-to csp-endpoint
```

Key directives:

- **`default-src 'self'`** — fallback for all fetch directives. Allow your own origin by default.
- **`script-src`** — controls JavaScript. Use a per-response nonce; the `strict-dynamic` keyword lets a trusted script load further trusted scripts.
- **`style-src`** — controls CSS. Same nonce model where possible.
- **`img-src`, `font-src`, `connect-src`, `media-src`** — list the third parties you actually use.
- **`frame-ancestors 'none'`** — replaces `X-Frame-Options`. See [Clickjacking protection](/security/frame-ancestors/).
- **`object-src 'none'`** — kills Flash and plugin embeds.
- **`base-uri 'none'`** — blocks `<base>` tag injection attacks.
- **`report-to`** — endpoint that receives violation reports as JSON.

Generate a fresh nonce per response and embed it in every inline `<script>` tag.

## Common mistakes

- **`unsafe-inline` and `unsafe-eval`.** Either one neutralises most of the protection. Use nonces or hashes instead.
- **Wildcards like `script-src *` or `https:` alone.** Almost as bad as no policy at all.
- **No `frame-ancestors`.** Leaves clickjacking open.
- **Forgetting the nonce on server-rendered inline scripts.** The browser will block them and the page breaks.
- **Shipping a report-only policy forever.** Use `Content-Security-Policy-Report-Only` to test, then switch to enforcing.

## Verification

- `curl -sI https://example.com | grep -i content-security-policy` should return the header.
- Run the page through [Google CSP Evaluator](https://csp-evaluator.withgoogle.com/).
- Open DevTools → Console. CSP violations appear as `Refused to load …` errors.
- Wire up a reporting endpoint and watch for unexpected blocks before tightening.

### Sources
- Content Security Policy Level 3 (W3C) — https://www.w3.org/TR/CSP3/
- MDN — Content-Security-Policy (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
- OWASP — Content Security Policy Cheat Sheet (OWASP) — https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html
- Google — Strict CSP (web.dev) — https://web.dev/articles/strict-csp

---

## /.well-known/security.txt

Status: recommended  ·  Source page: https://specification.website/spec/security/security-txt/

A standard text file at /.well-known/security.txt tells security researchers how to report vulnerabilities. It is cheap to publish and dramatically lowers the bar for responsible disclosure.

## What it is

`security.txt` is a plain-text file served at `/.well-known/security.txt` that lists the contact methods, policy URL, and encryption keys a security researcher should use to report a vulnerability in your site. It is defined by RFC 9116.

```http
GET /.well-known/security.txt HTTP/1.1
Host: example.com
```

A minimal file:

```
Contact: mailto:security@example.com
Expires: 2027-01-01T00:00:00Z
```

## Why it matters

When a researcher finds a vulnerability, the first question is "who do I tell?". Without a known address, reports go to `info@`, get lost in support queues, or — worse — get posted publicly because no one answered. `security.txt` removes the guesswork. It is the security equivalent of `robots.txt`: a small, standard, machine-readable file in a known location.

Bug-bounty platforms, automated scanners, and security teams check for it. Publishing one signals that you take reports seriously, and many researchers will not bother with a site that has no clear contact.

## How to implement

Create the file at `/.well-known/security.txt`. Serve it over HTTPS with `Content-Type: text/plain; charset=utf-8`. RFC 9116 fields:

- **`Contact:`** — required. One or more `mailto:`, `https:`, or `tel:` URIs. Use a monitored mailbox or form.
- **`Expires:`** — required. ISO 8601 timestamp. Set it to roughly a year out and update it before it lapses.
- **`Encryption:`** — optional. URL to a PGP key for encrypted reports.
- **`Preferred-Languages:`** — optional. Comma-separated BCP 47 tags.
- **`Canonical:`** — optional. The canonical HTTPS URL of the file itself; helps when the file is mirrored.
- **`Policy:`** — optional. URL to your responsible-disclosure or bug-bounty policy.
- **`Acknowledgments:`** — optional. URL to a hall of fame.
- **`Hiring:`** — optional. URL to security-team job listings.

Full example:

```
Contact: mailto:security@example.com
Contact: https://example.com/security/report
Expires: 2027-05-29T00:00:00Z
Encryption: https://example.com/.well-known/pgp-key.txt
Preferred-Languages: en, nl
Canonical: https://example.com/.well-known/security.txt
Policy: https://example.com/security/policy
```

RFC 9116 allows the file to be cryptographically signed with an inline PGP signature. Useful for high-trust environments, optional for most sites.

## Common mistakes

- **No `Expires:`.** The file is invalid per RFC 9116 without it.
- **Letting `Expires:` lapse.** Treat it like a certificate. Calendar reminder, automated check, or both.
- **Pointing `Contact:` at an unmonitored address.** Worse than no file at all.
- **Serving the file from `/security.txt` instead of `/.well-known/security.txt`.** RFC 9116 says the well-known path is canonical.

## Verification

- `curl -s https://example.com/.well-known/security.txt` should return the file.
- The response must be `200` and `Content-Type: text/plain`.
- Parse it with the validator at [securitytxt.org](https://securitytxt.org/).
- Check the `Expires:` date in your monitoring.

### Sources
- RFC 9116 — A File Format to Aid in Security Vulnerability Disclosure (IETF) — https://www.rfc-editor.org/rfc/rfc9116
- securitytxt.org (securitytxt.org) — https://securitytxt.org/
- MDN — Well-known URIs (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Well-Known_URIs

---

## X-Content-Type-Options: nosniff

Status: required  ·  Source page: https://specification.website/spec/security/x-content-type-options/

The nosniff header stops browsers from guessing a response's content type. It blocks a class of attacks where a benign-looking file is interpreted as script or stylesheet.

## What it is

`X-Content-Type-Options: nosniff` is a response header that tells the browser to trust the `Content-Type` you sent and not to guess. It takes exactly one value: `nosniff`.

```http
X-Content-Type-Options: nosniff
```

The Fetch Standard makes this behaviour normative: when `nosniff` is present, the browser blocks script and stylesheet responses whose declared MIME type does not match the request.

## Why it matters

Historically, browsers performed "MIME sniffing" — looking at the bytes of a response and second-guessing the server's `Content-Type`. That convenience was also an attack surface. An attacker who could upload a file to a user-content directory could craft something that looked like an image to the server but executed as JavaScript when included with `<script src=…>`. The same trick worked for stylesheets, fonts, and Flash.

`nosniff` shuts that door. A `text/plain` response is not treated as script. A `text/html` response is not loaded as a stylesheet. The header is small, costs nothing, and removes an entire category of "the upload form is also an XSS vector" bugs.

## How to implement

Send the header on every response. Most web servers and CDNs let you set it globally; there is no reason to be selective.

Nginx:

```
add_header X-Content-Type-Options "nosniff" always;
```

Apache:

```
Header always set X-Content-Type-Options "nosniff"
```

Express (Node.js) — Helmet sets it by default.

In a CDN or edge worker, add the header to every response. There is no separate "report-only" mode — it is enforce-only.

Pair `nosniff` with correct `Content-Type` headers on every response. The directive only helps if your server actually labels responses properly. JavaScript files must be served as `application/javascript` (or `text/javascript`), CSS as `text/css`, JSON as `application/json`, and so on.

## Common mistakes

- **Multiple values.** The header takes one token, `nosniff`. Anything else is ignored or rejected.
- **Sending the wrong `Content-Type`.** With `nosniff` on, mislabelling a script as `text/plain` breaks the page. Fix the label, not the header.
- **Skipping it on uploads or user-content subdomains.** Those are exactly the responses where it matters most.
- **Assuming a CDN sets it.** Many do not. Check the actual headers from production.

## Verification

- `curl -sI https://example.com | grep -i x-content-type-options` should print `X-Content-Type-Options: nosniff`.
- Run [securityheaders.com](https://securityheaders.com/) against the site and check the score.
- Try fetching a JSON or text endpoint with `<script src=…>`. The browser console should report a MIME-type mismatch and refuse to execute it.
- Audit your CDN, static host, and origin separately — each layer can strip or override headers.

### Sources
- MDN — X-Content-Type-Options (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
- Fetch Standard — MIME type checks (WHATWG) — https://fetch.spec.whatwg.org/#x-content-type-options-header
- OWASP Secure Headers Project (OWASP) — https://owasp.org/www-project-secure-headers/

---

## Clickjacking protection (frame-ancestors / X-Frame-Options)

Status: required  ·  Source page: https://specification.website/spec/security/frame-ancestors/

Tell browsers who is allowed to embed your pages in an iframe. Use CSP frame-ancestors. X-Frame-Options is the legacy fallback.

## What it is

A clickjacking attack loads your site inside an invisible iframe on an attacker-controlled page, then tricks a logged-in user into clicking buttons they cannot see. The defence is to tell the browser which origins are allowed to embed your page.

CSP `frame-ancestors` is the modern mechanism:

```http
Content-Security-Policy: frame-ancestors 'none'
```

`X-Frame-Options` is the legacy header, still respected by browsers for compatibility:

```http
X-Frame-Options: DENY
```

CSP Level 2 onwards specifies that `frame-ancestors` supersedes `X-Frame-Options` when both are present in conformant browsers.

## Why it matters

Without an embedding policy, any site on the web can wrap yours in an iframe and overlay invisible controls. A user thinks they are clicking "Win a prize" on attacker.example; in reality they are clicking "Transfer money" or "Delete account" on your site, with their session cookie attached. The attack works against any authenticated action that can be triggered with a single click.

`frame-ancestors` makes the browser refuse to render the embedded page at all, which neutralises the whole class of attacks.

## How to implement

Default to refusing all framing, then loosen only where needed.

Refuse all embedding:

```http
Content-Security-Policy: frame-ancestors 'none'
X-Frame-Options: DENY
```

Allow same-origin embedding (for example, an admin app that frames its own pages):

```http
Content-Security-Policy: frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN
```

Allow specific external embedders:

```http
Content-Security-Policy: frame-ancestors 'self' https://partner.example.com
```

`X-Frame-Options` cannot express a list of allowed origins — the historic `ALLOW-FROM` value is not supported in any current browser. If you need a list, rely on `frame-ancestors` and accept that very old browsers fall back to "deny all" via `X-Frame-Options`.

Send the headers on every HTML response. Send them even on pages that "wouldn't make sense" framed; attackers will frame anything that performs an authenticated action.

Combine with `SameSite` cookies (see [Cookie attributes](/security/cookie-attributes/)) for defence in depth.

## Common mistakes

- **Setting only `X-Frame-Options`.** Modern policies, including allow-lists, live in CSP. Set both for now.
- **`ALLOW-FROM`.** Deprecated and unsupported. Use `frame-ancestors`.
- **Allowing too broad a parent.** `frame-ancestors https:` is barely better than nothing.
- **Setting the headers on the API but not the HTML.** Only the HTML response matters — the iframe is the HTML document.
- **Forgetting login and OAuth screens.** These are the highest-value pages to clickjack.

## Verification

- `curl -sI https://example.com | grep -iE 'frame-ancestors|x-frame-options'`.
- Build a tiny test page with `<iframe src="https://example.com">` on a different origin. The frame should refuse to load and the console should log a violation.
- Run the site through [securityheaders.com](https://securityheaders.com/).
- Check that the headers are present on every HTML route, not just the homepage.

### Sources
- OWASP — Clickjacking Defense Cheat Sheet (OWASP) — https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html
- MDN — CSP: frame-ancestors (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors
- MDN — X-Frame-Options (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options

---

## Referrer-Policy

Status: recommended  ·  Source page: https://specification.website/spec/security/referrer-policy/

Referrer-Policy controls how much URL information your site leaks when users follow a link or load a subresource. strict-origin-when-cross-origin is the sensible default.

## What it is

When a browser navigates from one page to another, or loads an image, script, or fetch, it normally sends the URL of the originating page in the `Referer` header. `Referrer-Policy` lets you control exactly how much of that URL is shared, per response.

```http
Referrer-Policy: strict-origin-when-cross-origin
```

The header is defined by the W3C Referrer Policy specification. Modern Chrome, Edge, Firefox, and Safari use `strict-origin-when-cross-origin` as the default when none is set.

## Why it matters

URLs leak. A path like `/account/reset?token=abc123` or `/internal/customers/4711/edit` should never end up in the access logs of an unrelated third party. Without a referrer policy, every outbound link and every third-party subresource carries the full URL of the page the user was on.

A sensible policy keeps internal URLs internal, hands cross-site requests only the origin (`https://example.com`), and gives partners and analytics tools enough context to be useful without exposing path or query parameters.

## How to implement

Send the header on every HTML response. The recommended baseline is the modern browser default:

```http
Referrer-Policy: strict-origin-when-cross-origin
```

This sends the full URL on same-origin requests, only the origin on cross-origin requests over HTTPS, and nothing at all on HTTPS-to-HTTP downgrades.

Available values, from most permissive to most restrictive:

- **`unsafe-url`** — always sends the full URL. Avoid.
- **`no-referrer-when-downgrade`** — legacy default. Sends the full URL except on HTTPS-to-HTTP.
- **`origin`** — always sends just the origin.
- **`origin-when-cross-origin`** — full URL same-origin, origin cross-origin.
- **`same-origin`** — full URL same-origin, nothing cross-origin.
- **`strict-origin`** — origin only, never on downgrades.
- **`strict-origin-when-cross-origin`** — recommended default.
- **`no-referrer`** — never send the header.

You can also override per element:

```html
<a href="https://partner.example.com" referrerpolicy="no-referrer">Partner</a>
<meta name="referrer" content="strict-origin-when-cross-origin">
```

Use a stricter policy (`same-origin` or `no-referrer`) on pages with sensitive URLs — password reset, account settings, internal tools.

## Common mistakes

- **Relying on the browser default.** Different browsers historically used different defaults. Be explicit.
- **Setting `no-referrer` site-wide.** Some partners legitimately need the origin to attribute traffic.
- **Forgetting per-page overrides.** A single `<meta name="referrer">` on a reset-password page is worth more than a generic header everywhere else.
- **Leaking tokens in URLs in the first place.** Referrer policy reduces blast radius — it does not fix the underlying mistake.

## Verification

- `curl -sI https://example.com | grep -i referrer-policy` should show the header.
- Open DevTools → Network, click an outbound request, and check the `Referer` value matches the policy.
- Audit the URLs of authenticated pages for tokens, IDs, or anything that would embarrass you in a partner's logs.

### Sources
- Referrer Policy (W3C Editor's Draft) (W3C) — https://www.w3.org/TR/referrer-policy/
- MDN — Referrer-Policy (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
- web.dev — A new default Referrer-Policy for Chrome (web.dev) — https://web.dev/articles/referrer-best-practices

---

## Permissions-Policy

Status: recommended  ·  Source page: https://specification.website/spec/security/permissions-policy/

Permissions-Policy lets you turn off powerful browser features — camera, microphone, geolocation, payment, USB — for your own pages and for any iframes you embed.

## What it is

`Permissions-Policy` is the response header that succeeds the older `Feature-Policy`. It tells the browser which powerful features may be used by the current document and by any documents embedded in iframes. Features include camera, microphone, geolocation, payment, USB, fullscreen, autoplay, accelerometer, and many others.

```http
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()
```

An empty allow-list `()` disables the feature entirely. `(self)` allows it on the current origin. `(self "https://embed.example.com")` allows it on the current origin and one named third party.

## Why it matters

The default state of the web grants pages access to many powerful APIs as soon as the user accepts a prompt. If you do not use the camera on your marketing site, there is no reason for an embedded ad iframe to be able to ask for it. Permissions-Policy lets you turn off features you do not need, both for your own code (defence against XSS expanding into hardware access) and for embedded third parties (defence against ad networks and trackers).

It is also a useful privacy signal: a site that explicitly disables geolocation is announcing it does not collect location data.

## How to implement

Send the header on every HTML response. Start by denying everything you do not use:

```http
Permissions-Policy: accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(self), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=()
```

Then enable only the features you actually need, scoped as narrowly as possible:

```http
Permissions-Policy: camera=(self), microphone=(self), geolocation=(self), fullscreen=(self)
```

To allow a specific third party — say, a video embed:

```http
Permissions-Policy: fullscreen=(self "https://player.vimeo.com"), autoplay=(self "https://player.vimeo.com")
```

You can also constrain a single iframe with the `allow` attribute:

```html
<iframe src="https://player.vimeo.com/video/123" allow="fullscreen; autoplay"></iframe>
```

The iframe's effective permissions are the intersection of the page policy and the `allow` attribute.

## Common mistakes

- **Using the older `Feature-Policy` syntax.** Permissions-Policy uses structured headers with `()` lists, not space-separated origins.
- **Forgetting to allow features you actually use.** If `camera=()` is set, your own WebRTC code stops working.
- **Allowing `*` to "fix" a broken iframe.** Narrow it to the specific origin instead.
- **Setting the header on the API but not the HTML.** Only the top-level HTML response counts.

## Verification

- `curl -sI https://example.com | grep -i permissions-policy` should print the header.
- Visit [permissionspolicy.com](https://permissionspolicy.com/) or use Chrome DevTools → Application → Frames → Permissions Policy to see the effective policy.
- Try `navigator.mediaDevices.getUserMedia({camera: true})` from the console on a page where camera is denied — it should reject with a permissions error.
- Audit embedded iframes; check that their `allow` attributes match what they actually need.

### Sources
- Permissions Policy (W3C Working Draft) (W3C) — https://www.w3.org/TR/permissions-policy/
- MDN — Permissions-Policy (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy
- web.dev — Permissions Policy (Chrome for Developers) — https://developer.chrome.com/docs/privacy-security/permissions-policy

---

## Subresource Integrity (SRI)

Status: recommended  ·  Source page: https://specification.website/spec/security/subresource-integrity/

SRI adds a cryptographic hash to every third-party script and stylesheet so the browser refuses to run modified files. Essential for any external JS or CSS you depend on.

## What it is

Subresource Integrity is a W3C standard that lets you pin the exact content of a script or stylesheet. You include a cryptographic hash of the file in the `integrity` attribute, and the browser refuses to execute the resource if the hash does not match.

```html
<script
  src="https://cdn.example.com/widget.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
  crossorigin="anonymous"
></script>
```

SRI applies to `<script>` and `<link rel="stylesheet">`, and also `<link rel="preload">` and `<link rel="modulepreload">`.

## Why it matters

Every external script you load runs with full access to your origin. If the CDN is compromised, if an attacker buys an abandoned npm package, or if a CDN ops mistake swaps a file, that script can read cookies, exfiltrate form data, and rewrite the DOM. SRI shifts trust from "the CDN is currently honest" to "the file is byte-for-byte the one we audited".

This is the standard defence against the kind of supply-chain attack that hit Magecart, Polyfill.io, and Event-Stream. CSP can restrict which hosts you trust; SRI restricts which specific files you trust on those hosts.

## How to implement

For every external script or stylesheet, compute a SHA-384 hash of the exact file content and include it in the `integrity` attribute. Add `crossorigin="anonymous"` so the browser sends a CORS request and can verify the response without credentials.

```html
<link
  rel="stylesheet"
  href="https://cdn.example.com/styles.css"
  integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC"
  crossorigin="anonymous"
>
```

Generate the hash on the command line:

```
curl -s https://cdn.example.com/widget.js | openssl dgst -sha384 -binary | openssl base64 -A
```

SRI supports `sha256`, `sha384`, and `sha512`. SHA-384 is the recommended default. You may list multiple hashes separated by spaces; the browser passes the resource if any one matches — useful for a graceful version rollover.

Pair SRI with a strict CSP. CSP says "only load scripts from these hosts"; SRI says "and only this exact file from that host".

## Common mistakes

- **Forgetting `crossorigin="anonymous"`.** Without it, the browser silently refuses to validate the integrity and the script is blocked.
- **Pinning to a "latest" CDN URL.** The hash and the URL must match a specific immutable version. Use `/widget@1.2.3/widget.js`, never `/widget/widget.js`.
- **Updating the script but not the hash.** The page breaks. Automate hash generation in your build.
- **Using SRI on first-party assets you already control.** It is harmless but not the highest-value place to spend the effort; reserve attention for third parties.

## Verification

- View source. Every `<script src="https://…">` and external `<link rel="stylesheet">` should have an `integrity` and `crossorigin` attribute.
- Tamper with a byte of the file (via a local proxy) and confirm the browser refuses to run it; the console reports "Failed to find a valid digest".
- Use a tool like [SRI Hash Generator](https://www.srihash.org/) to compute hashes for ad-hoc checks.
- Audit dependency upgrades: any time a third-party file URL changes, the hash must change with it.

### Sources
- Subresource Integrity (W3C Recommendation) (W3C) — https://www.w3.org/TR/SRI/
- MDN — Subresource Integrity (MDN) — https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
- OWASP — Third Party JavaScript Management Cheat Sheet (OWASP) — https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html

---

## Cookie attributes — Secure, HttpOnly, SameSite

Status: required  ·  Source page: https://specification.website/spec/security/cookie-attributes/

Every cookie should be Secure, HttpOnly where possible, and have an explicit SameSite. Use __Host- and __Secure- prefixes for session cookies.

## What it is

Cookies carry session state, authentication, and preferences. The `Set-Cookie` response header has a handful of attributes that decide how much the cookie can be abused if something goes wrong. Setting them correctly is one of the cheapest, highest-impact security wins on any site.

```http
Set-Cookie: __Host-session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax
```

The attributes below are specified in RFC 6265bis (the in-progress update to RFC 6265).

## Why it matters

A cookie without `Secure` can leak over plain HTTP. A cookie without `HttpOnly` can be read by any JavaScript that runs in the page — including XSS payloads. A cookie without `SameSite` is attached to cross-site requests, which is exactly what CSRF needs. Modern browsers default `SameSite` to `Lax` when not set, but relying on the default leaves older clients and edge cases unprotected.

## How to implement

Set these attributes on every cookie unless you have a specific reason not to.

- **`Secure`** — sent only over HTTPS. Mandatory on any cookie that carries identity. Required for `SameSite=None`.
- **`HttpOnly`** — not exposed to `document.cookie`. Use on every session cookie. Skip it on cookies your JavaScript genuinely needs to read (preferences, A/B test bucket).
- **`SameSite=Lax`** — sent on top-level navigations to your site but not on cross-site iframes, images, or `fetch`. Sensible default for session cookies.
- **`SameSite=Strict`** — sent only on requests originating from your own site. Strongest CSRF defence; breaks the common pattern of arriving via an external link while already logged in.
- **`SameSite=None; Secure`** — required for cross-site cookies (third-party widgets, SSO, embedded checkouts). Use sparingly.

### Cookie prefixes

Two browser-enforced prefixes raise the bar further:

- **`__Secure-`** — the cookie name must start with `__Secure-`, and the browser only accepts the cookie if it has the `Secure` attribute.
- **`__Host-`** — name starts with `__Host-`, the cookie must be `Secure`, must have `Path=/`, and must not have a `Domain` attribute. Pins the cookie to the exact host.

Use `__Host-` for session cookies whenever you can. It blocks subdomain takeover from rewriting the session cookie.

```http
Set-Cookie: __Host-session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax
Set-Cookie: __Secure-prefs=dark; Path=/; Secure; SameSite=Lax; Max-Age=31536000
```

Always set an explicit `Path`, `Max-Age` or `Expires`, and a sensible value length. Avoid `Domain=example.com` unless you really need the cookie on subdomains.

## Common mistakes

- **No `Secure`.** A single HTTP request leaks the cookie.
- **No `HttpOnly` on session cookies.** Any XSS becomes an account takeover.
- **`SameSite=None` without `Secure`.** Modern browsers reject the cookie outright.
- **Putting `__Host-` on a cookie with `Domain` set.** Browser ignores it.
- **Sharing one cookie across many subdomains by default.** Set `Domain` only when you actually need it.

## Verification

- DevTools → Application → Cookies. Each row shows the attributes. Confirm `Secure`, `HttpOnly`, and `SameSite` on every session cookie.
- `curl -sI https://example.com | grep -i set-cookie`.
- Try setting `__Host-foo=1; Path=/` from a page without `Secure` — the browser should refuse.
- Audit cookies served by third parties; their defaults are not your defaults.

### Sources
- draft-ietf-httpbis-rfc6265bis — Cookies: HTTP State Management Mechanism (IETF) — https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis
- MDN — Set-Cookie (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
- OWASP — Session Management Cheat Sheet (OWASP) — https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
- web.dev — SameSite cookies explained (web.dev) — https://web.dev/articles/samesite-cookies-explained

---

## DNS CAA records

Status: recommended  ·  Source page: https://specification.website/spec/security/caa-records/

A CAA record tells certificate authorities which of them are allowed to issue certificates for your domain. Cheap to add, blocks a class of mis-issuance attacks.

## What it is

A Certification Authority Authorization record is a DNS record that names the certificate authorities allowed to issue TLS certificates for your domain. Specified in RFC 8659, CAA records are mandatory for CAs to check before issuing a publicly trusted certificate. Any CA that finds a CAA record listing a different issuer must refuse the request.

```
example.com.    300    IN    CAA    0 issue "letsencrypt.org"
example.com.    300    IN    CAA    0 issuewild "letsencrypt.org"
example.com.    300    IN    CAA    0 iodef "mailto:security@example.com"
```

## Why it matters

There are around 50 publicly trusted certificate authorities. Without a CAA record, any of them can issue a certificate for your domain — and historically several have, by mistake or after social engineering. A CAA record narrows that list to the CAs you actually use. If an attacker tricks a different CA into issuing a certificate, that CA's automated checks refuse the request before the certificate is signed.

CAA records do not encrypt or sign anything themselves. They are simply a published policy that compliant CAs must honour.

## How to implement

Add CAA records at the apex of your domain. They cover all subdomains unless overridden.

Common tags:

- **`issue`** — names a CA permitted to issue any certificate. A bare hostname like `letsencrypt.org` is the standard form. `";"` (a single semicolon) explicitly forbids all issuance.
- **`issuewild`** — names a CA permitted to issue wildcard certificates. Set this only if you need wildcards.
- **`iodef`** — an email or URL where CAs report failed checks (Incident Object Description Exchange Format).

Recommended starter set for a site using Let's Encrypt:

```
example.com.    300    IN    CAA    0 issue "letsencrypt.org"
example.com.    300    IN    CAA    0 issuewild ";"
example.com.    300    IN    CAA    0 iodef "mailto:security@example.com"
```

To allow a second CA (for redundancy or a different product):

```
example.com.    300    IN    CAA    0 issue "letsencrypt.org"
example.com.    300    IN    CAA    0 issue "sectigo.com"
```

Some CAs support extra parameters that pin the policy to a specific account or validation method. Let's Encrypt documents the `accounturi` and `validationmethods` extensions, which let you lock issuance to a specific ACME account.

Pair CAA with [DNSSEC](/security/dnssec/) where possible. CAA without DNSSEC still helps — CAs check it — but DNSSEC stops an attacker from spoofing the DNS response.

## Common mistakes

- **No CAA record at all.** Every public CA may issue. Set at least one record.
- **Forgetting `issuewild`.** Without it, issuance of wildcards inherits the `issue` tag, which may be more permissive than you intend.
- **Listing a CA you no longer use.** Audit the records when you change provider.
- **Setting CAA on a subdomain you do not control issuance for.** Records at the apex are usually enough; only override per-subdomain when needed.

## Verification

- `dig CAA example.com +short` lists the records.
- Use the [SSLMate CAA Test](https://sslmate.com/caa/) or `curl -s "https://crt.sh/?q=example.com"` to confirm only expected CAs have issued certificates.
- Try to issue a test certificate from a CA not on the list; the issuance should fail with a CAA error.
- Monitor `iodef` mail for unexpected attempts.

### Sources
- RFC 8659 — DNS Certification Authority Authorization (CAA) Resource Record (IETF) — https://www.rfc-editor.org/rfc/rfc8659
- Let's Encrypt — CAA (Let's Encrypt) — https://letsencrypt.org/docs/caa/
- MDN — DNS — CAA records (MDN) — https://developer.mozilla.org/en-US/docs/Glossary/CAA_record

---

## DNSSEC

Status: optional  ·  Source page: https://specification.website/spec/security/dnssec/

DNSSEC cryptographically signs DNS records so resolvers can verify they have not been tampered with. Strong defence in depth, but only with full registrar and registry support.

## What it is

DNS Security Extensions add cryptographic signatures to DNS records. A signed zone publishes a public key (`DNSKEY`); each record set is signed (`RRSIG`); the parent zone publishes a hash of your key (`DS`) so a resolver can build a chain of trust from the DNS root down to your domain. Defined originally in RFC 4033 and 4035, with operational guidance in RFC 9364.

A validating resolver that asks for `www.example.com` checks every signature on the way and refuses to return a forged answer.

## Why it matters

Plain DNS is unauthenticated. Anyone on the network path — a coffee-shop router, a compromised ISP, a malicious resolver — can lie about which IP your domain points to, where mail should go, or what TXT records exist. That undermines TLS issuance (because Domain Validation depends on DNS or HTTP that depends on DNS), email security (SPF, DKIM, DMARC live in TXT records), and CAA enforcement.

DNSSEC closes the cache-poisoning and on-path spoofing surface for any resolver that validates. It is also a prerequisite for protocols like DANE, which pin TLS keys in DNS.

The honest caveat: DNSSEC is operationally tricky. A misconfiguration — a missing `DS` record after a key rollover, an expired signature — takes your whole domain offline for validating resolvers, which is much worse than the average outage. The benefit is real but only worth taking on with tooling that handles rollovers automatically.

## How to implement

1. **Check support.** Your DNS provider must sign your zone, and your registrar must publish a `DS` record at the parent registry. Most managed DNS providers (Cloudflare, Route 53, Google Cloud DNS, DNSimple) can do both, often with a single toggle. Some legacy registrars cannot.
2. **Enable signing at the DNS provider.** This generates a Key Signing Key (KSK) and a Zone Signing Key (ZSK), publishes `DNSKEY` records, and signs every record set.
3. **Publish the `DS` record at the registrar.** Some providers automate this via CDS/CDNSKEY; otherwise you copy the `DS` from the provider's UI to the registrar's UI.
4. **Verify the chain.** Use `dig +dnssec` or [Verisign DNSSEC Debugger](https://dnssec-analyzer.verisignlabs.com/) to confirm every signature validates and the `DS` at the parent matches.

Example records (truncated):

```
example.com.    3600    IN    DNSKEY    257 3 13 mdsswUyr3DPW132mOi8V9xESWE8j...
example.com.    3600    IN    RRSIG     A 13 2 3600 20260701000000 20260601000000 12345 example.com. ...
com.            86400   IN    DS        12345 13 2 1F987CC6583E92DF0890718C42...
```

Algorithm 13 (ECDSA P-256 with SHA-256) is the recommended modern default; it is small, fast, and widely supported.

Operational hygiene:

- Automate key rollovers (KSK and ZSK). Manual rollovers fail.
- Monitor signature expiry. An expired `RRSIG` is an outage.
- Re-publish `DS` whenever the KSK rotates.
- Pair with [CAA records](/security/caa-records/) for defence in depth around certificate issuance.

## Common mistakes

- **Signing the zone but never publishing the `DS`.** Resolvers ignore the signatures — no protection.
- **Manual key management.** Rollovers will be missed. Use automation.
- **Forgetting to update `DS` after migrating DNS provider.** The chain breaks; the domain disappears.
- **Treating DNSSEC as a replacement for TLS.** It is complementary, not a substitute.

## Verification

- `dig +dnssec example.com` returns `RRSIG` records and the `ad` (authenticated data) flag.
- [DNSViz](https://dnsviz.net/) and the [Verisign DNSSEC Debugger](https://dnssec-analyzer.verisignlabs.com/) both visualise the chain.
- Set up monitoring that alerts before any `RRSIG` expires.
- Test from a validating resolver (Cloudflare `1.1.1.1`, Google `8.8.8.8`). Forged answers should be rejected.

### Sources
- RFC 4033 — DNS Security Introduction and Requirements (IETF) — https://www.rfc-editor.org/rfc/rfc4033
- RFC 4035 — Protocol Modifications for the DNS Security Extensions (IETF) — https://www.rfc-editor.org/rfc/rfc4035
- ICANN — DNSSEC (ICANN) — https://www.icann.org/resources/pages/dnssec-what-is-it-why-important-2019-03-05-en
- Internet Society — Deploying DNSSEC (Internet Society) — https://www.internetsociety.org/deploy360/dnssec/

---

# Well-Known URIs

Standard, agreed-upon paths under /.well-known/.

## Well-known URIs

Status: recommended  ·  Source page: https://specification.website/spec/well-known/well-known-overview/

The /.well-known/ path prefix is a standardised place to publish site-level metadata. RFC 8615 defines it; IANA keeps the registry of allowed names.

## What it is

A well-known URI is a resource served from a fixed path under `/.well-known/` on your origin. RFC 8615 reserves this prefix so that protocols and tools can probe a site for capabilities without guessing URLs or polluting the root namespace.

```
https://example.com/.well-known/change-password
https://example.com/.well-known/security.txt
https://example.com/.well-known/webfinger?resource=acct:user@example.com
```

The names allowed under `/.well-known/` are not arbitrary. IANA maintains a public registry; new names go through a review process. If you publish at a name that is not registered, you are claiming a path that may later be assigned to someone else.

## Why it matters

- **Discoverability.** Clients, browsers, password managers, federated servers, mobile operating systems and crawlers know exactly where to look. They do not need configuration per site.
- **Interoperability.** Standardised paths are what let Mastodon, Apple, Google, OpenID Connect, ACME (Let's Encrypt) and others work across millions of sites without coordination.
- **Stability.** The reserved prefix keeps protocol metadata out of the way of your application's routing. You will not accidentally collide with `/security.txt` if it lives under `/.well-known/`.

## How to implement

- Serve the resource over **HTTPS** on the canonical host.
- Use the **exact path and filename** the spec defines. Case matters on most servers.
- Set the **correct Content-Type** (often `application/json`, sometimes plain text or JSON variants like `application/jrd+json`).
- Return **HTTP 200** with the body, or follow the spec where it allows a redirect (for example, `change-password`).
- Allow your CDN, firewall and authentication middleware to pass through. A well-known URI behind a login wall is invisible.
- **Do not invent new names.** If you need a new well-known URI, register it via the IETF process described in RFC 8615 §3.

## Common mistakes

- Publishing under `/well-known/` (no leading dot). The spec requires `/.well-known/`.
- Serving the file with `Content-Type: text/html` because a framework wrapped it.
- Requiring authentication, blocking by user-agent, or rate-limiting probes so aggressively that legitimate clients fail.
- Using a name not in the IANA registry. Custom names belong elsewhere.

## Verification

- `curl -I https://example.com/.well-known/<name>` should return `200` and the correct content type.
- Confirm the name appears in the [IANA registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml).
- Probe from a network outside your own to catch firewall and WAF rules.

### Sources
- RFC 8615 — Well-Known Uniform Resource Identifiers (URIs) (IETF) — https://www.rfc-editor.org/rfc/rfc8615
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
- MDN — Well-known URIs (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

---

## /.well-known/change-password

Status: optional  ·  Source page: https://specification.website/spec/well-known/change-password/

A standard redirect endpoint that points password managers and users at your real change-password page. Only applicable if the site has user accounts — sites without logins have nothing to point at and should not implement it.

## What it is

`/.well-known/change-password` is a fixed URL that resolves, by redirect, to the page where a user can change their password. The W3C Web Application Security Working Group defined it so that password managers, browsers and security tooling can jump a user from a breach alert or rotation prompt to the right form in one click.

It is not a form itself. It is a discoverable pointer.

**Applies only if your site has user accounts.** A marketing site, documentation site, or any other site without a login flow has no change-password page to point at and should not implement this URL — see the note at the end of the implementation section.

## Why it matters

- **Password managers** (1Password, Bitwarden, iCloud Keychain, Chrome, Edge, Firefox) probe this URL when they detect a weak or breached credential. If it works, the "change password" button takes the user straight there.
- **Users** who type `example.com/.well-known/change-password` into the address bar get to the right place without hunting through account menus.
- **Security teams** can use it as part of incident response: send everyone to one URL and the redirect resolves the rest.

It costs almost nothing to implement and removes a step from one of the highest-friction user journeys on the web.

## How to implement

Serve an HTTP **302** (or **303**) redirect from `/.well-known/change-password` to your actual change-password page.

```http
GET /.well-known/change-password HTTP/1.1
Host: example.com

HTTP/1.1 302 Found
Location: https://example.com/account/security/password
```

Rules:

- Serve it over **HTTPS** on the canonical host (the same host users log in to).
- The destination must be the page where a logged-in user can **change their existing password** — not the password reset flow for forgotten passwords, and not the sign-up page.
- The destination should work for an unauthenticated user too: redirect them to sign in first, then back to the change-password page.
- Do not return **404**. A 404 tells password managers the feature is not supported.

If you do not have accounts at all (a static marketing site, a documentation site, a brochure-ware site), do not implement this URL. There is nothing for it to redirect to, and a broken or placeholder destination is worse than the absence of the endpoint — password managers treat a 404 here as "feature unsupported" and move on, which is the correct outcome for a site without logins.

## Common mistakes

- Pointing at the password **reset** flow instead of the **change** flow. Reset is for forgotten passwords; change is for known-good users rotating credentials.
- Returning a 200 with an HTML page instead of a redirect. Some clients follow it; the spec says redirect.
- Hiding it behind a `noindex` requirement or a WAF rule that blocks non-browser user agents.
- Forgetting the leading dot in `/.well-known/`.

## Verification

```
curl -I https://example.com/.well-known/change-password
```

You should see a `302` or `303` response with a `Location:` header pointing at your real change-password page. Test in a password manager: trigger a weak-password warning and confirm the "Change password" button works.

### Sources
- A Well-Known URL for Changing Passwords (W3C Web Application Security Working Group) — https://w3c.github.io/webappsec-change-password-url/
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
- MDN — Well-known URIs (MDN) — https://developer.mozilla.org/en-US/docs/Web/Security

---

## /.well-known/openid-configuration

Status: optional  ·  Source page: https://specification.website/spec/well-known/openid-configuration/

A JSON discovery document that describes an OpenID Connect provider's endpoints and capabilities. Only required if you are an OIDC identity provider.

## What it is

`/.well-known/openid-configuration` is a JSON document published by an OpenID Connect (OIDC) provider that describes how clients can interact with it. A relying party fetches this URL, parses the response, and then knows where to send authorisation requests, where to exchange tokens, how to verify signatures, and which features the provider supports.

The format is defined by **OpenID Connect Discovery 1.0**. A closely related document for plain OAuth 2.0 lives at `/.well-known/oauth-authorization-server` (RFC 8414).

## Why it matters

- **Zero hand-configuration.** A client only needs your issuer URL. It discovers everything else from this document.
- **Key rotation works.** The `jwks_uri` is the canonical source for signing keys. Rotate keys there and every client picks up the change.
- **Capability negotiation.** Clients see which scopes, claims, response types and signing algorithms you support, and behave accordingly.
- **Standardisation.** Every major identity library (Auth0, Okta, Keycloak, Microsoft Entra, Google, etc.) consumes this format. You do not have to write client SDKs.

Only publish this if you actually run an OIDC identity provider. A site that uses "Sign in with Google" is a relying party, not a provider, and should not expose this URL.

## How to implement

Serve the file as `application/json` from your issuer's origin. The minimum useful payload looks roughly like this:

```json
{
  "issuer": "https://login.example.com",
  "authorization_endpoint": "https://login.example.com/oauth2/authorize",
  "token_endpoint": "https://login.example.com/oauth2/token",
  "userinfo_endpoint": "https://login.example.com/oauth2/userinfo",
  "jwks_uri": "https://login.example.com/oauth2/jwks",
  "response_types_supported": ["code", "id_token", "code id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"]
}
```

Rules:

- The `issuer` value must **exactly match** the URL clients use, including scheme and absence of trailing slash. Mismatches are the single most common cause of "invalid issuer" errors.
- Always serve over **HTTPS**.
- Set `Cache-Control` sensibly — minutes to hours, not days. Clients re-fetch on errors.
- The `jwks_uri` must be reachable and return current signing keys.

## Common mistakes

- Publishing the file but having clients fail with "issuer mismatch" because the URL differs by a trailing slash, port number, or hostname casing.
- Exposing a stale `jwks_uri` after rotating keys.
- Marking the file as `text/html` because a framework rendered it as a page.
- Treating the file as static when endpoints actually move. If you change endpoints, change the file.

## Verification

```
curl -s https://login.example.com/.well-known/openid-configuration | jq .
```

The response should be valid JSON with at least `issuer`, `authorization_endpoint`, `token_endpoint` and `jwks_uri`. The `issuer` value must equal the URL prefix you advertise to clients.

### Sources
- OpenID Connect Discovery 1.0 (OpenID Foundation) — https://openid.net/specs/openid-connect-discovery-1_0.html
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
- RFC 8414 — OAuth 2.0 Authorization Server Metadata (IETF) — https://www.rfc-editor.org/rfc/rfc8414

---

## /.well-known/api-catalog

Status: recommended  ·  Source page: https://specification.website/spec/well-known/api-catalog/

RFC 9727 publishes a machine-readable index of the APIs and resources a host exposes. Served as a Linkset (RFC 9264) JSON document, discoverable via the api-catalog link relation.

## What it is

`/.well-known/api-catalog` is an IETF-standardised path at which an organisation publishes a machine-readable catalogue of the APIs and structured resources its host exposes. The document is a [Linkset](https://www.rfc-editor.org/rfc/rfc9264) (RFC 9264) — a JSON array of link relations grouped by an anchor URL.

```http
GET /.well-known/api-catalog HTTP/1.1
```

```http
HTTP/1.1 200 OK
Content-Type: application/linkset+json; charset=utf-8
```

```json
{
  "linkset": [
    {
      "anchor": "https://example.com/",
      "describedby": [
        { "href": "https://example.com/llms.txt", "type": "text/markdown" }
      ],
      "alternate": [
        { "href": "https://example.com/rss.xml", "type": "application/rss+xml" }
      ],
      "sitemap": [
        { "href": "https://example.com/sitemap-index.xml", "type": "application/xml" }
      ],
      "license": [
        { "href": "https://creativecommons.org/licenses/by/4.0/" }
      ]
    }
  ]
}
```

The path is registered in the [IANA Well-Known URIs Registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml) by RFC 9727 — unlike many AI-era conventions, this one is standards-track.

## Why it matters

- **One predictable fetch surfaces every machine-readable resource.** Agents that obey `/.well-known/api-catalog` get a typed list of feeds, sitemaps, llms.txt, OpenAPI specs, terms of service, licence URLs — without scraping HTML.
- **Pairs with the `Link` header.** Advertise `Link: </.well-known/api-catalog>; rel="api-catalog"` and the agent never has to guess the path. See [HTTP Link headers](/spec/agent-readiness/link-headers/).
- **Standards-track.** RFC 9727 (May 2024) is final, not a draft. The IANA registration anchors the path.
- **Cheap to ship.** A small static JSON file.

## How to implement

**Serve a Linkset.** RFC 9727 requires the response body to be a valid [Linkset](https://www.rfc-editor.org/rfc/rfc9264). The media type is `application/linkset+json`. Set the `Content-Type` accordingly — most static hosts default to `application/octet-stream` for files without an extension.

**Each `linkset` entry has an `anchor`** (the resource the links describe) and one or more relation-keyed arrays. Useful relations:

- `describedby` — a description of the anchor (llms.txt, OpenAPI).
- `service-desc` — a machine-readable description of an API (OpenAPI, AsyncAPI).
- `service-doc` — a human-readable description of an API.
- `alternate` — alternative representations of the anchor's content.
- `sitemap` — sitemap covering the anchor.
- `license`, `author`, `terms-of-service` — metadata.
- `status` — status / health endpoint.

**Advertise it.** Add the catalogue to your HTTP `Link` header on every response:

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"
```

This is what makes the path discoverable without an out-of-band hint.

**Update it when the surface changes.** A drifted catalogue is worse than no catalogue. CI should validate it on every change to the public resources it describes.

**Keep it small.** Catalogues are typically a few KB. Linksets are flat — there is no recursion to follow.

## Common mistakes

- Returning the catalogue with `Content-Type: application/json` (or `text/plain`). It must be `application/linkset+json` for RFC 9727 to apply; agents that strictly type-check will skip it otherwise.
- Inventing relation names. Use only those in the [IANA Link Relations Registry](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
- Wrapping the catalogue inside an authentication wall. The whole point is unauthenticated discovery.
- Forgetting to keep it in sync with `/llms.txt`, `/sitemap-index.xml`, and the `<link>` tags in HTML. They are different surfaces for the same statement of fact.
- Pairing it with `Link: </.well-known/api-catalog>; rel="describedby"`. The correct relation is `api-catalog` — that registration is what RFC 9727 added.

## Verification

- `curl -sI https://example.com/.well-known/api-catalog` returns `200` with `Content-Type: application/linkset+json`.
- The body parses as JSON and matches the Linkset schema (RFC 9264 §4).
- [Is It Agent Ready?](https://isitagentready.com/) flips `discovery.apiCatalog` to `pass`.
- Every URL the catalogue points at returns `200` from the same origin.

### Sources
- RFC 9727 — Publishing Organisation API Information (IETF) — https://www.rfc-editor.org/rfc/rfc9727
- RFC 9264 — Linkset: Media Types and a Link Relation Type for Link Sets (IETF) — https://www.rfc-editor.org/rfc/rfc9264
- RFC 8288 — Web Linking (IETF) — https://www.rfc-editor.org/rfc/rfc8288
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

---

## /.well-known/webfinger

Status: optional  ·  Source page: https://specification.website/spec/well-known/webfinger/

WebFinger (RFC 7033) resolves an account identifier such as acct:user@example.com to a set of links. The Fediverse uses it to discover ActivityPub actors.

## What it is

WebFinger is a discovery protocol defined in **RFC 7033**. A client asks `/.well-known/webfinger` for information about a resource identifier — typically an account in the form `acct:user@example.com` — and the server returns a JSON Resource Descriptor (JRD) describing that resource and where to find more.

It is the protocol that lets you type `@alice@mastodon.example` into any Fediverse client and have it resolve to Alice's ActivityPub profile, regardless of which server she lives on.

## Why it matters

- **Federation depends on it.** Mastodon, Pleroma, Misskey, GoToSocial, PeerTube, Lemmy and every other ActivityPub-speaking platform use WebFinger as step one of "who is this user".
- **It abstracts the URL.** A handle like `acct:joost@example.com` is human-friendly. The actual ActivityPub actor URL might be `https://example.com/users/joost`. WebFinger maps one to the other.
- **It works across protocols.** WebFinger is not tied to ActivityPub. It can advertise any kind of link relation for any kind of resource.

If your site does not host accounts that need to federate, you do not need this URL.

## How to implement

Accept GET requests with a `resource` query parameter. Return `application/jrd+json`.

```http
GET /.well-known/webfinger?resource=acct:joost@example.com HTTP/1.1
Host: example.com
Accept: application/jrd+json
```

A typical response for a Fediverse account:

```json
{
  "subject": "acct:joost@example.com",
  "aliases": [
    "https://example.com/@joost",
    "https://example.com/users/joost"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@joost"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://example.com/users/joost"
    }
  ]
}
```

Rules:

- Serve over **HTTPS**, and respond on the host that matches the right-hand side of the `acct:` URI. A query for `joost@example.com` must be answered by `example.com`, not `social.example.com`.
- Return `404` for unknown resources, `400` for a missing or malformed `resource` parameter.
- Accept the `rel` query parameter and filter the `links` array accordingly. Clients use it to reduce payload size.
- Set permissive `Access-Control-Allow-Origin: *` so browser-based clients can fetch the response.

## Common mistakes

- Answering on the wrong host. If user identifiers look like `@alice@example.com` but WebFinger lives on `social.example.com`, federation breaks. Fix this by serving WebFinger from `example.com` and redirecting or proxying as needed.
- Returning `text/plain` or `application/json` instead of `application/jrd+json`.
- Leaking the existence of accounts via different responses for "user exists but private" and "user does not exist". Pick one behaviour and apply it consistently.
- Ignoring the `rel` filter and always returning every link.

## Verification

```
curl -s "https://example.com/.well-known/webfinger?resource=acct:joost@example.com" | jq .
```

Then try to follow your account from a Mastodon server you do not control. If federation fails, WebFinger is almost always the first thing to check.

### Sources
- RFC 7033 — WebFinger (IETF) — https://www.rfc-editor.org/rfc/rfc7033
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
- ActivityPub — W3C Recommendation (W3C) — https://www.w3.org/TR/activitypub/

---

## /.well-known/apple-app-site-association

Status: optional  ·  Source page: https://specification.website/spec/well-known/apple-app-site-association/

A JSON file that tells iOS, iPadOS and macOS which Apple apps may handle which URLs on your domain. Required for Universal Links and several other Apple features.

## What it is

`apple-app-site-association` (often abbreviated **AASA**) is a JSON file Apple platforms fetch from your domain to verify that you authorise specific apps to handle specific URLs. It powers Universal Links (opening web URLs directly in an app), Handoff between web and app, Shared Web Credentials, and AutoFill of strong passwords across web and app.

It must live at `https://example.com/.well-known/apple-app-site-association`. Apple no longer accepts the legacy root-path location.

## Why it matters

- **Universal Links.** Without a valid AASA, a tap on `https://example.com/orders/123` in Mail or Messages opens Safari instead of your app. The whole "deep linking that survives links being shared" model depends on this file.
- **Password sharing.** Shared Web Credentials lets a password saved in Safari autofill in the corresponding app, and vice versa. It is gated by AASA.
- **Trust.** The fact that you control the domain and can publish this file is what Apple uses to prove that an app may claim URLs on your domain. There is no other mechanism.

If you do not have an iOS, iPadOS, macOS or visionOS app, you do not need this file.

## How to implement

Serve a JSON document with the App IDs and URL patterns that may handle your domain.

```json
{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/orders/*" },
          { "/": "/users/*/profile" }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.app"]
  }
}
```

Rules:

- The path is **exactly** `/.well-known/apple-app-site-association` with **no `.json` extension**.
- The response **Content-Type must be `application/json`**.
- The response must be served over **HTTPS** with a valid certificate. No redirects: respond with `200` directly.
- The file must be **publicly accessible** with no authentication, no rate limiting that blocks Apple's CDN, and no `Vary` header that breaks caching.
- Apple fetches the file through its own CDN (`app-site-association.cdn-apple.com`). Allow that user agent through your WAF.
- Keep the JSON **valid** and under Apple's size limit (currently 128 KB).

## Common mistakes

- Adding a `.json` extension because a server forced one.
- Serving with `Content-Type: text/plain` or `text/html`.
- Returning a redirect. Apple treats a redirect as a hard failure.
- Hiding the file behind Cloudflare's "Under Attack" mode, a login page, or a country block.
- Using only `paths` (the old key) without `components`. Modern iOS versions prefer `components`; ship both during migration.

## Verification

```
curl -I https://example.com/.well-known/apple-app-site-association
```

You should see `200 OK` and `Content-Type: application/json`. Apple's [App Search API Validation Tool](https://search.developer.apple.com/appsearch-validation-tool/) and the on-device "Diagnostics" build flag both report whether AASA loaded successfully.

### Sources
- Apple — Supporting associated domains (Apple Developer Documentation) — https://developer.apple.com/documentation/xcode/supporting-associated-domains
- Apple — Allowing apps and websites to link to your content (Apple Developer Documentation) — https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

---

## /.well-known/assetlinks.json

Status: optional  ·  Source page: https://specification.website/spec/well-known/assetlinks-json/

Android's Digital Asset Links file proves that an Android app and a web domain are owned by the same entity. It powers App Links and Smart Lock for Passwords.

## What it is

`assetlinks.json` is Google's equivalent of Apple's AASA file. It is a JSON document published at `/.well-known/assetlinks.json` that declares which Android applications are allowed to act on behalf of your web domain. Android verifies this file before honouring App Links and several credential-sharing features.

The format is defined by the **Digital Asset Links** protocol, which is also used for cross-app verification and SmartLock.

## Why it matters

- **Android App Links.** With a valid `assetlinks.json`, tapping `https://example.com/orders/123` in Gmail or Chrome opens directly in your app, with no "open with" dialog. Without it, the user lands on the web.
- **Credential sharing.** Saved passwords in Chrome can autofill in the corresponding Android app, and vice versa.
- **Trust.** Google needs cryptographic proof that the same party owns the domain and the app. Hosting this file at a URL only the domain owner controls provides that proof.

If you do not ship an Android app, you do not need this file.

## How to implement

Publish a JSON array. Each entry declares one relation between your site and one app.

```json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
      ]
    }
  }
]
```

Rules:

- The path is **exactly** `/.well-known/assetlinks.json`. The `.json` extension is required here (unlike Apple's AASA).
- Serve as **`Content-Type: application/json`** over **HTTPS**.
- Respond with **`200 OK`** directly. No redirects.
- The file must be **publicly readable**, with no authentication and no aggressive bot rules.
- The `sha256_cert_fingerprints` must include the SHA-256 of the signing certificate of every release variant — including the Play App Signing key, not just your upload key.
- Declare every relevant app, including any beta or staging packages.

## Common mistakes

- Listing the upload certificate fingerprint and forgetting Play App Signing's actual signing certificate.
- Leaving out a package because it shares code with another. Each package needs its own entry.
- Serving the file from a subdomain that is not the eTLD+1 the app is associated with.
- Returning a 301 to a CDN host. Google's verifier follows redirects in some cases and not others — do not depend on it.
- Letting a deploy pipeline rewrite JSON keys to camelCase.

## Verification

```
curl -s https://example.com/.well-known/assetlinks.json | jq .
```

Use Google's [Statement List Generator and Tester](https://developers.google.com/digital-asset-links/tools/generator) and Android Studio's "App Links Assistant". On a device, `adb shell pm get-app-links com.example.app` shows whether verification succeeded and why if it did not.

### Sources
- Digital Asset Links — Verify Android App Links (Google Developers) — https://developer.android.com/training/app-links/verify-android-applinks
- Digital Asset Links protocol (Google Developers) — https://developers.google.com/digital-asset-links/v1/getting-started
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

---

## /.well-known/nodeinfo

Status: optional  ·  Source page: https://specification.website/spec/well-known/nodeinfo/

A discovery URI for federated platforms. It returns links to NodeInfo documents that describe the software, version and basic statistics of a server.

## What it is

NodeInfo is a small, two-step discovery mechanism for federated and decentralised servers. A client first fetches `/.well-known/nodeinfo`, which returns a list of links pointing at versioned NodeInfo documents (typically `/nodeinfo/2.0` or `/nodeinfo/2.1`). Those documents then describe what software the server runs, which protocols it speaks, and basic statistics about users and posts.

The protocol started in Diaspora and is now used across Mastodon, PeerTube, Pleroma, Misskey, Friendica, GoToSocial, Lemmy, Funkwhale and most of the rest of the Fediverse.

## Why it matters

- **Server identification.** Crawlers, statistics sites (such as fediverse.observer), and admin tools use NodeInfo to recognise what platform a domain runs without screen-scraping HTML.
- **Federation health.** Admins can quickly check whether a peer is reachable, what version it runs, and whether it supports the protocols their server speaks.
- **Compatibility hints.** Clients can adapt to platform-specific quirks once they know whether they are talking to Mastodon, Misskey or something else.

If your site is not a federated server, you do not need NodeInfo.

## How to implement

Serve `/.well-known/nodeinfo` as JSON. The body lists one or more `rel`/`href` pairs that point at the actual NodeInfo documents.

```json
{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.0",
      "href": "https://example.com/nodeinfo/2.0"
    },
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.1",
      "href": "https://example.com/nodeinfo/2.1"
    }
  ]
}
```

Then serve the actual NodeInfo document at the linked URL:

```json
{
  "version": "2.1",
  "software": {
    "name": "examplesocial",
    "version": "1.4.2",
    "repository": "https://github.com/example/social"
  },
  "protocols": ["activitypub"],
  "services": { "inbound": [], "outbound": [] },
  "openRegistrations": false,
  "usage": {
    "users": { "total": 142, "activeMonth": 38, "activeHalfyear": 95 },
    "localPosts": 3120
  },
  "metadata": {}
}
```

Rules:

- Serve over **HTTPS** with `Content-Type: application/json`.
- Set permissive CORS (`Access-Control-Allow-Origin: *`) so browser-based dashboards can read it.
- Cache for **minutes**, not days — stats change.
- Support at least one of the current schema versions (2.0 or 2.1). Older versions (1.0, 1.1) are deprecated.

## Common mistakes

- Returning the NodeInfo document directly from `/.well-known/nodeinfo`. The well-known URI is a pointer; the document lives elsewhere.
- Returning HTML or `text/plain` because the response was wrapped by a framework.
- Hard-coding `openRegistrations: true` when registrations are actually closed, breaking sign-up flows from third-party clients.
- Forgetting to update `software.version` on deploy, so peer servers think you are running a year-old release.

## Verification

```
curl -s https://example.com/.well-known/nodeinfo | jq .
curl -s https://example.com/nodeinfo/2.1 | jq .
```

Cross-check on a statistics site (such as fediverse.observer) that your server appears with the correct software name and version.

### Sources
- NodeInfo — Protocol overview (NodeInfo project) — http://nodeinfo.diaspora.software/
- NodeInfo Protocol specification (NodeInfo project) — http://nodeinfo.diaspora.software/protocol.html
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

---

## /.well-known/traffic-advice

Status: optional  ·  Source page: https://specification.website/spec/well-known/traffic-advice/

A JSON file that tells private prefetch proxies — most notably Chrome's — whether to send prefetch traffic to your origin, and at what fraction. Optional opt-out / throttle mechanism, provisionally registered with IANA.

## What it is

`/.well-known/traffic-advice` is a JSON document that tells private prefetch proxies — most notably Chrome's [Private Prefetch Proxy](https://developer.chrome.com/blog/private-prefetch-proxy) — whether (and how much) to send prefetch traffic to your origin on a user's behalf. By default a proxy assumes consent. This file lets you refuse, or throttle to a fraction.

The body is a JSON array of advice objects, served as `application/trafficadvice+json`:

```json
[
  {"user_agent": "prefetch-proxy", "disallow": true}
]
```

Each object has a `user_agent` and either `disallow: true` (refuse traffic) or `fraction` (a value between 0 and 1, the share of traffic to allow). A proxy picks the most-specific match — its own brand name (e.g. `"ExamplePrivatePrefetchProxy"`), the generic class `"prefetch-proxy"`, or the wildcard `"*"`. The first identity that appears in the proxy's own self-identification list wins.

The convention was authored by Jeremy Roman at Google and is provisionally registered with IANA. Outside Chrome's Private Prefetch Proxy, no major implementer has adopted it yet.

## Why it matters

Most sites should never need this file. A prefetched response improves [Core Web Vitals](/spec/performance/core-web-vitals/) for the user who clicks through, and the proxy itself caches per HTTP semantics so origin load stays low. Reasons to override the default:

- **Origin under load.** Drop `fraction` during a launch or news spike to thin out speculative requests without affecting real traffic.
- **Log hygiene.** Proxy-sourced prefetches still hit access logs even though they bypass client-side analytics. Disallow to keep raw counts clean.
- **Bandwidth-billed infra.** Origins on per-byte billing may want a fraction below 1, or `disallow` outright.

If none of those apply, ship nothing here — a missing file is the correct signal for "default behaviour is fine".

## How to implement

```http
GET /.well-known/traffic-advice HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/trafficadvice+json
Cache-Control: public, max-age=3600

[
  {"user_agent": "prefetch-proxy", "fraction": 0.5}
]
```

- **`Content-Type: application/trafficadvice+json` is mandatory.** Any other value (including `application/json`) is treated as no advice and the proxy uses its default.
- **Cache lifetime.** The spec suggests a minimum freshness of 10 minutes and a maximum of 48 hours; agents default to 30 minutes when no `Cache-Control` is set. Pick a value short enough that posture changes propagate within an operationally reasonable window.
- **Match ordering.** List the broadest advice first (`"prefetch-proxy"`), then narrower per-implementer exceptions. A proxy walks its own identity list and takes the earliest match.
- **Status codes.** Return `200` with JSON, or omit the file. `429` and `503` signal back-pressure — the proxy will pause and retry later. Any other non-OK status is treated as "no advice".

## Common mistakes

- Returning `application/json` instead of `application/trafficadvice+json`. The spec requires the dedicated media type and proxies ignore anything else.
- Using `fraction: 0` to opt out. `disallow: true` is the documented refusal; `fraction: 0` works but is the wrong vocabulary.
- Forgetting the wildcard. To affect every prefetch proxy (not only Chrome's), include an entry with `"user_agent": "*"`.
- Treating absence as a bug. A missing file is the correct "default behaviour" signal — only ship the file when you have a reason to override.

## Verification

```
curl -I https://example.com/.well-known/traffic-advice
curl -s https://example.com/.well-known/traffic-advice | jq .
```

Confirm `Content-Type: application/trafficadvice+json` and a sensible `Cache-Control`. The body should parse as a JSON array; each entry should have a string `user_agent` and one of `disallow: true` or a numeric `fraction` between 0 and 1.

### Sources
- Traffic Advice — formal specification (Jeremy Roman (editor) / Private Prefetch Proxy community) — https://buettner.github.io/private-prefetch-proxy/traffic-advice.html
- private-prefetch-proxy on GitHub — traffic-advice.md (Private Prefetch Proxy community) — https://github.com/buettner/private-prefetch-proxy/blob/main/traffic-advice.md
- IANA — Well-Known URIs Registry (IANA) — https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
- Private Prefetch Proxy (Chrome for Developers) — https://developer.chrome.com/blog/private-prefetch-proxy

---

# Agent Readiness

Things that make a site legible to AI agents and crawlers.

## Agent readiness

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/agent-readiness-overview/

Agent readiness is the set of choices that make a site legible to AI agents and LLMs: stable URLs, structured data, clean semantics, robots controls, and machine-readable endpoints.

## What it is

Agent readiness is a loose umbrella term for the choices that make a website legible to AI agents — chat assistants, autonomous browsers, retrieval pipelines, and any other non-human client that reads the web at scale. None of it is a single formal standard. It is a collection of existing web fundamentals plus a few emerging conventions.

The clearest checklist is published at [isitagentready.com](https://isitagentready.com/), which scores sites against a small set of agent-friendly signals.

## Why it matters

Agents read the same HTML as browsers, but they read it differently. They:

- Fetch a page, often without executing JavaScript.
- Strip away navigation, ads, and chrome to extract the main content.
- Follow links, structured data, and well-known endpoints to discover more.
- Cache and quote your content in answers, with or without a link back.

If your content is locked behind client-side rendering, your URLs change every release, or your robots.txt blocks the assistants your customers use, you are invisible in that surface. The pages that win in agent answers are the ones that are easy to fetch, easy to parse, and easy to trust.

## How to implement

There is no single switch. The items in this category each cover one part:

- **Stable URLs** so cached answers stay valid.
- **Structured data** (JSON-LD) so agents can extract entities without guessing.
- **Clean semantic HTML** so content extraction does not pull in navigation.
- **A robots.txt that names AI crawlers explicitly** so your policy is unambiguous.
- **/llms.txt** as a curated index of your most important content (emerging).
- **Machine-readable endpoints** — sitemaps, RSS, JSON feeds — where they fit.
- **MCP server endpoints** for sites that expose tools or actions (emerging).

Most of these also benefit traditional search engines and accessibility. Agent readiness rarely conflicts with the rest of the spec; it just raises the priority of things that have always been good practice.

## Common mistakes

- Treating agent readiness as a separate project from SEO and accessibility. The work overlaps heavily.
- Assuming AI crawlers will execute JavaScript. Most do not, or do it inconsistently.
- Writing for the model rather than the reader. Agents quote what humans would quote.
- Blocking every AI crawler by default, then wondering why your brand has no presence in assistants.

## Verification

- Run your site through [isitagentready.com](https://isitagentready.com/).
- Fetch a key page with `curl` and confirm the main content is in the initial HTML.
- Check `/robots.txt` lists the crawlers you intend to allow or block.

### Sources
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/
- The /llms.txt proposal (llmstxt.org) — https://llmstxt.org/
- Overview of Google crawlers and fetchers (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers

---

## /llms.txt

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/llms-txt/

A proposed markdown file at the site root that gives LLMs a curated index of your most important content. Emerging convention, not a ratified standard.

## What it is

`/llms.txt` is a proposed convention for a markdown file served at the root of a site. It gives large language models a short, curated map of the content you most want them to see. The proposal lives at [llmstxt.org](https://llmstxt.org/) and was put forward by Jeremy Howard in 2024.

It is not a ratified standard. No major model vendor has committed to consuming it. Treat it as a low-cost bet that may pay off as agents look for cheap, authoritative summaries of a site.

The file is plain markdown with a defined structure: a top-level heading with the site name, a short blockquote summary, optional context paragraphs, and one or more `##` sections containing markdown links.

```md
# Example Corp

> Example Corp builds open-source tools for static-site authors.

We publish documentation, a blog, and reference specifications.

## Docs

- [Getting started](https://example.com/docs/start.md): Install and first build.
- [API reference](https://example.com/docs/api.md): All public functions.

## Optional

- [Changelog](https://example.com/changelog.md): Release notes.
```

## Why it matters

- It is short. A model can read it in one fetch and learn what your site is about without crawling everything.
- It is curated. You decide which pages matter, in which order.
- It is markdown. No parsing of HTML, no JavaScript, no ads to strip.
- It complements `sitemap.xml`, which is exhaustive and machine-only. `llms.txt` is selective and human-readable too.

The cost is low: one file, updated when your information architecture changes.

## How to implement

- Place the file at `https://example.com/llms.txt`. Serve as `text/markdown` or `text/plain`.
- Start with `# Site name` on the first line. Follow with a `> blockquote` summary.
- Use `##` headings to group links. Links should point to canonical pages.
- Prefer markdown versions of pages where you have them — many sites publish `page.md` alongside `page.html`.
- Keep it under a few hundred lines. If you want full content, see [/llms-full.txt](/spec/agent-readiness/llms-full-txt/).
- Link to it from your homepage or footer so humans can find it too.

## Common mistakes

- Treating it like a sitemap and listing every URL. The point is curation.
- Writing marketing copy in the summary. Models will quote it; write plainly.
- Letting it drift. A stale `llms.txt` is worse than none — it teaches models wrong things.
- Assuming any specific model uses it today. Adoption is uneven and not always disclosed.

## Verification

- Fetch `https://example.com/llms.txt` and confirm a `200` with markdown content.
- Validate the structure against the example on [llmstxt.org](https://llmstxt.org/).
- Re-check after every information-architecture change.

### Sources
- The /llms.txt proposal (llmstxt.org) — https://llmstxt.org/
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/

---

## /llms-full.txt

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/llms-full-txt/

An extended companion to /llms.txt that concatenates the full markdown content of your key pages into a single file. Useful for small sites, costly for large ones.

## What it is

`/llms-full.txt` is the long companion to [/llms.txt](/spec/agent-readiness/llms-txt/). Where `llms.txt` is an index of links, `llms-full.txt` concatenates the actual markdown content of those pages into a single file. The convention also originates with the [llmstxt.org](https://llmstxt.org/) proposal.

The idea is that an agent fetches one file and receives your entire documentation in plain markdown, ready to use as context. No crawling, no HTML extraction.

It is optional and emerging. Treat it as a nice-to-have for documentation-heavy sites where the content is reasonably small and stable.

```md
# Example Corp — full content

> All public documentation, concatenated.

---

# Getting started

(full markdown of the getting-started page)

---

# API reference

(full markdown of the API reference)
```

## Why it matters

- One fetch, all the content. No retries, no rate limits per page, no broken links.
- Markdown, not HTML. Agents do not have to strip navigation, ads, or scripts.
- Predictable structure. Pages are separated by horizontal rules and headings.
- Useful as a build artefact for your own retrieval pipelines and embeddings.

The trade-off is size. A large documentation site can easily produce a multi-megabyte file. Agents may refuse to load it, or load only the first slice. If your content does not fit comfortably in a single file, stick with `llms.txt` plus per-page markdown.

## How to implement

- Generate the file at build time. Manually maintaining it is not realistic.
- Concatenate the markdown source of the pages listed in `llms.txt`, in the same order.
- Separate sections with `---` and clear `#` headings. Include the page URL near each heading so agents can cite it.
- Strip front-matter and templating artefacts. Keep prose, headings, code blocks, and lists.
- Watch the size. Many model providers cap context windows; aim to stay well under common limits or split into focused files (`llms-api.txt`, `llms-guides.txt`).
- Serve as `text/markdown` or `text/plain`. Set sensible cache headers — this file changes on every doc update.

## Common mistakes

- Including every page on the site. Curate the same way `llms.txt` does.
- Forgetting to update it. A stale concatenation is harder to spot than a stale index.
- Letting it grow until it is too big to be useful. Split it before that point.
- Serving HTML by accident — check the response is real markdown.

## Verification

- Fetch the file and check the size. Anything over a couple of megabytes is suspect.
- Spot-check a few sections against the live pages they were generated from.
- Re-run the build after major content changes and diff against the previous version.

### Sources
- The /llms.txt proposal (llmstxt.org) — https://llmstxt.org/
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/

---

## Per-page Markdown source endpoints

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/markdown-source-endpoints/

Expose every documentation page's raw Markdown source at a predictable URL — via a .md suffix on the canonical URL, content negotiation, or both. Agents pull source instead of parsing HTML.

## What it is

A per-page Markdown source endpoint exposes the original, unrendered Markdown of a content page at a predictable URL. An agent — an LLM, a documentation index, a CLI tool — fetches the Markdown instead of the HTML and gets the same content without the lossy round trip through DOM parsing, ad scaffolding, navigation chrome, and JavaScript hydration.

Two conventions are emerging, and the best sites do both.

**1. URL suffix.** Append `.md` to the page path.

```http
GET /docs/getting-started/        HTTP/1.1
GET /docs/getting-started.md      HTTP/1.1
```

The first returns HTML. The second returns the raw Markdown source with a `text/markdown` content type.

**2. Content negotiation.** Send `Accept: text/markdown` to the canonical (HTML) URL and get Markdown back.

```http
GET /docs/getting-started/        HTTP/1.1
Accept: text/markdown
```

```http
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Content-Location: /docs/getting-started.md
Vary: Accept
```

The `Content-Location` header tells the client the canonical Markdown URL; `Vary: Accept` tells caches the response depends on the request's `Accept` header.

## Why it matters

- **Lossless source.** HTML extraction loses heading semantics, code-block language hints, callout syntax, and inline metadata. Markdown gives the agent exactly what the author wrote.
- **Smaller payloads.** A typical Markdown page is 5–20× smaller than its rendered HTML once you remove styling, scripts, and shared chrome.
- **No JavaScript runtime.** Crawlers that don't run JS still get full content.
- **Aligned with `llms.txt`.** [llms.txt](/spec/agent-readiness/llms-txt/) and [llms-full.txt](/spec/agent-readiness/llms-full-txt/) point at pages — `.md` makes the pointed-to representation directly usable.
- **Stable signal of intent.** Sites that expose `.md` are advertising "we want to be readable by agents," which is itself a useful discovery signal.

Anthropic's documentation, Stripe's, and a growing number of others ship the `.md` suffix. Treat the canonical URL with `Accept: text/markdown` as the next layer up — same content, the URL stays canonical, caches behave correctly.

## How to implement

**Ship the suffix at minimum.** For every Markdown-sourced page, serve the same Markdown at the URL with `.md` appended.

```http
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Cache-Control: public, max-age=3600
X-Markdown-Tokens: 1240
```

Include a YAML frontmatter block with the page's metadata so agents get structured context alongside the prose: `title`, `url` (the canonical HTML URL), `updated`, `sources`, `licence`. Don't ship implementation details an agent doesn't need (build timestamps, internal IDs).

**Hint the size.** Add an `X-Markdown-Tokens` response header carrying a rough token-count estimate for the body (any reasonable tokeniser — `tiktoken`'s `cl100k_base` is a fine default). The header is not a registered standard, but a growing number of agent-friendly sites ship it because it lets a caller decide whether to inline the page into a prompt, summarise it first, or skip it for a smaller one — without downloading the body. Recompute it whenever the Markdown changes; do not invent the number.

**Advertise it in `<head>`.** Add a discovery link to the HTML version so crawlers and tools find the Markdown without guessing the URL pattern.

```html
<link rel="alternate" type="text/markdown"
      href="https://example.com/docs/getting-started.md"
      title="Getting started — Markdown source">
```

**Add content negotiation if your edge supports it.** Cloudflare Pages Functions, Workers, Vercel Edge Middleware, Netlify Edge Functions, Fastly Compute, and Nginx can all branch on `Accept`. The middleware:

1. Matches the page URL pattern.
2. If `Accept` contains `text/markdown`, fetches the `.md` asset internally and returns its body with `Content-Type: text/markdown`, `Content-Location: /…/page.md`, and `Vary: Accept`.
3. Otherwise serves HTML, but still appends `Vary: Accept` so caches don't conflate the two representations of the same URL.

**Mention it in `llms.txt`.** Document both modes near the top of the file so agents can opt in on first read.

## Common mistakes

- Shipping the suffix but forgetting `Content-Type: text/markdown`. Browsers will then download the file instead of displaying it, and agents may misclassify it.
- Doing content negotiation without `Vary: Accept`. Caches will return whichever representation they cached first to every subsequent client, regardless of what they asked for.
- Returning Markdown that still contains template includes, unresolved shortcodes, or framework-specific syntax (e.g. `{{ component }}`). Serve the fully-rendered Markdown, not the source-of-source.
- Letting the Markdown drift from the HTML. The two should be generated from the same source at the same time, in the same build.
- Putting the `.md` behind authentication while the HTML is public. The two representations must have the same access policy.

## Verification

- `curl -i https://example.com/docs/getting-started.md` returns `200` with `Content-Type: text/markdown; charset=utf-8`.
- `curl -i -H 'Accept: text/markdown' https://example.com/docs/getting-started/` returns Markdown with `Content-Location` and `Vary: Accept`.
- The HTML response to the same URL also carries `Vary: Accept`.
- View source on any page — there is a `<link rel="alternate" type="text/markdown" …>` in `<head>`.
- The `.md` body contains the same headings, paragraphs, and code blocks as the rendered HTML, with frontmatter at the top.

### Sources
- RFC 9110 — HTTP Semantics §12 (Content Negotiation), §8.7 (Vary), §8.7.1 (Content-Location) (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-content-negotiation
- MDN — Vary (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary
- MDN — Content-Location (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Location
- Anthropic — docs.anthropic.com Markdown source (live example) (Anthropic) — https://docs.anthropic.com/en/docs/intro.md
- llmstxt.org (llmstxt.org) — https://llmstxt.org/

---

## robots.txt for AI crawlers

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/robots-for-ai-crawlers/

Major AI vendors publish named user-agents for their crawlers. Setting an explicit allow or disallow per agent is the clearest way to control how your content is used.

## What it is

The robots.txt file (see [robots.txt](/spec/seo/robots-txt/)) accepts rules per user-agent. Every major AI vendor now publishes a named user-agent for its training and retrieval crawlers, so you can allow or block each one independently of search.

The big ones, as of 2026:

- **GPTBot** — OpenAI training crawler.
- **OAI-SearchBot** — OpenAI retrieval crawler used by ChatGPT browsing.
- **ChatGPT-User** — on-demand fetches when a ChatGPT user asks for a URL.
- **ClaudeBot** — Anthropic training and retrieval crawler.
- **anthropic-ai** — legacy Anthropic user-agent, still seen.
- **Google-Extended** — opts out of Gemini and Vertex training without affecting Search.
- **Applebot-Extended** — opts out of Apple Intelligence training without affecting Siri/Spotlight.
- **PerplexityBot** — Perplexity retrieval crawler.
- **Bytespider** — ByteDance crawler, widely used for training.
- **CCBot** — Common Crawl, the dataset behind many open models.

## Why it matters

A blanket `Disallow: /` blocks everyone, including search. Naming agents lets you make precise decisions: allow retrieval bots so your content can be cited live, block training bots if you do not want to feed model weights, or the reverse.

Compliance is honour-based. Reputable vendors document and respect their user-agents. Unidentified scrapers will ignore robots.txt; defend against those with rate limits or WAF rules, not robots.

## How to implement

A reasonable default that allows search and retrieval but opts out of training:

```txt
User-agent: GPTBot
Disallow: /

User-agent: Google-Extended
Disallow: /

User-agent: Applebot-Extended
Disallow: /

User-agent: ClaudeBot
Disallow: /

User-agent: CCBot
Disallow: /

User-agent: OAI-SearchBot
Allow: /

User-agent: ChatGPT-User
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: *
Allow: /

Sitemap: https://example.com/sitemap_index.xml
```

Rules of thumb:

- Read each vendor's documentation; user-agents change.
- Decisions are per-host. A subdomain needs its own robots.txt.
- Combine with [/llms.txt](/spec/agent-readiness/llms-txt/) when you want to allow access but steer agents to specific pages.
- For paywalled or member content, keep auth in place — robots.txt is not a security boundary.

## Common mistakes

- Blocking `*` and forgetting that this also blocks Google.
- Blocking only `GPTBot` and assuming no OpenAI surface can see your site — `OAI-SearchBot` and `ChatGPT-User` are separate.
- Leaving stale user-agents from 2023 lists. Names change; the vendor docs are the source of truth.
- Treating disallow as deletion. Content already in training sets stays there.

## Verification

- Fetch `https://example.com/robots.txt` and check each rule renders.
- Cross-reference your list against the linked vendor pages — they are updated regularly.
- Watch server logs for the user-agents you care about and confirm they back off after a rule change.

### Sources
- OpenAI — GPTBot (OpenAI) — https://platform.openai.com/docs/bots
- Anthropic — Crawlers (Anthropic) — https://support.anthropic.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler
- Google — Google-Extended (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers#google-extended
- Apple — Applebot-Extended (Apple) — https://support.apple.com/en-us/119829

---

## Content Signals in robots.txt

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/content-signals/

Add Content-Signal directives to robots.txt to declare whether AI crawlers may search, ingest, or train on your content. An emerging IETF AI Preferences / IAB Tech Lab proposal that some validators already check.

## What it is

Content Signals is a proposed extension to `robots.txt` that adds new directives expressing how a site wants its content treated downstream — specifically by AI systems. The directives live in normal `robots.txt` groups and declare boolean preferences such as "you may use this for search" or "you may not train on this".

```
User-agent: *
Allow: /
Content-Signal: search=yes, ai-input=yes, ai-train=no
```

The three values that are emerging as canonical:

- **`search`** — whether the content may be indexed by search engines.
- **`ai-input`** — whether the content may be fetched as live input to an AI system (retrieval-augmented generation, summarisation at query time).
- **`ai-train`** — whether the content may be included in a training corpus.

Each takes `yes` or `no`. Multiple values are comma-separated on a single `Content-Signal:` line.

## Status of the proposal

This is **not yet a settled standard**. The work is split across two ongoing efforts:

- The **IETF AI Preferences working group ([aipref](https://datatracker.ietf.org/wg/aipref/documents/))** is working on a vocabulary and protocol-level definition.
- The **IAB Tech Lab Content Signals project** has published a parallel specification aimed at industry adoption.

Drafts have been circulating since 2024 and the vocabulary is converging. Treat Content Signals as recommended-to-experiment-with, not as a finalised standard. The directive will be ignored by every crawler that does not yet parse it — which today is most of them.

## Why it matters

- **A declarative opt-in / opt-out at the right layer.** Existing `User-agent: GPTBot / Disallow:` directives are coarse — they block a specific bot from fetching anything. Content Signals separates *what* the bot may do from *who* the bot is.
- **Validators already check for it.** [isitagentready.com](https://isitagentready.com/) explicitly looks for `Content-Signal:` lines in `robots.txt`. Sites that want a clean agent-readiness scorecard should add them.
- **Some major model providers have signalled future support.** Cloudflare, Google, and others have published positions on the IETF drafts.

## How to implement

**Per-group, in `robots.txt`.** Place the `Content-Signal:` line inside the same group as `User-agent:` and `Allow:` / `Disallow:`.

```
User-agent: *
Allow: /
Content-Signal: search=yes, ai-input=yes, ai-train=yes
```

The example above says: "any crawler may use this content for search, for AI input, and for AI training." That is the right declaration for a public spec that wants to be readable.

**Different signals per crawler if your policy varies.** Use a targeted group:

```
User-agent: GPTBot
Allow: /
Content-Signal: search=yes, ai-input=yes, ai-train=no

User-agent: *
Allow: /
Content-Signal: search=yes, ai-input=yes, ai-train=yes
```

**Pair with crawler-specific blocks where the answer is "no".** Content Signals is a hint; many crawlers still only obey `Disallow:`. A `Content-Signal: ai-train=no` paired with `User-agent: GPTBot \n Disallow: /` is stronger than either alone.

**Don't treat it as legal force.** It is a declaration. Compliance is voluntary, and the legal status of "you used my content for training despite my Content-Signal" is still developing.

## Common mistakes

- Spelling: `Content-Signal:` (singular). Not `Content-Signals:`.
- Putting the directive outside a group (no preceding `User-agent:` line). Some parsers will silently ignore it.
- Conflicting with `Disallow:`. If you `Disallow: /` for a bot, that bot was never going to fetch the page to read your `Content-Signal:`. They contradict; pick one.
- Inventing values beyond `yes` / `no`. The vocabulary is small on purpose.
- Treating it as a substitute for `Disallow:`. It is complementary.

## Verification

- `curl -s https://example.com/robots.txt | grep -i content-signal` lists every directive.
- [Is It Agent Ready?](https://isitagentready.com/) flips `botAccessControl.contentSignals` to `pass`.
- Track the [IETF aipref WG](https://datatracker.ietf.org/wg/aipref/documents/) for the final published vocabulary — names may yet shift before the RFC is published.

### Sources
- IETF AI Preferences WG (aipref) — drafts (IETF) — https://datatracker.ietf.org/wg/aipref/documents/
- IAB Tech Lab — Content Signals (IAB Tech Lab) — https://iabtechlab.com/working-groups/ai-content-signals/
- Is It Agent Ready? — Content Signals check (Is It Agent Ready?) — https://isitagentready.com/
- RFC 9309 — Robots Exclusion Protocol (IETF) — https://www.rfc-editor.org/rfc/rfc9309

---

## Web Bot Auth — verifiable bot identity

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/web-bot-auth/

Web Bot Auth lets a bot prove who it is by signing each HTTP request with a key it controls. Sites can then allow or block specific bots without IP allow-lists, user-agent strings, or guesswork. Built on RFC 9421 HTTP Message Signatures.

## What it is

Web Bot Auth is an emerging convention that lets a bot prove its identity cryptographically on every request, using the standard [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421) mechanism from RFC 9421. Instead of guessing whether a request really comes from OpenAI's crawler by inspecting the user-agent string and looking up reverse DNS, the server reads a `Signature` header, fetches the bot's public key from a published key directory, and verifies the signature.

The proposal lives in two IETF drafts: [draft-meunier-web-bot-auth-architecture](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) describes the trust model and discovery; [draft-meunier-web-bot-auth-http-signature](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-http-signature) profiles RFC 9421 for bot use. Cloudflare ships verification at the network edge, and a growing list of major crawlers sign their traffic.

## Why it matters

- **User-agent strings lie.** Anyone can set `User-Agent: GPTBot/1.0`. Signed requests cannot be forged without the bot operator's private key.
- **IP allow-lists rot.** Crawler IP ranges change. A signature-based check survives infrastructure migrations on the bot's side.
- **Granular policy.** Once you can verify the caller, you can apply different rules — paywall bypass for partner agents, slower rate limits for low-trust crawlers — without bespoke detection.
- **Composable with [Content Signals](/spec/agent-readiness/content-signals/) and [robots.txt for AI crawlers](/spec/agent-readiness/robots-for-ai-crawlers/).** robots.txt declares the policy; Web Bot Auth proves the identity the policy is about to be applied to.

Treat it as `optional` for now. The drafts are pre-RFC, the verifier ecosystem is small, and most sites will get the benefit transparently via their CDN before they touch any code. But the direction is clear: bot identity is moving from "trust the header" to "verify the signature".

## How to implement

**If you are running a site:**

- **Let the edge do it.** Cloudflare, Fastly, and other CDNs are adding signature verification as a configurable feature. Turn it on, expose the result to your origin as a request header (e.g. `Cf-Verified-Bot-Category`), and branch on it.
- **Combine, do not replace.** Web Bot Auth tells you who is calling. [robots.txt](/spec/seo/robots-txt/) and [Content Signals](/spec/agent-readiness/content-signals/) tell you what they may do with the response. Both layers are needed.
- **Do not punish unsigned traffic.** Treat unsigned requests with the same defaults you use today. Signed requests earn trust; unsigned ones do not lose it.

**If you operate a bot:**

- **Generate a signing keypair** (Ed25519 is the recommended algorithm in the draft).
- **Publish the public key** in a JWK Set at a stable URL declared in your bot's documentation. Per the draft, sites discover the key set from the `Signature-Agent` header or the bot's IANA-registered identity.
- **Sign every request** with the `signature-input` and `signature` headers per RFC 9421, covering at minimum `@method`, `@authority`, `@target-uri`, and a `created` timestamp.
- **Rotate keys** without breaking verifiers: keep the previous key in the published key set for at least a few weeks after rotation.

## Common mistakes

- Blocking unsigned traffic as a default. The standard is opt-in for bots; legitimate non-signing clients (including most browsers) will be locked out.
- Skipping the `created` field or accepting old timestamps. Without a freshness window, captured signatures replay forever.
- Verifying only the homepage. Bots fetch internal pages too; the policy has to apply site-wide.
- Treating the user-agent string as redundant. It still carries the human-readable bot name and version; signatures verify it, they do not replace it.

## Verification

- `curl -sI -H 'Signature: …' -H 'Signature-Input: …' https://example.com/` — a properly configured edge logs verification success and exposes a derived header to origin.
- For bot operators: feed your signed request into an RFC 9421 verifier and confirm the canonicalised signature base matches what your client constructed.
- Check your access logs for a verified-bot tag on traffic from signing crawlers (OpenAI, Anthropic, Perplexity, and others publish their key sets).

### Sources
- RFC 9421 — HTTP Message Signatures (IETF) — https://www.rfc-editor.org/rfc/rfc9421
- draft-meunier-web-bot-auth-architecture (IETF) — https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture
- draft-meunier-web-bot-auth-http-signature (IETF) — https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-http-signature
- Cloudflare — Forget IPs: using cryptography to verify bot and agent traffic (Cloudflare) — https://blog.cloudflare.com/web-bot-auth/

---

## Stable URLs

Status: required  ·  Source page: https://specification.website/spec/agent-readiness/stable-urls/

URLs are public contracts. Once published, they should keep working. Breaking them invalidates citations, bookmarks, links, and agent caches — and is almost always avoidable.

## What it is

A stable URL is one that keeps resolving to the same content over time, or — when content moves — redirects permanently to its new location. The principle was set out by Tim Berners-Lee in 1998 in *Cool URIs don't change* and has only become more important as agents, archives, and citations multiply.

A URL is a public contract. Once you publish one, every link, bookmark, citation, RSS reader, search index, and agent cache assumes it will keep working.

## Why it matters

- **Agents cache answers.** When a model quotes your page, it cites the URL. If that URL 404s next month, the citation is broken and your authority drops.
- **Search engines lose ranking signals.** Backlinks accumulated over years are tied to the URL.
- **Humans hate broken links.** Bookmarks, shared chat messages, printed materials.
- **Internal links rot.** Every change inside your own site creates work elsewhere on it.

A site that reorganises its URLs every release teaches the web not to trust it.

## How to implement

Design for permanence from the start:

- **Avoid implementation details.** No `/wp-content/`, `/index.php`, `.aspx`, or `?id=42`. These leak the stack and break when you switch it.
- **Avoid dates unless they are essential to the resource.** A news article can keep `/2025/03/headline`. An evergreen documentation page should not.
- **Avoid the author or department.** Authors leave and departments rename.
- **Use kebab-case slugs.** Lowercase, hyphens between words, no trailing slashes mixed with non-trailing slashes — pick one and enforce it.
- **Pick a canonical host.** `www.` or no-`www.`, HTTPS only, one path style. Redirect the rest.

When a URL must change, redirect:

- Issue a `301 Moved Permanently` (or `308` to preserve the method) from the old URL to the new one.
- Keep the redirect forever. Removing it years later breaks links you have forgotten about.
- Avoid chains: redirect `A` directly to `C`, not `A` to `B` to `C`.
- Never redirect everything to the homepage. That is worse than a 404 — it tells crawlers the page intentionally still exists.

For deletions, a clean `410 Gone` is more honest than a soft 404 or a homepage redirect.

## Common mistakes

- Re-platforming and changing every URL slug "while we're at it".
- Adding session IDs, tracking parameters, or A/B variants to canonical URLs.
- Letting trailing slashes serve different content from non-trailing slashes.
- 302 (temporary) redirects for moves that are permanent.
- Removing redirect maps after a year because the file got big.

## Verification

- Crawl old URLs after a migration and confirm each returns `301` to a working target.
- Use search-console reports to find 404s coming from external links.
- Spot-check archived URLs in the Wayback Machine. If they still load, your redirects are doing their job.

### Sources
- Cool URIs don't change (W3C — Tim Berners-Lee) — https://www.w3.org/Provider/Style/URI
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/
- Google — Redirects and Search (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/301-redirects

---

## Structured data for agents

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/structured-data-for-agents/

JSON-LD with schema.org types gives agents typed facts about your page. It is the same markup search engines use, and agents lean on it just as heavily.

## What it is

Structured data is a machine-readable description of what a page is about, embedded in the page itself. The dominant vocabulary is [schema.org](https://schema.org/), and the recommended syntax is JSON-LD: a `<script type="application/ld+json">` block inside `<head>`.

The same markup that drives rich results in Google also helps agents understand who wrote a page, what it describes, and how it relates to other entities. Agents do not parse open prose well; they parse JSON-LD reliably.

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Setting up CSP",
  "datePublished": "2026-05-12",
  "author": {
    "@type": "Person",
    "name": "Joost de Valk",
    "url": "https://example.com/about/joost"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Corp",
    "url": "https://example.com"
  }
}
</script>
```

## Why it matters

- **Disambiguation.** "Joost de Valk" is text. `Person` with a `url` is a typed identity.
- **Extraction quality.** Agents pull facts from JSON-LD with near-perfect accuracy. The same facts in prose are guessed.
- **Cross-page consistency.** A consistent `Organization` block across the site lets agents merge data into a single entity.
- **Search overlap.** What helps agents here is the same work that drives rich results and Knowledge Graph entries.

It is also one of the easiest items in this spec to verify: the markup is right there in the HTML.

## How to implement

Pick the types that match your pages. Common ones:

- `Article`, `BlogPosting`, `NewsArticle` for editorial content.
- `Product` with `Offer`, `AggregateRating`, `Review` for commerce.
- `FAQPage` and `Question` for Q&A content.
- `Person`, `Organization` for entity pages, used as nested references everywhere else.
- `Event`, `Recipe`, `HowTo`, `JobPosting`, `LocalBusiness` for vertical-specific pages.
- `BreadcrumbList` for breadcrumb trails.
- `WebSite` with `SearchAction` on the homepage.

Rules to follow:

- Use JSON-LD over Microdata or RDFa. Easier to write, easier to keep in sync.
- One block per type is fine; multiple blocks per page are also fine.
- Reuse `@id` URIs so agents can link entities across pages.
- Mirror what is visible on the page. Schema for content that does not appear violates Google's guidelines and trains agents to mistrust your markup.
- Test with the [Schema Markup Validator](https://validator.schema.org/) and Google's Rich Results Test.

## Common mistakes

- Marking up an `Article` that is actually a category page.
- Inflating `AggregateRating` with fake reviews. Both search engines and agents penalise this when caught.
- Leaving stale `datePublished` or `author` after a CMS migration.
- Forgetting to update structured data when the visible content changes.
- Using `@type: "WebPage"` for everything. Pick a specific type.

## Verification

- Run the page through [validator.schema.org](https://validator.schema.org/) and Google's Rich Results Test.
- Fetch the HTML and confirm the JSON-LD is present before JavaScript executes.
- Spot-check that the JSON-LD matches what a reader actually sees.

### Sources
- schema.org (schema.org) — https://schema.org/
- Google — Intro to structured data (Google Search Central) — https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data
- JSON-LD 1.1 (W3C) — https://www.w3.org/TR/json-ld11/
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/

---

## Machine-readable formats

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/machine-readable-formats/

Offer JSON, RSS, or plain markdown endpoints alongside HTML where it makes sense. Agents and feed readers prefer typed data over scraped HTML.

## What it is

A machine-readable format is a representation of your content designed to be consumed by software rather than rendered for humans. HTML is the universal default, but for lists, feeds, and structured records it is the wrong shape. JSON, RSS, Atom, and plain markdown are better.

Most sites already publish one without thinking about it: `sitemap.xml`. Adding a feed and an optional JSON endpoint covers the cases agents and aggregators care about most.

```xml

<rss version="2.0">
  <channel>
    <title>Example Corp Blog</title>
    <link>https://example.com/blog</link>
    <description>Notes on building things.</description>
    <item>
      <title>Setting up CSP</title>
      <link>https://example.com/blog/csp</link>
      <pubDate>Tue, 12 May 2026 10:00:00 GMT</pubDate>
    </item>
  </channel>
</rss>
```

```json
// /index.json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Example Corp Blog",
  "home_page_url": "https://example.com/blog",
  "feed_url": "https://example.com/index.json",
  "items": [
    {
      "id": "https://example.com/blog/csp",
      "url": "https://example.com/blog/csp",
      "title": "Setting up CSP",
      "date_published": "2026-05-12T10:00:00Z",
      "content_html": "<p>...</p>"
    }
  ]
}
```

## Why it matters

- Agents that need a list of recent posts can fetch one URL instead of scraping a paginated index.
- Feed readers, archive tools, and notification services have decades of support for RSS and Atom.
- JSON Feed is friendlier to modern toolchains and easier to extend.
- For documentation, exposing a `.md` next to each `.html` gives agents the source without HTML extraction.

The cost is small and the upside compounds: every consumer that does not have to parse HTML is one less source of bad quotes.

## How to implement

- **Sitemap.** Every site should have one — see [XML sitemaps](/spec/seo/xml-sitemaps/).
- **A feed.** Publish RSS 2.0 or Atom at a discoverable URL such as `/feed`, `/feed.xml`, or `/rss.xml`. Optionally publish a JSON Feed at `/feed.json` or `/index.json`. Link both from `<head>`:

```html
  <link rel="alternate" type="application/rss+xml" title="Blog" href="/feed.xml">
  <link rel="alternate" type="application/json" title="Blog" href="/feed.json">
  ```

- **Markdown sources.** For documentation, serve `page.md` alongside `page.html` — see [Per-page Markdown source endpoints](/spec/agent-readiness/markdown-source-endpoints/) for the full pattern, including `Accept: text/markdown` content negotiation done correctly with `Vary: Accept`.
- **Content negotiation.** Powerful, but easy to misuse. Always set `Vary: Accept` on every representation, otherwise caches will pin the wrong one for every subsequent visitor. When the formats are very different (HTML vs JSON), distinct URLs are usually simpler.
- **Stable schemas.** Once published, treat the field names as a contract — same rule as URLs.

## Common mistakes

- Truncating feed items to a one-line teaser. If you want agents to quote you fairly, give them the full content.
- Forgetting to update `pubDate` or `date_published`, so readers think nothing has changed.
- Letting the feed go stale because the CMS export broke quietly. Monitor it.
- Mixing absolute and relative URLs inside feed items. Use absolute everywhere.

## Verification

- Validate RSS at [validator.w3.org/feed](https://validator.w3.org/feed/).
- Validate JSON Feed against the [spec](https://www.jsonfeed.org/version/1.1/).
- Subscribe to your own feed in a reader and confirm new posts appear.

### Sources
- RSS 2.0 Specification (RSS Advisory Board) — https://www.rssboard.org/rss-specification
- JSON Feed 1.1 (JSON Feed) — https://www.jsonfeed.org/version/1.1/
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/

---

## HTTP Link headers for discovery

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/link-headers/

Use the HTTP Link header to advertise machine-readable resources — llms.txt, sitemap, api-catalog, RSS — directly in the response. Agents that never parse your HTML can still find what they need.

## What it is

The `Link` HTTP response header points the client at related resources. It is the same mechanism as `<link rel="…">` in HTML — same syntax, same registered relation types — except it travels with every response, including responses that have no HTML body (a JSON endpoint, a PDF, a 204).

```http
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Link: </llms.txt>; rel="describedby"; type="text/markdown"; title="Site index for LLMs",
      </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
      </sitemap-index.xml>; rel="sitemap"; type="application/xml",
      </rss.xml>; rel="alternate"; type="application/rss+xml"
```

Multiple links may be sent as comma-separated entries inside a single `Link` header (the form above) or as several `Link` headers. Both are valid per [RFC 8288 §3](https://www.rfc-editor.org/rfc/rfc8288#section-3).

## Why it matters

- **HTML-free discovery.** A crawler fetching `HEAD /` sees every machine-readable surface without downloading or parsing the body.
- **Universal.** Works on any response — `application/json`, `image/png`, a 304 Not Modified. There is no `<head>` on a JSON endpoint to put `<link>` tags in.
- **Cache-friendly.** A CDN can route to alternative representations purely from the `Link` header.
- **Required by agent-readiness validators.** [isitagentready.com](https://isitagentready.com/) explicitly checks for it on the homepage. Failing this check is a fail of the whole "discoverability" group.

## How to implement

**Pick registered relation types.** The [IANA Link Relations Registry](https://www.iana.org/assignments/link-relations/link-relations.xhtml) is the source of truth. Inventing your own is a bad signal. The relations a content site usually wants:

| `rel` | Purpose |
|---|---|
| `describedby` | A machine-readable description of this resource. Right for `llms.txt`. |
| `alternate` | An alternative representation of the same content (different format or language). Right for `.md` siblings, RSS, Atom, JSON Feed. |
| `api-catalog` | RFC 9727 — the location of `/.well-known/api-catalog`. |
| `sitemap` | The XML sitemap (or sitemap index). |
| `service-desc` / `service-doc` | A machine-readable / human-readable description of an API. |
| `security` | The `security.txt` policy. |
| `author` | Author resource. |
| `license` | Licence terms. |

**Send absolute or root-relative URLs.** Both are valid in `Link`; prefer root-relative for portability across protocols and ports.

**Include `type` and `title`.** They are optional in the header but make the link self-describing without an extra fetch.

**Ship on the homepage at minimum.** If you can afford it, ship on every response — the discovery benefit compounds when the agent enters mid-site.

**Edge configuration is the right layer.** Set `Link` headers at the CDN or reverse proxy, not in application code, so non-HTML responses get them too. On Cloudflare Pages this is one line in [`_headers`](https://developers.cloudflare.com/pages/configuration/headers/). On nginx it is `add_header Link …;`. On Vercel and Netlify it is config-driven.

## Common mistakes

- Sending `Link` only on HTML responses. Defeats the "HTML-free" point — agents looking at your `/api/users.json` get nothing.
- Inventing a custom `rel`. Crawlers ignore it. Use IANA-registered relations only.
- Wrapping URLs in quotes. Per RFC 8288, the URI goes inside `<>` angle brackets, not quotes.
- Forgetting to comma-separate when listing multiple links in one header. Without the comma, parsers see one malformed entry.
- Sending `Link` headers that contradict the HTML `<link rel>` entries. The headers and the HTML should be consistent — they describe the same site.

## Verification

- `curl -sI https://example.com/ | grep -i ^link` — lists every advertised relation in one shot.
- [Is It Agent Ready?](https://isitagentready.com/) flips `discoverability.linkHeaders` to `pass`.
- [Web Linking validator](https://datatracker.ietf.org/doc/html/rfc8288) — parse-and-render tools spot syntactic errors.
- Cross-check against `<head>`: every `rel` in the HTML should have an equivalent in the headers.

### Sources
- RFC 8288 — Web Linking (IETF) — https://www.rfc-editor.org/rfc/rfc8288
- RFC 9727 — Publishing Organisation API Information (IETF) — https://www.rfc-editor.org/rfc/rfc9727
- RFC 9264 — Linkset: Media Types and a Link Relation Type for Link Sets (IETF) — https://www.rfc-editor.org/rfc/rfc9264
- IANA — Link Relations Registry (IANA) — https://www.iana.org/assignments/link-relations/link-relations.xhtml
- Is It Agent Ready? — Link headers check (Is It Agent Ready?) — https://isitagentready.com/

---

## MCP and tool discovery

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/mcp-and-tool-discovery/

The Model Context Protocol is an emerging way for sites to expose queryable tools to agents over JSON-RPC. Relevant whenever your content has structure worth filtering — even for a static reference site like this one.

## What it is

The Model Context Protocol (MCP) is an open protocol, originally proposed by Anthropic in late 2024, that defines how language-model clients talk to external tools and data sources. Instead of an agent scraping your UI, you expose an MCP server that declares a set of tools, resources, and prompts; the agent calls them directly.

MCP is built on JSON-RPC over a few transports — stdio for local servers, HTTP plus Server-Sent Events for remote ones. A tool definition includes a name, a description, and a JSON Schema for inputs.

This is relevant when your site exposes actions a user might want an agent to take: search a catalogue, create a ticket, book an appointment, query an account. For static content sites and blogs, MCP often adds little — well-cached HTML and a feed are enough. The exception is structured content sites where the data is filterable: a documentation set, a spec, a knowledge base. There an MCP server lets an agent ask "list all required SEO topics" or "give me the canonical CSP page" in a single typed call, instead of crawling and parsing.

This site ships such a server as a worked example. See [mcp.specification.website](https://mcp.specification.website/) for the live endpoint, [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json) for the discovery document, and the [`mcp/` directory of the source repo](https://github.com/jdevalk/specification.website/tree/main/mcp) for a ~300-line Cloudflare Worker implementation.

## Why it matters

- Agents call your functionality through a defined contract instead of guessing from a UI. Behaviour is predictable and auditable.
- One MCP server can be reused across Claude, ChatGPT (via connectors), and any other MCP-aware client. No per-vendor integration.
- Authorisation is explicit. Tools declare what they do; the agent (and the user) consents before calling.
- The same server is useful for your own internal automation, not just public agents.

Adoption is real but uneven. Treat it as an emerging convention worth investing in if your product is API-shaped, and as overkill if it is not.

## How to implement

- Decide what you want agents to do. Read-only tools (`search_products`, `get_order_status`) are a safe first step; write tools (`create_ticket`, `update_address`) come with stronger auth requirements.
- Build an MCP server. The reference SDKs cover TypeScript, Python, and others; see [modelcontextprotocol.io](https://modelcontextprotocol.io/).
- Host it at a discoverable URL such as `/mcp` or a subdomain like `mcp.example.com`. Document the endpoint in your developer docs and link it from [/llms.txt](/spec/agent-readiness/llms-txt/).
- **Publish a server card.** Ship `/.well-known/mcp/server-card.json` describing the server's name, version, transport, endpoint URL, capabilities, tools, and prompts. Add a `Link: </.well-known/mcp/server-card.json>; rel="mcp"` header on your main site so the card is discoverable without guessing the path — see [HTTP Link headers](/spec/agent-readiness/link-headers/) and [`/.well-known/api-catalog`](/spec/well-known/api-catalog/).
- Use OAuth 2.1 (the MCP spec aligns with it) for any tool that touches user data. Never accept long-lived API keys in tool calls.
- Keep tool descriptions short and precise. Agents pick which tool to call from the description.
- Version the schema. Renaming a tool or changing its input shape is a breaking change.

## Common mistakes

- Exposing every internal API as an MCP tool. Curate; agents reason better about a small, well-named surface.
- Skipping rate limits and audit logs. An MCP endpoint that an agent can call repeatedly is an abuse vector.
- Mixing read and write tools without clear naming. Make destructive actions obvious in the tool name.
- Treating MCP as a replacement for documentation. It complements it; it does not replace it.

## Verification

- Connect your server with the MCP Inspector or a reference client and confirm tools list, call, and return as expected.
- Review the OAuth flow end to end.
- Watch logs after a public launch for unexpected call patterns.

### Sources
- Model Context Protocol (Anthropic / MCP project) — https://modelcontextprotocol.io/
- MCP specification (MCP project) — https://modelcontextprotocol.io/specification
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/

---

## A2A agent cards

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/a2a-agent-cards/

The Agent-to-Agent (A2A) protocol lets an autonomous agent find another autonomous agent and call it over JSON-RPC. Discovery hinges on a single well-known file: `/.well-known/agent-card.json`. Relevant whenever your service exposes agentic behaviour another agent might want to delegate to.

## What it is

The Agent-to-Agent (A2A) protocol is an open standard for one autonomous agent to discover and call another. It was originally proposed by Google in 2025 and donated to the Linux Foundation later that year. It complements the [Model Context Protocol](/spec/agent-readiness/mcp-and-tool-discovery/): MCP exposes tools an LLM can call; A2A exposes a whole agent another agent can delegate to.

Discovery is deliberately small. An A2A-speaking service hosts a JSON manifest at the well-known URI `/.well-known/agent-card.json`. The manifest is the **agent card** — a self-describing document that names the agent, lists its skills, declares its capabilities, and points at one or more transport endpoints that speak the A2A wire protocol (JSON-RPC, gRPC, or HTTP+JSON).

The minimum field set is small and stable. Required fields per the spec are `name`, `description`, `version`, `supportedInterfaces` (each with `url`, `protocolBinding`, `protocolVersion`), `capabilities`, `defaultInputModes`, `defaultOutputModes`, and `skills` (each with `id`, `name`, `description`, `tags`). Optional fields cover provider, documentation URL, security schemes, JWS signatures, and an icon URL.

This site ships such a card as a worked example. The static manifest is at [`/.well-known/agent-card.json`](/.well-known/agent-card.json); the JSON-RPC endpoint is at [`mcp.specification.website/a2a/v1`](https://mcp.specification.website/a2a/v1). It is intentionally minimal — `message/send` only, no streaming, no task lifecycle — and it wraps the same search and topic-fetch logic the MCP server already exposes.

## Why it matters

- An agent card is the standard way for a calling agent to learn what you do, before any call is made. Without it, the calling agent has to be hard-coded against your service or guess from a UI.
- A2A is transport-agnostic: a single card can advertise JSON-RPC, gRPC, and HTTP+JSON endpoints in priority order. Clients pick the binding they support.
- It composes cleanly with MCP. An MCP server gives an LLM tools; an A2A card lets that whole LLM-plus-tools agent be reached by *other* agents. The two protocols are not alternatives.
- The card is a contract. Treat changes to `skills[].id`, `supportedInterfaces[].url`, or `capabilities` as breaking, and bump `version` accordingly.

Adoption is early but accelerating. The protocol reached version 1.0 in March 2026. Treat A2A as `optional` for now — useful if your product is itself an agent or wraps one, overkill if it is a static brochure.

## How to implement

- **Build the card.** Author a JSON document with `protocolVersion`, `name`, `description`, `version`, `provider`, `supportedInterfaces`, `capabilities`, `defaultInputModes`, `defaultOutputModes`, and `skills`. Use the [A2A specification](https://a2a-protocol.org/latest/specification/) as the field reference. Use camelCase keys throughout.
- **Pick a transport.** JSON-RPC over HTTPS is the lowest-friction option and is what we ship here. gRPC is appropriate when you already speak gRPC; HTTP+JSON when you have an existing REST surface to wrap.
- **Serve it at the canonical URI.** Per [RFC 8615](https://www.rfc-editor.org/rfc/rfc8615), publish at `/.well-known/agent-card.json` with `Content-Type: application/json` and a sensible `Cache-Control` (an hour is fine; ETag is better).
- **Advertise it.** Add a `Link: </.well-known/agent-card.json>; rel="service-desc"; type="application/json"` response header so clients can discover the card without guessing the path. Add the same link to your [`/.well-known/api-catalog`](/spec/well-known/api-catalog/) Linkset entry. See [HTTP Link headers](/spec/agent-readiness/link-headers/).
- **Ship the endpoint behind it.** Do not publish a card that points at a non-existent URL. The first call most validators make is to the endpoint; a 404 there is worse than no card at all. At minimum, implement the `message/send` JSON-RPC method and return method-not-found for the rest.
- **Be honest about capabilities.** If you do not support streaming, set `capabilities.streaming` to `false`. The same goes for `pushNotifications` and `extendedAgentCard`. Lying here breaks clients that probe before they call.
- **Sign the card if you care about provenance.** A2A allows JWS signatures (`signatures[]`); useful in curated registries, optional for direct discovery.

## Common mistakes

- Publishing a card that points at a URL that 404s. Discovery validators check the URI; runtime agents check the endpoint. Both matter.
- Mixing up `agent-card.json` with `agent.json`. The canonical filename is `agent-card.json` — pick it, do not invent a redirect.
- Claiming capabilities you do not implement. Setting `streaming: true` without a working `message/stream` method is a contract violation, not a polite overstatement.
- Treating the card as static when the agent evolves. Every change to skills or transports needs a `version` bump.
- Forgetting the `Content-Type`. A card served as `text/plain` will be rejected by stricter clients. Serve it as `application/json`.

## Verification

- `curl https://your-site.example/.well-known/agent-card.json` returns 200 with `Content-Type: application/json` and parses as JSON.
- The JSON validates against the A2A schema for your `protocolVersion`. Required fields are present; `supportedInterfaces[0].url` resolves; `skills` are non-empty.
- `curl -X POST` against `supportedInterfaces[0].url` with a minimal `message/send` JSON-RPC body returns a JSON-RPC response (not an HTML error page).
- The card appears in your `/.well-known/api-catalog` Linkset and in the `Link` response header on `/`.
- A live test: connect the agent from a second A2A-speaking client and confirm at least one skill round-trips end-to-end.

### Sources
- A2A Protocol — Specification (A2A Project (Linux Foundation)) — https://a2a-protocol.org/latest/specification/
- A2A Protocol — Agent Discovery (A2A Project (Linux Foundation)) — https://a2a-protocol.org/latest/topics/agent-discovery/
- a2aproject/A2A on GitHub (A2A Project) — https://github.com/a2aproject/A2A
- RFC 8615 — Well-Known URIs (IETF) — https://www.rfc-editor.org/rfc/rfc8615

---

## Agent Skills discovery

Status: recommended  ·  Source page: https://specification.website/spec/agent-readiness/agent-skills-discovery/

A well-known URI that lists Agent Skills — short, scoped instructions an AI agent can load to work better with your site. Emerging convention via a Cloudflare-led RFC; still draft, still cheap to ship.

## What it is

An Agent Skill is a small Markdown file — a `SKILL.md` with YAML frontmatter — that gives an AI agent a focused capability: when to use it, how to call your APIs, which conventions to follow. The format originated with Anthropic; the [agentskills.io specification](https://agentskills.io/specification) documents it.

Agent Skills Discovery is the convention for *publishing* those skills so any agent can find them. Per the Cloudflare-led [discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) (currently draft v0.2.0), publishers ship a JSON index at:

```
/.well-known/agent-skills/index.json
```

Each entry in the index has a `name`, `type` (`skill-md` or `archive`), `description`, `url`, and a `sha256` digest of the artefact. A top-level `$schema` field identifies the index version.

This site publishes one such skill: [`/.well-known/agent-skills/specification-website/SKILL.md`](/.well-known/agent-skills/specification-website/SKILL.md), advertised in [`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json). It teaches an agent how to query the spec via Markdown endpoints, [llms.txt](/spec/agent-readiness/llms-txt/), and the [MCP server](/spec/agent-readiness/mcp-and-tool-discovery/).

## Why it matters

- One URL answers "what skills does this site publish for agents?" — no scraping, no per-vendor registry.
- Skills are vendor-neutral Markdown. The same file works in Claude, in agent harnesses, and in anything else that loads the format.
- The `digest` field gives clients cheap change detection and integrity verification.
- It composes with other agent-readiness signals: a skill can teach an agent to prefer your `.md` endpoints, hit your MCP server, or follow your structured-data conventions.

Adoption is early. Treat it as a low-cost bet, not a settled standard.

## How to implement

- Author one or more `SKILL.md` files. Each MUST start with YAML frontmatter containing `name` (lowercase, hyphens, 1–64 chars) and `description` (≤1024 chars, written so an agent can decide whether to load the full body).
- Host each skill at `/.well-known/agent-skills/<name>/SKILL.md`. Serve as `text/markdown`.
- Publish `/.well-known/agent-skills/index.json` with `$schema` set to `https://schemas.agentskills.io/discovery/0.2.0/schema.json` and a `skills` array. Each entry needs `name`, `type`, `description`, `url`, and `digest`.
- Compute the digest as `sha256:<hex>` over the raw bytes of the artefact. Recompute and update the index every time the artefact changes.
- Advertise the index in [`/.well-known/api-catalog`](/spec/well-known/api-catalog/) and as a [`Link`](/spec/agent-readiness/link-headers/) header: `rel="agent-skills"; type="application/json"`.
- Serve both files with CORS open (`Access-Control-Allow-Origin: *`) so browser-based agents can fetch them.

## Common mistakes

- Letting the `digest` drift from the file. A mismatch makes the artefact unverifiable; compliant clients will refuse it.
- Writing the description as marketing copy. It is the only thing most agents read — front-load the *when to use this* signal.
- Bundling many unrelated capabilities into one skill. Prefer several small skills with sharp descriptions over one omnibus file.
- Forgetting `$schema`. Without it, clients fall back to v0.1.0 parsing and your entries may be ignored.
- Hosting `SKILL.md` with the wrong content type. `text/html` will confuse agents that fetch it directly.

## Verification

- `curl -sI https://example.com/.well-known/agent-skills/index.json` — confirm `200`, `Content-Type: application/json`.
- Parse the JSON and verify `$schema` matches the v0.2.0 URI.
- For each entry, fetch the `url`, hash the bytes, and confirm the result equals the `digest`.
- Validate with [isitagentready.com](https://isitagentready.com/) — `checks.discovery.agentSkills.status` should report `pass`.

### Sources
- Agent Skills Discovery via Well-Known URIs (RFC draft) (Cloudflare) — https://github.com/cloudflare/agent-skills-discovery-rfc
- Agent Skills specification (agentskills.io) — https://agentskills.io/specification
- RFC 8615 — Well-Known URIs (IETF) — https://datatracker.ietf.org/doc/html/rfc8615
- Is It Agent Ready? (Is It Agent Ready?) — https://isitagentready.com/

---

## DNS for AI Discovery (DNS-AID)

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/dns-aid/

Publish SVCB/HTTPS records under _agents.example.com so agents can discover your services from DNS, before any HTTP round-trip. Pair with DNSSEC so the answer is authenticated.

## What it is

DNS for AI Discovery (DNS-AID) is a draft IETF proposal that uses the existing [SVCB and HTTPS resource records](/spec/security/dnssec/) (RFC 9460) under a reserved `_agents` label to advertise where agents can reach your services. Instead of crawling a homepage to find a `Link` header or a `.well-known/` document, a client makes a single DNS query and gets a typed answer.

The well-known names follow the `_<service>._agents.<domain>` pattern. Two that the current draft and tooling check for:

| Name | Purpose |
|---|---|
| `_index._agents.example.com` | General entry point. Points at the canonical site. |
| `_mcp._agents.example.com`   | An [MCP](/spec/agent-readiness/mcp-and-tool-discovery/) server. |
| `_a2a._agents.example.com`   | An A2A (agent-to-agent) endpoint. |

Each record is in ServiceMode (priority ≥ 1), carrying `alpn` and `port` parameters at minimum:

```
_index._agents.example.com.  3600 IN HTTPS 1 example.com.            alpn="h3,h2" port=443
_mcp._agents.example.com.    3600 IN HTTPS 1 mcp.example.com.        alpn="h3,h2" port=443 mandatory="alpn,port"
```

## Why it matters

- **Discovery before the first HTTP request.** A DNS lookup is on the critical path for almost every connection anyway; piggybacking discovery on it is free.
- **Works for non-HTTP services too.** Any service with an ALPN identifier can be advertised this way.
- **Authenticated.** Combined with [DNSSEC](/spec/security/dnssec/), a validating resolver returns proof-of-authenticity. Without DNSSEC the record is just a hint.
- **Required by some agent-readiness validators.** [isitagentready.com](https://isitagentready.com/) explicitly checks for these records and for DNSSEC validation on the answer.

## How to implement

**Pick the services to advertise.** At minimum: `_index._agents`. If you run a public MCP server, also `_mcp._agents`. Add `_a2a._agents` when you support agent-to-agent endpoints. Don't advertise endpoints you don't actually offer.

**Use HTTPS records for HTTPS-based services and SVCB for everything else.** Both serialise the same way; HTTPS is the convenience alias for the common case.

**Required parameters:** `alpn` (the protocol the client will speak — typically `h3,h2` for browser-style HTTPS) and `port` (almost always `443`). The draft recommends including `mandatory="alpn,port"` on at least one record to signal to clients that those parameters must be understood.

**Sign the zone.** Without [DNSSEC](/spec/security/dnssec/), the discovery answer is unauthenticated and validators will downgrade or fail. Enable DNSSEC at your authoritative DNS, then ensure your registrar publishes the corresponding DS record.

**Advertise on the canonical domain, not the platform's vendor subdomain.** Records on `your-site.netlify.app` or `your-project.pages.dev` don't help agents that already know your real domain.

**Implementation, on Cloudflare specifically:** create the records as `HTTPS` type with name `_index._agents` (Cloudflare auto-appends the zone), priority `1`, target the canonical hostname, parameters as above. Enable DNSSEC under DNS settings. See `scripts/publish-dns-aid.sh` in this repo for the API call.

## Common mistakes

- Publishing in AliasMode (priority `0`) when you meant ServiceMode. Validators expect ServiceMode for the discovery use case.
- Missing `port`. Most parsers tolerate the omission and assume 443; some don't.
- Inventing custom params with unallocated names. Until the IETF assigns them, use the numeric `keyNNNNN` form rather than guessing a string identifier.
- Forgetting the trailing dot on the target hostname in zone-file syntax. Without it, the target is treated as relative.
- Enabling DNSSEC on the Cloudflare side but not pasting the DS record at an external registrar. The signature exists but the chain of trust breaks at the parent.
- Pointing `_index._agents` at a `pages.dev` / `netlify.app` / `vercel.app` host. Use your real domain.

## Verification

- `dig +short HTTPS _index._agents.example.com` returns a record beginning with `1 example.com.`.
- `dig +dnssec +cd HTTPS _index._agents.example.com` returns an `RRSIG` line — confirming DNSSEC is signing the answer.
- `dig +short DS example.com` returns at least one DS record at the registrar — confirming the chain of trust.
- [Is It Agent Ready?](https://isitagentready.com/) flips `discoverability.dnsAid` to `pass`.
- [Cloudflare DNSSEC Debugger](https://dnssec-debugger.verisignlabs.com/) or `dnssec-analyzer` shows a clean validation chain.

### Sources
- draft-mozleywilliams-dnsop-dnsaid — DNS for AI Discovery (IETF) — https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/
- RFC 9460 — Service Binding and Parameter Specification via the DNS (SVCB and HTTPS RRs) (IETF) — https://www.rfc-editor.org/rfc/rfc9460
- RFC 4033 — DNS Security Introduction and Requirements (IETF) — https://www.rfc-editor.org/rfc/rfc4033
- Is It Agent Ready? — DNS-AID check (Is It Agent Ready?) — https://isitagentready.com/

---

## NLWeb — conversational interface discovery

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/nlweb/

NLWeb is an emerging convention for exposing a site as a conversational AI endpoint. A site advertises an `/ask`-style endpoint via a `rel="nlweb"` link and serves an MCP-compatible JSON-RPC interface that agents can query in natural language.

## What it is

NLWeb is an open project, originally from Microsoft, that lets any website expose a conversational query interface in a standard way. A site implements a small HTTP endpoint — by convention `/ask` — that accepts a natural-language query and returns a structured answer grounded in the site's own content, typically built from its [schema.org](https://schema.org/) data and embeddings of its pages.

Discovery is one HTML link tag:

```html
<link rel="nlweb" href="/ask" title="Ask this site">
```

An agent that recognises the relation knows the site speaks NLWeb without further negotiation. The endpoint itself follows a documented JSON shape and can additionally be wrapped as an MCP tool, so the same query path is reachable from both browser-side and server-side agent runtimes.

## Why it matters

- **One endpoint per site, not per question.** NLWeb gives agents a single answerable surface instead of asking them to crawl, embed, and reason over every page themselves.
- **Grounded in your own content.** Answers come from the site's structured data and corpus. A site retains editorial control over what gets cited.
- **Composes with [MCP](/spec/agent-readiness/mcp-and-tool-discovery/).** The NLWeb endpoint can also be exposed as an `ask_site` MCP tool. Same logic, two transports.
- **Cheap to ship.** A static site with [structured data](/spec/agent-readiness/structured-data-for-agents/) and a small vector index can answer most factual questions about its own content without a chatbot UI.

The convention is early and mostly Microsoft-driven so far, but the discovery link is a single line in `<head>` and the endpoint shape is documented. Treat NLWeb as `optional` — recommended where the site already has the corpus to ground answers, skippable for small static sites.

## How to implement

- **Build the corpus.** Index your pages — embeddings of the body text, plus the [JSON-LD](/spec/agent-readiness/structured-data-for-agents/) you already publish. Many implementations use the same schema.org data they ship in `<head>` as the source of truth.
- **Expose `/ask`.** Accept `GET` with a `query` parameter, or `POST` with a JSON body. Return JSON with the answer, the sources cited (URLs into your own site), and any structured results.
- **Advertise it.** Add `<link rel="nlweb" href="/ask">` to `<head>` and a matching `Link: </ask>; rel="nlweb"` HTTP header. See [HTTP Link headers](/spec/agent-readiness/link-headers/).
- **Mirror as an MCP tool.** If you already ship an [MCP server](/spec/agent-readiness/mcp-and-tool-discovery/), register a tool — `ask_site` is the common name — that wraps the same endpoint. Agents that speak MCP but not NLWeb get the same capability.
- **Cite, always.** Every answer should include the source URLs it was built from. Answers without citations train users (and agents) to mistrust the surface.

## Common mistakes

- Answering questions the site has no authority to answer. Scope `/ask` to your own corpus; refuse off-topic questions rather than guessing.
- Shipping a chatbot UI without the discovery link. Agents need the `rel="nlweb"` signal to find the endpoint; humans clicking a widget do not.
- Letting the index go stale. A grounded answer pulled from last quarter's corpus reads as a wrong answer, not a delayed one.
- Returning HTML. NLWeb is a machine interface; the response is JSON. If you also want to render the answer in a UI, do it client-side from the JSON.

## Verification

- `curl -sI https://example.com/ | grep -i nlweb` returns a `Link` header with `rel="nlweb"`.
- View source on the homepage — `<link rel="nlweb" href="…">` is present.
- `curl 'https://example.com/ask?query=what+do+you+do'` returns a JSON body with an `answer` field and a `sources` array of URLs into your own site.
- Spot-check that the cited URLs exist and that the answer matches what is on them.

### Sources
- microsoft/NLWeb on GitHub (Microsoft) — https://github.com/microsoft/NLWeb
- NLWeb — Overview (Microsoft) — https://github.com/microsoft/NLWeb/blob/main/docs/nlweb-rest.md
- schema.org (schema.org) — https://schema.org/

---

## WebMCP — browser-native tools for agents

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/webmcp/

WebMCP lets a page register tools that an in-browser AI agent can call directly, using a `navigator.modelContext` JavaScript API. It turns a site into an agent surface without server-side MCP plumbing.

## What it is

WebMCP is an emerging browser API that lets a page register structured tools — named functions with input schemas — that an AI agent running inside the same browser (a sidebar assistant, a built-in browser agent, an extension) can invoke directly. The shape mirrors [Model Context Protocol](/spec/agent-readiness/mcp-and-tool-discovery/) tools, hence the name: it is MCP, but the transport is the JavaScript heap instead of HTTP+JSON-RPC.

The proposal is incubated in the [W3C Web Machine Learning Community Group](https://webmachinelearning.github.io/webmcp/). The current spec surface is `document.modelContext`; earlier drafts (and some shipping implementations) exposed it as `navigator.modelContext` and a portable script feature-detects both. A page registers a tool by calling `registerTool({ name, description, inputSchema, annotations, execute })`. The browser exposes registered tools to the local agent; the agent calls `execute()` and gets a result back, all without leaving the tab.

```js
const mc =
  (typeof document !== 'undefined' && document.modelContext) ||
  (typeof navigator !== 'undefined' && navigator.modelContext);

mc?.registerTool({
  name: 'search_docs',
  description: 'Search the documentation for a query.',
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query'],
  },
  annotations: { readOnlyHint: true },
  async execute({ query }) {
    const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
    return { content: [{ type: 'text', text: await res.text() }] };
  },
});
```

**This site ships it.** Every page on `specification.website` loads [`/webmcp.js`](/webmcp.js), which registers `search_spec`, `list_topics`, `get_topic`, `open_search`, and `open_checklist` tools — generated at build time from the same content collection that powers the rest of the site. An in-browser agent can search and read the spec without going through the remote [MCP server](/spec/agent-readiness/mcp-and-tool-discovery/).

## Why it matters

- **Same vocabulary as server-side MCP.** A team that already builds MCP tools on the server can expose the same shapes in the browser without re-modelling.
- **Sees the logged-in user.** A browser-side tool runs inside the user's authenticated session, including cookies, IndexedDB, and any per-tab state. A server MCP server has none of that without explicit auth plumbing.
- **No new transport.** Nothing to host, nothing to scale, no auth headers to wire up. The browser is the transport.
- **Composes with MCP.** A site can ship both: an HTTP MCP server for headless agents and a WebMCP surface for in-browser agents. Same tool names, same schemas, same intent.

The API is early — implementations are shipping behind flags and via polyfill. Treat WebMCP as `optional` until at least one major browser exposes it without a flag. The cost of being early is low; the design follows MCP closely so most code will port forward.

## How to implement

- **Register tools at page load**, after `navigator.modelContext` is feature-detected. If the API is absent, do nothing — never throw.
- **Mirror your server-side MCP tools.** If you already publish `search_docs` on an HTTP MCP server, register a tool with the same name, description, and input schema in the browser. An agent that knows the server-side tool will recognise the browser one immediately.
- **Use the `annotations` field** to declare safety properties: `readOnlyHint: true` for tools that do not mutate state, `destructiveHint: true` for ones that do. The agent uses these to decide whether to confirm with the user.
- **Pick `mode: 'summarize'`** when the tool returns a single result rather than streaming. Streaming is supported but adds complexity that most page tools do not need.
- **Keep `execute()` small.** A tool is a thin call into existing site functionality (search, navigation, account actions), not a bespoke pipeline.
- **Document the tools.** Add them to your [agent skills index](/spec/agent-readiness/agent-skills-discovery/) so agents that read the site's discovery surfaces — not just ones already in the browser — know they exist.

## Common mistakes

- Registering tools that bypass the site's own access controls. A WebMCP tool runs as the logged-in user; treat it like any other JavaScript-callable action and apply the same authorisation checks server-side.
- Forgetting feature detection. `navigator.modelContext` does not exist in most browsers yet. Guard every call.
- Designing tools that only make sense in the browser. If a server-side MCP server can do the same job, ship both — agents should be able to use whichever transport they have.
- Treating annotations as cosmetic. `readOnlyHint` and `destructiveHint` change agent behaviour; declare them honestly.

## Verification

- `typeof navigator.modelContext?.registerTool === 'function'` in a console on a supporting browser.
- The browser's agent UI lists your registered tools by name and description.
- Calling a registered tool from a test agent returns a well-formed MCP-shaped result (`{ content: [...] }`).
- If you ship a parallel HTTP MCP server, the tool names match across both surfaces.

### Sources
- WebMCP — W3C Web Machine Learning Community Group (W3C WebML CG) — https://webmachinelearning.github.io/webmcp/
- webmachinelearning/webmcp on GitHub (W3C WebML CG) — https://github.com/webmachinelearning/webmcp
- Model Context Protocol — Tools (MCP) — https://modelcontextprotocol.io/specification/2025-06-18/server/tools

---

## Schemamap — discoverable JSON-LD endpoints per resource

Status: optional  ·  Source page: https://specification.website/spec/agent-readiness/schemamap/

A convention this site proposes — no external standard exists yet. `/schemamap.xml` indexes one JSON-LD endpoint per resource so agents fetch the structured-data graph directly instead of extracting it from HTML.

## What it is

Schemamap is a convention this site proposes. It has no external standard, no IANA-registered link relation, and no second implementer at the time of writing. It is documented here as a worked proposal — not as settled web infrastructure. Treat the status as `optional` and adopt it because the design fits your needs, not because anyone else expects you to ship it.

The shape:

1. **A per-resource JSON-LD endpoint.** Every page that has structured data exposes its JSON-LD graph at a predictable URL — by convention, the canonical URL with a `.jsonld` suffix — served with `Content-Type: application/ld+json`. The endpoint returns the same `@graph` the HTML embeds, in a stable shape, with no surrounding markup to parse.

2. **An index — `/schemamap.xml`.** A sitemap-shaped XML file at the site root lists every resource that has a JSON-LD endpoint. Each `<resource>` carries the canonical URL, the `.jsonld` URL, the schema.org `@type`s present, and an optional `<lastmod>`.

3. **HTML discovery.** Two `<link>` tags in `<head>`. The site-wide one points at the index using the proposed `rel="schemamap"`. The per-page one points at this resource's JSON-LD endpoint using the registered `rel="alternate" type="application/ld+json"` — so agents that do not recognise `schemamap` still find the per-page graph through a standard relation.

```html

<link rel="alternate" type="application/ld+json"
      href="https://example.com/articles/foo.jsonld"
      title="Foo — JSON-LD graph">

<link rel="schemamap" type="application/xml"
      href="/schemamap.xml"
      title="Schemamap index">
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<schemamap xmlns="https://example.com/schemas/schemamap/0.1">
  <resource>
    <loc>https://example.com/articles/foo/</loc>
    <jsonld>https://example.com/articles/foo.jsonld</jsonld>
    <type>Article</type>
    <type>BreadcrumbList</type>
    <lastmod>2026-05-29</lastmod>
  </resource>
</schemamap>
```

**This site ships it.** Every spec page exposes a JSON-LD graph at `/spec/<category>/<slug>.jsonld`, and the index at [`/schemamap.xml`](/schemamap.xml) lists all of them. The per-page graph is also registered in the [api-catalog Linkset](/.well-known/api-catalog) under a URI-based rel so the discovery path is self-describing without the IANA registry.

## Why it matters

The status quo for structured data is "parse the HTML and pick out every `<script type=\"application/ld+json\">`". That works, but it has costs:

- **Lossy extraction.** Some sites ship multiple disagreeing JSON-LD blocks across plugins or templates on the same page; the [structured-data page](/spec/seo/structured-data/) flags this as a common mistake. There is no contract that says which block is canonical.
- **Hydration risk.** Frameworks that emit JSON-LD after JavaScript runs make the markup invisible to non-rendering crawlers. A dedicated endpoint runs no JavaScript.
- **No index.** The XML sitemap lists URLs; it does not say which of those URLs carries `Article`, `Product`, or `BreadcrumbList` markup. An agent that wants every `Recipe` on a site has to fetch every page.
- **Cross-page `@id` linking is harder than it should be.** When the graph lives in `<script>` tags scattered across the site, you cannot dereference an `@id` URI unless every page that mentions the entity is fetched.

A discoverable index of JSON-LD endpoints fixes all four cheaply. The cost is one new endpoint type and one extra file. Compare with the [Markdown source endpoints](/spec/agent-readiness/markdown-source-endpoints/) convention, which solves the same kind of problem for prose.

## How to implement

**Expose the per-page endpoint first.** Without `.jsonld` URLs, the index has nothing to point at. For each page that ships structured data, render the same graph you embed in the HTML to a separate endpoint:

```http
GET /articles/foo.jsonld HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/ld+json; charset=utf-8
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=3600
```

Use a stable `@id` on every node (the canonical URL with a fragment is fine — `#article`, `#breadcrumb`, `#organization`). Include a `license` field on the graph if your content is licensed.

**Build the index from the same content source.** On `specification.website`, [`src/pages/schemamap.xml.ts`](https://github.com/jdevalk/specification.website/blob/main/src/pages/schemamap.xml.ts) iterates the content collection that drives the rest of the site, so the index cannot drift from the per-page endpoints. Sort entries by category then order then title — agents that incrementally fetch will see the same ordering as humans on `/spec/`.

**Advertise discovery in `<head>`.**

```html
<link rel="alternate" type="application/ld+json" href="…/page.jsonld" title="… JSON-LD graph">
<link rel="schemamap" type="application/xml" href="/schemamap.xml" title="Schemamap index">
```

Add the per-page link on every page that has a JSON-LD endpoint. Add the schemamap link site-wide.

**Pick the right serving headers.** `Content-Type: application/ld+json` for the endpoints, `application/xml` for the index. Set `Access-Control-Allow-Origin: *` so cross-origin agents can fetch the graph from a browser context. Cache aggressively — the graph only changes when the source content does.

**Be honest in the index about the registration gap.** The `rel="schemamap"` value is not in the [IANA Link Relations Registry](https://www.iana.org/assignments/link-relations/link-relations.xhtml). [HTTP Link headers](/spec/agent-readiness/link-headers/) explicitly warns against inventing custom `rel` values for that reason. Two ways to handle it:

- **In HTML `<head>` only.** Ship `rel="schemamap"` in the page — that link tag *is* the proposal under test. Do not add it to the global HTTP `Link` header until the relation is registered. This site takes that route.
- **Use a URI-form `rel` instead.** Per [RFC 8288 §2.1.1](https://www.rfc-editor.org/rfc/rfc8288#section-2.1.1), a `rel` value that is a URI does not require IANA registration. This site exposes the schemamap entry in `/.well-known/api-catalog` under `https://specification.website/schemas/schemamap/0.1#index`, so any client that reads the api-catalog finds it without depending on a bare-name relation at all.

Registration is the prerequisite for promoting any of this beyond `optional`. Until then, treat schemamap as an opt-in proposal you can audit and walk back from.

## Common mistakes

- **Drift between the HTML graph and the `.jsonld` endpoint.** They have to be generated from the same source at the same time. If the page changes and the endpoint does not, every agent that trusted the index now has stale facts.
- **Inventing `@type` values to fill the index.** Only list real, valid schema.org types. Lying about types pollutes the only thing that makes the index more useful than a sitemap.
- **Forgetting CORS.** Without `Access-Control-Allow-Origin: *`, a browser-side agent cannot fetch the JSON-LD even though a backend crawler can — the discovery surface fragments by client.
- **Listing pages whose JSON-LD is just `WebSite`.** The homepage's `WebSite` block is the same on every page; it carries no resource-specific facts. The index should list resources whose graph adds something — articles, products, events, recipes, persons — not boilerplate.
- **Treating schemamap as a substitute for the XML sitemap or `llms.txt`.** They answer different questions: the sitemap lists URLs for indexing, `llms.txt` summarises content for LLMs, schemamap lists structured-data endpoints. Ship all three.

## Verification

- `curl -sI https://example.com/articles/foo.jsonld` returns `200` with `Content-Type: application/ld+json` and `Access-Control-Allow-Origin: *`.
- `curl -s https://example.com/schemamap.xml | xmllint --noout -` parses cleanly. Every `<jsonld>` URL it lists fetches with `200`.
- Compare the `.jsonld` body to the `<script type="application/ld+json">` block on the same page — the graph (after sorting keys) should be identical.
- Fetch the page HTML and confirm both `<link rel="alternate" type="application/ld+json">` and `<link rel="schemamap">` are present in `<head>`.
- Validate the JSON-LD body with the [Schema Markup Validator](https://validator.schema.org/).

### Sources
- JSON-LD 1.1 Specification (W3C) — https://www.w3.org/TR/json-ld11/
- Schema.org (schema.org) — https://schema.org/
- RFC 8288 — Web Linking (IETF) — https://www.rfc-editor.org/rfc/rfc8288
- IANA — Link Relations Registry (IANA) — https://www.iana.org/assignments/link-relations/link-relations.xhtml
- Sitemaps XML format (sitemaps.org) — https://www.sitemaps.org/protocol.html

---

# Performance

Core Web Vitals, caching, images, fonts, network behaviour.

## Core Web Vitals (LCP, INP, CLS)

Status: required  ·  Source page: https://specification.website/spec/performance/core-web-vitals/

Core Web Vitals measure loading, responsiveness, and visual stability. Hit LCP ≤ 2.5s, INP ≤ 200ms, and CLS ≤ 0.1 at the 75th percentile of real users.

## What it is

Core Web Vitals are three user-centric metrics that Google uses to score the quality of a page experience:

- **Largest Contentful Paint (LCP)** — time from navigation start until the largest visible element is painted. Measures loading.
- **Interaction to Next Paint (INP)** — the slowest interaction the user has with the page, from input to the next frame. Measures responsiveness.
- **Cumulative Layout Shift (CLS)** — the sum of unexpected layout shift scores during the page's lifecycle. Measures visual stability.

The targets, measured at the 75th percentile of page loads across mobile and desktop:

| Metric | Good | Needs improvement | Poor |
|---|---|---|---|
| LCP | ≤ 2.5s | ≤ 4.0s | > 4.0s |
| INP | ≤ 200ms | ≤ 500ms | > 500ms |
| CLS | ≤ 0.1 | ≤ 0.25 | > 0.25 |

## Why it matters

The numbers that count are **field data** from real users, captured in the Chrome User Experience Report (CrUX) and surfaced in Search Console, PageSpeed Insights, and the CrUX API. Lab data from Lighthouse is a useful proxy but not the score Google ranks on.

Slow pages lose users. Field studies consistently show conversion, bounce rate, and session depth all degrading sharply past the "good" thresholds. Core Web Vitals are also a confirmed Google ranking signal as part of page experience.

## How to implement

**LCP** — identify the LCP element (usually a hero image or heading) and make it arrive fast. Serve it from the origin, preload it, avoid lazy-loading it, and keep it out of client-rendered components.

**INP** — break up long JavaScript tasks, defer non-critical work, and avoid heavy work in event handlers. Use `requestIdleCallback` or `scheduler.postTask` for non-urgent work. Audit third-party scripts.

**CLS** — set explicit `width` and `height` on images, iframes, and video. Reserve space for ads and embeds. Avoid inserting content above existing content. Preload fonts to reduce FOUT swaps.

## Common mistakes

- Optimising lab scores while field data stays red.
- Treating LCP as "first paint" — it is the largest element, often well into the page.
- Lazy-loading the LCP image. It must load eagerly.
- Measuring INP only on the homepage — interaction-heavy pages such as forms and search results are usually the worst offenders.

## Verification

- Check field data in [PageSpeed Insights](https://pagespeed.web.dev) — it pulls from CrUX.
- Use the [web-vitals JavaScript library](https://github.com/GoogleChrome/web-vitals) to send real-user metrics to your analytics.
- In Chrome DevTools, the Performance panel flags LCP, INP, and layout shifts.

### Sources
- web.dev — Web Vitals (web.dev) — https://web.dev/articles/vitals
- Chrome User Experience Report (Chrome for Developers) — https://developer.chrome.com/docs/crux
- web.dev — Interaction to Next Paint (INP) (web.dev) — https://web.dev/articles/inp
- web.dev — Cumulative Layout Shift (CLS) (web.dev) — https://web.dev/articles/cls

---

## Image optimisation

Status: required  ·  Source page: https://specification.website/spec/performance/image-optimization/

Serve images in modern formats (WebP, AVIF), at the right size for the viewport, with explicit dimensions. Images are the largest payload on most pages.

## What it is

Image optimisation is the practice of shipping the smallest visually acceptable image for the user's device. It covers format, dimensions, compression, and how the browser chooses between sources.

```html
<img
  src="hero-800.webp"
  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1600.webp 1600w"
  sizes="(max-width: 600px) 100vw, 800px"
  width="800"
  height="450"
  alt="Wide view of the harbour at dusk"
/>
```

## Why it matters

Images are the single largest contributor to page weight on the web — typically 40–50% of total bytes per the HTTP Archive Web Almanac. They are usually the LCP element, so their delivery directly drives Core Web Vitals. Oversized images also waste mobile data, drain battery, and hurt users on slow connections.

## How to implement

**Use a modern format.** AVIF gives the smallest files but encodes slowly; WebP is well-supported and faster to produce. Both beat JPEG and PNG by 25–50% at equivalent quality. Use `<picture>` to offer fallbacks:

```html
<picture>
  <source srcset="photo.avif" type="image/avif">
  <source srcset="photo.webp" type="image/webp">
  <img src="photo.jpg" width="1200" height="800" alt="…">
</picture>
```

**Serve responsive sizes.** Generate the same image at several widths and let `srcset` plus `sizes` pick the right one. A 4000px image in a 400px slot wastes ~99% of the bytes.

**Always set `width` and `height`.** The browser computes the aspect ratio and reserves the slot, preventing CLS when the image loads.

**Compress aggressively.** Quality 75–80 in WebP is visually indistinguishable from quality 95 for photos. Use tools such as `sharp`, `squoosh`, or `cwebp`.

**Strip metadata.** EXIF, colour profiles, and thumbnails can add tens of kilobytes per image.

## Common mistakes

- Shipping the original camera JPEG (5MB, 6000px) into a 400px card.
- PNG for photos. PNG is for graphics with sharp edges and few colours.
- Omitting `width` and `height`, then wondering why CLS is poor.
- Single fixed `src` with no `srcset` — mobile users download the desktop image.
- Serving an "optimised" image that is still 1MB because compression was set to 100.

## Verification

- DevTools → Network → Img. Sort by size. Anything over 200KB needs a second look.
- Lighthouse flags "Properly size images" and "Serve images in next-gen formats".
- Run [Squoosh](https://squoosh.app) on the worst offenders and compare.

### Sources
- MDN — <img>: The Image Embed element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img
- web.dev — Use modern image formats (web.dev) — https://web.dev/articles/uses-webp-images
- web.dev — Serve responsive images (web.dev) — https://web.dev/articles/serve-responsive-images
- HTTP Archive — Web Almanac: Media (HTTP Archive) — https://almanac.httparchive.org/en/2024/media

---

## Lazy loading images, iframes, and video

Status: recommended  ·  Source page: https://specification.website/spec/performance/lazy-loading/

Native lazy loading defers off-screen images, iframes, and (recently) video until the user scrolls near them. Use loading="lazy" — but never on the LCP element.

## What it is

The `loading` attribute lets the browser defer fetching a resource until it is close to the viewport. It is a single HTML attribute — no JavaScript, no IntersectionObserver. It applies to three elements:

```html
<img src="diagram.webp" width="800" height="600" loading="lazy" decoding="async" alt="…">
<iframe src="https://www.youtube.com/embed/…" loading="lazy" title="Demo"></iframe>
<video src="clip.mp4" loading="lazy" controls width="800" height="450"></video>
```

Valid values: `lazy` (defer), `eager` (load immediately — the default).

`<img>` has supported `loading="lazy"` since Chrome 77 (2019) and is universally available across modern browsers. `<iframe>` followed shortly after. **`<video loading="lazy">` is the newest member** — added to the HTML Living Standard in 2026 and shipping in Chromium-based browsers; treat it as progressive enhancement, since older browsers simply ignore the attribute and fall back to the element's existing `preload` behaviour.

## Why it matters

A typical article page has a dozen images below the fold that the user may never scroll to. Loading them eagerly costs bandwidth, blocks more important requests, and steals decode time from the main thread. Lazy loading defers that work, often cutting initial bytes by 30–60% on long pages.

`decoding="async"` is complementary: it lets the browser decode the image off the main thread, so the image arriving doesn't jank scrolling or interactions.

## How to implement

**Default off-screen images to lazy.** Anything below the fold — gallery thumbnails, author avatars, embedded tweets, YouTube embeds — should be `loading="lazy"`.

**Keep the LCP image eager.** The hero image, the article lead, the product photo — these must not be lazy-loaded. Browsers honour `loading="lazy"` even when the image is just below the fold on a small viewport, and the LCP cost is significant. When in doubt, use `loading="eager"` (or omit the attribute) for above-the-fold images.

**Add `decoding="async"` to all images.** It has no downside and helps with main-thread responsiveness.

**Lazy-load iframes by default.** YouTube and map embeds pull hundreds of kilobytes of JavaScript on every page view. `loading="lazy"` on the iframe defers all of it.

**Lazy-load below-the-fold video.** Combine `loading="lazy"` with `preload="none"` (or `preload="metadata"` if you need the poster frame) so neither the video bytes nor its metadata are fetched until the user reaches it. In older browsers without `loading="lazy"` support, `preload` alone still gives you most of the win.

```html
<video loading="lazy" preload="none" poster="poster.webp" controls
       width="800" height="450">
  <source src="clip.av1.mp4" type="video/mp4; codecs=av01.0.05M.08">
  <source src="clip.h264.mp4" type="video/mp4; codecs=avc1.42E01E">
</video>
```

**Keep `width` and `height`.** Lazy loading does not change layout — without dimensions you still get CLS when the resource arrives.

## Common mistakes

- `loading="lazy"` on the LCP image. The single biggest lazy-loading mistake. Lighthouse and PageSpeed Insights flag it explicitly.
- Custom JavaScript lazy-loaders running on top of native lazy loading, doubling the work.
- Lazy-loading every image to "be safe" — the first screenful must load eagerly.
- Omitting dimensions, so lazy-loaded images shift the layout on arrival.

## Verification

- DevTools → Network → throttle to "Slow 4G", reload, watch which images fetch immediately and which wait for scroll.
- Lighthouse audit: "Largest Contentful Paint image was lazily loaded" is a hard failure to fix.
- View source: every below-the-fold `<img>` and `<iframe>` should have `loading="lazy"`.

### Sources
- MDN — <img> loading attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
- MDN — <iframe> loading attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading
- MDN — <video> loading attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#loading
- HTML Living Standard — The video element (WHATWG) — https://html.spec.whatwg.org/multipage/media.html#the-video-element
- web.dev — Browser-level image lazy loading (web.dev) — https://web.dev/articles/browser-level-image-lazy-loading
- MDN — decoding attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#decoding

---

## Preload, prefetch, preconnect

Status: recommended  ·  Source page: https://specification.website/spec/performance/preload-prefetch-preconnect/

Resource hints let you tell the browser what is coming. Preload the LCP image and critical fonts, preconnect to third-party origins, prefetch the next navigation.

## What it is

Four `<link rel>` hints in the head tell the browser to start work earlier than the parser would:

- **preconnect** — open a TCP+TLS connection now, body comes later.
- **dns-prefetch** — resolve DNS only. The cheap fallback when preconnect is too aggressive.
- **preload** — fetch this exact resource now at high priority.
- **prefetch** — fetch this resource at low priority for a future navigation.

```html
<link rel="preconnect" href="https://cdn.example.com" crossorigin>
<link rel="dns-prefetch" href="https://analytics.example.com">
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="/hero.avif" as="image" fetchpriority="high">
<link rel="prefetch" href="/next-article" as="document">
```

## Why it matters

The browser only discovers resources as it parses HTML and CSS. By the time it sees a `<link rel="stylesheet">` that references a font, several round-trips have already passed. Hints move that discovery earlier — sometimes saving 200–500ms on the LCP element.

Used badly, the same hints **harm** performance by contending for bandwidth with the actual critical request. Hint sparingly.

## How to implement

**Preload the LCP image.** If your LCP is a hero image, preload it. Combine with `fetchpriority="high"` so it jumps the queue. Do not preload images that already appear early in the HTML — the preload scanner finds them anyway.

**Preload critical fonts.** Fonts requested from inside CSS are discovered late. Preload them with `as="font" type="font/woff2" crossorigin`. The `crossorigin` attribute is mandatory even for same-origin fonts.

**Preconnect to third-party origins.** If you load images from a CDN, fonts from Google, or analytics from a third party, preconnect saves the TCP+TLS handshake (~100–300ms). Use `crossorigin` for resources fetched with CORS (fonts, fetch, modules).

**Use dns-prefetch as a fallback.** Older browsers and proxies sometimes ignore preconnect. Pair it with dns-prefetch:

```html
<link rel="preconnect" href="https://cdn.example.com" crossorigin>
<link rel="dns-prefetch" href="https://cdn.example.com">
```

**Prefetch the next likely page.** On a landing page, prefetch the obvious next step. The fetch happens at low priority and won't interfere with the current page.

## Common mistakes

- Preloading 10 things. They all fight for bandwidth and nothing wins.
- Forgetting `crossorigin` on font preloads — the browser then fetches the font twice.
- Preconnecting to origins you don't actually use.
- Preloading a stylesheet then forgetting to add `<link rel="stylesheet">`. The preload sits unused; Chrome logs a warning.
- Using prefetch for the LCP image of the current page. That is preload's job.

## Verification

- DevTools → Network → look at the priority and start time of LCP and font requests.
- Chrome logs `<link rel="preload"> was preloaded using link preload but not used within a few seconds` for misused hints.
- Lighthouse "Preload key requests" and "Preconnect to required origins" surface missing hints.

### Sources
- MDN — <link>: The External Resource Link element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
- web.dev — Preload critical assets to improve loading speed (web.dev) — https://web.dev/articles/preload-critical-assets
- web.dev — Establish network connections early to improve perceived page speed (web.dev) — https://web.dev/articles/preconnect-and-dns-prefetch
- MDN — rel=preload (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload

---

## Cache-Control headers

Status: required  ·  Source page: https://specification.website/spec/performance/cache-control/

Cache-Control tells browsers and CDNs how long to keep a response. Use immutable + max-age=31536000 for fingerprinted assets and short or no-cache for HTML.

## What it is

`Cache-Control` is an HTTP response header that governs how, where, and for how long a response may be stored and reused. It is defined in RFC 9111 and replaces the older `Expires` and `Pragma` headers.

```http
Cache-Control: public, max-age=31536000, immutable
```

Key directives:

- `public` — any cache may store it (CDN, proxy, browser).
- `private` — only the user's browser may store it.
- `no-cache` — store, but revalidate before reuse.
- `no-store` — do not store at all.
- `max-age=<seconds>` — fresh for this many seconds.
- `s-maxage=<seconds>` — same, but only for shared caches (CDNs).
- `immutable` — promise that the body will never change, so the browser can skip revalidation.
- `stale-while-revalidate=<seconds>` — serve stale while fetching a fresh copy in the background.

## Why it matters

A correct cache policy is the cheapest possible performance win. Repeat visitors download nothing for cached assets. CDNs absorb traffic before it reaches your origin. Without it, every page view re-fetches the same CSS, JS, and images. With it, the second visit can be near-instant.

`no-cache` is also a privacy tool: it forces revalidation of HTML so users see your latest content, while still allowing 304s.

## How to implement

**Fingerprinted assets — cache forever.** If the URL contains a content hash (`app.4f3a2b.js`), the body cannot change. Cache aggressively:

```http
Cache-Control: public, max-age=31536000, immutable
```

`immutable` matters: without it, Firefox revalidates on reload even with `max-age` set.

**HTML — short or no cache.** Pages change often and rarely have fingerprinted URLs. Use:

```http
Cache-Control: public, max-age=0, must-revalidate
```

or, for highly dynamic pages:

```http
Cache-Control: no-store
```

Pair with `ETag` so revalidation is cheap.

**Per-user content — private.** Anything personalised needs `private` to prevent shared caches from leaking one user's data to another.

**Set `Vary` correctly.** If the response varies by `Accept-Encoding` or `Accept-Language`, set `Vary` accordingly. Missing `Vary` causes a CDN to serve gzip to a client that asked for brotli.

## Common mistakes

- No `Cache-Control` at all. Browsers then use heuristic caching, which is unpredictable.
- `max-age=31536000` on HTML. Users get stale pages and you can't fix bugs without changing the URL.
- `no-cache` mistaken for "do not cache". It only means "revalidate first". Use `no-store` to actually prevent storage.
- Missing `Vary: Accept-Encoding` when serving brotli/gzip via a CDN.
- Fingerprinted URL without `immutable` — Firefox will still revalidate on reload.

## Verification

- `curl -I https://example.com/app.4f3a2b.js` — confirm `Cache-Control` is set.
- DevTools → Network → Size column shows "(memory cache)" or "(disk cache)" for cached resources.
- Webhint and Lighthouse flag inefficient cache policy.

### Sources
- RFC 9111 — HTTP Caching (IETF) — https://www.rfc-editor.org/rfc/rfc9111
- MDN — Cache-Control (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
- MDN — HTTP caching (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching
- MDN — Vary (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary

---

## No-Vary-Search response header

Status: recommended  ·  Source page: https://specification.website/spec/performance/no-vary-search/

The `No-Vary-Search` response header tells browsers and caches that some URL query parameters (tracking, UTM, sort order) do not change the response. The cached entry for the canonical URL is reused for variants — fewer fetches, better prefetch hits, less duplicate work.

## What it is

`No-Vary-Search` is a response header that tells the browser's HTTP cache (and the Speculation Rules prefetch/prerender cache) which URL query parameters are irrelevant to the response. By default, every distinct query string is treated as a distinct resource. `No-Vary-Search` lets the server say "the response for `/products?utm_source=x` is identical to the response for `/products`" without redirecting.

```http
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
No-Vary-Search: params=("utm_source" "utm_medium" "utm_campaign" "utm_term" "utm_content"), key-order
```

The directives are small and precise:

- `params=("a" "b")` — these specific parameters do not change the response.
- `params` (no value) — none of the query parameters change the response.
- `except=("page")` — every parameter except these does not change the response (inverse form).
- `key-order` — the order of parameters in the URL does not matter.

## Why it matters

- **Prefetch hits land more often.** Pages prefetched via [Speculation Rules](/spec/performance/speculation-rules.md) only count as a hit if the final URL matches. Without `No-Vary-Search`, a click that adds `?utm_source=newsletter` misses the prefetch and re-fetches the page.
- **CDN cache hit rate improves.** The same logic applies to shared caches: declaring that tracking params do not vary the response lets one cached object serve every campaign.
- **Less duplicate work for archives and crawlers.** Search engines treat URL variants as distinct pages by default; the [canonical link](/spec/foundations/canonical-url.md) collapses them for indexing, but `No-Vary-Search` collapses them at the HTTP layer too.
- **Cheap to ship.** It is one response header. No code changes, no URL rewriting, no redirects to debug.

## How to implement

- **List the tracking parameters you actually receive.** UTMs are the universal set. Add `gclid`, `fbclid`, `msclkid`, `mc_cid`, `mc_eid`, and anything else your analytics pipeline adds and your application logic does not consume.
- **Set the header at the edge.** Like [Cache-Control](/spec/performance/cache-control/), this belongs in CDN or reverse-proxy config so it applies to every response in the matched path.

```http
No-Vary-Search: params=("utm_source" "utm_medium" "utm_campaign" "utm_content" "utm_term"
                        "gclid" "fbclid" "msclkid"), key-order
```

- **Add `key-order` unless ordering matters.** It almost never does for query strings, and it catches the common case where the same parameters arrive in different orders.
- **Apply it broadly.** Pages, RSS, JSON endpoints, static assets — anywhere a tracking parameter might end up appended.
- **Combine with [Speculation Rules](/spec/performance/speculation-rules/).** Without `No-Vary-Search`, an `eagerness: "moderate"` prefetch is wasted the moment a tracking param is added to the link.

**This site ships it.** `specification.website` sets `No-Vary-Search` on every response via [`public/_headers`](https://github.com/jdevalk/specification.website/blob/main/public/_headers), covering the common UTM parameters plus `gclid`, `fbclid`, `msclkid`, `mc_cid`, `mc_eid`, and `ref`, with `key-order` so parameter ordering is also ignored.

## Common mistakes

- Listing a parameter that does change the response. Adding `page` or `sort` to `params=` collapses different pages into one cached entry. Use `except=` to be safe when in doubt.
- Forgetting that the directive is per-response. The header has to ship on the response that should be reused; setting it only on the variant URL has no effect.
- Treating `No-Vary-Search` as a substitute for `rel="canonical"`. The two solve different problems: this one tells caches not to vary; the canonical tells search engines which URL to index. Ship both.
- Shipping the header without testing prefetch hits. Use Chrome DevTools' Application → Speculative loads panel; a hit will be labelled accordingly.

## Verification

- `curl -sI https://example.com/ | grep -i ^no-vary-search` returns the configured directives.
- In Chrome DevTools, prefetch a URL via Speculation Rules, then navigate to the same URL with extra UTM parameters appended. The Application panel logs it as a prefetch hit.
- Hit the page twice with different UTM strings while watching the CDN's cache-status header (`Cf-Cache-Status`, `X-Cache`, etc.) — both should be `HIT` after the first miss.
- A cache analytics dashboard shows fewer near-duplicate URL entries.

### Sources
- No-Vary-Search — WICG editor's draft (WICG) — https://wicg.github.io/nav-speculation/no-vary-search.html
- MDN — No-Vary-Search (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/No-Vary-Search
- Chrome Status — No-Vary-Search (Google) — https://chromestatus.com/feature/5202380930678784

---

## Compression (gzip, brotli, zstd)

Status: required  ·  Source page: https://specification.website/spec/performance/compression/

Compress text responses with brotli where supported, gzip everywhere else. zstd is emerging. Don't compress already-compressed media.

## What it is

HTTP content encoding compresses response bodies on the server and decompresses them in the browser. The client advertises supported algorithms in `Accept-Encoding`; the server picks one and announces it in `Content-Encoding`.

```http
Request:
Accept-Encoding: br, gzip, zstd

Response:
Content-Encoding: br
Vary: Accept-Encoding
```

The common algorithms:

- **gzip** — universally supported since the late 1990s. Good ratio, fast.
- **brotli (br)** — Google, standardised as RFC 7932. 15–25% smaller than gzip for text. Supported by all modern browsers.
- **zstd** — RFC 8878. Comparable ratio to brotli with faster decompression. Supported by Chrome 123+, Firefox 126+, Safari 17.4+.
- **deflate** — avoid. Ambiguity between raw deflate and zlib wrapping has bitten implementations for decades.

## Why it matters

Text resources — HTML, CSS, JavaScript, JSON, SVG, XML — compress to 20–30% of their original size. On a 200KB JavaScript bundle, that is 140KB saved per request, multiplied by every user. Compression is one of the cheapest performance wins available, and a Lighthouse audit failure if missing.

## How to implement

**Compress all text.** HTML, CSS, JS, JSON, SVG, XML, plain text, and most fonts (WOFF2 is already compressed; WOFF is not).

**Negotiate via `Accept-Encoding`.** Most servers and CDNs do this automatically. Configure them to prefer brotli, fall back to gzip:

- nginx: `brotli on; brotli_static on; gzip on;`
- Apache: `mod_brotli` and `mod_deflate`.
- Cloudflare, Fastly, Cloudfront: enable in the dashboard.

**Pre-compress static assets.** For files that don't change (your bundled JS), compress at build time to maximum level (brotli quality 11, gzip level 9) and let the server serve the `.br` or `.gz` file directly. Runtime compression usually runs at level 5–6 for CPU reasons.

**Set `Vary: Accept-Encoding`.** Tells CDNs to keep a separate cache entry per encoding. Without it, gzip clients may receive a brotli body they can't decode.

**Don't double-compress.** Images (JPEG, PNG, WebP, AVIF), video, fonts (WOFF2), and zip files are already compressed. Re-encoding wastes CPU and often grows the file.

## Common mistakes

- Compression off entirely. Lighthouse "Enable text compression" fails immediately.
- gzip only — a 20% saving left on the table for every brotli-capable browser.
- Compressing images or video. Pure waste.
- Missing `Vary: Accept-Encoding` behind a CDN. Cache poisoning waiting to happen.
- Brotli at quality 11 on dynamic responses. The encode cost erases the wire saving.

## Verification

- `curl -H "Accept-Encoding: br, gzip" -I https://example.com/main.css` — check `Content-Encoding`.
- DevTools → Network → response headers should show `content-encoding: br`.
- Compare Network "Size" (over the wire) vs "Resources" (decompressed). The ratio shows compression is working.

### Sources
- RFC 7932 — Brotli Compressed Data Format (IETF) — https://www.rfc-editor.org/rfc/rfc7932
- MDN — Accept-Encoding (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
- MDN — Content-Encoding (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
- RFC 8878 — Zstandard Compression (IETF) — https://www.rfc-editor.org/rfc/rfc8878

---

## Web font loading

Status: recommended  ·  Source page: https://specification.website/spec/performance/font-loading/

Self-host WOFF2 fonts, subset them, preload the critical face, and use font-display: swap so text is readable while the font is still loading.

## What it is

Web fonts are font files (TTF, OTF, WOFF, WOFF2) downloaded by the browser and applied via `@font-face`. Loading them well means short delay, no flash of invisible text, no layout shift when they swap in.

```css
@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-var.woff2") format("woff2-variations");
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
}
```

## Why it matters

A custom font that loads late causes one of two bad outcomes: **FOIT** (flash of invisible text — the page renders blank rectangles), or **FOUT** (flash of unstyled text — system font flashes, then jumps to the custom font, causing CLS). Both hurt user experience and Core Web Vitals.

Fonts can also be heavy. A single weight of a Latin font is ~30KB in WOFF2; a full multi-script variable font can be 300KB+. They block paint of the text they style.

## How to implement

**Self-host.** Third-party font services add a DNS lookup, TLS handshake, and a second domain to track. Download the WOFF2 files and serve them from your origin.

**Use WOFF2 only.** All modern browsers support it. WOFF2 is pre-compressed (do not gzip), 30% smaller than WOFF, and 50% smaller than TTF.

**Subset to what you use.** Google Fonts' default Latin subset covers most English-language sites. If your content is English only, drop Cyrillic, Greek, and Vietnamese subsets — that can halve the file. Tools: `pyftsubset`, `glyphhanger`, `subfont`.

**Preload the critical face.** The body text font is render-blocking for most of the page. Preload it:

```html
<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
```

`crossorigin` is mandatory even for same-origin fonts — without it the preload misses the cache and the font fetches twice.

**Set `font-display`.** `swap` shows the fallback immediately and swaps when the custom font arrives. `optional` is stricter: if the font isn't cached and ready within ~100ms, the fallback is used permanently — best for CLS. Avoid `block`, which causes FOIT.

**Use variable fonts.** A single variable font file replaces 9 weight + style combinations and is usually smaller than 2 static weights.

**Match metrics to reduce shift.** Use `size-adjust`, `ascent-override`, and `descent-override` on the fallback `@font-face` so the swap doesn't reflow the layout.

## Common mistakes

- Loading from `fonts.googleapis.com` and a self-host preload. Double-fetch.
- Preloading without `crossorigin`. Double-fetch.
- `font-display: block` (or the default `auto`). Causes invisible text for up to 3 seconds.
- Shipping 6 static weights when a variable font covers all of them.
- Loading the full multi-script font for a Latin-only site.

## Verification

- DevTools → Network → filter by Font. Count requests; check sizes; confirm WOFF2.
- DevTools → Rendering → Emulate "Slow 4G" and reload. Watch for FOIT or large layout shifts.
- Lighthouse "Ensure text remains visible during webfont load" flags missing `font-display`.

### Sources
- MDN — @font-face (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face
- web.dev — Best practices for fonts (web.dev) — https://web.dev/articles/font-best-practices
- MDN — font-display (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display
- web.dev — Avoid invisible text during font loading (web.dev) — https://web.dev/articles/avoid-invisible-text

---

## Critical CSS and render-blocking resources

Status: recommended  ·  Source page: https://specification.website/spec/performance/critical-css/

Inline the CSS needed for above-the-fold content and defer the rest. Render-blocking resources in <head> are the single biggest cause of slow first paint.

## What it is

A render-blocking resource is one the browser must fetch and parse before it can paint pixels. By default, every `<link rel="stylesheet">` and every synchronous `<script>` in `<head>` blocks rendering.

**Critical CSS** is the subset of your stylesheet needed to render the visible part of the page on first load. Inlined in a `<style>` tag in `<head>`, it lets the browser paint without waiting for the full stylesheet.

```html
<head>
  <style>/* ~14KB of styles for above-the-fold content */</style>
  <link rel="preload" href="/site.css" as="style" onload="this.rel='stylesheet'">
  <noscript><link rel="stylesheet" href="/site.css"></noscript>
</head>
```

## Why it matters

A typical site stylesheet is 100–300KB. On a slow connection, fetching it adds 500ms+ before any pixel appears. That delay shows up directly as poor LCP and First Contentful Paint. Render-blocking JavaScript is even worse — it blocks both parsing and rendering.

Inlining the critical CSS removes one round-trip from the critical path. The non-critical CSS still loads, but in parallel with rendering rather than ahead of it.

## How to implement

**Identify above-the-fold styles.** Tools such as `critical`, `penthouse`, and `critters` parse the rendered page and extract only the rules used in the initial viewport. Build-time generation is fine; per-page is better.

**Inline in `<head>`.** Keep the inlined CSS under ~14KB (one TCP slow-start window) so it fits in the first packet.

**Load the rest asynchronously.** The `preload` + `onload` swap shown above is the standard pattern. A `<noscript>` fallback covers browsers with JavaScript disabled.

**Move JavaScript out of the critical path.** Add `defer` or `type="module"` to script tags. Both fetch in parallel and execute after parsing:

```html
<script src="/app.js" defer></script>
<script type="module" src="/app.mjs"></script>
```

Use `async` only for truly independent third-party scripts.

**Don't block on third-party CSS.** Webfont providers, analytics dashboards, and chat widgets that drop a stylesheet in `<head>` add an unknown origin to your critical path. Self-host or load asynchronously.

**Watch the `media` attribute.** `<link rel="stylesheet" media="print">` does not block rendering. Useful for splitting print styles out.

## Common mistakes

- Inlining the entire stylesheet. The HTML balloons; nothing is cacheable across pages.
- Forgetting the `<noscript>` fallback. Users with JS off see an unstyled page.
- Loading a synchronous `<script>` tag in `<head>` for analytics. Now analytics blocks your LCP.
- Critical CSS generated once for the homepage and reused everywhere. Article pages and product pages need different critical styles.
- Mistaking `async` for `defer`. `async` can execute mid-parse and block rendering.

## Verification

- DevTools → Performance → record a load. The "Render-Blocking" badge marks every blocking request.
- Lighthouse "Eliminate render-blocking resources" lists them with estimated savings.
- View source: every non-critical `<link rel="stylesheet">` should be deferred; every `<script>` in `<head>` should have `defer` or `async`.

### Sources
- web.dev — Extract critical CSS (web.dev) — https://web.dev/articles/extract-critical-css
- web.dev — Defer non-critical CSS (web.dev) — https://web.dev/articles/defer-non-critical-css
- MDN — Render-blocking resources (MDN) — https://developer.mozilla.org/en-US/docs/Glossary/Render_blocking
- web.dev — Eliminate render-blocking resources (web.dev) — https://web.dev/articles/render-blocking-resources

---

## Script loading — defer, async, module

Status: recommended  ·  Source page: https://specification.website/spec/performance/script-loading/

Choose the right script-loading attribute for every <script>: defer for app code, async for independent third-party, type=module for modern code. Bare <script> in <head> is always wrong.

## What it is

The `<script>` element has four loading modes that differ in *when the browser pauses HTML parsing* and *when the script runs*. Pick the wrong one and you block paint, break execution order, or ship code older browsers cannot evaluate.

```html

<script src="/app.js"></script>

<script src="https://cdn.example.com/analytics.js" async
        integrity="sha384-OqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
        crossorigin="anonymous"></script>

<script src="/app.js" defer></script>

<script src="/app.js" type="module"></script>
```

Plus the platform extras: `nomodule` for legacy fallback, `crossorigin` for CORS, `integrity` for [SRI](/spec/security/subresource-integrity/), `fetchpriority` for prioritisation hints, `blocking="render"` for the rare case you genuinely need a blocking script.

## Why it matters

A `<script>` in `<head>` with no `async`, `defer`, or `type="module"` halts HTML parsing while it downloads *and* executes. On a slow network, that one tag can delay the first paint by seconds. Done wrong site-wide, render-blocking scripts are the single biggest cause of poor [LCP](/spec/performance/core-web-vitals/) and the most common Lighthouse failure on real sites.

The four modes:

- **Blocking** — parser stops, browser fetches, browser executes, parser resumes. Catastrophic in `<head>`. Acceptable only for tiny inline scripts that must run before paint (e.g. a critical CSP nonce setter, a colour-scheme fix).
- **`async`** — parser does not stop; script downloads in parallel; runs as soon as it arrives, *in arrival order*, possibly mid-parse. Right for self-contained third-party code that doesn't depend on your DOM (analytics, error reporters).
- **`defer`** — parser does not stop; script downloads in parallel; runs in document order *after* the parser finishes, before `DOMContentLoaded`. Right for your application code that depends on the DOM and on other scripts in order.
- **`type="module"`** — `defer` semantics by default; supports `import`; runs in strict mode; deduplicates by URL. Right for modern ES modules.

For first-party app code, the practical answer in 2026 is almost always `type="module"` or `defer`, placed in `<head>`.

## How to implement

**Default to `<script defer src="…">` in `<head>` for app code.** It starts downloading early (parallel with HTML), runs in order, and runs before `DOMContentLoaded`. Cleaner than placing scripts at the end of `<body>`, equally non-blocking, and works in every browser that matters.

```html
<head>
  <script src="/app.js" defer></script>
  <script src="/widget.js" defer></script>
</head>
```

`app.js` runs before `widget.js`. Both run before `DOMContentLoaded`.

**Use `async` for independent third-party.** Analytics, A/B tooling, chat widgets — anything that doesn't depend on your code or DOM order. Always pair with [Subresource Integrity](/spec/security/subresource-integrity/) and `crossorigin="anonymous"` so a compromised CDN cannot ship modified code to your visitors:

```html
<script src="https://cdn.example.com/widget.js" async
        integrity="sha384-OqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
        crossorigin="anonymous"></script>
```

Some vendors (rolling-release analytics, A/B platforms) ship a script whose contents change at the vendor's discretion and therefore cannot be pinned with SRI. In that case the integrity guarantee becomes "I trust this vendor with my origin" — make that an explicit risk decision, document it, and consider a [strict CSP](/spec/security/content-security-policy/) with a per-deploy allow-list as compensating control.

If two third-party scripts depend on each other, neither can be `async`. Use `defer` on both.

**Use `type="module"` for modern code.** It's `defer` by default, supports `import`, and gives you a single canonical place for tree-shaking, code-splitting, and dynamic `import()` for route-level lazy loading.

```html
<script type="module" src="/app.js"></script>
```

**Preload module dependencies.** Modules fetched via `import` are discovered lazily — preload them so the browser starts fetching during initial parse:

```html
<link rel="modulepreload" href="/lib/router.js">
<link rel="modulepreload" href="/lib/store.js">
<script type="module" src="/app.js"></script>
```

See [resource hints](/spec/performance/resource-hints/) for the decision table.

**Drop the legacy `nomodule` shim.** Every shipping browser in 2026 supports `type="module"`. The `nomodule` fallback was useful in 2018; it now ships a second bundle for users who don't exist.

**Inline tiny critical scripts in `<head>` if and only if** they must run before paint and are small enough that the cost of inlining is less than the cost of a separate request. Theme colour application, CSP setup, FOUC prevention — yes. A 50 KB framework runtime — no.

**Combine with `fetchpriority`** for the rare case you have a script that's deferred but critical:

```html
<script src="/critical.js" defer fetchpriority="high"></script>
```

**Set CSP allow-listing and SRI** ([subresource integrity](/spec/security/subresource-integrity/)) on every third-party script. The loading attribute does not change those obligations.

## Common mistakes

- `<script src="…">` in `<head>` with no attribute. Blocks paint until the script downloads and executes.
- Scripts at the end of `<body>` instead of `<head>` with `defer`. Modern advice is `<head>` + `defer`: the browser discovers the URL earlier and starts the fetch sooner. The body-end pattern is a hold-over from when `defer` was unreliable.
- `async` on a script that depends on another `async` script. Order is racy; you may get a working build by luck on your machine and broken in production.
- Shipping the same module both as `type="module"` *and* via a separate `defer` `<script>`. It downloads and runs twice.
- Forgetting `defer` on the second of two ordered scripts. The first defers, the second is blocking — parser stops mid-execution, partial DOM exposed.
- Inline `<script>` for tracking pixels under a strict [CSP](/spec/security/content-security-policy/) without a nonce or hash. CSP blocks the inline script, the tracker doesn't fire, "why is data missing?" three months later.
- Treating `type="module"` as "must use `import`." It works fine for a single-file module too, and inherits the `defer` behaviour for free.

## Verification

- View source on every page — every `<script src>` should have `defer`, `async`, or `type="module"` unless it is a tiny inline script with a documented reason.
- Chrome DevTools → Network → JS — column "Initiator" should show the script started loading during the initial HTML parse, not after.
- Lighthouse "Eliminate render-blocking resources" reports zero offending scripts.
- WebPageTest filmstrip — the first paint should not be delayed by JavaScript download/execution.
- For CSP compatibility, run [CSP Evaluator](https://csp-evaluator.withgoogle.com/) on production headers and confirm every `<script>` is allowed.

### Sources
- HTML Living Standard — The script element (WHATWG) — https://html.spec.whatwg.org/multipage/scripting.html#the-script-element
- MDN — <script> (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script
- web.dev — Eliminate render-blocking resources (web.dev) — https://web.dev/articles/render-blocking-resources
- web.dev — JavaScript module scripts (web.dev) — https://web.dev/articles/modulepreload

---

## HTTP/2 and HTTP/3

Status: recommended  ·  Source page: https://specification.website/spec/performance/http3/

Serve over HTTP/2 at minimum and HTTP/3 where you can. Multiplexing eliminates head-of-line blocking; QUIC removes TCP handshake delays.

## What it is

- **HTTP/1.1** (1997) — one request at a time per connection. Browsers open six parallel connections per origin to compensate. Plain text framing.
- **HTTP/2** (RFC 9113) — binary framing over a single TLS-over-TCP connection. Multiple requests interleaved (multiplexing). Header compression with HPACK.
- **HTTP/3** (RFC 9114) — same semantics as HTTP/2, but over QUIC instead of TCP. QUIC is a UDP-based transport with built-in TLS 1.3 and per-stream flow control.

HTTP/3 is advertised to clients via the `Alt-Svc` header on an HTTP/2 response:

```http
Alt-Svc: h3=":443"; ma=86400
```

After the first HTTP/2 connection, the browser remembers `Alt-Svc` and uses HTTP/3 directly for subsequent requests.

## Why it matters

HTTP/2 fixed HTTP/1.1's head-of-line blocking at the application layer: a single slow response no longer holds up the others on the connection. Combined with header compression, it typically cuts overhead by 30–50% on resource-heavy pages.

HTTP/3 fixes TCP's head-of-line blocking at the transport layer. On a lossy mobile network, a single dropped packet in TCP stalls every stream until it's retransmitted. QUIC streams are independent, so the loss only affects the one stream. HTTP/3 also handles connection migration (e.g. Wi-Fi to cellular) without dropping the connection, and reduces handshake round-trips with 0-RTT.

For users on flaky networks — the majority of mobile users globally — the difference is large and measurable.

## How to implement

**Turn it on at the edge.** Most CDNs (Cloudflare, Fastly, CloudFront, Bunny, Akamai) support HTTP/3 with a single checkbox. The TLS certificate, HSTS, and origin setup don't change.

**Require TLS.** HTTP/2 and HTTP/3 are HTTPS-only in browsers. There is no path forward without a valid certificate.

**Drop HTTP/1.1 optimisations.** Domain sharding, image sprites, and CSS concatenation were workarounds for HTTP/1.1's 6-connection limit. Under HTTP/2 they hurt: they break caching, prevent prioritisation, and inflate transfer sizes.

**Keep one origin.** HTTP/2 and HTTP/3 reward consolidation. Splitting assets across `cdn1`, `cdn2`, `assets.` forces new connections; on a single origin everything reuses the same one.

**Verify `Alt-Svc`.** If you've enabled HTTP/3 but `Alt-Svc` isn't set, browsers will never upgrade. Most edge providers add it automatically.

## Common mistakes

- TLS 1.0 or 1.1 still configured — HTTP/2 needs TLS 1.2+; HTTP/3 needs TLS 1.3.
- Domain sharding left over from HTTP/1.1 days, forcing extra connections.
- Inlining everything (CSS, JS, SVG) into HTML because that "saves a request" — under HTTP/2 it doesn't save much and it kills caching.
- Firewall or load balancer blocking UDP/443. HTTP/3 won't work and there is no error message — the browser just silently falls back to HTTP/2.

## Verification

- DevTools → Network → right-click the columns header → enable "Protocol". You should see `h2` and ideally `h3` for repeat requests.
- `curl --http3 -I https://example.com` confirms HTTP/3 is reachable.
- [https://http3check.net](https://http3check.net) and Cloudflare Radar both probe HTTP/3 support.

### Sources
- RFC 9114 — HTTP/3 (IETF) — https://www.rfc-editor.org/rfc/rfc9114
- RFC 9113 — HTTP/2 (IETF) — https://www.rfc-editor.org/rfc/rfc9113
- MDN — Evolution of HTTP (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Evolution_of_HTTP
- MDN — Alt-Svc (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc

---

## Speculation Rules

Status: recommended  ·  Source page: https://specification.website/spec/performance/speculation-rules/

Tell the browser which links to prefetch or prerender before the user clicks. Done well, navigations feel instant; done carelessly, you burn bandwidth on pages nobody visits.

> **This site ships it.** Every page emits a `<script type="speculationrules">` block from `BaseLayout.astro` — `prerender` on `moderate` for HTML same-origin links, `prefetch` on `conservative` as a fallback. The CSP allows the block via `'inline-speculation-rules'` (no `'unsafe-inline'`), and our bot logger drops requests with `Sec-Purpose: prefetch` so the stats stay honest.

## What it is

Speculation Rules let a page declare, in a structured way, which URLs the browser should **prefetch** (download the response in advance) or **prerender** (download *and* render the full page in a hidden background tab). When the user actually clicks, the navigation can complete in milliseconds because the work is already done.

The rules live in a `<script type="speculationrules">` block:

```html
<script type="speculationrules">
{
  "prerender": [{
    "where": { "href_matches": "/spec/*" },
    "eagerness": "moderate"
  }],
  "prefetch": [{
    "where": { "href_matches": "/*" },
    "eagerness": "conservative"
  }]
}
</script>
```

`eagerness` ranges from `conservative` (only on hover/touch) to `eager` (as soon as the rule is parsed). `moderate` is the sensible default — Chromium triggers on hover-with-intent and pointerdown.

This supersedes the older `<link rel="prerender">` hint, which has been removed from the platform.

## Why it matters

- **Sub-100ms navigations.** A prerendered page activates in single-digit milliseconds when the user clicks. It feels like the same page, not a navigation.
- **Improved INP and LCP on the next page.** Because the work is already done, the metrics on the destination page record near-zero delay.
- **Declarative.** No JavaScript event handlers, no IntersectionObserver, no custom hover-detection — the browser implements the heuristics.

Cross-site prerender is gated on Chrome's [No-Vary-Search](https://developer.chrome.com/blog/no-vary-search) and additional restrictions; same-site is the realistic target for most sites.

## How to implement

**Start small.** Prerender only the obvious next pages — the main nav links from the homepage, the next page in a paginated list, the most-clicked CTA. Prerendering everything wastes data on links nobody clicks.

**Prefer `moderate` eagerness over `eager`.** It limits speculation to links the user is about to interact with.

**Combine prefetch + prerender.** Prefetch broadly (cheap), prerender narrowly (expensive). The rules above show the pattern.

**Handle JavaScript correctly.** Prerendered pages run their JS in a hidden, non-active context. Wait for the [`prerenderingchange`](https://developer.mozilla.org/en-US/docs/Web/API/Document/prerenderingchange_event) event before running analytics, starting media, or anything user-visible:

```html
<script>
if (document.prerendering) {
  document.addEventListener('prerenderingchange', () => init(), { once: true });
} else {
  init();
}
</script>
```

**Pair with [view transitions](/spec/performance/view-transitions/)** for cross-document animations on prerendered navigations — together they make MPA navigations feel like an SPA.

**Don't speculate on URLs with side effects.** Logout endpoints, "delete" actions, payment flows. Use `urls`/`href_matches` carefully and exclude them.

## Common mistakes

- `eagerness: "eager"` on every link in the nav. Burns bandwidth and DB load.
- Prerendering pages whose analytics fire on script load instead of `prerenderingchange` — every prerender now counts as a fake pageview.
- Speculation rules that prefetch a page the server treats as cacheable but personalises silently (e.g. session-dependent content). The user lands on stale data.
- Forgetting that prerender is currently Chromium-only. Other browsers ignore the rules entirely — there is no regression, but the upside is browser-specific. Don't take a hard dependency on it.
- Conflicting `Cache-Control: no-store` headers on the target page. Browsers refuse to prerender no-store responses by design.

## Verification

- Chrome DevTools → Application → Speculative Loads. Lists every rule, what it matched, and whether the prerender succeeded.
- `chrome://prerender-internals` for low-level state.
- After implementation, the "Next-page navigation" line in Chrome User Experience Report drops sharply.
- Lighthouse does not yet score speculation rules directly, but field LCP/INP on landing pages reached via speculated navigations should improve.

### Sources
- MDN — Speculation Rules API (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API
- WICG — Speculation Rules (W3C / WICG) — https://wicg.github.io/nav-speculation/speculation-rules.html
- Chrome for Developers — Speculation Rules (Google) — https://developer.chrome.com/docs/web-platform/prerender-pages
- web.dev — Speculation rules API (web.dev) — https://web.dev/articles/speculation-rules

---

## Resource hints overview

Status: recommended  ·  Source page: https://specification.website/spec/performance/resource-hints/

Five resource hints — dns-prefetch, preconnect, preload, modulepreload, prefetch — cover every stage of the request lifecycle. Pick the right one for the job.

## What it is

Resource hints are `<link rel>` declarations that tell the browser to do work earlier than the HTML parser would otherwise discover it. The W3C Resource Hints specification defines four; HTML adds two more (`preload`, `modulepreload`).

| Hint | What it does | Use when |
|---|---|---|
| `dns-prefetch` | Resolve DNS for the origin. | Cheap fallback for older browsers; large numbers of secondary origins. |
| `preconnect` | DNS + TCP + TLS handshake to the origin. | You will definitely request from this origin in the next ~10 seconds. |
| `preload` | Fetch a specific resource at high priority. | Late-discovered critical resource (LCP image, font referenced from CSS). |
| `modulepreload` | Fetch and parse an ES module, including its dependency graph. | Critical JS module that would otherwise be discovered after the parser hits `<script type="module">`. |
| `prefetch` | Fetch a resource at low priority for a future navigation. | The user's next likely page (article → comments, search → first result). |

## Why it matters

The browser's parser discovers resources in source order. Anything referenced from CSS, JavaScript, or a late `<link>` is found late, after several round-trips. Hints move discovery to the start of the document so work overlaps with the rest of HTML parsing.

Used wrongly, hints **harm** performance — preloading 20 things slows the LCP element because everything fights for the same bandwidth. Treat each hint as a deliberate decision.

## How to implement

A practical decision flow:

1. **Is this for the current page?**
   - Yes → next question.
   - No, it's the next navigation → `prefetch` (as `document` for HTML, otherwise blank).

2. **Is it a specific URL the browser would otherwise discover late?**
   - Yes, and it's an ES module → `modulepreload`.
   - Yes, anything else → `preload` with the correct `as=` (image, font, style, script, fetch).
   - No, you don't know the URL yet but you know the origin → next question.

3. **How many requests will you make to that origin?**
   - 1+ — use `preconnect` (with `crossorigin` if the requests use CORS).
   - 0–1 maybe — use `dns-prefetch` only. Cheaper.

Example head with each hint serving a distinct purpose:

```html

<link rel="preconnect" href="https://cdn.example.com" crossorigin>

<link rel="dns-prefetch" href="https://stats.example.com">

<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>

<link rel="preload" href="/hero.avif" as="image" fetchpriority="high">

<link rel="modulepreload" href="/router.mjs">

<link rel="prefetch" href="/articles/next" as="document">
```

See [preload-prefetch-preconnect](/spec/performance/preload-prefetch-preconnect/) for syntax details and gotchas.

## Common mistakes

- Preloading the same resource that is already referenced by a `<link rel="stylesheet">` higher in the head. The preload scanner finds it; the hint is noise.
- Mixing `preload` and `prefetch` semantics. `preload` is for the current page; `prefetch` is for the next one.
- Forgetting `crossorigin` on font preloads or preconnects to CORS origins.
- `modulepreload` on a non-module script. Use `preload as="script"` for classic scripts.
- More than ~5 hints in the head. Each one competes for bandwidth.

## Verification

- DevTools → Network → check the start time and priority of hinted resources. Hints should pull them left.
- Chrome console logs unused preloads after a few seconds.
- Lighthouse "Preload key requests" and "Preconnect to required origins" cover the common cases.

### Sources
- W3C — Resource Hints (W3C) — https://www.w3.org/TR/resource-hints/
- MDN — <link>: The External Resource Link element (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
- web.dev — Preload critical assets (web.dev) — https://web.dev/articles/preload-critical-assets
- MDN — rel=modulepreload (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/modulepreload

---

## View Transitions

Status: recommended  ·  Source page: https://specification.website/spec/performance/view-transitions/

Animate between states (same-document) or between pages (cross-document) with a single CSS opt-in. Replaces ad-hoc SPA animation libraries with a platform primitive.

## What it is

The View Transitions API animates the change from one DOM state to another — or from one document to the next — by taking a snapshot of the old state, applying the change, taking a snapshot of the new state, and cross-fading between them. There are two flavours.

**Same-document (JS-driven).** A single-page-app pattern. Wrap any DOM mutation in `document.startViewTransition()`:

```js
document.startViewTransition(() => {
  // any DOM update — render new view, swap routes, etc.
  app.navigate(targetUrl);
});
```

**Cross-document (declarative).** Two normal HTML pages opt into a shared transition with a single CSS rule on each:

```css
@view-transition {
  navigation: auto;
}
```

When the user navigates from page A to page B and both pages have this rule, the browser captures A, replaces it with B, and cross-fades. No JavaScript required.

**This site ships it.** [`global.css`](https://github.com/jdevalk/specification.website/blob/main/src/styles/global.css) carries `@view-transition { navigation: auto }`, so cross-document navigations between any two pages on `specification.website` cross-fade on supporting browsers. The matching `prefers-reduced-motion: reduce` rule zeroes `animation-duration` on the view-transition pseudo-elements, so reduced-motion users get an instant swap. Pairs with our [Speculation Rules](/spec/performance/speculation-rules/) prerender — the next page is already in memory, then it animates in.

You shape the animation with the `::view-transition-*` pseudo-elements:

```css
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 200ms;
}

/* Tag elements that should animate independently */
.hero {
  view-transition-name: hero;
}
```

## Why it matters

- **Replaces a stack of dependencies.** Framer Motion, GSAP page transitions, hand-rolled FLIP — replaced by a CSS declaration and a pseudo-element.
- **Bridges MPA and SPA UX.** Cross-document view transitions give a traditional multi-page site the feel of an SPA without an SPA's complexity, JavaScript weight, or accessibility regressions.
- **Pairs with [Speculation Rules](/spec/performance/speculation-rules/).** A prerendered next page + a cross-document view transition is the closest the platform gets to "instant, animated" navigation.
- **Respects user preferences.** Browsers honour `prefers-reduced-motion: reduce` and skip the animation. You should still check it explicitly when you customise.

## How to implement

**Cross-document, the minimum:**

```css
@view-transition {
  navigation: auto;
}
```

Ship that on every page you want to participate. The browser handles the rest.

**Same-document, the minimum:**

```js
if (!document.startViewTransition) {
  updateDom();
  return;
}
document.startViewTransition(() => updateDom());
```

Feature-detect — older browsers run the callback synchronously without the transition.

**Tag persistent elements** so they morph instead of cross-fading:

```css
.product-card[data-id="42"] { view-transition-name: product-42; }
```

The same name on both old and new DOM signals "this is the same conceptual element — animate the position/size delta."

**Respect reduced motion:**

```css
@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none !important;
  }
}
```

**Keep transitions short** — 150–250ms. Longer feels sluggish; shorter feels like a flash.

## Common mistakes

- Same `view-transition-name` on multiple elements at once. The browser logs an error and skips the morph.
- Animating layout-dependent properties (width, height) when you could animate transforms. Transforms compositor-only, layout properties trigger reflow.
- Long animations on data-heavy navigations. The user is waiting for the page, not for your animation. Cap at ~250ms.
- Ignoring `prefers-reduced-motion`. People with vestibular disorders should not be motion-tested for a route change.
- Same-document transitions that swallow exceptions in the callback. Wrap with try/catch and re-throw on transition rejection.

## Verification

- DevTools → Animations panel. Records every view transition with timing.
- `caniuse.com/view-transitions` — current browser support matrix. Same-document is broadly available; cross-document still rolling out (Chromium first, WebKit shipping, Gecko in progress).
- Toggle `prefers-reduced-motion: reduce` in DevTools → Rendering. The transition must disappear, not just shorten.
- Run a Lighthouse audit on the destination page — adding view transitions must not regress LCP or INP. If it does, your animation is too long or too expensive.

### Sources
- MDN — View Transition API (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API
- CSS View Transitions Module Level 2 (W3C) — https://drafts.csswg.org/css-view-transitions-2/
- Chrome for Developers — Same-document view transitions (Google) — https://developer.chrome.com/docs/web-platform/view-transitions/
- Chrome for Developers — Cross-document view transitions (Google) — https://developer.chrome.com/docs/web-platform/view-transitions/cross-document
- WebKit — View Transitions (WebKit) — https://webkit.org/blog/16557/view-transitions/

---

## Back/forward cache (BFCache)

Status: recommended  ·  Source page: https://specification.website/spec/performance/bfcache/

Keep pages BFCache-eligible so back/forward navigation restores them instantly from memory, with no reload, no hydration, and no repaint.

## What it is

When the user navigates away from a page, the browser may snapshot the whole thing — DOM, JavaScript heap, scroll position, in-flight timers — into memory. On back or forward navigation, that snapshot is restored. No network request. No HTML parse. No script execution. No paint beyond compositing the existing frame.

Chrome, Firefox, and Safari all ship a BFCache (Safari has had it the longest, as "page cache"). The eligibility rules differ in the corners but the broad shape is the same: pages that look like they can be safely frozen and thawed are cached; pages that hold open connections, listen for `unload`, or are explicitly marked uncacheable are not.

This page is mostly about *not breaking* a feature you get for free.

## Why it matters

- **It is the fastest navigation the platform has.** A BFCache restore is faster than a prerendered page, faster than a service-worker cache hit, faster than anything you can build. The frame is already composited.
- **It feeds Core Web Vitals.** Field metrics count BFCache restores. A site that ships BFCache-eligible pages reports better LCP, CLS, and INP at the 75th percentile than an otherwise-identical site that disqualifies itself.
- **It costs nothing if you don't break it.** Most of the work is removing legacy patterns — an old `unload` listener, a blanket `Cache-Control: no-store` — not adding new code.

## How to implement

**Never listen for `unload`.** This is the single most common disqualifier. Use `pagehide` for cleanup and `visibilitychange` for "user left the tab" semantics. Both fire reliably and neither blocks BFCache.

**Do not set `Cache-Control: no-store` on HTML.** All major browsers refuse to cache `no-store` responses for BFCache. `no-cache` is fine — it forces revalidation on a real navigation, but the page is still eligible to be restored from memory on back/forward. See [Cache-Control](/spec/performance/cache-control/).

**Close stateful connections in `pagehide`.** Open IndexedDB transactions, WebSockets, and `BroadcastChannel`s can block eligibility or get torn down on eviction. Close them when the page hides; reopen them in `pageshow` if the page is restored.

**Handle the restore.** The `pageshow` event fires with `event.persisted === true` when the page comes back from BFCache. Treat it as "I was frozen — re-sync":

```js
window.addEventListener("pageshow", (event) => {
  if (!event.persisted) return;
  // Restored from BFCache — re-run analytics, refresh stale UI, restart polling.
  window.dataLayer?.push({ event: "bfcache_restore" });
});
```

**Watch `window.opener` and same-origin iframes.** A page that holds a live reference to another window, or that contains a same-origin iframe with its own disqualifiers, may inherit ineligibility.

## Common mistakes

- A single `addEventListener("unload", ...)` anywhere on the page — often from a legacy analytics shim or a third-party widget. One listener disqualifies the whole document.
- `Cache-Control: no-store` applied site-wide to "be safe". It silently turns off the fastest navigation the browser has.
- Running analytics only on `DOMContentLoaded`. BFCache restores skip it, so session metrics under-report back navigations. Send a pageview on `pageshow` when `persisted` is true.
- Assuming the cache is permanent. Browsers evict aggressively under memory pressure and after a timeout (Chrome currently caps around 10 minutes). Design for "usually instant", not "always instant".
- Third-party scripts that register their own `unload` handler. Audit them; some vendors offer a `pagehide`-based mode.

## Verification

- Chrome DevTools → **Application** → **Back/forward cache** → **Test back/forward cache** runs an eligibility check on the current page and lists every disqualifying reason by name.
- The [`NotRestoredReasons` API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons) on `PerformanceNavigationTiming` reports why a back/forward navigation was *not* served from BFCache. Send it from real-user monitoring to find disqualifiers you can't reproduce locally.
- Lighthouse flags **"Page prevented back/forward cache restoration"** as a discrete audit, with the failure reason.
- Manual smoke test: load the page, navigate to any other origin, hit back. If you see a network request in DevTools, BFCache did not restore.

### Sources
- WHATWG HTML — Navigation and session history (WHATWG) — https://html.spec.whatwg.org/multipage/nav-history-apis.html
- web.dev — Back/forward cache (Google) — https://web.dev/articles/bfcache
- MDN — bfcache (MDN) — https://developer.mozilla.org/en-US/docs/Glossary/bfcache
- Chrome for Developers — Back/forward cache (Google) — https://developer.chrome.com/docs/web-platform/back-forward-cache

---

## Visibility-aware rendering

Status: recommended  ·  Source page: https://specification.website/spec/performance/visibility-aware-rendering/

Use `content-visibility` with `contain-intrinsic-size` to skip layout and paint for off-screen content, and Intersection Observer to drive lazy behaviour, instead of scroll and resize listeners.

## What it is

Two platform primitives for "do work only when content is actually visible".

**`content-visibility: auto`** is a CSS property from the Containment module. It tells the browser it may skip rendering work — layout, style, paint — for a subtree while that subtree is off-screen. When the element scrolls near the viewport, the browser renders it as normal.

**Intersection Observer** is a Web API that fires a callback when an element crosses a configurable threshold relative to the viewport (or another scroll root). It replaces hand-rolled `scroll` and `resize` listeners that ran on every frame.

## Why it matters

- **Long pages and card grids get cheaper.** A page with hundreds of sections, product cards, or comments pays the layout and paint cost for all of them on every change. `content-visibility: auto` reduces that to just what is on screen, often a multiple-times reduction in rendering time on initial load and interaction.
- **Scroll handlers stop being the bottleneck.** `scroll` listeners fire dozens of times per second on the main thread. Intersection Observer hands the work to the browser's compositor and only wakes your code at the threshold you asked for.
- **Built-in primitives beat libraries.** Lazy-init for embeds, "load more" triggers, viewport-driven analytics, and reveal animations all collapse to the same small API.

## How to implement

**`content-visibility` on long, repeating sections.** Always pair it with `contain-intrinsic-size` so the browser can reserve layout space for the skipped subtree:

```css
.card,
article > section {
  content-visibility: auto;
  contain-intrinsic-size: auto 600px;
}
```

The intrinsic size is a placeholder used until the real content is rendered. Pick a value close to the real rendered size of the block.

**Intersection Observer for everything `loading="lazy"` doesn't cover.** Native `loading="lazy"` on `<img>` and `<iframe>` already handles the simple image case — reach for IO for widgets, infinite-scroll triggers, and visibility analytics:

```js
const io = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    if (entry.isIntersecting) {
      entry.target.dataset.seen = 'true';
      io.unobserve(entry.target);
    }
  }
}, { rootMargin: '200px 0px' });

document.querySelectorAll('[data-lazy]').forEach((el) => io.observe(el));
```

`rootMargin` lets you start work *before* the element is on screen, so the user doesn't see a flash of empty space.

## Common mistakes

- **Omitting `contain-intrinsic-size`.** The skipped subtree collapses to zero height, the scrollbar jumps as content streams in, and CLS suffers.
- **Picking an intrinsic size much smaller than reality.** Same scrollbar-jank problem, just spread across the whole page.
- **Using Intersection Observer where `loading="lazy"` would do.** For below-the-fold images and iframes, the HTML attribute is simpler and ships in every modern browser.
- **Debounced scroll listeners.** If you're throttling `scroll` to fake an IO callback, just use IO. It is cheaper and more accurate.
- **Forgetting to `disconnect()`.** In long-lived single-page apps, observers attached to torn-down views leak. Disconnect when the view unmounts.

## Verification

- Chrome DevTools → Performance panel. Record a scroll through a long page with and without `content-visibility: auto`. The "Rendering" and "Painting" bands should shrink sharply.
- DevTools → Rendering → "Layout Shift Regions" and the Web Vitals overlay. Verify CLS does not regress after adding `content-visibility` — if it does, your `contain-intrinsic-size` is wrong.
- In the console, inspect `IntersectionObserverEntry.intersectionRatio` and `entry.isIntersecting` inside your callback to confirm thresholds fire when expected.
- Search the codebase for `addEventListener('scroll'` and `addEventListener('resize'`. Each hit is a candidate for replacement.

### Sources
- CSS Containment Module Level 2 (W3C CSSWG) — https://drafts.csswg.org/css-contain-2/
- MDN — content-visibility (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/content-visibility
- Intersection Observer (W3C) — https://www.w3.org/TR/intersection-observer/
- MDN — Intersection Observer API (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API

---

## CSS containment

Status: optional  ·  Source page: https://specification.website/spec/performance/css-containment/

Use `contain: layout paint style` (or the `contain: content` shorthand) to tell the browser that an element's internals cannot affect the rest of the page, so reflow and repaint stay isolated to that subtree.

## What it is

The `contain` CSS property is a hint to the rendering engine: the element's subtree is independent of the rest of the document, so the browser can scope layout, paint, and style work to it. Four containment types compose:

- **`layout`** — descendants do not affect the layout of anything outside the element, and vice versa.
- **`paint`** — descendants are clipped to the element's box; nothing paints outside it.
- **`style`** — counters and quotes inside the element do not leak out.
- **`size`** — the element's own size is computed without consulting its children. Requires an explicit size or `contain-intrinsic-size`, otherwise the box collapses.

The shorthand `contain: content` is equivalent to `layout paint style` — deliberately excluding `size`, because most components do not have a known intrinsic size. The stricter `contain: strict` adds `size` on top.

## Why it matters

Browsers optimise rendering by computing layout, paint, and style for the smallest possible scope. Without containment, a class change deep inside a card can force the browser to recompute the layout of the surrounding page, because, in principle, an element's children can affect ancestors (think percentage heights, intrinsic sizing, or `position: absolute` escaping). Containment lets you assert that they cannot, so the engine can skip work it would otherwise have to do defensively.

The payoff is largest on pages with many independent components — feeds, grids, dashboards, long article comments — where a single interaction would otherwise invalidate a chunk of the document.

## How to implement

Apply `contain: content` to self-enclosed components — cards, sidebars, widgets, repeated list items — where children stay within the box and have predictable sizing:

```css
.card,
.sidebar-widget,
.feed-item {
  contain: content;
}
```

For off-screen sections, pair with `content-visibility: auto` so the browser can skip rendering entirely until the section approaches the viewport:

```css
article > section {
  content-visibility: auto;
  contain-intrinsic-size: 0 800px;
}
```

## Common mistakes

- **Applying `contain: size` without `contain-intrinsic-size`.** The box collapses to zero in the contained axis, because children no longer contribute to its size.
- **Containing elements whose children must overflow visually.** Tooltips, dropdown menus, and floating labels get clipped by `paint` containment.
- **Reaching for `contain: strict` at the page level.** Sticky positioning, fixed children, and anchor scrolling break when their containing block is unexpectedly isolated.
- **Treating containment as free.** There is a small cost to maintaining the boundary; apply it where you have measured a benefit, not as a reflex.

## Verification

- Chrome DevTools → Performance panel. Record an interaction before and after; recalc-style and layout costs on the contained subtrees should drop.
- DevTools → Rendering → "Paint flashing" and "Layer borders". Confirms the isolation is real — paint should not extend past contained boxes.
- Test scroll and interaction on long pages on a mid-range device. If frame times do not improve, the bottleneck was elsewhere; revert.

### Sources
- CSS Containment Module Level 2 (W3C) — https://drafts.csswg.org/css-contain-2/
- MDN — contain (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/contain
- web.dev — Learn CSS containment (Google) — https://web.dev/learn/performance/css-containment

---

## Scroll-driven animations

Status: optional  ·  Source page: https://specification.website/spec/performance/scroll-driven-animations/

Drive CSS animations from scroll position or element visibility with `scroll-timeline` and `view-timeline`, replacing JS scroll-listener libraries with compositor-thread animation.

## What it is

Scroll-driven animations tie a CSS animation's progress to scroll position instead of the wall clock. The browser provides two timelines.

**`scroll-timeline`** — progress maps to how far a scroll container has been scrolled. Useful for reading-progress bars and parallax tied to the document.

**`view-timeline`** — progress maps to a subject element's intersection with its scrollport. Useful for "reveal as you scroll" effects, sticky-section pinning, and per-element entrance animations.

Anonymous shorthands cover the common cases without naming a timeline:

- `animation-timeline: scroll()` — bind to the nearest scrollable ancestor.
- `animation-timeline: view()` — bind to this element's own viewport intersection.

The colour status is `optional` because nothing breaks if you ship none of this. Where motion is part of the design, however, it is the right answer: it replaces a category of janky JavaScript with a declarative primitive that the compositor can run.

## Why it matters

- **Off the main thread.** Compositor-only properties (`transform`, `opacity`, `filter`) animate without touching JavaScript or layout. No INP cost, no scroll-listener debouncing, no `requestAnimationFrame` loop.
- **No library needed.** Replaces a stack of intersection-observer-plus-rAF code, often shipped as 20–60 kB of JavaScript, with a few lines of CSS.
- **Honours user preferences when you opt in.** Because the motion is yours, you must gate it on `prefers-reduced-motion: reduce` — see [reduced motion](/spec/accessibility/reduced-motion/).
- **Composable with view transitions.** Pair with [view transitions](/spec/performance/view-transitions/) for entrance + navigation animation that stays on the compositor.

## How to implement

Fade an element in as it scrolls into view:

```css
@keyframes fade-in {
  from { opacity: 0; transform: translateY(1rem); }
  to   { opacity: 1; transform: none; }
}

.reveal {
  animation: fade-in linear both;
  animation-timeline: view();
  animation-range: entry 0% cover 30%;
}

@media (prefers-reduced-motion: reduce) {
  .reveal { animation: none; }
}
```

`animation-range` tells the browser which slice of the view timeline drives the animation — here, from the element entering the scrollport until it has covered 30% of it.

For a top-of-page reading-progress bar, use `scroll()` instead:

```css
.progress {
  transform-origin: 0 50%;
  animation: progress linear;
  animation-timeline: scroll(root block);
}
@keyframes progress { to { transform: scaleX(1); } }
```

## Common mistakes

- **Animating layout properties** (`width`, `height`, `top`, `margin`) instead of `transform` and `opacity`. The compositor win disappears the moment the browser has to relayout on every frame.
- **Forgetting `prefers-reduced-motion`.** Scroll-driven motion is exactly the kind that triggers vestibular issues. Always provide an opt-out.
- **Replacing an Intersection Observer that runs logic.** Scroll-driven animations animate; they do not fire callbacks. If you need to lazy-init a widget, hydrate an island, or fetch data on visibility, keep the observer — see [visibility-aware rendering](/spec/performance/visibility-aware-rendering/).
- **Reaching for `scroll-timeline` when `view-timeline` would do.** Per-element reveal effects are simpler, more local, and easier to maintain with `view()`. Reserve `scroll()` for document-level effects like progress bars.
- **Long ranges with heavy keyframes.** Keep ranges tight; an animation that runs over half the page tends to feel laggy even when it is technically free.

## Verification

- Chrome DevTools → Animations panel records scroll-driven timelines and lets you scrub them.
- Toggle `prefers-reduced-motion: reduce` in DevTools → Rendering. The motion must disappear, not merely shorten.
- Run a Lighthouse or Web Vitals check. INP should be unaffected; if it regresses, you are animating the wrong property.
- Confirm the page still works with JavaScript disabled — scroll-driven animations are pure CSS and should degrade gracefully where unsupported.

### Sources
- CSS Scroll-driven Animations Module Level 1 (W3C) — https://drafts.csswg.org/scroll-animations-1/
- MDN — CSS scroll-driven animations (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_scroll-driven_animations
- MDN — animation-timeline (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline
- Chrome for Developers — Scroll-driven animations (Google) — https://developer.chrome.com/articles/scroll-driven-animations

---

## Scrollbar gutter

Status: recommended  ·  Source page: https://specification.website/spec/performance/scrollbar-gutter/

Use scrollbar-gutter: stable to reserve scrollbar space and stop horizontal layout shift between pages or states that overflow vs. don't.

## What it is

`scrollbar-gutter` is a CSS property that controls whether a scroll container reserves space for a classic scrollbar even when one isn't currently shown. It takes three values you actually care about:

- **`auto`** (default) — the gutter appears only when content overflows. Short pages have no scrollbar; tall pages do.
- **`stable`** — the gutter is always reserved on the inline-end edge, whether or not the scrollbar is visible.
- **`stable both-edges`** — the gutter is reserved on both inline edges, so horizontal symmetry is preserved.

It only affects *classic* scrollbars — the kind that take layout space, common on Windows and on macOS when "Always show scrollbars" is enabled. Overlay scrollbars (the macOS and mobile default) float over content, so the property has no visible effect there.

```css
html {
  scrollbar-gutter: stable;
}
```

This site ships exactly that on `:root` in `src/styles/global.css`.

## Why it matters

- **No more page-to-page jolt.** A short page has no scrollbar; the next page does. Without `scrollbar-gutter: stable`, the viewport width snaps by 15–17px between navigations and the whole layout jumps sideways.
- **No mid-page jolt either.** The same shift happens within a single page when content grows or shrinks — a filter panel collapsing, an accordion opening, async-loaded content arriving below the fold.
- **Field-CLS friendly.** Layout shift caused by scrollbar appearance counts as real CLS in many implementations. It's a cheap [Core Web Vitals](/spec/performance/core-web-vitals/) win.
- **Animated navigations need it.** Paired with [view transitions](/spec/performance/view-transitions/) and prerendered links, a 15px width snap on swap makes an otherwise polished navigation look amateur.

## How to implement

Apply it once at the root:

```css
:root {
  scrollbar-gutter: stable;
}
```

That's the whole intervention for the common case. If your layout is centred and you want guaranteed symmetry regardless of overflow state:

```css
:root {
  scrollbar-gutter: stable both-edges;
}
```

Apply it to genuinely-scrollable nested regions (a sidebar with its own overflow, a modal body) on the same principle — but only those, not every element with `overflow` set.

## Common mistakes

- Applying it to a small element where the scrollbar is part of the visual design. The gutter then shows even when no scroll is needed. Restrict it to the root viewport or genuinely-scrollable regions.
- Combining it with custom `::-webkit-scrollbar` styling that already reserves layout space. You'll end up with a double gutter.
- Forgetting RTL. `stable` reserves on the inline-end edge — right in LTR, left in RTL. If you need predictable symmetry across both directions, use `stable both-edges`.
- Reaching for it to fix fluctuating content widths inside the page. That's a `min-height`, container query, or `aspect-ratio` job — `scrollbar-gutter` only addresses the scrollbar itself.

## Verification

- Open a short page and a tall page on the same site in the same window. The horizontal position of every element should stay identical. Without `scrollbar-gutter: stable`, it doesn't.
- Chrome DevTools → Rendering → Layout Shift Regions. Navigate between pages; there should be no flash on the right edge.
- Test on a system using overlay scrollbars (macOS default) *and* one using classic scrollbars (Windows default, or macOS Settings → Appearance → "Always" show scrollbars). Only the classic case shows the difference — which is exactly why it has to be tested there.

### Sources
- CSS Overflow Module Level 3 — scrollbar-gutter (W3C CSSWG) — https://drafts.csswg.org/css-overflow-3/#scrollbar-gutter-property
- MDN — scrollbar-gutter (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-gutter
- web.dev — Prevent layout shifts with scrollbar-gutter (Google) — https://web.dev/articles/scrollbar-gutter

---

# Privacy

Consent, signals, and respecting visitor choice.

## Privacy policy

Status: required  ·  Source page: https://specification.website/spec/privacy/privacy-policy/

A privacy policy tells visitors what personal data you collect, why, on what legal basis, who you share it with, how long you keep it, and what rights they have.

## What it is

A privacy policy is the public document that explains how your website handles personal data. Under the GDPR it satisfies the transparency obligations of Articles 13 and 14 — the right of the data subject to be informed about processing. Similar laws exist in the UK (UK GDPR), California (CCPA/CPRA), Brazil (LGPD), and most other jurisdictions.

It is not a disclaimer. It is a binding statement of practice.

## Why it matters

If you collect any personal data — names, email addresses, IP addresses, cookies tied to a user, form submissions — you owe the visitor an accurate description of what happens to it. Regulators treat a missing, vague, or out-of-date policy as a transparency failure on its own, even before they look at what you actually do with the data.

A clear policy also reduces support load. Most "what do you do with my data?" questions disappear when there is a page to point at.

## How to implement

A privacy policy should disclose, at minimum:

- **Identity of the controller**, including a postal address and a contact for privacy questions. If you have a Data Protection Officer, name them.
- **Categories of personal data** you process — account data, usage data, payment data, contact data, technical identifiers like IP addresses.
- **Purposes** for each category — running the service, billing, marketing, analytics, security, legal compliance.
- **Lawful basis** under GDPR Article 6 for each purpose: consent, contract, legal obligation, vital interests, public task, or legitimate interests. If you rely on legitimate interests, say what they are.
- **Recipients and processors** — payment providers, hosting, email, analytics, customer support tools. List by name or category, and indicate transfers outside the EU/UK with the safeguard used (SCCs, adequacy decision).
- **Retention periods** for each category, or the criteria used to determine them.
- **Rights** — access, rectification, erasure, restriction, portability, objection, and the right to lodge a complaint with a supervisory authority.
- **Cookies and tracking**, either inline or by linking to a separate cookie notice.
- **A "last updated" date** that is visible at the top of the page.

Link to the policy from the footer of every page. Do not put it behind a login.

## Common mistakes

- Copy-pasted boilerplate that mentions practices you do not have, or omits ones you do.
- A single "we may share data with partners" line that names no one.
- No retention information at all.
- Hiding the policy in the terms of service.
- Updating the document without changing the date — or changing the date without telling existing users.

### Sources
- GDPR Articles 13 and 14 — Information to be provided (EU GDPR) — https://gdpr-info.eu/art-13-gdpr/
- ICO — Right to be informed (ICO) — https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/individual-rights/the-right-to-be-informed/
- EDPB Guidelines on Transparency under Regulation 2016/679 (EDPB) — https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-transparency-under-regulation-2016679_en

---

## Cookie consent

Status: required  ·  Source page: https://specification.website/spec/privacy/cookie-consent/

In the EU and UK, non-essential cookies and similar storage require freely given, informed, specific, and unambiguous opt-in consent before they are set.

## What it is

In the EU and UK, the ePrivacy Directive — implemented through national laws such as PECR in the UK — requires consent before storing or reading information on a user's device. The GDPR then defines what valid consent looks like: a freely given, specific, informed, and unambiguous indication of the user's wishes, given by a clear affirmative action.

This applies to cookies, but also to localStorage, sessionStorage, IndexedDB, fingerprinting, and pixel trackers. The technology does not matter; the storage and access do.

## Why it matters

Cookie consent is the most enforced part of EU privacy law on the public web. National regulators — CNIL, the Garante, the ICO, the Belgian DPA — issue fines regularly, and most of them target the same patterns: pre-ticked boxes, "reject" buttons hidden two clicks away, and banners that count scrolling as consent.

A non-compliant banner is also a poor user experience. Visitors do not want to negotiate with your site before reading it.

## How to implement

The principles are simpler than vendors make them sound:

- **Strictly necessary cookies do not need consent.** Session cookies for login, shopping carts, security tokens, and load balancing are exempt. Analytics, advertising, social embeds, and A/B testing are not.
- **Set no non-essential cookies before the user accepts.** This includes Google Analytics, Meta Pixel, Hotjar, YouTube embeds, and most "marketing" tags.
- **Give "accept" and "reject" equal prominence.** Same size, same colour weight, same number of clicks. A bright green "Accept all" next to a grey "Manage preferences" is non-compliant.
- **Rejecting must be as easy as accepting.** One click. Not a maze of toggles.
- **Reject means reject.** No tracking cookies, no fingerprinting fallback, no "legitimate interests" toggle that is on by default.
- **Be specific about purposes.** "Analytics" and "marketing" are categories users can choose between; "improving your experience" is not.
- **Let users change their mind.** A persistent link in the footer to reopen the banner.
- **Re-ask only when the purposes change**, not every visit.

The banner is not the consent record. Store the user's choice — what they consented to, when, and which version of the notice they saw.

## Common mistakes

- Pre-ticked boxes for any non-essential purpose. The CJEU ruled this invalid in *Planet49* (2019).
- "By using this site you agree" — implied consent is not valid consent under GDPR.
- Loading analytics scripts before the user has chosen.
- A "reject" button that is visually deprioritised, or only appears after clicking "preferences".
- No way to withdraw consent later.
- Treating the UK as exempt from these rules — UK GDPR and PECR are substantively the same.

### Sources
- EDPB Guidelines 03/2022 on deceptive design patterns in social media (EDPB) — https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-032022-deceptive-design-patterns-social-media_en
- ICO — Cookies and similar technologies (ICO) — https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/guide-to-pecr/cookies-and-similar-technologies/
- CNIL — Cookies and other trackers (CNIL) — https://www.cnil.fr/en/cookies-and-other-trackers
- ePrivacy Directive 2002/58/EC, Article 5(3) (EUR-Lex) — https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:02002L0058-20091219

---

## Global Privacy Control (GPC)

Status: recommended  ·  Source page: https://specification.website/spec/privacy/global-privacy-control/

Global Privacy Control is a browser-level signal that tells websites the user opts out of the sale or sharing of their personal data. California and Colorado require sites to honour it.

## What it is

Global Privacy Control (GPC) is a simple machine-readable signal that a user — through their browser, an extension, or a privacy-focused tool like DuckDuckGo or Brave — broadcasts to every site they visit. It says: *I do not want my personal data sold or shared.*

The signal is sent two ways:

- An HTTP request header: `Sec-GPC: 1`
- A JavaScript property: `navigator.globalPrivacyControl === true`

Both are read-only and trivial to detect server-side or client-side.

## Why it matters

Under the California Consumer Privacy Act (CCPA/CPRA), the California Attorney General has confirmed that GPC is a valid opt-out signal that businesses must honour. Enforcement has followed — Sephora paid \$1.2 million in 2022 in part for failing to process GPC signals. The Colorado Privacy Act explicitly lists GPC-style universal opt-out mechanisms as a required path from July 2024 onward. Connecticut and several other states have followed.

GPC does not replace cookie banners under EU law, because the EU regime is opt-in rather than opt-out. But it is a strong privacy signal everywhere, and respecting it costs almost nothing.

## How to implement

Detect the signal on every request:

```js
// Client-side
if (navigator.globalPrivacyControl) {
  // user has opted out
}
```

```
# Server-side (any language)
if request.headers.get("Sec-GPC") == "1":
    opt_out = True
```

When the signal is present:

- **Do not sell or share** personal information as those terms are defined under the user's applicable law.
- **Do not load advertising trackers**, retargeting pixels, or data-broker tags.
- **Suppress consent-banner "accept" defaults** — the user has already expressed a preference.
- **Record the opt-out** as you would any other privacy request, including the timestamp and the URL.
- **Disclose your behaviour** in the privacy policy: state that you honour GPC and what that means in practice.

For sites that serve both EU and US users, GPC should be treated as one of several inputs alongside cookie consent and any in-product privacy settings. The strictest preference wins.

## Common mistakes

- Ignoring the signal entirely and continuing to load tracking scripts.
- Honouring GPC only for users who identify themselves as Californian. The signal does not include a state, and the AG has been clear: process it for any user who sends it.
- Treating GPC as a cookie banner replacement under GDPR. EU consent is opt-in; GPC is opt-out.
- Failing to mention GPC in the privacy policy, so users have no way to verify the site respects it.

### Sources
- Global Privacy Control specification (W3C Community Group) — https://globalprivacycontrol.github.io/gpc-spec/
- California Attorney General — Frequently Asked Questions: CCPA (California Office of the Attorney General) — https://oag.ca.gov/privacy/ccpa
- Colorado Privacy Act Rules — Universal Opt-Out Mechanism (Colorado Attorney General) — https://coag.gov/resources/colorado-privacy-act/

---

## Third-party scripts and privacy

Status: recommended  ·  Source page: https://specification.website/spec/privacy/third-party-scripts/

Every script loaded from another domain can read cookies, see the URL, and exfiltrate data from your page. Audit them, justify them, and lock them down.

## What it is

A third-party script is any `<script src="…">` whose source is not your own origin. Once it loads, it runs with full access to the page: the DOM, cookies that are not `HttpOnly`, localStorage, the URL, the referrer, form inputs as the user types, and any data your own JavaScript exposes.

The browser also tells the third party about the visit at the network layer: IP address, user-agent, Accept-Language, the page that loaded the script (Referer), and any cookies that domain has set.

## Why it matters

Third-party scripts are the largest source of unintended data leaks on the modern web. A single tag for a chat widget, A/B tester, fonts service, or "session replay" tool can ship every URL a logged-in user visits to a third party. Some of those tools record keystrokes by default.

From a legal standpoint, the EDPB has confirmed that the ePrivacy Directive applies to any technology that reads or writes to the user's device, not just cookies — so a tracking pixel without a cookie is still in scope. From a security standpoint, a compromised third-party script becomes a compromise of your site. *Magecart*-style supply-chain attacks have hit British Airways, Ticketmaster, and many smaller sites by injecting code into a single trusted vendor.

## How to implement

Treat every third party as a liability you are choosing to take on.

- **Audit what you have.** Use the network panel, or a tool like Request Map, to list every domain your pages contact. Most sites are surprised.
- **Justify each one.** What does it do, who owns it, what data does it receive, and what is the business case for keeping it? Anything that fails this should be removed.
- **Self-host where you can.** Fonts, JavaScript libraries, and icon sets rarely need to come from a CDN. Self-hosting eliminates a third-party contact entirely and is often faster.
- **Defer or gate the rest.** Anything that is not essential to first render should load after user interaction, or only after consent for non-essential storage.
- **Use a Content Security Policy.** A `script-src` allowlist prevents a compromised page from loading scripts you did not approve. See `security/content-security-policy`.
- **Use Subresource Integrity** for any script you must load from a third party where the URL is stable. An SRI hash ensures the file has not changed since you audited it. See `security/subresource-integrity`.
- **Set a Referrer-Policy** of `strict-origin-when-cross-origin` or stricter so third parties do not see full URLs.

## Common mistakes

- Loading dozens of marketing tags through a tag manager and treating the tag manager as the audit.
- Hot-linking fonts or libraries from a public CDN to "save bandwidth" while leaking visitor IPs to that CDN.
- Adding session-replay tools without checking what they record. Many capture passwords and credit cards by default.
- Setting a permissive CSP (`script-src *`) that defeats the protection.
- Auditing once at launch and never again.

### Sources
- MDN — Content Security Policy (CSP) (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
- EDPB Guidelines 2/2023 on Technical Scope of Art. 5(3) ePrivacy Directive (EDPB) — https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-22023-technical-scope-art-53-eprivacy-directive_en
- MDN — Subresource Integrity (MDN) — https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity

---

## Privacy-respecting analytics

Status: recommended  ·  Source page: https://specification.website/spec/privacy/analytics-privacy/

You can measure traffic without surveilling visitors. Aggregate, cookieless, EU-hosted analytics tools answer most product questions without the consent and transfer problems of ad-tech analytics.

## What it is

Privacy-respecting analytics measure what visitors do on your site without building a persistent profile of each visitor. The pattern: collect the smallest useful unit of data, aggregate it on the server, drop or hash anything that could identify a person, and keep it out of jurisdictions that introduce transfer problems.

Most product questions — what pages people read, where they came from, where they drop off — can be answered without cookies, fingerprints, or cross-site identifiers.

## Why it matters

Between 2022 and 2023, the Austrian, French, Italian, and Danish data protection authorities ruled that the standard configuration of Google Analytics violated the GDPR because of transfers to the US. The EU–US Data Privacy Framework has changed the legal picture, but regulators still treat ad-tech-grade analytics with scrutiny, and the underlying design problem — every visit shared with a third party that combines it with data from millions of other sites — has not gone away.

There is a more practical reason: a cookieless analytics tool does not require a consent banner under EU rules, because nothing is stored on the user's device. The data you get is also more representative, because nobody opts out.

## How to implement

The pattern is the same across tools:

- **Measure without cookies.** Use a daily-rotating hash of IP + user-agent + a site salt to estimate uniques. Drop the raw IP before it hits disk.
- **Aggregate at write time.** Store counts per page per day, not individual events with timestamps, unless you genuinely need them.
- **Anonymise the IP** at the edge if any IP is kept. The last octet of an IPv4 (or the last 80 bits of an IPv6) is enough to break linkability and still keep country-level geo.
- **Keep data in the relevant jurisdiction.** For EU traffic, that means an EU-hosted analytics endpoint and an EU sub-processor list.
- **Set a short retention.** Ninety days of daily aggregates answers most product questions. Raw events should be even shorter.
- **Document it.** The privacy policy should name the analytics tool, the data collected, the retention period, and the legal basis.

Tools that follow this pattern include **Plausible**, **Fathom**, self-hosted **Matomo** (configured for IP anonymisation and no cookies), and **Cloudflare Web Analytics**. Listed as patterns, not endorsements — the specific tool matters less than the configuration.

If you must use ad-tech-grade analytics for marketing attribution, isolate it behind explicit consent and treat it as a separate system from product analytics.

## Common mistakes

- Treating "we anonymise IPs" as enough while still loading a third-party script that fingerprints the browser.
- Using GA4 with default settings and assuming the EU–US DPF closes the case. The EDPB and national authorities still expect documented assessment.
- Running a "privacy-friendly" analytics tool *and* GA *and* Hotjar. Each one introduces its own consent and transfer questions.
- Keeping raw event logs forever because storage is cheap.
- Forgetting to disclose the analytics tool in the privacy policy.

### Sources
- EDPB — 101 complaints concerning EU-U.S. data transfers (Google Analytics) (EDPB) — https://edpb.europa.eu/news/news/2022/austrian-dpa-decision-101-complaints-issued_en
- CNIL — Use of Google Analytics and data transfers to the United States (CNIL) — https://www.cnil.fr/en/use-google-analytics-and-data-transfers-united-states-cnil-orders-website-manageroperator-comply
- ICO — Guidance on the use of cookies and similar technologies (ICO) — https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/guide-to-pecr/cookies-and-similar-technologies/

---

## Data minimisation

Status: recommended  ·  Source page: https://specification.website/spec/privacy/data-minimization/

Collect only the personal data you actually need for a specific purpose, keep it only as long as you need it, and redact it from anywhere it leaks unnecessarily.

## What it is

Data minimisation is the principle that personal data must be "adequate, relevant and limited to what is necessary in relation to the purposes for which they are processed" — GDPR Article 5(1)(c). It is one of the foundational principles of EU and UK data protection law, and it is echoed in most modern privacy regimes.

In practice it is a design constraint: do not collect a field unless you have decided in advance what you will do with it.

## Why it matters

Every personal data point you hold is a liability. It can be breached, subpoenaed, misused by an insider, or simply held longer than the law allows. The cheapest way to protect data is not to collect it. The second cheapest is to delete it as soon as you no longer need it.

Minimisation is also the principle regulators reach for when no other rule clearly applies. If a form collects a date of birth and the service has no age requirement, no insurance product, and no birthday email, that field is hard to justify — even if the user typed it in voluntarily.

## How to implement

Apply minimisation at four points: collection, storage, logging, and retention.

**Collection.** Walk through every form and every API. For each field, name the purpose. Drop anything that fails the test.

- A newsletter signup needs an email address. It does not need a name, a phone number, or a job title.
- A contact form needs a way to reply. If you reply by email, you do not need a phone number.
- A delivery address is necessary to deliver a physical product. It is not necessary to download a PDF.
- Use a country dropdown instead of asking for a full address when only country matters for tax or compliance.

**Storage.** Separate identifiers from behavioural data where you can. Hash or tokenise where the raw value is not needed for the operation. For free-text fields, expect users to paste in personal data and plan accordingly.

**Logging.** Logs are the most common place where minimisation quietly fails. A request log that records full URLs will capture query-string tokens, search terms, and form data submitted over GET. Redact known sensitive fields, truncate URLs at the path, and never log request bodies in plain text in production.

**Retention.** Set a maximum retention period for each category of data and enforce it with a scheduled job, not a wiki page. Build deletion into the system from the start; retrofitting it after a request from a regulator is painful.

## Common mistakes

- Treating "we might want this later" as a purpose.
- Asking for a phone number "in case we need to call" when you never call.
- Storing IP addresses in analytics or logs indefinitely.
- Logging request bodies, including login payloads, in production.
- A retention policy in the privacy notice that no system enforces.
- Forgetting that backups age out on their own schedule — deletion needs to flow through to them too.

### Sources
- GDPR Article 5 — Principles relating to processing of personal data (EU GDPR) — https://gdpr-info.eu/art-5-gdpr/
- ICO — Data minimisation (ICO) — https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/data-protection-principles/a-guide-to-the-data-protection-principles/the-principles/data-minimisation/
- EDPB Guidelines 4/2019 on Article 25 Data Protection by Design and by Default (EDPB) — https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-42019-article-25-data-protection-design-and_en

---

# Resilience

Graceful failure — error pages, offline, redirects.

## Custom error pages (404, 500)

Status: required  ·  Source page: https://specification.website/spec/resilience/error-pages/

Custom error pages must return the correct HTTP status code, explain what went wrong in plain language, and offer the user a way forward without leaking implementation details.

## What it is

A custom error page is the document a server returns when it cannot fulfil a request. The two pages every site needs are the **404 Not Found** for missing resources and the **500 Internal Server Error** for unexpected failures. The page must be styled to match the rest of the site and must return the matching HTTP status code in the response headers.

## Why it matters

The status code is what crawlers, link checkers, and monitoring tools read. A "page not found" message that returns `200 OK` is a **soft 404**: search engines index the error page, link checkers see no broken links, and analytics tools count failures as normal traffic. Google explicitly treats soft 404s as a quality problem.

For humans, a generic server error page or a stack trace damages trust and may leak file paths, framework versions, or database details that help an attacker. A custom page keeps users in the site and gives them an obvious next step.

## How to implement

For a **404**:

- Return HTTP status `404`. Verify with `curl -I https://example.com/does-not-exist`.
- Set a clear heading: "We could not find that page."
- Offer a search box, a link to the homepage, and links to the most visited sections.
- Keep navigation, header, and footer so the user can carry on browsing.
- Log the request so you can find broken inbound links.

For a **500**:

- Return HTTP status `500`.
- Acknowledge the failure in one sentence. Do not show stack traces, framework names, or environment variables.
- Offer a retry, a link home, and a support contact if you have one.
- Log the underlying error server-side with a request ID and surface that ID to the user so support can correlate.

Configure both pages at the server or edge layer (Nginx `error_page`, Apache `ErrorDocument`, Cloudflare custom error pages, Netlify `_redirects` with status overrides) so they work even when the application is down.

**Localise error pages too.** On a multilingual site, the 404 a French visitor lands on should be in French — the URL prefix (`/fr/this-page-does-not-exist`) already tells the server which locale to render. Match the page's `lang` attribute, translate the heading and copy, and keep the search box and home link pointed at the same locale.

## Common mistakes

- Returning `200 OK` for a "page not found" message — the classic soft 404.
- Redirecting all unknown URLs to the homepage with a `302`. Search engines flag this as a soft 404 too.
- Exposing stack traces, SQL errors, or framework debug pages in production.
- A 404 page that loads a heavy JavaScript bundle before showing the message.
- Forgetting the 500 page entirely, so users see the default web server error.

## Verification

- `curl -I https://example.com/this-does-not-exist` returns `HTTP/2 404`.
- Force a 500 in staging and confirm the response code and that no stack trace leaks.
- Check Google Search Console under **Pages** for "Soft 404" warnings.
- Run a link checker against your site and confirm broken links surface as 404s, not 200s.

### Sources
- RFC 9110 — HTTP Semantics: 404 Not Found (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found
- RFC 9110 — HTTP Semantics: 500 Internal Server Error (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error
- Google Search Central — Soft 404 errors (Google Search Central) — https://developers.google.com/search/docs/crawling-indexing/http-network-errors#soft-404-errors
- MDN — HTTP response status codes (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

---

## Maintenance pages and 503

Status: recommended  ·  Source page: https://specification.website/spec/resilience/maintenance-pages/

When the site is intentionally offline, return HTTP 503 with a Retry-After header and a page that tells users what is happening and when to come back.

## What it is

A maintenance page is what visitors see during planned downtime — a database migration, a major deploy, a hardware swap. The page itself is only half of the requirement. The other half is the HTTP response: status `503 Service Unavailable` with a `Retry-After` header that tells crawlers and clients when to come back.

```
HTTP/2 503
Retry-After: 3600
Content-Type: text/html; charset=utf-8
```

## Why it matters

A maintenance page that returns `200 OK` is indistinguishable from your real site to a search engine. Googlebot will happily index "We're back in an hour" as the content of every URL on your domain. If the outage lasts a day, you can wake up to a site that ranks for nothing.

`503` is the explicit signal that the server is unavailable on purpose and that the condition is temporary. Crawlers slow down or pause. CDNs may serve stale content from cache. Monitoring tools record an outage instead of a successful response. Browsers and SDKs that respect `Retry-After` back off cleanly.

## How to implement

Configure the edge or load balancer to return the maintenance response, not the application itself — the application is the thing you're taking down.

- Status code: `503`.
- `Retry-After` header: either an integer number of seconds (`Retry-After: 1800`) or an HTTP date (`Retry-After: Wed, 29 May 2026 14:00:00 GMT`). Use the form that matches your confidence in the ETA.
- Body: a single HTML page that loads no external dependencies, no analytics, and no fonts from CDNs that may also be down.
- Tell the user: what is happening, when you expect to be back, and where to get updates (status page, social account).

Most edge providers (Cloudflare, Fastly, Nginx, HAProxy) can serve a static maintenance page with a 503 from a single rule. Allow an admin IP through so you can verify the deploy before lifting the block.

```nginx
# Nginx example
if (-f /etc/nginx/maintenance.flag) {
  return 503;
}
error_page 503 @maintenance;
location @maintenance {
  root /var/www/maintenance;
  rewrite ^.*$ /index.html break;
  add_header Retry-After 1800 always;
}
```

## Common mistakes

- Returning `200 OK` with a "we'll be back soon" message. Search engines treat this as the new content of every URL.
- Returning `503` with no `Retry-After`. Clients have to guess.
- Loading third-party scripts (analytics, chat widgets, fonts) on the maintenance page. Most of them will fail and the page may not render.
- Forgetting to remove the maintenance flag after the deploy and leaving the site at 503 for hours.

## Verification

- `curl -I https://example.com/` returns `HTTP/2 503` and a `Retry-After` header.
- The page renders without the application backend running.
- Status page (if you have one) shows the planned window.

### Sources
- RFC 9110 — HTTP Semantics: 503 Service Unavailable (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable
- RFC 9110 — HTTP Semantics: Retry-After (IETF) — https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after
- Google Search Central — How to deal with planned site downtime (Google Search Central) — https://developers.google.com/search/blog/2011/01/how-to-deal-with-planned-site-downtime

---

## Offline support and service workers

Status: optional  ·  Source page: https://specification.website/spec/resilience/offline-support/

A service worker can serve a cached offline fallback page when the network fails, keeping the site usable on flaky connections and turning hard failures into graceful ones.

## What it is

A service worker is a JavaScript file that the browser runs in the background, separate from any page. It sits between the page and the network and can intercept requests, return cached responses, and respond when the network is unavailable. The minimum useful offline feature is a single cached fallback page that the worker serves when a navigation request fails.

## Why it matters

Connections drop. Mobile users walk into lifts and tunnels. Captive portals block traffic until the user logs in. Without a service worker, every one of these turns into the browser's generic "no internet" screen, with your brand nowhere in sight. A fallback page keeps the site present and gives users a clear message instead of a dead tab.

For content-heavy sites, caching previously visited pages lets users re-read articles offline. For applications, careful caching of shell HTML, CSS, and JavaScript turns the second visit into an instant load even on slow networks.

## How to implement

```js
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}
```

The worker pre-caches a fallback page on install and serves it when a navigation request fails:

```js
// sw.js
const CACHE = 'v1';
const OFFLINE_URL = '/offline.html';

self.addEventListener('install', (event) => {
  event.waitUntil(caches.open(CACHE).then((c) => c.add(OFFLINE_URL)));
  self.skipWaiting();
});

self.addEventListener('fetch', (event) => {
  if (event.request.mode === 'navigate') {
    event.respondWith(
      fetch(event.request).catch(() =>
        caches.match(OFFLINE_URL)
      )
    );
  }
});
```

Pick a caching strategy per resource type:

- **Cache-first** for fonts, icons, and versioned static assets. Fast, no network round-trip, fine because the URL changes on update.
- **Network-first** for HTML pages and API responses. Fresh by default, with the cache as the fallback.
- **Stale-while-revalidate** for images and non-critical content. Serve cached, then update in the background.

Always include a version string in the cache name and clean up old caches on `activate`, or you'll ship stale code on the next deploy.

## Common mistakes

- Caching the whole site indiscriminately and serving stale HTML for weeks.
- Forgetting to bump the cache version on deploy, so users never see new content.
- Registering the service worker before the page is interactive and blocking first paint.
- Caching responses with `Cache-Control: no-store` or authenticated API calls.
- No way to unregister — once a buggy worker ships, it can be hard to remove.

## Verification

- DevTools → **Application** → **Service Workers**: confirm the worker is active for the scope you want.
- DevTools → **Network**: tick "Offline" and reload. The fallback page should render.
- Lighthouse PWA audit reports the offline behaviour.
- Ship a `?sw=off` kill switch that unregisters the worker, in case you need to disable it in production.

### Sources
- MDN — Service Worker API (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API
- MDN — Using Service Workers (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers
- web.dev — Offline cookbook (web.dev) — https://web.dev/articles/offline-cookbook
- W3C — Service Workers (W3C) — https://www.w3.org/TR/service-workers/

---

## Web app manifest

Status: recommended  ·  Source page: https://specification.website/spec/resilience/pwa-manifest/

A web app manifest is a small JSON file that tells browsers how the site should appear when installed — its name, icons, start URL, theme colour, and display mode.

## What it is

A web app manifest is a JSON document linked from the HTML head that describes how the site should behave when installed to a device's home screen or app launcher. It is the entry point for the Progressive Web App features modern browsers expose — installability, splash screens, themed UI, and maskable icons that look right on every platform.

Serve it at `/site.webmanifest` or `/manifest.webmanifest` and link it from the page:

```html
<link rel="manifest" href="/site.webmanifest">
```

## Why it matters

Without a manifest, browsers cannot offer to install the site, and on Android the "Add to Home Screen" prompt falls back to a generic browser icon and the page title. With a manifest, the installed site gets a proper icon, a controlled start URL, and a window mode that can hide browser chrome. The same icons feed Android shortcuts, iOS home screen entries, Windows jump lists, and Chrome OS launchers.

The theme colour also lets browsers tint the status bar and the address bar to match the brand, which makes the site feel native even when it isn't installed.

## How to implement

A minimal manifest:

```json
{
  "name": "The Website Specification",
  "short_name": "WebSpec",
  "start_url": "/?utm_source=pwa",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0b5fff",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-maskable.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}
```

Required fields for installability in Chromium browsers:

- `name` and `short_name` — the long form for splash screens, the short form for the home screen.
- `start_url` — usually `/`. Add a tracking parameter if you want to count installed launches separately.
- `display` — `standalone` hides browser chrome; `minimal-ui` keeps a tiny bar; `browser` opens in a regular tab.
- `icons` — at least one 192×192 and one 512×512 PNG. Add a separate icon with `"purpose": "maskable"` so Android can apply its adaptive icon mask without cropping content.
- `theme_color` and `background_color` — the first themes the OS chrome, the second paints the splash screen before the page loads.

Serve the file with `Content-Type: application/manifest+json`.

## Common mistakes

- Linking the manifest but serving it as `text/html` or with a missing file — installability silently fails.
- One square icon with the logo touching the edge, used as the maskable icon. Android crops it into a circle and chops the brand.
- `start_url` pointing to a 404 because someone changed the URL structure.
- Setting `display: fullscreen` and breaking the user's ability to leave the site.
- Forgetting `theme_color`, leaving the status bar bright white.

## Verification

- DevTools → **Application** → **Manifest**: every field parses, every icon loads.
- The "Install" affordance appears in the address bar in Chromium browsers.
- Test the maskable icon with [maskable.app](https://maskable.app).
- `curl -I https://example.com/site.webmanifest` returns `200` and `application/manifest+json`.

### Sources
- W3C — Web Application Manifest (W3C) — https://www.w3.org/TR/appmanifest/
- MDN — Web app manifest (MDN) — https://developer.mozilla.org/en-US/docs/Web/Manifest
- web.dev — Add a web app manifest (web.dev) — https://web.dev/articles/add-manifest

---

## Monitoring and uptime

Status: recommended  ·  Source page: https://specification.website/spec/resilience/monitoring-uptime/

Monitor the site from outside your own infrastructure, combine synthetic checks with real user data, and run a status page on a separate host so it stays up when the site does not.

## What it is

Monitoring is the continuous check that the site is reachable, correct, and fast. Uptime is the headline number — the percentage of time the site responded successfully over a window. Together they answer two questions: is the site up right now, and how often has it been down this month?

Three layers cover most needs:

1. **Synthetic monitoring** — a script in another data centre requests the site on a schedule and alerts when the response is wrong.
2. **Real User Monitoring (RUM)** — JavaScript on the page reports real visitor experience: load times, errors, Core Web Vitals.
3. **A public status page** — a page on a separate host where users can check whether the issue is yours or theirs.

## Why it matters

Internal dashboards go down with the application. A check that runs inside the same VPC as the database cannot tell you the DNS provider has failed, the TLS certificate has expired, or the CDN is serving stale content. External monitoring catches the failures your users see first.

Synthetic checks tell you whether the site works. RUM tells you whether it works **for the people who use it** — on real devices, on real networks, in the regions you actually serve. The two are complementary: synthetic is fast feedback in a controlled environment, RUM is ground truth.

A status page reduces support load during incidents. When the homepage is down, "is it just me?" is the first question every user asks. A status page on a separate domain answers it without a support ticket.

## How to implement

For synthetic monitoring, pick one external service and run checks every minute from multiple regions:

- **Hosted**: UptimeRobot, Pingdom, StatusCake, Better Stack, Checkly, Datadog Synthetics.
- **Self-hosted**: Uptime Kuma, Healthchecks.io.

Check more than the homepage. A login flow, a search endpoint, and a checkout step catch problems the home page does not. Validate the response body, not just the status code, so a `200 OK` returning the maintenance page still trips an alert.

For RUM, send Core Web Vitals (LCP, INP, CLS) and JavaScript errors to a collector. The `web-vitals` library, Sentry, Datadog RUM, and Cloudflare Web Analytics all do this in a few kilobytes.

Run the status page on a different host and a different DNS provider from the main site. Common pattern: `status.example.com` resolved through a CDN-fronted static site, with the status records stored at a third-party provider (Statuspage, Instatus, BetterStack, or a static site you update manually). The point is that when the primary site is unreachable, the status page must not be unreachable too.

## Common mistakes

- A monitor that hits the homepage from one region every five minutes and reports 100% uptime while half the world cannot reach the site.
- Checking only the status code, so a 200 OK returning an error page passes.
- Status page on the same domain as the site. When the site is down, so is the status page.
- Alerting on every blip. Pages every five minutes train operators to ignore the alert.
- No on-call rota, so alerts go to an inbox no one reads at 3am.

## Verification

- Trigger a controlled outage in staging. Confirm the monitor alerts within the expected window.
- Check that the status page resolves when the main site's CDN is blocked at the network level.
- Review the past month's incidents and confirm RUM data and synthetic checks agree on when the site was degraded.

### Sources
- Google SRE Book — Monitoring Distributed Systems (Google SRE) — https://sre.google/sre-book/monitoring-distributed-systems/
- web.dev — User-centric performance metrics (web.dev) — https://web.dev/articles/user-centric-performance-metrics
- Google SRE Workbook — SLO engineering case studies (Google SRE) — https://sre.google/workbook/implementing-slos/

---

# Internationalisation

Language, locale, direction, and translated content.

## International URL structure

Status: recommended  ·  Source page: https://specification.website/spec/i18n/international-url-structure/

Pick a single URL pattern for multilingual or multi-regional content — country-code top-level domain, subdomain, or subdirectory — and stick with it. Optionally localise the slugs too.

## What it is

When a site serves more than one language or region, every localised page needs its own stable URL. Three patterns are in common use, all compatible with [hreflang](/i18n/hreflang) and standard crawling:

```
ccTLD:        https://example.de/
Subdomain:    https://de.example.com/
Subdirectory: https://example.com/de/
```

A fourth pattern — a query parameter such as `https://example.com/?loc=de` — exists in the wild but is explicitly discouraged by Google for geotargeting because the locale is not part of the resource identity. Treat it as out of scope.

## Why it matters

The URL pattern is the foundation everything else in your internationalisation stack annotates. [hreflang](/i18n/hreflang), [sitemap hreflang entries](/i18n/sitemap-hreflang), the [language switcher](/i18n/language-switcher), canonical tags, and analytics segmentation all reference the same URLs. Change the pattern later and every one of those has to be rebuilt, with 301 redirects to preserve link equity.

The pattern also signals locality to users and search engines. A `.de` domain reads as German to a visitor before the page loads. A `/de/` path reads as "the German section of an international site". Neither is wrong; they communicate different things.

## How to implement

Pick one of the three patterns for the whole site:

| Pattern | Geotargeting | Server location | Infra cost | Perceived locality |
|---|---|---|---|---|
| ccTLD (`example.de`) | Automatic by TLD | Anywhere | High — separate domains, certificates, DNS | Strongest |
| Subdomain (`de.example.com`) | Set per host in Search Console | Anywhere | Medium — DNS + certificate per locale | Medium |
| Subdirectory (`example.com/de/`) | Set per path in Search Console | Anywhere | Low — one domain, one certificate | Weakest |

Choose by what dominates the decision:

- **Strong country presence and budget for separate operations:** ccTLD. Best signal of locality, hardest to consolidate authority across locales.
- **One brand, distinct regional teams or stacks:** subdomain. Geotargeting is per-host in Search Console.
- **One brand, shared codebase, fastest to ship:** subdirectory. Authority concentrates on a single domain; geotargeting is per-path.

Then:

- **Pair every canonical URL with [hreflang](/i18n/hreflang).** The URL pattern identifies the resource; hreflang tells search engines which locale it serves.
- **Localise the slug where it adds clarity.** `/about/` to `/sobre/` is helpful for Spanish readers; `/api/v1/` is not worth translating. Consistency matters more than translation: localise all slugs in a section, or none.
- **Keep slug rules from the general [URL structure](/seo/url-structure) page.** Lowercase, hyphenated, ASCII-where-possible, stable.
- **Set the locale from the URL, not from the `Accept-Language` header.** The W3C recommends against silent language negotiation because it breaks sharing — see [avoid auto geo redirects](/i18n/avoid-auto-geo-redirects).

## Common mistakes

- Mixing patterns within one site (`example.com/de/` for German, `fr.example.com` for French). Pick one.
- Using a query parameter (`?lang=de`, `?country=de`) as the locale identifier. Search engines treat it as the same URL.
- Using a country code as a language indicator: `/uk/` for English-language content served to the UK is fine as a *region* path, but should not be confused with the BCP 47 language tag (`en-GB`).
- Redirecting the root URL based on IP — see [avoid auto geo redirects](/i18n/avoid-auto-geo-redirects). Serve a language picker or an `x-default` page instead.
- Localising slugs inconsistently, so half the German site lives at `/de/about/` and half at `/de/uber-uns/`.

### Sources
- Google Search Central — Managing multi-regional and multilingual sites (Google Search Central) — https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites
- W3C i18n — When should I use language negotiation? (W3C) — https://www.w3.org/International/questions/qa-when-lang-neg
- RFC 3986 — Uniform Resource Identifier (URI): Generic Syntax (IETF) — https://www.rfc-editor.org/rfc/rfc3986

---

## hreflang for language and regional URLs

Status: recommended  ·  Source page: https://specification.website/spec/i18n/hreflang/

hreflang tells search engines which language or regional version of a page to show to which user. It uses BCP 47 codes and must be reciprocal across all alternates.

## What it is

`hreflang` is a signal that tells search engines a page has equivalent versions in other languages or regions. It lives on a `<link rel="alternate">` element, an HTTP `Link` header, or a `<xhtml:link>` entry in an XML sitemap. Each alternate carries a [BCP 47](https://www.rfc-editor.org/info/bcp47) language tag such as `en`, `en-GB`, `fr-CA`, or `zh-Hant`.

```html
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/" />
<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/" />
<link rel="alternate" hreflang="fr-CA" href="https://example.com/fr-ca/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />
```

## Why it matters

Without `hreflang`, search engines guess which version of a page to surface. A user in Paris may get the US English page; a user in Quebec may get the page intended for France. `hreflang` removes that guesswork, reduces duplicate-content confusion across localised URLs, and improves click-through because the result matches the user's language and region.

It does not influence ranking on its own. It is purely a swap signal: same query, better-matched URL.

## How to implement

- **Use BCP 47 codes.** Language only (`en`, `de`), or language plus region (`en-GB`, `pt-BR`). Region alone (`hreflang="GB"`) is invalid. Script subtags are allowed where they disambiguate, e.g. `zh-Hans` and `zh-Hant`.
- **Self-reference.** Every page must list itself among its alternates.
- **Reciprocal links.** If page A points to page B, page B must point back to page A. One-way links are ignored.
- **`x-default`.** Add a `hreflang="x-default"` entry for the URL shown when no other alternate matches the user's locale. This is typically a language picker or the default-region homepage.
- **Pick one delivery method.** Use HTML `<link>` for static pages, the HTTP `Link` header for non-HTML resources such as PDFs, and the XML sitemap for sites with many alternates — mixing them on the same URL set creates conflicts.

A sitemap entry covers all alternates of a URL in one place:

```xml
<url>
  <loc>https://example.com/en-gb/</loc>
  <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/" />
  <xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr-ca/" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/" />
</url>
```

## Common mistakes

- Using a country code as a language code (`hreflang="UK"` instead of `en-GB`).
- Pointing alternates at URLs that redirect or 404.
- Forgetting the self-reference. Google then ignores the whole cluster.
- Mixing `hreflang` declarations in HTML, headers and sitemaps — pick one source of truth.
- Setting `hreflang` on canonicalised-away pages. Each alternate should be the canonical URL of its locale.

### Sources
- Google Search Central — Localized versions of your pages (Google Search Central) — https://developers.google.com/search/docs/specialized/international/localized-versions
- BCP 47 — Tags for Identifying Languages (IETF) — https://www.rfc-editor.org/info/bcp47
- W3C i18n — Choosing a language tag (W3C) — https://www.w3.org/International/questions/qa-choosing-language-tags

---

## Localised page metadata

Status: recommended  ·  Source page: https://specification.website/spec/i18n/localised-metadata/

Translate every visible string in the head and in structured data — title, meta description, Open Graph fields, JSON-LD names and descriptions, image alt text — not just the body. A localised body with English metadata is a half-translation.

## What it is

Localised metadata means every audience-facing string outside the visible body is translated to match the page's locale: the `<title>`, the meta description, every Open Graph and Twitter Card field, every name and description inside JSON-LD, `alt` text on images, the PWA manifest name, and the Open Graph image itself when it carries text. A page that ships a translated body but English metadata is half-translated — and the English half is what shows up in search results and social previews.

## Why it matters

[hreflang](/i18n/hreflang) tells search engines which URL to surface for which user, but it does not translate anything. A common real-world failure is a French page at `/fr/` that ranks correctly in `google.fr` and then appears in the SERP with an English title and English snippet, because the templating layer only swapped the body. The user sees a foreign-language result, distrusts it, and clicks the competitor.

The same applies to shared links. When someone in São Paulo pastes the Portuguese URL into WhatsApp and the unfurl card is in English, the link looks broken even though the landing page is fine. Screen readers reading `alt="Company logo"` in an otherwise Spanish page jar the listener in exactly the same way.

## How to implement

Every locale needs its own translated version of:

- `<title>` and `<meta name="description">`.
- `<meta property="og:title">`, `og:description`, `og:site_name`, `og:image:alt`.
- `og:locale` set to this page's locale, `og:locale:alternate` listing the others. Open Graph uses underscored tags (`fr_FR`), unlike BCP 47 elsewhere — that mismatch is OGP's quirk.
- `twitter:title`, `twitter:description`, `twitter:image:alt`.
- JSON-LD `name`, `description`, `headline`, `articleSection`, and `inLanguage` (BCP 47, matching the page).
- `alt` text on every `<img>` — translated, not left in the source language.
- `<meta name="application-name">` and any PWA manifest `name` / `short_name`.
- The Open Graph image itself when it contains text — render a per-locale variant rather than reusing one English card.

Set the matching [`lang` on `<html>`](/foundations/html-lang) so assistive tech and crawlers know which language the metadata is in. Use BCP 47 in `lang`, `hreflang`, and `inLanguage` (`fr-FR`); the underscored form (`fr_FR`) only applies to `og:locale`.

```html
<html lang="fr-FR">
<head>
  <title>Spécification du Web — un bon site web fait ces choses</title>
  <meta name="description" content="Un guide indépendant de la plateforme…">
  <meta property="og:title" content="Spécification du Web">
  <meta property="og:description" content="Un guide indépendant…">
  <meta property="og:locale" content="fr_FR">
  <meta property="og:locale:alternate" content="en_GB">
  <meta property="og:image" content="https://example.com/og/fr.png">
  <meta property="og:image:alt" content="Logo de Spécification du Web">
  <link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/">
  <link rel="alternate" hreflang="en-GB" href="https://example.com/en/">
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "WebPage",
    "name": "Spécification du Web",
    "description": "Un guide indépendant…",
    "inLanguage": "fr-FR"
  }
  </script>
</head>
```

## Common mistakes

- Translating the body but leaving the head in the source language — the most damaging case, because the head is what search results and unfurl cards display.
- Forgetting `alt` text on images. It is usually the last string translators see, and often the one they never receive.
- Reusing a single Open Graph image with English text on it across every locale. The shareable card stays monolingual even when the page is not.
- Omitting `inLanguage` on JSON-LD. Consumers fall back to guessing from `lang` or content sniffing, and they guess wrong on short pages.
- `og:locale` left as `en_US` on every page because it was copy-pasted from a template.
- Schema `description` fields that quietly duplicate the body text instead of being translated to match the locale.

## Verification

- Fetch each locale's URL and grep the head for any source-language strings that survived.
- Run each locale through Google's Rich Results Test and confirm `inLanguage` is emitted on the structured data.
- Paste the URL into the Facebook Sharing Debugger and LinkedIn Post Inspector — the title, description, and image alt on the card should all match the page's locale.
- Spot-check the SERP with a query like `site:example.com/fr/` and confirm every title and snippet is in French, not English.

### Sources
- Google Search Central — Tell Google about localized versions (Google Search Central) — https://developers.google.com/search/docs/specialty/international/localized-versions
- schema.org — inLanguage (schema.org) — https://schema.org/inLanguage
- Open Graph protocol (ogp.me) — https://ogp.me/
- W3C — Internationalization Quick Tips for the Web (W3C) — https://www.w3.org/International/quicktips/

---

## hreflang in XML sitemaps

Status: optional  ·  Source page: https://specification.website/spec/i18n/sitemap-hreflang/

Declare language and regional alternates inside the XML sitemap with xhtml:link instead of in the HTML head. Easier to maintain at scale and keeps localisation metadata separate from content.

## What it is

The sitemap form of [hreflang](/i18n/hreflang). Instead of declaring language and regional alternates with `<link rel="alternate" hreflang="...">` in every HTML head, you list them once per URL inside the XML sitemap using the `<xhtml:link>` element. The namespace `xmlns:xhtml="http://www.w3.org/1999/xhtml"` is declared on the root `<urlset>`. The signal sent to search engines is identical to the inline form — only the delivery mechanism changes.

```xml
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/en/page</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/seite"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
  </url>
  <url>
    <loc>https://example.com/de/seite</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/seite"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
  </url>
  <url>
    <loc>https://example.com/fr/page</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/seite"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
  </url>
</urlset>
```

## Why it matters

On a large multilingual site, declaring hreflang inline becomes painful. A cluster of ten locales means ten `<link>` elements in every page's head, every locale, every template — eleven with `x-default`. Adding an eleventh locale touches every template and every cached page. Moving the declaration to the sitemap keeps page HTML clean, centralises localisation metadata in one machine-generated file, and lets you add or remove a locale by regenerating one document.

The signal is equivalent. Google, Bing and Yandex all read `<xhtml:link>` entries from the sitemap as authoritative alternates.

## How to implement

- **Pick one delivery method per site.** Use either inline [hreflang](/i18n/hreflang) in the HTML head, the HTTP `Link` header, or sitemap `<xhtml:link>` — not several at once on the same URLs. Mixed signals get ignored or produce conflicts.
- **Declare the namespace.** Add `xmlns:xhtml="http://www.w3.org/1999/xhtml"` on the root `<urlset>`.
- **Group all alternates inside each `<url>`.** Every `<url>` entry lists every alternate URL in the group, including itself. The bidirectional rule still applies: if A lists B, B must list A.
- **Self-reference always.** Each URL must include a `<xhtml:link>` pointing at itself with its own `hreflang`. Omitting it invalidates the entire cluster.
- **Add `x-default`.** Point it at the language selector or the default-region landing page.
- **Use BCP 47 tags.** Language (`en`, `de`), or language plus region (`en-GB`, `pt-BR`). Never a country code on its own.
- **Reach for the sitemap when** you have many locales, many pages, or generate alternates from the same source that already generates the sitemap. Reach for inline `<link>` when you don't ship an XML sitemap, or when alternates differ from how the sitemap is built.

## Common mistakes

- Forgetting the `xmlns:xhtml` namespace declaration — the entries parse but search engines ignore them.
- Listing only the "other" languages and skipping the self-reference.
- Shipping both inline `<link rel="alternate">` and sitemap `<xhtml:link>` for the same URLs, with different sets.
- Pointing alternates at non-canonical URLs, redirects, or 404s.
- Splitting a language cluster across multiple sitemap files — keep all alternates of a URL inside the same `<url>` entry.

## Verification

- Fetch the sitemap and confirm the `xhtml` namespace is declared on `<urlset>`.
- Pick one URL and confirm every alternate listed there reciprocally lists it back.
- Use Search Console's International Targeting report (or equivalent) to confirm clusters are detected without "no return tags" errors.

### Sources
- Google Search Central — Tell Google about localized versions (Google Search Central) — https://developers.google.com/search/docs/specialty/international/localized-versions
- sitemaps.org — XML sitemap protocol (sitemaps.org) — https://www.sitemaps.org/protocol.html
- BCP 47 — Tags for Identifying Languages (IETF) — https://www.rfc-editor.org/info/bcp47

---

## Avoid automatic IP-based language redirects

Status: avoid  ·  Source page: https://specification.website/spec/i18n/avoid-auto-geo-redirects/

Automatically redirecting visitors to a locale based on IP geolocation or Accept-Language is an anti-pattern. It traps users in the wrong language, breaks search crawlers, and breaks shared links. Let users choose.

## What it is

An automatic locale redirect is when the server, CDN, or edge function inspects the visitor's IP address (geolocation) or the `Accept-Language` request header and issues an HTTP redirect — typically `302` — to a localised URL such as `/de/` or `de.example.com`, without giving the visitor a choice.

The classic shapes:

- A visitor on a German IP requests `/en/pricing` and is bounced to `/de/pricing`.
- A visitor with `Accept-Language: fr-FR` requests `https://example.com/` and is redirected to `/fr/`, with no way to land on the English root.
- A localised URL silently rewrites its content based on the visitor's country, so `/de/about` shows English text to a US visitor.

In each case, the URL no longer determines the content. The visitor's network location does.

## Why it matters

**Search engines never see the localised content they need to index.** Googlebot crawls predominantly from US IPs. If every request from a US IP is redirected to `/en-us/`, the German, French, and Japanese pages are never reached. The site effectively de-indexes its own translations.

**Users get trapped in the wrong language.** A British expat in Berlin gets German pages they cannot read. A French speaker on a US-exit VPN gets English. A traveller checking a booking from abroad cannot return to their own locale. There is often no visible way out, because the switcher itself redirects them back.

**Shared links break.** A user in Paris sends `/fr/article-x` to a colleague in Tokyo. The colleague clicks it and lands on `/ja/article-x` — or, worse, on the homepage. The link no longer means what it said.

**`Accept-Language` is unreliable.** Most browsers ship a default of `en-US,en;q=0.9` regardless of the user's actual preference, and most users never change it. Treating it as a preference signal is guessing.

## What to do instead

- Ship a visible [language switcher](/spec/i18n/language-switcher) on every page. The user, not the server, picks the locale.
- On first visit, it is acceptable to show a **non-blocking banner** suggesting another locale based on detected hints ("This page is also available in Deutsch — switch?"). Never auto-redirect.
- Persist the user's *explicit* choice in a cookie, `localStorage`, or account preference — but only after they have picked. Do not persist a guess.
- Use [hreflang](/spec/i18n/hreflang) so search engines route the right query to the right locale.
- Localised URLs (`/de/`, `/fr-ca/`) must serve their declared content unconditionally to every visitor and every crawler. The URL is the contract.
- Content negotiation on the **root URL only** is fine as a soft default, provided the localised URLs are stable and the user can override the choice.

## Verification

- Open a localised URL through a VPN exit in another country. The content must match the URL, not the exit's location.
- `curl -H "Accept-Language: de" https://example.com/en/pricing` must return the English page.
- `curl -A "Googlebot" https://example.com/de/pricing` must return the German page, with `200 OK` and no redirect.
- Click the language switcher, copy the resulting URL, open it in a private window from a different country. It must still resolve to the same locale.

### Sources
- Google Search Central — Managing multi-regional and multilingual sites (Google Search Central) — https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites
- W3C i18n — When should I use language negotiation? (W3C) — https://www.w3.org/International/questions/qa-when-lang-neg
- W3C i18n — Using language selectors (W3C) — https://www.w3.org/International/questions/qa-navigation-select

---

## lang attribute on inline content

Status: required  ·  Source page: https://specification.website/spec/i18n/lang-attribute/

Mark passages, phrases, and inline elements that differ from the document language with a lang attribute. WCAG 3.1.2 requires it so assistive tech can switch pronunciation.

## What it is

`lang` is a global HTML attribute that names the natural language of the element's content. The root document language belongs on `<html lang="…">` (covered by [the html lang attribute spec page](/foundations/html-lang)). This page is about the *other* `lang` declarations — the ones you add to spans, paragraphs, quotes, and any inline content whose language differs from the page default.

```html
<p>The German verb <span lang="de">verschlimmbessern</span> means to make
something worse by trying to improve it.</p>
```

## Why it matters

WCAG 2.4.2 Level A requires a page-level language. [WCAG 3.1.2 Level AA](https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html) requires per-part language declarations for any passage or phrase whose language differs from the surrounding text. The benefits are concrete:

- **Screen readers** switch voice and pronunciation rules. VoiceOver reads a French sentence with a French voice when it sees `lang="fr"`; without it, it mangles the words with the document-language voice.
- **Browsers** apply the correct spellcheck dictionary, font fallback, hyphenation rules, and quotation marks.
- **Search engines and translation tools** know which spans to leave alone and which to translate.
- **CSS** can target language with the `:lang()` pseudo-class — useful for typography and quotation marks.

## How to implement

Use [BCP 47](https://www.rfc-editor.org/info/bcp47) tags, the same tagging system used for `hreflang`. Language subtag first, optional script and region after.

```html
<html lang="en-GB">
  <body>
    <blockquote lang="fr">
      Je pense, donc je suis.
    </blockquote>
    <p>The motto <i lang="la">per aspera ad astra</i> is Latin.</p>
    <p>The Japanese term <span lang="ja">改善</span>
       (<span lang="ja-Latn">kaizen</span>) means continuous improvement.</p>
  </body>
</html>
```

Rules of thumb:

- **Mark the smallest correct element.** A `<span>` around a foreign phrase is fine.
- **Mark scripts when relevant.** `zh-Hans` vs `zh-Hant` matters for font selection. `ja-Latn` distinguishes romanised Japanese from kanji.
- **Do not mark proper names** that are widely used in the page language ("Paris" in an English text does not need `lang="fr"`).
- **Quotes and citations** are good candidates — `<blockquote lang="…">` and `<q lang="…">` change quotation-mark glyphs via the browser.

## Common mistakes

- Tagging every loanword. "Café" and "ad hoc" in English text are English now.
- Using invalid codes like `lang="english"` or `lang="UK"`. Use `en` or `en-GB`.
- Setting `lang=""` (empty) on an element to "unset" it — that is only valid on `<html>` when the language is genuinely unknown.
- Forgetting the script subtag for CJK content, which causes wrong font rendering.

### Sources
- WCAG 3.1.2 — Language of Parts (Level AA) (W3C) — https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html
- W3C i18n — Declaring language in HTML (W3C) — https://www.w3.org/International/questions/qa-html-language-declarations
- MDN — The lang global attribute (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang

---

## Language switcher

Status: recommended  ·  Source page: https://specification.website/spec/i18n/language-switcher/

List each locale in its own language ('Deutsch', '日本語', 'العربية') and mark it with the right lang attribute. Don't use flags — flags are countries, not languages.

## What it is

A language switcher is the UI control that lets a visitor pick which localised version of your site they want to read. It pairs with [`hreflang`](/spec/i18n/hreflang) (which tells search engines about alternates) and with the page-level [`lang` attribute](/spec/i18n/lang-attribute) (which tells assistive tech what language the current page is in). The switcher is the human-facing half: a discoverable, persistent control that puts the choice in the user's hands.

## Why it matters

A visitor who landed on the wrong locale has to be able to fix it without reading the current page. That sounds obvious, and it's the one rule most sites break. If your German switcher option is labelled "German" in English, a user who only reads German cannot find it. If you label locales with flags, you have told a Mexican Spanish speaker that Spanish belongs to Spain, and an Arabic speaker that their language belongs to a single country it does not. The switcher is also what makes it safe to [avoid automatic geo-redirects](/spec/i18n/avoid-auto-geo-redirects): you can serve a sensible default and trust users to correct it.

## How to implement

- **Label each option in its own language.** "Deutsch", not "German". "日本語", not "Japanese". "Français", not "French". W3C is explicit about this: users who can't read the current page need the link in their own language.
- **Add the region only when it disambiguates.** "Português (Portugal)" vs "Português (Brasil)", "English (UK)" vs "English (US)".
- **Mark each link with `lang` (and `hreflang`).** Screen readers switch voice on `lang`, so the option is announced correctly even when the surrounding page is in another language.
- **Don't use flags for languages.** Spanish is not Spain. Arabic is not any single country. English is neither the UK nor the US. Use flags only when you genuinely mean a country (a regional storefront, a shipping selector).
- **Make it discoverable.** Visible without hover, in or near the header or the footer. Not buried inside a hamburger menu or hidden behind an icon-only button.
- **Persist the choice.** When a user picks a locale, remember it (cookie, `localStorage`, account preference) and honour it on return — but never override an explicit URL. `/de/` always serves German.
- **Link to the equivalent page, not the locale homepage.** If a user switches language from `/pricing/`, they should land on `/de/pricing/`, not `/de/`.
- **Indicate the current locale.** Mark it with `aria-current="true"` (or style it as non-interactive) so screen-reader users know where they are.

```html
<nav aria-label="Language">
  <ul>
    <li><a href="/de/" lang="de" hreflang="de">Deutsch</a></li>
    <li><a href="/ja/" lang="ja" hreflang="ja">日本語</a></li>
    <li><a href="/ar/" lang="ar" hreflang="ar">العربية</a></li>
    <li><a href="/pt-br/" lang="pt-BR" hreflang="pt-BR">Português (Brasil)</a></li>
    <li><a aria-current="true">English</a></li>
  </ul>
</nav>
```

## Common mistakes

- Labelling locales in the page's current language ("German", "Japanese") instead of the target language.
- Flags as language indicators.
- Omitting `lang` on each option, so screen readers mispronounce "日本語" in an English voice.
- Switching language always sends the user to the locale homepage, losing their context.
- The switcher overrides an explicit `/de/` URL with a stored preference for English.
- The switcher only appears after JavaScript runs, or only on hover.

## Verification

- A visitor who cannot read the current page can still find and recognise the link to their language.
- Test with a screen reader: each option is announced in its own voice, confirming the per-link `lang` attribute works.
- The current locale is indicated (`aria-current="true"` or equivalent styling), not just unlinked or invisible.
- Switching language from a deep page lands on the equivalent localised URL, not the homepage.
- A stored preference does not override an explicit locale URL.

### Sources
- W3C i18n — Using language selectors (W3C) — https://www.w3.org/International/questions/qa-navigation-select
- W3C — Internationalization Quick Tips for the Web (W3C) — https://www.w3.org/International/quicktips/
- BCP 47 — Tags for Identifying Languages (IETF) — https://www.rfc-editor.org/info/bcp47

---

## RTL and bidirectional text

Status: recommended  ·  Source page: https://specification.website/spec/i18n/rtl-support/

Sites that serve Arabic, Hebrew, Persian, or Urdu must set dir="rtl" and use CSS logical properties so layouts mirror correctly without hard-coded left and right.

## What it is

Right-to-left (RTL) scripts — Arabic, Hebrew, Persian, Urdu, Pashto, Dhivehi, and others — read from right to left. So do their layouts: the logo sits on the right, navigation flows right-to-left, scrollbars are on the left, and progress indicators advance leftwards. Bidirectional ("bidi") text is content that mixes RTL and LTR runs, for example an English brand name embedded inside an Arabic paragraph.

The HTML `dir` attribute declares direction. The Unicode Bidirectional Algorithm handles inline mixing automatically when `dir` is set correctly.

```html
<html lang="ar" dir="rtl">
```

## Why it matters

For roughly half a billion readers, an LTR-only layout looks broken: cramped, misaligned, with arrows and icons pointing the wrong way. Get direction wrong and you also break the bidi algorithm — phone numbers, dates, and Latin brand names appear in the wrong order inside RTL paragraphs. Setting `dir` correctly fixes most of this without any per-element work.

## How to implement

**Set direction on `<html>`.** Use `dir="rtl"` on the root for RTL locales. Set `dir="auto"` on user-generated content (comments, messages) so the browser picks direction from the first strong character.

```html
<html lang="ar" dir="rtl">
<html lang="he" dir="rtl">
<html lang="en" dir="ltr">  
```

**Override per element.** A search box that always takes Latin input can stay LTR inside an RTL page:

```html
<input type="search" dir="ltr" name="q">
```

**Use CSS logical properties, not physical ones.** Replace `left`/`right` with `inline-start`/`inline-end`, and `top`/`bottom` with `block-start`/`block-end`. The same stylesheet then works in both directions:

```css
/* Instead of: */
.card { margin-left: 1rem; padding-right: 0.5rem; border-left: 1px solid; }

/* Use: */
.card { margin-inline-start: 1rem; padding-inline-end: 0.5rem; border-inline-start: 1px solid; }
```

The full set includes `margin-inline-*`, `padding-inline-*`, `border-inline-*`, `inset-inline-*`, `text-align: start | end`, and the shorthand `inline-size` / `block-size` instead of `width` / `height` when direction matters.

**Mirror directional icons.** Arrows, chevrons, back buttons, progress bars, and breadcrumbs should mirror in RTL. Use `transform: scaleX(-1)` or supply mirrored SVGs. Do not mirror logos, photos, numerals, or media controls (play stays a right-pointing triangle universally).

**Test bidi inline.** Embed Latin text inside an Arabic paragraph and check digits, punctuation, and parentheses sit correctly.

**Use the right element for unknown or overridden direction.** Three HTML mechanisms exist for inline bidi control, each with a distinct job:

- **`dir="auto"`** on any element — the browser picks direction from the first strong character. The right default for any field that displays user-generated content (comments, usernames, message bodies, search queries).
- **`<bdi>`** — short for "bidi isolation". Wraps a fragment whose direction is unknown so it does not break the surrounding paragraph's bidi algorithm. Use for usernames, titles, and any embedded foreign-language string inside running text: `Mentioned by <bdi>@محمد</bdi> in the thread`.
- **`<bdo dir="ltr">` or `<bdo dir="rtl">`** — force a specific direction regardless of content. Rare; use only when you genuinely need to override the algorithm.

`<bdi>` is the one most sites forget. Without it, an RTL username injected into an LTR template can flip surrounding punctuation and timestamps; the page looks broken and the fix is one element.

For vertical scripts (Japanese, Mongolian) and CJK line breaking, see [writing-modes](/i18n/writing-modes). Direction (`dir`) is about LTR vs RTL; `writing-mode` is about horizontal vs vertical. They are separate axes.

## Common mistakes

- Hard-coding `left:` and `right:` in CSS, then duplicating every rule for `[dir="rtl"]`.
- Forgetting to mirror icons, leaving back-arrows pointing forward.
- Setting `dir="rtl"` only on `<body>` — flexbox, grid, and form widgets read it from `<html>`.
- Reversing numbers manually; the bidi algorithm handles them when `dir` is correct.
- Mirroring logos, code snippets, or telephone numbers, which should stay LTR.

### Sources
- W3C i18n — Structural markup and right-to-left text in HTML (W3C) — https://www.w3.org/International/questions/qa-html-dir
- W3C i18n — Inline markup and bidirectional text in HTML (W3C) — https://www.w3.org/International/articles/inline-bidi-markup/
- MDN — CSS logical properties and values (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values

---

## Writing modes and CJK line breaking

Status: optional  ·  Source page: https://specification.website/spec/i18n/writing-modes/

Vertical text (Japanese, Traditional Chinese, Mongolian) needs CSS writing-mode. Chinese, Japanese, Korean, and Thai also need explicit line-break and word-break rules so wrapping respects script-specific conventions.

## What it is

Two CSS controls govern how non-Latin scripts flow and wrap, and neither has anything to do with the bidi mirroring covered by [RTL and bidirectional text](/spec/i18n/rtl-support/).

`writing-mode` sets the axis along which lines stack. `horizontal-tb` is the default. `vertical-rl` produces the traditional top-down, right-to-left columns used in Japanese and Traditional Chinese publishing. `vertical-lr` is used for Mongolian and some Manchu typesetting. Combine it with `text-orientation: mixed | upright | sideways` so Latin glyphs and digits inside a vertical CJK run render correctly.

`line-break` and `word-break` control where a line may wrap. Chinese, Japanese, Korean, and Thai each have script-specific rules — Japanese publishers forbid breaks before small kana and between certain punctuation pairs, Thai has no inter-word spaces at all — and CSS exposes them through `line-break: strict` and `word-break: keep-all`.

## Why it matters

Vertical CJK layouts are not decorative — they are how books, newspapers, and signage are typeset for hundreds of millions of readers. Without `writing-mode`, the only fallback is a rotated image, which kills selection, search, and accessibility.

Wrapping rules matter just as much. A Japanese paragraph allowed to break anywhere will split punctuation from its host character, leaving a comma stranded at the start of a line. A Chinese column wrapped with `word-break: break-all` becomes unreadable because Han characters get separated mid-compound. Get this right and the page reads naturally; get it wrong and native readers immediately mark the site as foreign-built.

## How to implement

Pair every styling rule with the correct `lang` on the containing element. Browsers use [`lang`](/spec/i18n/lang-attribute/) to pick the right line-break dictionary; CSS alone is not enough.

```css
:lang(ja), :lang(zh) {
  line-break: strict;
  word-break: keep-all;
}

.vertical {
  writing-mode: vertical-rl;
  text-orientation: mixed;
}
```

Use `line-break: strict` for Japanese — it enforces the publisher conventions described in JIS X 4051. Use `word-break: keep-all` for CJK so breaks fall only between Han characters, never inside a compound. For Thai, lean on `line-break: auto` and the browser's ICU-based segmentation; do not force `break-all`.

Switch from physical to logical properties everywhere. `padding-inline-start` and `padding-inline-end` follow the writing mode; `padding-left` and `padding-right` do not. The same applies to `margin-inline-*`, `border-inline-*`, `inset-inline-*`, and `text-align: start | end`.

Remember that flexbox and grid axes follow `writing-mode` too. Under `vertical-rl`, `flex-direction: row` runs vertically. Lay out with logical axes (`row` and `column`) and let the writing mode rotate them.

Enable `hyphens: auto` only where it applies. It needs a correct `lang` to pick a hyphenation dictionary, and most CJK content does not hyphenate at all.

## Common mistakes

- Setting `word-break: break-all` globally because "it stops overflow" — it destroys CJK readability.
- Vertical layouts without `text-orientation: mixed` — Latin runs and digits render sideways and unreadable.
- Forgetting that flexbox and grid axes follow `writing-mode`; a `row` becomes vertical under `vertical-rl`.
- Hard-coding `padding-left` and `padding-right` instead of `padding-inline-start` and `padding-inline-end` — fragile under both RTL and vertical writing modes.
- Omitting `lang` on CJK or Thai content, so the browser cannot pick the right line-break dictionary and falls back to generic wrapping.

### Sources
- CSS Writing Modes Level 3 (W3C) — https://www.w3.org/TR/css-writing-modes-3/
- CSS Text Module Level 3 — Line Breaking and Word Boundaries (W3C) — https://www.w3.org/TR/css-text-3/#line-break-property
- W3C i18n — Approaches to line breaking (W3C) — https://www.w3.org/International/articles/typography/linebreak.en
- MDN — writing-mode (MDN) — https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode

---

## Locale-aware content

Status: recommended  ·  Source page: https://specification.website/spec/i18n/locale-content/

Dates, numbers, currency, and units should be formatted in the user's locale. Use Intl APIs in the browser and the same locale data server-side so output matches expectations.

## What it is

Locale-aware content adapts the *presentation* of data to the user's conventions. "9/5/2026" means September 5 in en-US and May 9 in en-GB. "1,000" is one thousand in English and one in German. "10:30 PM" is unfamiliar where 24-hour clocks dominate. Currency symbols, decimal separators, list separators, sort order, plural rules, and unit systems all vary.

The spec is `ECMA-402` (Internationalisation API), exposed in JavaScript as the [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) namespace. Equivalent ICU-backed libraries exist for every server platform.

## Why it matters

Wrong locale formatting introduces real bugs: a US user reads a price as `$1,000.00` when the server emitted `1.000,00 €`, a delivery time is parsed as the wrong day, a sort order looks random because it used codepoint order instead of a locale collator. These errors silently erode trust. Doing it right is cheap because the platform owns the data.

## How to implement

**Pick the locale once, use it everywhere.** Resolve a single locale string per request (e.g. `en-GB`) from, in order: a user preference, a URL segment or subdomain (`/en-gb/`), the `Accept-Language` header, and a sensible default. Store it on the request and pass it to every formatter.

**Format with `Intl` in the browser:**

```js
const locale = document.documentElement.lang; // e.g. "en-GB"

new Intl.DateTimeFormat(locale, { dateStyle: "long" }).format(new Date());
// → "29 May 2026"

new Intl.NumberFormat(locale, { style: "currency", currency: "GBP" }).format(1299.5);
// → "£1,299.50"

new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(-1, "day");
// → "yesterday"

new Intl.ListFormat(locale, { type: "conjunction" }).format(["a", "b", "c"]);
// → "a, b, and c"
```

**Format on the server too.** Send pre-formatted strings in initial HTML so users without JavaScript still see the right output, and so the page does not flash with a server-formatted value being rewritten on hydration. Most languages have an ICU binding: `Intl` in Node and Deno, `babel.dates` in Python, `java.text.MessageFormat` in Java, `NumberFormatter` in PHP.

**Negotiate locale, do not assume it.** Parse `Accept-Language`, match against your supported locales with a proper algorithm (e.g. `Intl.Locale` plus `lookup`/`best-fit`), and let the user override and persist that choice.

**Format the right things.**

- Dates and times — always with a timezone, and prefer `dateStyle`/`timeStyle` over manual patterns.
- Numbers, currency, percentages — `Intl.NumberFormat`.
- Sorting and search — `Intl.Collator`.
- Plurals — `Intl.PluralRules` (English has 2 forms, Arabic has 6). Covered in detail in [plural-rules](/i18n/plural-rules).
- Lists — `Intl.ListFormat`.

## Common mistakes

- Concatenating strings like `` `${day}/${month}/${year}` `` instead of using a formatter.
- Hard-coding currency symbols rather than `currency` and `currencyDisplay`.
- Using `toLocaleString()` with no locale argument, which depends on the runtime's default and is inconsistent server vs. client.
- Storing locale-formatted strings in the database. Store ISO data (`2026-05-29`, `1299.50 GBP`) and format on read.
- Treating language and locale as the same. `en` is a language; `en-GB` is a locale. Use the locale for formatting.

### Sources
- MDN — Intl (MDN) — https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl
- W3C i18n — Working with language and locale (W3C) — https://www.w3.org/International/articlelist#locales
- MDN — Accept-Language header (MDN) — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

---

## Plural rules and grammatical number

Status: recommended  ·  Source page: https://specification.website/spec/i18n/plural-rules/

Most languages don't pluralise like English. Use CLDR plural categories — zero, one, two, few, many, other — via Intl.PluralRules instead of hard-coded 'item' vs 'items' logic.

## What it is

Grammatical number is how a language changes a word to reflect how many things it refers to. English has two forms — "1 item", "0 items", "2 items", "1.5 items" — and most developers write `count === 1 ? "item" : "items"` without thinking about it. That logic is wrong for most of the world's languages.

The [Unicode Common Locale Data Repository (CLDR)](https://cldr.unicode.org/index/cldr-spec/plural-rules) defines up to six plural *categories* that a language may use: `zero`, `one`, `two`, `few`, `many`, and `other`. Each language picks a subset and a rule that maps a number to one of them. Arabic uses all six. Russian, Polish and Ukrainian use `one` / `few` / `many` / `other`, switching on the last digit of the number ("1 файл", "2 файла", "5 файлов"). Welsh uses six. Japanese, Chinese, Korean and Vietnamese have no grammatical number at all — every count uses `other`.

`Intl.PluralRules` exposes CLDR's rules to the runtime, so you never have to encode the logic yourself.

## Why it matters

Hard-coded English plural logic produces broken sentences in every locale it cannot describe. A Russian user seeing "5 файла" instead of "5 файлов" reads it the way an English reader reads "5 file" — visibly wrong and visibly machine-translated. Translation memory and review costs go up because translators have to fight the code, and copy quality drops because there is no place to put the right forms.

## How to implement

Store strings *by category*, not by number, and let `Intl.PluralRules` pick the category.

```js
const ar = new Intl.PluralRules("ar");
ar.select(0);   // "zero"
ar.select(1);   // "one"
ar.select(2);   // "two"
ar.select(3);   // "few"
ar.select(11);  // "many"
ar.select(100); // "other"

const messages = {
  zero: "لا توجد ملفات",
  one: "ملف واحد",
  two: "ملفان",
  few: "{n} ملفات",
  many: "{n} ملفاً",
  other: "{n} ملف",
};
const text = messages[ar.select(n)].replace("{n}", n);
```

Use `Intl.PluralRules` with `{ type: "ordinal" }` for "1st / 2nd / 3rd / 4th" — these follow a different CLDR rule set from cardinals. Pair the result with `Intl.NumberFormat` so digits are rendered for the locale too (Arabic-Indic digits in `ar-EG`, Latin digits in `ar-SA`).

Any serious translation file format already encodes this: ICU MessageFormat (`{count, plural, one {1 file} other {# files}}`), Fluent, and gettext's `Plural-Forms` header all map a number to a category at runtime. Use one of those formats so translators can author the forms their language needs without touching code.

## Common mistakes

- `count === 1 ? "item" : "items"` — only works for English-like languages.
- Detecting the category by string-matching the number ("if it ends in 1…") — that is reinventing CLDR badly, and different languages have different rules.
- Concatenating strings like `"You have " + count + " items"`. Even with the right plural, word order differs by language. Use a template with a placeholder.
- Forgetting ordinals — "1st place" does not translate via cardinal rules.
- Adding a `zero` form to English. CLDR says English has no `zero` category; "0 items" uses `other`.

### Sources
- Unicode CLDR — Language Plural Rules (Unicode) — https://cldr.unicode.org/index/cldr-spec/plural-rules
- MDN — Intl.PluralRules (MDN) — https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules
- W3C — Internationalization Quick Tips for the Web (W3C) — https://www.w3.org/International/quicktips/

---

## Internationalised Domain Names (IDN)

Status: optional  ·  Source page: https://specification.website/spec/i18n/idn-support/

IDNs let domain names contain non-ASCII characters. They are encoded as Punycode on the wire and rendered as Unicode in the browser, subject to anti-spoofing rules.

## What it is

Internationalised Domain Names allow labels in a hostname to contain characters outside ASCII — Cyrillic, Greek, Han, Arabic, accented Latin, and so on. `münchen.de`, `日本語.jp`, and `παράδειγμα.gr` are all valid.

DNS itself only carries ASCII, so each non-ASCII label is encoded with [Punycode](https://www.rfc-editor.org/rfc/rfc3492) and prefixed with `xn--`. The browser shows the Unicode form to the user; the resolver, certificate, and `Host` header see the ASCII form.

```
User sees:    münchen.de
On the wire:  xn--mnchen-3ya.de
```

The current standard is **IDNA 2008** ([RFC 5890–5894](https://www.rfc-editor.org/rfc/rfc5891)), with [Unicode TR #46](https://unicode.org/reports/tr46/) defining the compatibility processing browsers actually use.

## Why it matters

For users outside the ASCII-Latin world, a domain in their own script is more memorable, more brandable, and easier to type than a transliteration. For everyone, the security implications matter: visually similar characters across scripts ("paypal" written with a Cyrillic "а" instead of Latin "a") enable **homograph attacks**, where a malicious domain impersonates a real one. Browsers therefore apply display rules that decide when to show the Unicode form and when to fall back to Punycode in the address bar.

## How to implement

Most sites only consume IDNs; few operate them. Either way, get the basics right.

**If you own an IDN:**

- Register both the IDN and an ASCII fallback, and `301` between them so links and analytics consolidate.
- Get a TLS certificate that covers both forms. Modern CAs handle this automatically when you submit the A-label (`xn--…`); verify the certificate's `dNSName` SAN entries include the encoded form.
- Set `<link rel="canonical">` to one form (typically the Unicode form) so search engines pick a single representation.
- Test mail flow. Local-part Internationalised Email ([RFC 6531](https://www.rfc-editor.org/rfc/rfc6531)) is a separate spec and patchily supported.

**If your site accepts hostnames as input (email, URLs, webhooks):**

- Normalise with **IDNA 2008 + UTS #46** before storing. Use a library (`idna` in Python, `url.domainToASCII` in Node, `IDN` in the JDK) rather than hand-rolling the algorithm.
- Store the A-label (`xn--…`) as the canonical key and display the U-label (Unicode) to users.
- Apply your platform's spoofing protection: mixed-script detection, confusable-character checks, and the [Unicode confusables data](https://www.unicode.org/Public/security/latest/confusables.txt).

**Browser display rules.** Chromium, Firefox, and Safari each maintain a policy: show Unicode if the label is in a single script (with a few mixed exceptions), or if the user's configured languages include that script. Otherwise show Punycode. You cannot override this from a website, and you should not try — it is the user's protection against homograph attacks. Test your IDN in each browser and accept that some users will see `xn--mnchen-3ya.de`.

## Common mistakes

- Comparing hostnames as raw Unicode strings, missing case folding, NFC normalisation, and IDNA mapping. Always normalise to the A-label first.
- Accepting an IDN at registration but not on login because two libraries normalise differently.
- Assuming the address bar always shows Unicode. Browser policy may downgrade to Punycode, which is fine.
- Issuing a certificate only for the U-label. Certificates must cover the A-label encoding.
- Treating IDN as a green-light for arbitrary Unicode. IDNA 2008 disallows many code points (symbols, emoji, joiners) for safety.

### Sources
- RFC 5891 — IDNA 2008: Protocol (IETF) — https://www.rfc-editor.org/rfc/rfc5891
- RFC 5890 — IDNA 2008: Definitions and Document Framework (IETF) — https://www.rfc-editor.org/rfc/rfc5890
- Unicode TR #46 — Unicode IDNA Compatibility Processing (Unicode) — https://unicode.org/reports/tr46/
- Chromium — IDN in Google Chrome (Chromium project) — https://chromium.googlesource.com/chromium/src/+/main/docs/idn.md

---