About this spec

The Website Specification is an attempt to answer one question: regardless of the stack you build on, what should a good website do? Not a framework. Not a guide. A spec — what is required, what is recommended, and what to avoid.

Why this exists

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. Search engines publish their own rules. Browsers add their own quirks. Designers, developers, and accessibility specialists each carry a slice of the picture. Almost nobody carries the whole picture.

This site collects the slices into one platform-agnostic specification — sources cited, MIT licensed, open for pull requests.

Who it is for

• Engineers auditing or building a website and wanting a single reference.
• Designers and PMs trying to scope quality without inventing it from scratch.
• Agents — yes, AI agents — that need a machine-readable description of what to check.

Status levels

Every topic has a status. Use them as the default — context can justify exceptions.

• Required — leaving it out breaks the web platform contract (e.g. <title>, charset, HTTPS).
• Recommended — meeting modern expectations of users, search engines, agents, and browsers.
• Optional — useful in some contexts, not all. Pick when it applies.
• Avoid — outdated, harmful, or actively superseded.

How it is built

Static site, generated with Astro, deployed to Cloudflare Pages from GitHub. The content lives in plain Markdown files under src/content/spec/. Sources are part of the schema — a page without a source link should not be merged.

Dogfooding

This site itself follows the spec. Everything listed below is implemented here. If you spot a contradiction between what we say and what we do, that is a bug.

• Strict Content-Security-Policy served as a response header.
• Full set of security headers via Cloudflare Pages’ _headers.
• /.well-known/security.txt for vulnerability reports.
• llms.txt and llms-full.txt for AI agents.
• robots.txt, sitemap index, and RSS feed.
• JSON-LD structured data on every page; Open Graph and Twitter Cards for sharing.
• WCAG-aligned colour contrast, focus indicators, skip link, semantic landmarks.

Credits

The spec draws on (and credits, on every applicable page):

• MDN Web Docs — the canonical platform reference.
• Yoast Developer Portal — SEO patterns and structured data.
• Equalize Digital — Accessibility Checker docs — practical accessibility problems and fixes.
• WP Accessibility Knowledge Base — community documentation on accessibility patterns and pitfalls.
• Wikipedia — Well-known URI, and the IETF RFCs it points at.
• Is It Agent Ready? — agent-readiness checks.
• joost.blog — long-running writing on SEO, accessibility, and open source.
• WHATWG, W3C, IETF, WCAG, IANA, and the people who write the standards.

Licensing

Content: CC BY 4.0. Code: MIT. Use it, fork it, ship it.

Contact

Maintained by Joost de Valk and contributors. For security reports, please follow /.well-known/security.txt. For everything else, open an issue.