From 9f1af5560246d31650d9be7a407938b46f9a104a Mon Sep 17 00:00:00 2001
From: Jim Myhrberg <contact@jimeh.me>
Date: Sun, 11 Jan 2026 01:53:24 +0000
Subject: [PATCH] refactor(spec): move spec page rendering to dedicated layout

---
 CLAUDE.md                                     | 27 +++++++++++++++++--
 .../SpecLayout.astro}                         | 14 +++++-----
 src/pages/index.astro                         |  4 +--
 src/pages/spec/[version].astro                |  4 +--
 4 files changed, 36 insertions(+), 13 deletions(-)
 rename src/{components/SpecPage.astro => layouts/SpecLayout.astro} (76%)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1c4d347..652ece4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,6 +27,16 @@ bun run build
 # Preview built site
 bun run preview
 
+# Type checking
+bun run check
+
+# Linting
+bun run lint
+
+# Formatting
+bun run format
+bun run format:check
+
 # Update specs from upstream (fetches from github.com/jimeh/common-flow)
 bun run update
 ```
@@ -45,9 +55,22 @@ The site is built to `docs/` for GitHub Pages hosting.
 
 - `src/config.ts` - Site configuration with version list
 - `src/content.config.ts` - Astro content collection definition
-- `src/layouts/Default.astro` - Main layout with sidebar
-- `src/components/` - Sidebar, MenuToggle, ThemeToggle components
+- `src/layouts/BaseLayout.astro` - Base layout with head, meta tags, theme scripts
+- `src/layouts/SpecLayout.astro` - Spec page layout composing all sections
+- `src/components/` - UI components:
+  - `Header.astro` - Site header with navigation
+  - `Footer.astro` - Site footer
+  - `Hero.astro` - Landing page hero section
+  - `AboutSection.astro` - About Common-Flow section
+  - `FAQSection.astro` - FAQ section
+  - `SpecSection.astro` - Individual spec section renderer
+  - `SpecSidebar.astro` - Spec page table of contents sidebar
+  - `ThemeToggle.astro` - Dark/light mode toggle
+  - `VersionSelector.astro` - Spec version dropdown
+- `src/pages/index.astro` - Landing page
+- `src/pages/404.astro` - 404 error page
 - `src/pages/spec/[version].astro` - Dynamic route for spec versions
+- `src/utils/parseSpecContent.ts` - Markdown parsing utilities
 - `src/content/spec/*.md` - Versioned spec documents
 - `public/spec/*.svg` - SVG diagrams for each version
 - `scripts/update-specs.ts` - Fetches specs from GitHub
diff --git a/src/components/SpecPage.astro b/src/layouts/SpecLayout.astro
similarity index 76%
rename from src/components/SpecPage.astro
rename to src/layouts/SpecLayout.astro
index bc6793a..5f3d2a0 100644
--- a/src/components/SpecPage.astro
+++ b/src/layouts/SpecLayout.astro
@@ -3,13 +3,13 @@ import type { CollectionEntry } from "astro:content";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import BaseLayout from "../layouts/BaseLayout.astro";
-import Header from "./Header.astro";
-import Hero from "./Hero.astro";
-import AboutSection from "./AboutSection.astro";
-import SpecSection from "./SpecSection.astro";
-import FAQSection from "./FAQSection.astro";
-import Footer from "./Footer.astro";
+import BaseLayout from "./BaseLayout.astro";
+import Header from "../components/Header.astro";
+import Hero from "../components/Hero.astro";
+import AboutSection from "../components/AboutSection.astro";
+import SpecSection from "../components/SpecSection.astro";
+import FAQSection from "../components/FAQSection.astro";
+import Footer from "../components/Footer.astro";
 import { parseSpecContent } from "../utils/parseSpecContent";
 
 interface Props {
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 77c9531..0603fd1 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -1,7 +1,7 @@
 ---
 import { getCollection } from "astro:content";
 
-import SpecPage from "../components/SpecPage.astro";
+import SpecLayout from "../layouts/SpecLayout.astro";
 import { config } from "../config";
 
 // Render the current/latest version
@@ -14,4 +14,4 @@ if (!spec) {
 }
 ---
 
-<SpecPage spec={spec} />
+<SpecLayout spec={spec} />
diff --git a/src/pages/spec/[version].astro b/src/pages/spec/[version].astro
index 65c67bd..007d9eb 100644
--- a/src/pages/spec/[version].astro
+++ b/src/pages/spec/[version].astro
@@ -1,7 +1,7 @@
 ---
 import { getCollection } from "astro:content";
 
-import SpecPage from "../../components/SpecPage.astro";
+import SpecLayout from "../../layouts/SpecLayout.astro";
 
 export async function getStaticPaths() {
   const specs = await getCollection("spec");
@@ -14,4 +14,4 @@ export async function getStaticPaths() {
 const { spec } = Astro.props;
 ---
 
-<SpecPage spec={spec} />
+<SpecLayout spec={spec} />