Versioned documentation site for a design system

WHAT THIS TESTS Whether you understand that documentation must be pinned to released versions, and whether you can design routing, build, and UX so users land on accurate docs for the version they actually consume.

A GOOD ANSWER COVERS Build documentation from the same source as each released version and snapshot it at release time, so the docs reflect that version's real API. Serve versions under stable, version-prefixed routes, for example /v2/components/button and /v3/components/button. Provide a persistent version switcher in the header that preserves the current page across versions when possible. Default the bare URL to the latest stable release and set canonical links to avoid duplicate-content SEO problems. Mark old versions as outdated with a banner and link to the migration guide. Keep an archive but freeze old builds so they never change.

COMMON WRONG ANSWERS Serving only the latest docs from main, which misleads teams pinned to older majors. Regenerating all versions from current source, which silently shows new APIs on old version pages. No version switcher, forcing manual URL editing. Letting old docs drift instead of freezing snapshots.

LIKELY FOLLOW-UPS How do you generate per-version docs in CI? How long do you keep old versions live? How do you handle search across versions? How do you deep-link a user from an old version to the migration guide?

ONE CONCRETE EXAMPLE On each release, CI checks out the version tag, builds its docs, and publishes them to /v3/. The site root redirects to /v3/ as latest, while /v2/ remains a frozen snapshot. A version dropdown lets a team still on v2 read accurate v2 props, and a banner reminds them v3 is available with a link to the upgrade guide.