fix(docs): serve Pages at vd3.vanduo.dev with root base

.github/workflows/deploy.yml

@@ -1,7 +1,7 @@
 name: Deploy to GitHub Pages
 
-# Builds the vite-ssg site and publishes dist/ to the GitHub Pages project page
-# (https://vanduo-oss.github.io/vd3-docs/, base /vd3-docs/).
+# Builds the vite-ssg site and publishes dist/ to GitHub Pages at
+# https://vd3.vanduo.dev/ (custom domain; Vite base `/`).
 # All @vanduo-oss/* dependencies now install from npm (the .npmrc excludes the
 # @vanduo-oss/* scope from the minimum-release-age delay), so this is a plain
 # single-repo build — no sibling checkouts.
@@ -42,25 +42,19 @@ jobs:
       # deploy.yml runs on push to main INDEPENDENTLY of ci.yml, so a type /
       # a11y / bundle-size regression could otherwise auto-publish before ci.yml
       # (which does not run these suites) ever fails. Gate them here so a broken
-      # build cannot reach Pages. The a11y + size suites read the built dist and
-      # assume base '/', so they run against a base-'/' build; the Pages artifact
-      # is rebuilt with the /vd3-docs/ base afterwards.
+      # build cannot reach Pages. Custom domain vd3.vanduo.dev is served at the
+      # site root, so one base-'/' build is both the gate artifact and the
+      # Pages upload (a11y + size suites already assume base '/').
       - run: pnpm run typecheck
 
       - name: Install Chromium for the a11y smoke
         run: pnpm exec playwright install --with-deps chromium
 
-      - name: Build (base '/') for the a11y + size gates
+      - name: Build for GitHub Pages (base '/')
         run: pnpm run build
       - run: pnpm run test:a11y
       - run: pnpm run test:size
 
-      # Project-page deploy lives under https://vanduo-oss.github.io/vd3-docs/,
-      # so rebuild with that base (assets + router resolve under /vd3-docs/).
-      - name: Build for GitHub Pages (base /vd3-docs/)
-        run: pnpm run build
-        env:
-          VITE_BASE: /vd3-docs/
       - name: Disable Jekyll processing
         run: touch dist/.nojekyll
 

README.md

@@ -62,7 +62,8 @@ pnpm run test:a11y    # axe accessibility smoke, Chromium Desktop
 CI (`.github/workflows/ci.yml`) runs typecheck, lint, stylelint, format:check,
 and build on Node 24. The unit/e2e/size suites are run locally (they are omitted
 from CI to conserve Actions minutes). `deploy.yml` builds and publishes `dist/`
-to GitHub Pages.
+to GitHub Pages at [https://vd3.vanduo.dev/](https://vd3.vanduo.dev/)
+(`public/CNAME`, Vite base `/`).
 
 ## Layout
 

openspec/config.yaml

@@ -15,8 +15,9 @@ context: |
   Tests: vitest units, Playwright visual parity (all routes, committed baselines),
   layout-navigation interactions, gzip size budget, @axe-core/playwright a11y smoke.
   Changelog policy: documents PACKAGE releases only (@vanduo-oss/vd3, @vanduo-oss/vd3-cbun),
-  never docs-site content. Deploy workflow is live on push to main (GitHub Pages project
-  page, base /vd3-docs/); apex vanduo.dev belongs to the home/ repo, so no CNAME here.
+  never docs-site content. Deploy workflow is live on push to main (GitHub Pages at
+  https://vd3.vanduo.dev/, Vite base `/`, public/CNAME); apex vanduo.dev belongs to
+  the home/ repo.
   Old-line repos (vd2 especially) are READ-ONLY reference material — never edit.
 
 rules:

openspec/specs/base-safe-public-assets/spec.md

@@ -11,7 +11,8 @@ attributes — SHALL construct the URL as `` `${import.meta.env.BASE_URL}<path>`
 with `<path>` having **no** leading slash. Such references MUST NOT be authored as
 root-absolute paths (`/music/…`, `/images/…`). This guarantees the asset resolves
 under both the root base (`/`, used by dev, preview, and the test suites) and the
-project-page base (`/vd3-docs/`, used by the GitHub Pages deploy).
+project-page base (`/vd3-docs/`, used when deliberately testing a non-root
+layout via `VITE_BASE=/vd3-docs/`; production deploy uses `/`).
 
 Reference `<img src>` attributes are exempt: the Vue SFC compiler rewrites those
 for `base` automatically, so they MAY remain root-absolute.

openspec/specs/docs-build/spec.md

@@ -282,16 +282,16 @@ bundle-size regression cannot auto-publish. Because `deploy.yml` runs on push to
 `main` independently of `ci.yml` (which does not run those suites), the gates
 SHALL live in the deploy job itself. The a11y and size suites SHALL run against a
 base-`/` build (the test suites assume base `/`); the uploaded artifact SHALL
-still be rebuilt with the `/vd3-docs/` project-page base (`VITE_BASE=/vd3-docs/`).
+be that same base-`/` build (custom domain `vd3.vanduo.dev` is served at the
+site root).
 
 #### Scenario: a failing gate blocks the deploy
 
 - **GIVEN** `deploy.yml` after this change
 - **WHEN** the build job runs on a push to `main`
 - **THEN** `pnpm run typecheck`, `pnpm run test:a11y`, and `pnpm run test:size`
   all run before `upload-pages-artifact`, any non-zero exit fails the job so
-  nothing is published, and the uploaded artifact is the `VITE_BASE=/vd3-docs/`
-  build
+  nothing is published, and the uploaded artifact is the base-`/` build
 
 ### Requirement: the docs-app interactive surfaces carry regression tests
 

openspec/specs/repo-scaffold/spec.md

@@ -34,17 +34,18 @@ The repository MUST contain a `README.md` that identifies the repo as the
 documentation site for the vd3 line (`@vanduo-oss/vd3` + `@vanduo-oss/vd3-cbun`),
 names it the Vue3-only successor of the vd2 docs site, and SHALL state the current
 status honestly: the site is launched, dogfoods the published packages, and is
-deployed to the GitHub Pages project page at `https://vanduo-oss.github.io/vd3-docs/`
-(base `/vd3-docs/`) on push to `main`. The README MUST NOT describe the repo as
-pre-scaffold, local-only, or deploys-disabled, and MUST NOT claim a `vanduo.dev`
-CNAME (that apex belongs to the `home/` repo).
+deployed to GitHub Pages at `https://vd3.vanduo.dev/` (Vite base `/`, via
+`public/CNAME`) on push to `main`. The README MUST NOT describe the repo as
+pre-scaffold, local-only, or deploys-disabled, and MUST NOT claim the
+`vanduo.dev` apex CNAME (that apex belongs to the `home/` repo; the docs site
+uses the `vd3.vanduo.dev` subdomain).
 
 #### Scenario: a visitor learns the repo state from the README alone
 
 - **GIVEN** a contributor who has never seen the vd3 program plan
 - **WHEN** they read `README.md` at the repo root
 - **THEN** they learn what the repo hosts (vd3-line docs, Vue3-only), that the
   site is live and dogfoods the published `@vanduo-oss/vd3` / `@vanduo-oss/vd3-cbun`
-  packages, and that it deploys to the `/vd3-docs/` Pages project page on push to
-  `main` — with no pre-scaffold, deploys-disabled, or `vanduo.dev`-CNAME claims
+  packages, and that it deploys to `https://vd3.vanduo.dev/` on push to
+  `main` — with no pre-scaffold, deploys-disabled, or `vanduo.dev`-apex-CNAME claims
 

package.json

@@ -4,7 +4,7 @@
   "description": "Vue 3 + vite-ssg documentation site for the vd3 line (@vanduo-oss/vd3 + @vanduo-oss/vd3-cbun)",
   "private": true,
   "type": "module",
-  "homepage": "https://vanduo-oss.github.io/vd3-docs/",
+  "homepage": "https://vd3.vanduo.dev/",
   "license": "MIT",
   "author": "vanduo-oss",
   "exports": {

public/CNAME

@@ -0,0 +1 @@
+vd3.vanduo.dev

scripts/generate-sitemap.mjs

@@ -4,7 +4,7 @@ import { readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BASE_URL = "https://vanduo-oss.github.io/vd3-docs";
+const BASE_URL = "https://vd3.vanduo.dev";
 const distDir = fileURLToPath(new URL("../dist", import.meta.url));
 
 /** Recursively collect every .html file under dist/. */

src/App.vue

@@ -16,7 +16,7 @@ const theme = useThemeStore();
 const customizer = useCustomizerStore();
 
 // ── Per-route SEO (baked into the SSG HTML via @unhead) ──────────────
-const BASE_URL = "https://vanduo-oss.github.io/vd3-docs";
+const BASE_URL = "https://vd3.vanduo.dev";
 const BRAND_TITLE = "Vanduo — Fibonacci-Tuned Vue 3 Design System";
 const DEFAULT_DESCRIPTION =
   "Vanduo is a Fibonacci-tuned Vue 3 design system: first-class components and composables on a golden-ratio scale with a single, consistent token set.";

src/components/showcase/ShowcaseProjectRow.vue

@@ -4,6 +4,7 @@ defineProps<{
   icon: string;
   blurb: string;
   imageSrc: string;
+  imageSrcDark: string;
   imageAlt: string;
   demoUrl: string;
   repoUrl: string;
@@ -30,13 +31,23 @@ defineProps<{
         </div>
         <div class="showcase-frame-body">
           <img
+            class="showcase-img showcase-img-light"
             :src="imageSrc"
             :alt="imageAlt"
             loading="lazy"
             decoding="async"
             width="1280"
             height="800"
           />
+          <img
+            class="showcase-img showcase-img-dark"
+            :src="imageSrcDark"
+            :alt="imageAlt"
+            loading="lazy"
+            decoding="async"
+            width="1280"
+            height="800"
+          />
         </div>
       </a>
     </div>
@@ -206,14 +217,41 @@ defineProps<{
   background: var(--vd-bg-primary);
 }
 
-.showcase-frame-body img {
-  display: block;
+.showcase-frame-body .showcase-img {
   width: 100%;
   height: 100%;
   object-fit: cover;
   object-position: top center;
 }
 
+/* Default: light image; dark image hidden */
+.showcase-frame-body .showcase-img-light {
+  display: block;
+}
+
+.showcase-frame-body .showcase-img-dark {
+  display: none;
+}
+
+/* Full selector inside :global() — Vue scoped otherwise drops the descendants. */
+:global([data-theme="dark"] .showcase-frame-body .showcase-img-light) {
+  display: none;
+}
+
+:global([data-theme="dark"] .showcase-frame-body .showcase-img-dark) {
+  display: block;
+}
+
+@media (prefers-color-scheme: dark) {
+  :global(:root:not([data-theme]) .showcase-frame-body .showcase-img-light) {
+    display: none;
+  }
+
+  :global(:root:not([data-theme]) .showcase-frame-body .showcase-img-dark) {
+    display: block;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .showcase-frame,
   .showcase-frame:hover {

src/main.ts

@@ -19,11 +19,10 @@ export const createApp = ViteSSG(
   {
     // vite-ssg feeds this to the vue-router history base
     // (createWebHistory(routerOptions.base)); WITHOUT it the router defaults to
-    // "/" even when the site is built under a sub-path. On the GitHub Pages
-    // project deploy (VITE_BASE=/vd3-docs/) that mismatch made every RouterLink
-    // render unprefixed (/docs-landing instead of /vd3-docs/docs-landing) and
-    // made the root URL hydrate to the NotFound page. import.meta.env.BASE_URL
-    // is "/" locally and "/vd3-docs/" in the Pages build, so both work.
+    // "/" even when the site is built under a sub-path, which breaks RouterLinks
+    // and hydrates the root as NotFound. import.meta.env.BASE_URL is "/" locally
+    // and on the vd3.vanduo.dev Pages deploy (override with VITE_BASE only when
+    // testing a non-root layout).
     base: import.meta.env.BASE_URL,
     routes,
     scrollBehavior(to, _from, savedPosition) {

src/pages/components/ExpandingCards.vue

@@ -18,8 +18,8 @@ interface ColorCard extends Card {
   color: string;
 }
 
-// Public assets resolve against the deploy base (`/` locally, `/vd3-docs/` on
-// GitHub Pages). Vite does not rebase root-absolute paths in JS data, so prefix
+// Public assets resolve against the deploy base (`/` locally and on
+// vd3.vanduo.dev). Vite does not rebase root-absolute paths in JS data, so prefix
 // `import.meta.env.BASE_URL` (always trailing-slashed).
 const base = import.meta.env.BASE_URL;
 

src/pages/media/ImageBox.vue

@@ -8,7 +8,7 @@ useImageBox(root);
 
 // `data-image-box-full-src` is read verbatim by the runtime lightbox, so Vite
 // cannot rebase it the way it does `<img src>`. Prefix the deploy base (`/`
-// locally, `/vd3-docs/` on GitHub Pages) so click-to-zoom loads the full image.
+// locally and on vd3.vanduo.dev) so click-to-zoom loads the full image.
 const base = import.meta.env.BASE_URL;
 
 const vue3Wiring = `import { ref } from 'vue';

src/pages/media/MusicPlayer.vue

@@ -49,9 +49,9 @@ type ComponentExpose = {
   container: () => HTMLElement | null;
 };
 
-// Public assets are served from the deploy base (`/` in dev/preview/tests,
-// `/vd3-docs/` on GitHub Pages). Vite does not rebase root-absolute paths in
-// JS data, so prefix `import.meta.env.BASE_URL` (always trailing-slashed).
+// Public assets are served from the deploy base (`/` locally and on
+// vd3.vanduo.dev). Vite does not rebase root-absolute paths in JS data, so
+// prefix `import.meta.env.BASE_URL` (always trailing-slashed).
 const base = import.meta.env.BASE_URL;
 
 const tracks: Track[] = [

src/pages/showcase.vue

@@ -9,6 +9,7 @@ interface ShowcaseProject {
   icon: string;
   blurb: string;
   image: string;
+  imageDark: string;
   imageAlt: string;
   demoUrl: string;
   repoUrl: string;
@@ -25,6 +26,7 @@ const projects: ShowcaseProject[] = [
     blurb:
       "A casual FOSS browser chess app on vd3 — play Aurora Polaris or TomitankChess in a Web Worker, with themes, move history, and engine-match mode. Fully static-hosted; no server required.",
     image: `${base}images/showcase/aurora-polaris-chess.png`,
+    imageDark: `${base}images/showcase/aurora-polaris-chess-dark.png`,
     imageAlt:
       "Aurora Polaris Chess — browser chess board and controls built with vd3",
     demoUrl: "https://nostromo-618.github.io/aurora-polaris-chess/",
@@ -39,6 +41,7 @@ const projects: ShowcaseProject[] = [
     blurb:
       "An interactive Ikigai purpose map using vd3 plus the CBUN flowchart canvas — rearrange tiles, export PNG/SVG/HTML, read the philosophy, and take the Ikigai-9 quiz. Map data stays in this browser only.",
     image: `${base}images/showcase/ikigai.png`,
+    imageDark: `${base}images/showcase/ikigai-dark.png`,
     imageAlt:
       "Ikigai — interactive purpose map powered by vd3 and vd3-cbun flowchart",
     demoUrl: "https://nostromo-618.github.io/ikigai/",
@@ -79,6 +82,7 @@ const projects: ShowcaseProject[] = [
         :icon="project.icon"
         :blurb="project.blurb"
         :image-src="project.image"
+        :image-src-dark="project.imageDark"
         :image-alt="project.imageAlt"
         :demo-url="project.demoUrl"
         :repo-url="project.repoUrl"

vite.config.ts

@@ -11,11 +11,11 @@ const APP_VERSION = JSON.parse(
 ).version as string;
 
 export default defineConfig({
-  // Base path. Defaults to "/" so local dev, `pnpm run preview`, and the
-  // Playwright suites all serve from the root (route paths like `/about` work
-  // unchanged). The GitHub Pages deploy builds a project-page site under
-  // `/vd3-docs/`, so `deploy.yml` sets `VITE_BASE=/vd3-docs/`. vite-ssg feeds
-  // this to the router history base via `import.meta.env.BASE_URL`.
+  // Base path. Defaults to "/" so local dev, `pnpm run preview`, Playwright,
+  // and the GitHub Pages deploy at https://vd3.vanduo.dev/ all serve from the
+  // root. Override with `VITE_BASE` only when deliberately testing a non-root
+  // project-page layout. vite-ssg feeds this to the router history base via
+  // `import.meta.env.BASE_URL`.
   base: process.env.VITE_BASE ?? "/",
   plugins: [vue()],
   define: {