create-ailk 0.7.0 → 0.9.0

package/templates/apps/web/lib/__tests__/site-theme.test.ts

@@ -20,16 +20,21 @@
  * true of any declared palette. Deleting the `theme:` block still fails, on the
  * `toBeDefined()` below.
  */
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 
-import { PartialColorPaletteSchema } from "@working-theory/site-config/schema";
-import { siteColorTokenMap, themeToCssVarsBothModes } from "@working-theory/theme";
+import { PartialColorPaletteSchema, SiteThemeSchema } from "@working-theory/site-config/schema";
+import {
+  siteColorTokenMap,
+  siteThemeShapeCss,
+  siteThemeToBrandTokens,
+  themeToCssVarsBothModes,
+} from "@working-theory/theme";
 
-import { loadSiteBrandTokens } from "../site-theme";
+import { loadSiteBrandTokens, loadSiteShapeCss } from "../site-theme";
 
 const REPO_CONTENT_ROOT = join(__dirname, "..", "..", "..", "..", "content");
 
@@ -46,19 +51,28 @@ function darkBlock(css: string): string {
 /** The two modes, as the palette and the emitted CSS both name them. */
 const MODES = ["light", "dark"] as const;
 
+type ModeColors = Partial<Record<(typeof MODES)[number], Record<string, string>>>;
+
 /**
- * The `theme.colors` block exactly as the `_site.mdx` under test declares it —
- * raw SLOT names (`text`, `primary`), not token keys. Read with the same
+ * The colours the `_site.mdx` under test declares — `theme.colors` with any
+ * `brand.colors` (the brand triad, #6820) layered over it per mode — as raw
+ * SLOT names (`text`, `primary`), not token keys. Read with the same
  * frontmatter parse `site-theme.ts` uses, so the test cannot pass against a
- * file the implementation reads differently.
+ * file the implementation reads differently, and derived from the layered
+ * result so a scaffold whose owner sets a triad stays green.
  */
-function declaredColors(): Partial<Record<(typeof MODES)[number], Record<string, string>>> {
+function declaredColors(): ModeColors {
   const raw = readFileSync(join(REPO_CONTENT_ROOT, "_site.mdx"), "utf8");
   const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
   const parsed = parseYaml(frontmatter?.[1] ?? "") as
-    | { theme?: { colors?: Record<string, Record<string, string>> } }
+    | { theme?: { colors?: ModeColors }; brand?: { colors?: ModeColors } }
     | null;
-  return parsed?.theme?.colors ?? {};
+  const out: ModeColors = {};
+  for (const mode of MODES) {
+    const layered = { ...parsed?.theme?.colors?.[mode], ...parsed?.brand?.colors?.[mode] };
+    if (Object.keys(layered).length > 0) out[mode] = layered;
+  }
+  return out;
 }
 
 /**
@@ -210,6 +224,85 @@ describe("loadSiteBrandTokens — the real content/_site.mdx", () => {
   });
 });
 
+/**
+ * The brand triad (#6820) — `brand.colors` / `brand.fonts` layered over the
+ * theme. The golden: a site with a theme and no triad emits exactly the CSS
+ * the pre-triad formula emitted; a site with a triad carries its fonts and
+ * primary into both mode blocks.
+ */
+describe("loadSiteBrandTokens — the brand triad", () => {
+  const originalRoot = process.env.AILK_CONTENT_ROOT;
+  const tempRoots: string[] = [];
+
+  afterEach(() => {
+    if (originalRoot === undefined) delete process.env.AILK_CONTENT_ROOT;
+    else process.env.AILK_CONTENT_ROOT = originalRoot;
+    for (const root of tempRoots.splice(0)) rmSync(root, { recursive: true, force: true });
+  });
+
+  /** The repo's own `theme:` block, as YAML text and as parsed. */
+  function repoTheme(): { yaml: string; parsed: unknown } {
+    const raw = readFileSync(join(REPO_CONTENT_ROOT, "_site.mdx"), "utf8");
+    const parsed = (
+      parseYaml(/^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)?.[1] ?? "") as { theme?: unknown }
+    ).theme;
+    return { yaml: stringifyYaml({ theme: parsed }), parsed };
+  }
+
+  function useSiteMdx(frontmatter: string): void {
+    const root = mkdtempSync(join(tmpdir(), "ailk-site-triad-"));
+    tempRoots.push(root);
+    writeFileSync(join(root, "_site.mdx"), `---\nsiteName: Test\n${frontmatter}---\n`, "utf8");
+    process.env.AILK_CONTENT_ROOT = root;
+  }
+
+  /** The layout's emission, verbatim (`app/[locale]/layout.tsx`). */
+  function layoutCss(): string {
+    const brand = loadSiteBrandTokens();
+    return themeToCssVarsBothModes(brand ? { brand } : {}) + loadSiteShapeCss();
+  }
+
+  it("golden: the repo's theme with no triad emits the pre-triad CSS byte for byte", () => {
+    const { yaml, parsed } = repoTheme();
+    useSiteMdx(`${yaml}brand:\n  logomark: { light: /logomark.svg, dark: /logomark.svg, alt: Test }\n`);
+
+    const theme = SiteThemeSchema.parse(parsed);
+    const before = siteThemeToBrandTokens(theme);
+    expect(layoutCss()).toBe(
+      themeToCssVarsBothModes(before ? { brand: before } : {}) + siteThemeShapeCss(theme),
+    );
+  });
+
+  it("golden: no _site.mdx emits the default CSS", () => {
+    process.env.AILK_CONTENT_ROOT = join(__dirname, "no-such-content-root");
+    expect(layoutCss()).toBe(themeToCssVarsBothModes({}));
+  });
+
+  it("a declared triad reaches --font-display / --font-body and --color-brand in both blocks", () => {
+    const { yaml } = repoTheme();
+    useSiteMdx(
+      `${yaml}brand:\n` +
+        `  colors:\n    light: { primary: "#0a3d62" }\n    dark: { primary: "#82ccdd" }\n` +
+        `  fonts:\n    display: "'Fraunces', Georgia, serif"\n    body: "Inter, sans-serif"\n`,
+    );
+
+    const css = layoutCss();
+    for (const [mode, block] of [
+      ["light", lightBlock(css)],
+      ["dark", darkBlock(css)],
+    ] as const) {
+      expect(block).toContain("--font-display: 'Fraunces', Georgia, serif;");
+      expect(block).toContain("--font-body: Inter, sans-serif;");
+      expect(block).toContain(`--color-brand: ${mode === "light" ? "#0a3d62" : "#82ccdd"};`);
+    }
+  });
+
+  it("refuses an unknown brand key by name", () => {
+    useSiteMdx("brand:\n  corners: square\n");
+    expect(() => loadSiteBrandTokens()).toThrow(/corners/);
+  });
+});
+
 /**
  * The twelve customer-facing colour slots live in `@working-theory/site-config`
  * and the map from them to token names lives in `@working-theory/theme`;

package/templates/apps/web/lib/__tests__/structured-data.test.tsx

@@ -53,6 +53,8 @@ import {
   type SchemaOrgType,
   type ValidationError,
 } from "@working-theory/schema-validator";
+
+import { MEET_PLACEHOLDER_HUB } from "../meet-placeholder";
 import type { ReactElement } from "react";
 import { parse as parseYaml } from "yaml";
 
@@ -447,19 +449,31 @@ function routeIdentity(
 
 type PageModule = {
   default: (props: {
-    params: Promise<{ locale: string; slug?: string }>;
+    params: Promise<{ locale: string; slug?: string; detail?: string }>;
   }) => Promise<ReactElement>;
 };
 
 async function renderRoute(
   file: string,
+  route: string,
   slug: string | undefined,
 ): Promise<HTMLElement> {
   // Resolved at test time from the walk above — a static import would dangle
   // in a scaffold that gated the surface off.
   const mod = require(file) as PageModule;
-  const params: { locale: string; slug?: string } = { locale: DEFAULT_LOCALE };
-  if (slug !== undefined) params.slug = slug;
+  const params: { locale: string; slug?: string; detail?: string } = {
+    locale: DEFAULT_LOCALE,
+  };
+  // #6897 D2 — params are built from the route's OWN dynamic segments: the
+  // `[slug]/[detail]` placeholder route's `slug` param is fixed to the meet
+  // hub, and its content slug rides `detail` instead — never a copied
+  // literal for the hub name.
+  if (route === "[slug]/[detail]") {
+    params.slug = MEET_PLACEHOLDER_HUB;
+    if (slug !== undefined) params.detail = slug;
+  } else if (slug !== undefined) {
+    params.slug = slug;
+  }
   const element = await mod.default({ params: Promise.resolve(params) });
   return render(element).container;
 }
@@ -531,12 +545,15 @@ describe("structured data — every route emits a valid JSON-LD script", () => {
     for (const slug of slugs) {
       const container = await renderRoute(
         file,
+        route,
         identity.slug === null ? slug : undefined,
       );
       const blocks = extractJsonLdBlocks(container);
       const pageLabel =
         identity.slug === null
-          ? `${label.replace(/\[slug\]$/, "")}${slug}`
+          ? route === "[slug]/[detail]"
+            ? `/${DEFAULT_LOCALE}/${MEET_PLACEHOLDER_HUB}/${slug}`
+            : `${label.replace(/\[slug\]$/, "")}${slug}`
           : label;
       if (blocks.length === 0) {
         failures.push(

package/templates/apps/web/lib/locale-guard.ts

@@ -0,0 +1,18 @@
+/**
+ * The `[locale]` layout's first check (#6107 F5).
+ *
+ * A dotted path that is not a file — the `/.well-known` directory, `/foo.bar`
+ * — skips the middleware matcher and reaches `app/[locale]` with that segment
+ * as `locale`. Anything outside the enabled-locale list (the same list the
+ * footer switcher offers) is a 404, not the whole site rendered under a bogus
+ * locale.
+ */
+import { readLocales } from "@working-theory/web-i18n";
+import { notFound } from "next/navigation";
+
+export function assertEnabledLocale(
+  locale: string,
+  locales: readonly string[] = readLocales(),
+): void {
+  if (!locales.includes(locale)) notFound();
+}

package/templates/apps/web/lib/meet-placeholder.ts

@@ -0,0 +1,5 @@
+// The Free `/meet/<slug>` placeholder hub (#6897 D2). `MEET_PLACEHOLDER_HUB`
+// is the one fixed top-level slug the `[slug]/[detail]` route answers under —
+// never a copied literal, so the route and the structured-data walk
+// (`apps/web/lib/__tests__/structured-data.test.tsx`) can never drift.
+export const MEET_PLACEHOLDER_HUB = "meet";

package/templates/apps/web/lib/nav-config.ts

@@ -1,30 +1,14 @@
-// nav-config.ts — Nav item registry for apps/web (#1451, re-shaped by #5469,
-// #6508).
+// nav-config.ts — site-nav registry.
 //
-// The Free marketing-site template's nav (the approved chrome, #5469 D5,
-// #6508 D5): a Product flyout (How it works · Features · FAQ) rendered as a
-// fixed-640px two-column panel (the Standard Issue direction — #6508), then
-// How it works, Pricing and About as top-level items. Paths are
-// locale-agnostic; Nav prefixes them with the active locale at render.
-// `footerColumns` carries the footer's column groups (#6468), keys only — the
-// layout resolves the labels.
+// GENERATED by create-ailk from the declared route surfaces. Every entry here
+// points at a route this site actually carries — the nav is regenerated with
+// the surface set so it can never link a page that was not scaffolded.
 //
-// In a SCAFFOLD this file is regenerated by create-ailk from the declared
-// route surfaces (`renderNavConfig` in packages/create-ailk/src/surfaces.ts)
-// so the nav never links a page the scaffold does not carry — keep the two in
-// step when the base item set changes.
-//
-// SOFT_LOCK_OK: #6508 — Product's flyout is `width: "panel"` (D4/D5): a fixed
-// 640px, two-column grid, replacing the prior "list"/"trigger" one-column
-// menu. `presentation` is omitted — it defaults to "grid" (D5). The `docs`
-// action is dropped (it duplicated the first feature's /how-it-works
-// destination, § 1.4). This note lives here, not inside the `navItems` array
-// below, so this file's `navItems`/`footerColumns` blocks stay byte-identical
-// to `renderNavConfig`'s generated output — the mirror test (#6468) diffs the
-// arrays verbatim.
-
+// Adding a link: scaffold the page (the `add-page` skill), then add an
+// entry below with a `labelKey` that exists in the `nav` namespace of
+// `apps/web/messages/<locale>.json`. Paths are locale-agnostic — Nav prefixes
+// them with the active locale at render.
 import type { NavItem } from "@working-theory/ui";
-import { HelpCircle, Layers, Sparkles } from "lucide-react";
 
 export const navItems: NavItem[] = [
   {
@@ -32,19 +16,41 @@ export const navItems: NavItem[] = [
     flyout: {
       width: "panel",
       features: [
-        { labelKey: "useCases", descKey: "useCasesDesc", icon: Layers, path: "/use-cases" },
-        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/software/product" },
-        { labelKey: "faq", descKey: "faqDesc", icon: HelpCircle, path: "/faq" },
+        { labelKey: "feature1", path: "/features/feature-1" },
+        { labelKey: "feature2", path: "/features/feature-2" },
+        { labelKey: "feature3", path: "/features/feature-3" },
+        { labelKey: "customer1", path: "/for/persona-1" },
+        { labelKey: "customer2", path: "/for/persona-2" },
+        { labelKey: "customer3", path: "/for/persona-3" },
+      ],
+      groups: [
+        {
+          headingKey: "flyoutFeaturesHeading",
+          items: [
+            { labelKey: "feature1", path: "/features/feature-1" },
+            { labelKey: "feature2", path: "/features/feature-2" },
+            { labelKey: "feature3", path: "/features/feature-3" },
+          ],
+        },
+        {
+          headingKey: "flyoutCustomersHeading",
+          items: [
+            { labelKey: "customer1", path: "/for/persona-1" },
+            { labelKey: "customer2", path: "/for/persona-2" },
+            { labelKey: "customer3", path: "/for/persona-3" },
+          ],
+        },
       ],
       actions: [],
     },
   },
-  { labelKey: "useCases", path: "/use-cases" },
   { labelKey: "blog", path: "/blog" },
   { labelKey: "pricing", path: "/pricing" },
   { labelKey: "about", path: "/about" },
 ];
 
+// Footer column groups. Keys only — the layout resolves each `headingKey`
+// and `labelKey` through the same `nav` labels as the header.
 export interface FooterColumnConfig {
   headingKey: string;
   items: { labelKey: string; path: string }[];
@@ -54,23 +60,30 @@ export const footerColumns: FooterColumnConfig[] = [
   {
     headingKey: "footerSitePagesHeading",
     items: [
-      { labelKey: "features", path: "/software/product" },
+      { labelKey: "features", path: "/features" },
       { labelKey: "pricing", path: "/pricing" },
-      { labelKey: "useCases", path: "/use-cases" },
+      { labelKey: "portfolio", path: "/portfolio" },
       { labelKey: "about", path: "/about" },
       { labelKey: "contact", path: "/contact" },
-      { labelKey: "bookACall", path: "/book-a-call" },
+      { labelKey: "bookACall", path: "/meet/book-a-call" },
     ],
   },
   {
     headingKey: "footerFeaturesHeading",
     items: [
-      { labelKey: "feature1", path: "/software/product" },
-      { labelKey: "feature2", path: "/software/product" },
-      { labelKey: "feature3", path: "/software/product" },
-      { labelKey: "feature4", path: "/software/product" },
-      { labelKey: "feature5", path: "/software/product" },
-      { labelKey: "allFeatures", path: "/software/product" },
+      { labelKey: "feature1", path: "/features/feature-1" },
+      { labelKey: "feature2", path: "/features/feature-2" },
+      { labelKey: "feature3", path: "/features/feature-3" },
+      { labelKey: "allFeatures", path: "/features" },
+    ],
+  },
+  {
+    headingKey: "footerCustomersHeading",
+    items: [
+      { labelKey: "customer1", path: "/for/persona-1" },
+      { labelKey: "customer2", path: "/for/persona-2" },
+      { labelKey: "customer3", path: "/for/persona-3" },
+      { labelKey: "allCustomers", path: "/for" },
     ],
   },
   {

package/templates/apps/web/lib/site-brand.tsx

@@ -20,7 +20,7 @@
  * rather than a dependency on `@working-theory/site-config`'s `loadSiteConfig`
  * (`packages/site-config/src/server/load.ts`): that package is async (this
  * module's exports are plain constants, read at many synchronous call
- * sites — Nav/Footer props, `siteLogo()`, edge-safe route defaults) and
+ * sites — Nav/Footer props, the raw logomark `siteLogo()` in `site-logo.tsx` renders, edge-safe route defaults) and
  * brings gray-matter + Zod validation + optimistic-locking writes built for
  * the agent-operator editing workflow — disproportionate for reading two
  * fields. See docs/specs/4157-scaffold-brand-defaults-spec.md § Design
@@ -30,7 +30,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ReactElement } from "react";
 import { parse as parseYaml } from "yaml";
 
 /** Neutral, non-vendor fallback — see module doc comment point 3. */
@@ -46,6 +45,8 @@ interface SiteFrontmatter {
   // `undefined` (a plain `?: string` would forbid that explicit assignment).
   siteName?: string | undefined;
   baseUrl?: string | undefined;
+  /** `brand.logomark`, raw — validated by `siteLogo()` when it renders. */
+  logomark?: unknown;
 }
 
 /**
@@ -83,10 +84,14 @@ function readSiteFrontmatter(): SiteFrontmatter | null {
     const parsed: unknown = parseYaml(match[1] ?? "");
     if (!parsed || typeof parsed !== "object") return null;
 
-    const { siteName, baseUrl } = parsed as Record<string, unknown>;
+    const { siteName, baseUrl, brand } = parsed as Record<string, unknown>;
     return {
       siteName: typeof siteName === "string" ? siteName : undefined,
       baseUrl: typeof baseUrl === "string" ? baseUrl : undefined,
+      logomark:
+        brand && typeof brand === "object"
+          ? ((brand as Record<string, unknown>).logomark ?? undefined)
+          : undefined,
     };
   } catch {
     return null;
@@ -108,10 +113,9 @@ export const SITE_BASE_URL =
   process.env.NEXT_PUBLIC_BASE_URL ?? siteFrontmatter?.baseUrl ?? FALLBACK_BASE_URL;
 
 /**
- * Shared brand mark — the square logomark (the central brand library's
- * `logomark/loop/tile-black.svg`). The Nav pairs it with `/wordmark.svg`.
- * RSC-safe (no hooks, no client state).
+ * The raw `brand.logomark` from `_site.mdx`, or `undefined` when none is
+ * declared. Unvalidated: `siteLogo()` (`site-logo.tsx`) parses it on the
+ * render that uses it, so a malformed mark never breaks `SITE_NAME` /
+ * `SITE_BASE_URL` for the routes that read only those.
  */
-export function siteLogo(): ReactElement {
-  return <img src="/logomark.svg" alt={SITE_NAME} width={28} height={28} className="block" />;
-}
+export const SITE_LOGOMARK: unknown = siteFrontmatter?.logomark;

package/templates/apps/web/lib/site-identity.ts

@@ -85,6 +85,20 @@ function readFeatureList(contentRoot: string, locale: string): string[] {
     const frontmatter = readFrontmatter(join(productDir, name));
     if (frontmatter !== undefined) return featuresOf(frontmatter);
   }
+  // #6721 — the Free roster's feature PAGES (one `Feature` seed per feature,
+  // #6721) are the featureList when the site carries no product page: each
+  // page's title, in sorted file order.
+  const featureDir = join(contentRoot, locale, "Feature");
+  try {
+    const titles = readdirSync(featureDir)
+      .filter((name) => name.endsWith(".mdx"))
+      .sort()
+      .map((name) => readFrontmatter(join(featureDir, name))?.["title"])
+      .filter((title): title is string => typeof title === "string" && title.length > 0);
+    if (titles.length > 0) return titles;
+  } catch {
+    // No Feature directory — fall through to the legacy probe.
+  }
   let typeDirs: string[];
   try {
     typeDirs = readdirSync(join(contentRoot, locale)).sort();

package/templates/apps/web/lib/site-logo.tsx

@@ -0,0 +1,36 @@
+/**
+ * Site logo — the site's declared `brand.logomark` (#6820), else the square
+ * logomark (the central brand library's `logomark/loop/tile-black.svg`).
+ *
+ * Split from `site-brand.tsx`, which ten route and lib modules import for
+ * `SITE_NAME` / `SITE_BASE_URL`: the mark needs `@working-theory/ui`'s
+ * `Image` and site-config's schema, and those stay out of that wider graph
+ * (spec #6820 § 5.4). The two layouts are the only callers.
+ */
+
+import { BrandLogomarkSchema } from "@working-theory/site-config/schema";
+import { Image } from "@working-theory/ui/primitives";
+import type { ReactElement } from "react";
+
+import { SITE_LOGOMARK, SITE_NAME } from "./site-brand";
+
+/**
+ * Shared brand mark. The Nav pairs it with `/wordmark.svg`. RSC-safe (no
+ * hooks, no client state).
+ *
+ * The logomark is validated here, on the render that uses it, not at module
+ * init: a malformed mark throws naming the field while `SITE_NAME` /
+ * `SITE_BASE_URL` stay readable by the routes that need only them. A mark
+ * whose dark source differs renders through the `Image` primitive's
+ * `darkSrc` swap, so the dark mark is not dropped.
+ */
+export function siteLogo(): ReactElement {
+  if (SITE_LOGOMARK === undefined) {
+    return <img src="/logomark.svg" alt={SITE_NAME} width={28} height={28} className="block" />;
+  }
+  const { light, dark, alt } = BrandLogomarkSchema.parse(SITE_LOGOMARK);
+  if (light === dark) {
+    return <img src={light} alt={alt} width={28} height={28} className="block" />;
+  }
+  return <Image src={light} darkSrc={dark} alt={alt} width={28} height={28} />;
+}

package/templates/apps/web/lib/site-theme.ts

@@ -15,21 +15,26 @@
  * The translation itself lives in `@working-theory/theme`
  * (`siteThemeToBrandTokens`) — the token vocabulary is that package's own.
  *
- * Returns `undefined` when the site declares no theme, so the layout passes
- * no `brand` at all and the resolver emits byte-for-byte the CSS it emitted
- * before this wiring existed.
+ * The brand triad (#6820) — `brand.colors` and `brand.fonts`, a sibling of
+ * `theme:` that applying a design never rewrites — is read in the same parse
+ * and layered over the theme by `siteBrandToBrandTokens`.
+ *
+ * Returns `undefined` when the site declares no theme and no triad, so the
+ * layout passes no `brand` at all and the resolver emits byte-for-byte the
+ * CSS it emitted before this wiring existed.
  */
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { SiteThemeSchema } from "@working-theory/site-config/schema";
+import { BrandSchema, SiteThemeSchema } from "@working-theory/site-config/schema";
 import {
+  siteBrandToBrandTokens,
   siteThemeShapeCss,
-  siteThemeToBrandTokens,
   type BrandTokenOverrides,
 } from "@working-theory/theme";
 import { parse as parseYaml } from "yaml";
+import { z } from "zod";
 
 import { resolveContentRoot } from "./site-brand";
 
@@ -38,40 +43,55 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
 const SOURCE = "content/_site.mdx theme";
 
 /**
- * The `theme:` value as it appears in the frontmatter, or `undefined` when
- * `_site.mdx` is absent, unreadable, or declares no theme. A site with no
- * readable config has no theme to apply, and the default palette is the
- * correct result — the same fallback `site-brand.tsx` takes.
+ * `brand:` as this loader validates it: every key checked by name, but the
+ * `logomark` left to `siteLogo()` (`site-brand.tsx`), which parses it on the
+ * render that uses it — one throw site per field.
+ */
+const BrandTriadSchema = BrandSchema.extend({
+  logomark: z.unknown().optional(),
+}).strict();
+
+/**
+ * The `theme:` and `brand:` values as they appear in the frontmatter, each
+ * `undefined` when `_site.mdx` is absent, unreadable, or does not declare it.
+ * A site with no readable config has no theme to apply, and the default
+ * palette is the correct result — the same fallback `site-brand.tsx` takes.
  *
- * "Declares no theme" covers a bare `theme:` key with nothing under it, which
- * YAML parses to `null`. That is the shape the most natural edit produces —
- * commenting out the block's children leaves the key dangling — and it means
- * exactly what an absent key means, so it takes the same path rather than
- * reaching the schema and throwing out of a Server Component.
+ * "Does not declare it" covers a bare `theme:` key with nothing under it,
+ * which YAML parses to `null`. That is the shape the most natural edit
+ * produces — commenting out the block's children leaves the key dangling —
+ * and it means exactly what an absent key means, so it takes the same path
+ * rather than reaching the schema and throwing out of a Server Component.
  */
-function readThemeBlock(): unknown {
+function readSiteBlocks(): { theme: unknown; brand: unknown } {
   try {
     const raw = readFileSync(join(resolveContentRoot(), "_site.mdx"), "utf8");
     const match = FRONTMATTER_RE.exec(raw);
-    if (!match) return undefined;
+    if (!match) return { theme: undefined, brand: undefined };
 
     const parsed: unknown = parseYaml(match[1] ?? "");
-    if (!parsed || typeof parsed !== "object") return undefined;
+    if (!parsed || typeof parsed !== "object") {
+      return { theme: undefined, brand: undefined };
+    }
 
-    return (parsed as Record<string, unknown>).theme ?? undefined;
+    const { theme, brand } = parsed as Record<string, unknown>;
+    return { theme: theme ?? undefined, brand: brand ?? undefined };
   } catch {
-    return undefined;
+    return { theme: undefined, brand: undefined };
   }
 }
 
 export function loadSiteBrandTokens(): BrandTokenOverrides | undefined {
-  const block = readThemeBlock();
-  if (block === undefined) return undefined;
+  const blocks = readSiteBlocks();
+  if (blocks.theme === undefined && blocks.brand === undefined) return undefined;
 
   // Validation failures and unsupported colours BOTH throw, deliberately: a
   // customer who set a colour and saw no change would have been lied to.
-  const theme = SiteThemeSchema.parse(block);
-  return siteThemeToBrandTokens(theme, SOURCE);
+  const theme =
+    blocks.theme === undefined ? undefined : SiteThemeSchema.parse(blocks.theme);
+  const brand =
+    blocks.brand === undefined ? undefined : BrandTriadSchema.parse(blocks.brand);
+  return siteBrandToBrandTokens(theme, brand, SOURCE);
 }
 
 /**
@@ -79,7 +99,7 @@ export function loadSiteBrandTokens(): BrandTokenOverrides | undefined {
  * override block for `:root`. "" when the site sets neither.
  */
 export function loadSiteShapeCss(): string {
-  const block = readThemeBlock();
-  if (block === undefined) return "";
-  return siteThemeShapeCss(SiteThemeSchema.parse(block));
+  const { theme } = readSiteBlocks();
+  if (theme === undefined) return "";
+  return siteThemeShapeCss(SiteThemeSchema.parse(theme));
 }