twosugar fac783bcdb docs(spec): openapi-website astro migration design ...

Architectural spec for migrating openapi-website from VitePress
2.0-alpha + Vue 3 to Astro 7 + React 19 + Tailwind v4, referencing
whale-apidocs.

Top-level constraint: user-facing experience must remain identical
(URLs, visuals, interactions, load, search, component behavior). Only
approved exception: shiki code-highlight token color drift <=2%.

Two-stage plan:
- Stage 1: architecture + primitives + shell (remove vitepress, wire
  content collections, sidebar generator from _category_.json, theme
  pre-paint, region system, Pagefind search, opencli URL/DOM gate).
- Stage 2: composite components (TryIt rebuilt with react-hook-form,
  ApiReference React CSR port, NewHomePage, inspira animations), all
  extracted into 6 workspace packages.

opencli A/B verification via chrome-devtools MCP, DOM topology >=95%,
URL set diff = empty, layered CI (per-PR sample, canary full-site
visual, release-gate experience assertions).

Decision log: 21 entries, all open questions closed.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-08-17 15:17:59 +08:00

..

2026-08-17-openapi-astro-migration-design.md

docs(spec): openapi-website astro migration design

2026-08-17 15:17:59 +08:00