From f417223df268278eaf8b4021fa6bd8b9ad94f065 Mon Sep 17 00:00:00 2001
From: Nahiyan Khan <nahiyan@squareup.com>
Date: Wed, 9 Sep 2026 00:28:59 -0400
Subject: [PATCH] Fix and validate rendered guidance examples

---
 apps/docs/src/data/guidance-examples.ts   | 58 ++++++++++++++++++++++
 apps/docs/src/pages/index.astro           | 59 +----------------------
 packages/ghost/test/docs-examples.test.ts | 11 +++++
 3 files changed, 70 insertions(+), 58 deletions(-)
 create mode 100644 apps/docs/src/data/guidance-examples.ts
 create mode 100644 packages/ghost/test/docs-examples.test.ts

diff --git a/apps/docs/src/data/guidance-examples.ts b/apps/docs/src/data/guidance-examples.ts
new file mode 100644
index 00000000..4da6153a
--- /dev/null
+++ b/apps/docs/src/data/guidance-examples.ts
@@ -0,0 +1,58 @@
+export const guidanceExamples = [
+  {
+    label: "visual decision",
+    path: "pattern.crop-with-intent.md",
+    body: `---
+for: Photography. Gather when a composition uses a photo.
+materials:
+  - brand/photography/portrait.jpg
+---
+
+# Crop with intent
+
+Crop around one clear subject. Let the subject meet at least one edge.
+
+Reject cautious full-object framing and collages that avoid choosing a focal point.`,
+    palette: [],
+  },
+  {
+    label: "product pattern",
+    path: "condition.blocked-progress.md",
+    body: `---
+for: Blocked progress. Gather when someone cannot continue a task.
+materials:
+  - src/components/error-state/index.tsx
+---
+
+# Keep a path forward
+
+Keep the explanation and one next action together.
+
+If the person cannot resolve the problem, state what happens next. Do not end on a disabled control.`,
+    palette: [],
+  },
+  {
+    label: "exact material",
+    path: "asset.color-roles.md",
+    body: `---
+for: Exact color roles and values. Gather before assigning color.
+materials:
+  - src/styles/brand-tokens.css
+---
+
+# Color roles
+
+Ink carries content. Signal marks selection. Correction marks review.
+
+\`\`\`css
+--ink: #171714;
+--signal: #e8df55;
+--correction: #c83e36;
+\`\`\``,
+    palette: [
+      ["ink", "#171714"],
+      ["signal", "#e8df55"],
+      ["correction", "#c83e36"],
+    ],
+  },
+] as const;
diff --git a/apps/docs/src/pages/index.astro b/apps/docs/src/pages/index.astro
index 4ad44d2b..b32cdf88 100644
--- a/apps/docs/src/pages/index.astro
+++ b/apps/docs/src/pages/index.astro
@@ -3,6 +3,7 @@ import DocSection from "@/components/DocSection.astro";
 import { GatherDemo } from "@/components/docs/gather-demo";
 import Hero from "@/components/Hero.astro";
 import SectionWrapper from "@/components/SectionWrapper.astro";
+import { guidanceExamples } from "@/data/guidance-examples";
 import Base from "@/layouts/Base.astro";
 const fragments = [
   ["product", "components, tokens, interaction patterns, UI copy"],
@@ -39,64 +40,6 @@ const steeringDiagnoses = [
   },
 ] as const;
 
-const guidanceExamples = [
-  {
-    label: "visual decision",
-    path: "pattern.crop-with-intent.md",
-    body: `---
-for: Photography. Gather when a composition uses a photo.
-materials:
-  - brand/photography/**
----
-
-# Crop with intent
-
-Crop around one clear subject. Let the subject meet at least one edge.
-
-Reject cautious full-object framing and collages that avoid choosing a focal point.`,
-    palette: [],
-  },
-  {
-    label: "product pattern",
-    path: "condition.blocked-progress.md",
-    body: `---
-for: Blocked progress. Gather when someone cannot continue a task.
-materials:
-  - src/components/error-state/**
----
-
-# Keep a path forward
-
-Keep the explanation and one next action together.
-
-If the person cannot resolve the problem, state what happens next. Do not end on a disabled control.`,
-    palette: [],
-  },
-  {
-    label: "exact material",
-    path: "asset.color-roles.md",
-    body: `---
-for: Exact color roles and values. Gather before assigning color.
-materials:
-  - src/styles/brand-tokens.css
----
-
-# Color roles
-
-Ink carries content. Signal marks selection. Correction marks review.
-
-\`\`\`css
---ink: #171714;
---signal: #e8df55;
---correction: #c83e36;
-\`\`\``,
-    palette: [
-      ["ink", "#171714"],
-      ["signal", "#e8df55"],
-      ["correction", "#c83e36"],
-    ],
-  },
-] as const;
 
 ---
 
diff --git a/packages/ghost/test/docs-examples.test.ts b/packages/ghost/test/docs-examples.test.ts
new file mode 100644
index 00000000..a14e051f
--- /dev/null
+++ b/packages/ghost/test/docs-examples.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { guidanceExamples } from "../../../apps/docs/src/data/guidance-examples.js";
+import { parseNode } from "../src/ghost-core/node/parse.js";
+
+describe("rendered docs guidance examples", () => {
+  it.each(guidanceExamples)("$path parses without errors", ({ body }) => {
+    const { node, report } = parseNode(body);
+    expect(report.errors, JSON.stringify(report.issues)).toBe(0);
+    expect(node).not.toBeNull();
+  });
+});