The Website Specification

The website specification — from <title> to /.well-known/security.txt, from WCAG contrast to llms.txt. Platform-agnostic, sourced on every page, written for humans and agents. MIT licensed, open for pull requests.

Live site: https://specification.website MCP server: https://mcp.specification.website/mcp

What this is

The web is a layer cake of standards: WHATWG defines HTML, W3C ratifies WCAG, the IETF publishes the RFCs behind security headers and /.well-known/ URIs, IANA registers the namespaces, search engines publish their own rules, browsers add quirks. Almost nobody carries the whole picture.

This site collects the slices into one platform-agnostic specification — sources cited on every page.

It is not a framework. It is not a tutorial. It is a spec, in the same way the HTML Living Standard is a spec: outcomes, requirements, references.

What this is not

• Not platform-specific. No "use this Next.js plugin" advice — the spec describes the outcome, you choose the implementation.
• Not opinion. Where there is no settled standard, the spec says so.
• Not a marketing site. No newsletter capture. No cookies. Aggregate Plausible analytics; that's it.

Categories

• Foundations — HTML, head, document basics.
• SEO — search visibility.
• Accessibility — WCAG-aligned rules.
• Security — headers, transport, policies.
• Well-Known URIs — agreed paths under /.well-known/.
• Agent Readiness — making a site legible to AI agents.
• Performance — Core Web Vitals, caching, fonts.
• Privacy — consent, signals, respecting choice.
• Resilience — graceful failure.
• Internationalisation — language, locale, direction.

Development

Requirements: Node.js 22.12+, npm.

npm install
npm run dev      # http://localhost:31337
npm run build    # static output in ./dist
npm run preview  # serve ./dist on port 31337

The dev server runs on port 31337 by convention (because of course it does).

Adding or changing a spec page

1. Find the right category under src/content/spec/<category>/.
2. Copy an existing .md file — for example, src/content/spec/foundations/title.md.
3. Fill in the front matter (see schema in src/content.config.ts). At minimum: title, summary, category, status, order, and sources.
4. Write the body. Sections: ## What it is, ## Why it matters, ## How to implement, ## Common mistakes, ## Verification.
5. Open a PR.

The build will fail if the schema is invalid — that is intentional.

Everything derived from the spec content updates automatically: /spec/, /checklist/, /llms.txt, /llms-full.txt, /sitemap-index.xml, /rss.xml, per-page .md endpoints, the Pagefind search index, and the MCP server's bundled data. Never hand-edit those; edit the source markdown.

Status levels

• Required — the web platform contract breaks without it.
• Recommended — modern sites should do it.
• Optional — depends on context.
• Avoid — outdated, harmful, or actively superseded.

Sources

Every page cites at least one source. The site draws on: