From 3c06a55415b0f98aa5982d8e0f56dc59138716bb Mon Sep 17 00:00:00 2001
From: Damian Reeves <957246+DamianReeves@users.noreply.github.com>
Date: Wed, 28 Oct 2026 03:29:24 -0500
Subject: [PATCH] docs(site): adopt the Morphir MoonBit design

---
 NOTICE                                        |   4 +
 docs/site-foundation.md                       |  19 ++
 .../add-documentation-site/design.html        |   5 +-
 .../add-documentation-site/proposal.md        |   2 +-
 .../specs/docs/site/spec.md                   |   7 +
 .../changes/add-documentation-site/tasks.md   |   2 +
 scripts/site_tool.py                          |  33 ++++
 site/browser/site.spec.mjs                    |  26 +++
 site/pages/index.html                         |  55 ++++++
 site/pages/index.md                           |  32 ----
 site/theme/README.md                          |  11 ++
 site/theme/morphir.css                        | 175 ++++++++++++++++++
 tests/unit/test_site_tool.py                  |  36 ++++
 13 files changed, 373 insertions(+), 34 deletions(-)
 create mode 100644 site/pages/index.html
 delete mode 100644 site/pages/index.md
 create mode 100644 site/theme/README.md
 create mode 100644 site/theme/morphir.css

diff --git a/NOTICE b/NOTICE
index 1499d7b0..57d47999 100644
--- a/NOTICE
+++ b/NOTICE
@@ -2,3 +2,7 @@ morphir-python - FINOS
 Copyright 2026 - FINOS - info@finos.org
 
 This product includes software developed at the Fintech Open Source Foundation (https://www.finos.org/).
+
+The documentation theme adapts the FINOS morphir-moonbit site design
+from revision bd3adc52e6b8f6368fdaee50f76535799732f8d6, under Apache-2.0.
+See site/theme/README.md for source attribution.
diff --git a/docs/site-foundation.md b/docs/site-foundation.md
index 44cf6d42..7ee8413a 100644
--- a/docs/site-foundation.md
+++ b/docs/site-foundation.md
@@ -38,3 +38,22 @@ Telescope 0.2.1 treats existing files outside discovered roots as missing.
 minimal reproduction and requested source-link contract. Explicit GitHub URLs
 are the current non-blocking workaround; internal published-page links remain
 relative and checked.
+
+## Morphir theme and landing page
+
+The Python site uses the blue/orange palette and responsive landing-page design
+from [morphir-moonbit at bd3adc52](https://github.com/finos/morphir-moonbit/blob/bd3adc52e6b8f6368fdaee50f76535799732f8d6/site/pages/index.html).
+The attributed consumer theme lives in `site/theme/morphir.css`; its README
+records the source revision and digest. The landing model matches the checked
+`examples/model/acme/models.py` source. Browser checks cover both themes, narrow
+and desktop screens, root and project bases, guide navigation and exact colors.
+
+Telescope 0.2.1 has no consumer stylesheet hook. Replacing its reserved
+`assets/site.css` through static resources fails with a duplicate-output error.
+[Telescope issue 13](https://github.com/moonrockz/telescope/issues/13) records the
+reproduction and requested reusable extension. The current consumer build stages
+stock output, appends the theme to its CSS, runs the stock checker on those final
+bytes, then atomically promotes the checked tree. A failed stylesheet check
+preserves the previous output. The site publisher seals those final bytes, so
+there is no styling transformation during deployment. Adopt a published upstream
+stylesheet hook when qualified, replacing this bounded workaround.
diff --git a/openspec/changes/add-documentation-site/design.html b/openspec/changes/add-documentation-site/design.html
index bcbd06aa..52df927b 100644
--- a/openspec/changes/add-documentation-site/design.html
+++ b/openspec/changes/add-documentation-site/design.html
@@ -22,7 +22,7 @@
 <body>
 <main>
 <h1>add-documentation-site</h1>
-<p class="meta">OpenSpec change · Bead <code>morphir-ukvn.9</code> · 2026-10-28 · Implemented, awaiting review</p>
+<p class="meta">OpenSpec change · Bead <code>morphir-ukvn.9</code> · 2026-10-28 · Published foundation; MoonBit visual alignment in progress</p>
 
 <nav class="toc" aria-label="Contents">
 <ul>
@@ -76,6 +76,9 @@ <h3 id="site-1">SITE-1. Consume the published Telescope CLI</h3>
 </code></pre>
 <p>This is a configuration starting point, not the final navigation manifest. Configure exclusions, navigation and static resources using the pinned version's supported contract. Build to <code>_site/</code>; test both <code>/</code> and <code>/morphir-python/</code>. Keep existing guide URLs in the repository useful and add site links to READMEs. Copying MoonBit's renderer would duplicate work now owned by Telescope; a separate Python documentation framework would split that shared foundation.</p>
 
+<h3 id="site-2">SITE-2. Reuse the Morphir MoonBit visual design</h3>
+<p>Use the blue/orange palette and responsive hero, code window, pipeline and feature cards from morphir-moonbit bd3adc52, adapting only the Python content and guide links. Keep the attributed CSS in site/theme/morphir.css and bridge Telescope shell variables to the same palette. The hero model is the checked examples/model/acme/models.py source; browser checks compare the displayed text and exercise both themes, viewports and deployment bases.</p>
+<p>Telescope 0.2.1 has no consumer stylesheet hook and rejects a static assets/site.css collision. Append the consumer theme to stock generated CSS in a private build directory, run Telescope checks on those final bytes, then atomically promote the checked tree. A broken CSS reference must leave the previous publication unchanged. Report this reusable gap upstream and retain the published renderer rather than fork it. This workaround changes presentation, not the renderer or browser controls.</p>
 <h3 id="docs-1">DOCS-1. Organize around complete user journeys</h3>
 <table>
 <thead><tr><th>Navigation</th><th>Initial content</th></tr></thead>
diff --git a/openspec/changes/add-documentation-site/proposal.md b/openspec/changes/add-documentation-site/proposal.md
index ea477956..1dbd0b5e 100644
--- a/openspec/changes/add-documentation-site/proposal.md
+++ b/openspec/changes/add-documentation-site/proposal.md
@@ -6,7 +6,7 @@ Python users need a discoverable guide to the library, compiler API, CLI and ext
 
 ## What Changes
 
-- Publish a repository-owned documentation site using a pinned release of moonrockz/telescope, with navigation, search, readable code examples and local preview instructions informed by morphir-moonbit's site.
+- Publish a repository-owned documentation site using a pinned release of moonrockz/telescope, with navigation, search, readable code examples and local preview instructions. Use morphir-moonbit's blue/orange palette and responsive hero, code window, pipeline and feature-card landing design.
 - Add tested examples for Python API compilation/generation, IR codecs and migration, SDK usage, and CLI compile/generate/inspect/convert workflows. Explain package installation, supported platforms, diagnostics and language limits.
 - Document the Python extension's qualified installation and invocation through finos/morphir. Publish a compatibility matrix and verified file-based IR interchange recipes for the MoonBit-based CLI, with explicit unsupported cases.
 - Keep MoonBit Extism adapter implementation in a separate upstream proposal. This change documents current support and links the follow-up; it does not claim that the existing Python WASM bundle works with the MoonBit core-WASM adapter.
diff --git a/openspec/changes/add-documentation-site/specs/docs/site/spec.md b/openspec/changes/add-documentation-site/specs/docs/site/spec.md
index 4e610e08..b5353db6 100644
--- a/openspec/changes/add-documentation-site/specs/docs/site/spec.md
+++ b/openspec/changes/add-documentation-site/specs/docs/site/spec.md
@@ -52,3 +52,10 @@ When a site-foundation limitation obstructs a required experience, contributors
 #### Scenario: A required presentation feature is unavailable
 - **WHEN** a contributor confirms the pinned foundation cannot render a required example interaction
 - **THEN** the change records an upstream report or existing proposal and labels any workaround and remaining acceptance gap
+
+### Requirement: The site follows the Morphir MoonBit visual design
+The documentation SHALL use morphir-moonbit's blue/orange palette in light and dark themes, and its landing-page structure with a split hero, code window, workflow pipeline and feature cards. Content and calls to action SHALL describe qualified Python workflows and remain usable at 360 pixels. The displayed model MUST match a canonical checked Python example. (bead: morphir-ukvn.9.1)
+
+#### Scenario: Open the Python landing page
+- **WHEN** a reader opens the site at either supported deployment base in either theme
+- **THEN** the Morphir palette and responsive landing design are visible, the model matches the checked source, and the main actions reach the API and CLI guides without overflow
diff --git a/openspec/changes/add-documentation-site/tasks.md b/openspec/changes/add-documentation-site/tasks.md
index baf9375b..301fb988 100644
--- a/openspec/changes/add-documentation-site/tasks.md
+++ b/openspec/changes/add-documentation-site/tasks.md
@@ -10,6 +10,8 @@ Implement the contracts in `specs/docs/` using the decisions in `design.html`. S
 - [x] 1.4 Add browser smoke coverage for desktop and 360px, light/dark themes, keyboard focus, navigation, search and code copying; verify no page-level overflow and retain screenshots/results for the candidate.
 - [x] 1.5 Record the foundation/version/limitations in `docs/site-foundation.md`; link Telescope's existing tutorial intent when durable, and report any confirmed reusable blocker upstream with reproduction and acceptance criteria. Verify each remaining gap has a linked report or an explicit non-blocking consumer workaround.
 
+- [ ] 1.6 Match morphir-moonbit revision bd3adc52 colors and landing design using an attributed theme and Python example; verify both themes, desktop/mobile layouts, canonical source, base paths and atomic failure preservation, report the Telescope customization gap upstream and verify the published site after merge.
+
 ## 2. Publish verified Python API and CLI examples (morphir-ukvn.9.2)
 
 - [x] 2.1 Add canonical multi-module model, compiler API and CLI recipe sources under `examples/`, with a prerequisite/result manifest; verify compile/generate/recompile semantic assertions and diagnostic/output-safety cases against installed packages outside the checkout.
diff --git a/scripts/site_tool.py b/scripts/site_tool.py
index 202af6ab..ed074c6f 100644
--- a/scripts/site_tool.py
+++ b/scripts/site_tool.py
@@ -111,6 +111,37 @@ def setup() -> Path:
         )
 
 
+def build_site(binary: Path, base: str, out: str, *, root: Path = ROOT) -> None:
+    """Check Telescope output and the consumer theme before atomic promotion."""
+    root = root.resolve()
+    destination = (root / out).resolve()
+    if destination == root or not destination.is_relative_to(root):
+        raise SiteError("Site output must be a directory inside the project")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(
+        prefix=f".{destination.name}-", dir=destination.parent
+    ) as scratch:
+        staged = Path(scratch) / "site"
+        arguments = ["--config", "site/site.json", "--out", str(staged), "--base", base]
+        subprocess.run([str(binary), "build", *arguments], cwd=root, check=True)
+        # Telescope has no consumer stylesheet hook. Preserve its shell and
+        # append our attributed theme before checking and sealing final bytes.
+        stylesheet = staged / "assets/site.css"
+        with stylesheet.open("ab") as stream:
+            stream.write(b"\n/* Morphir consumer theme */\n")
+            stream.write((root / "site/theme/morphir.css").read_bytes())
+        subprocess.run([str(binary), "check", *arguments], cwd=root, check=True)
+        previous = Path(scratch) / "previous"
+        if destination.exists():
+            destination.rename(previous)
+        try:
+            staged.rename(destination)
+        except OSError:
+            if previous.exists():
+                previous.rename(destination)
+            raise
+
+
 def main(argv: list[str] | None = None) -> None:
     """Run a reproducible site command without installing the Rust toolchain."""
     parser = argparse.ArgumentParser(description=__doc__)
@@ -129,6 +160,8 @@ def main(argv: list[str] | None = None) -> None:
                 [sys.executable, str(ROOT / "scripts/docs_examples.py"), "archive"],
                 check=True,
             )
+            build_site(binary, args.base, args.out)
+            return
         command = [
             str(binary),
             args.command,
diff --git a/site/browser/site.spec.mjs b/site/browser/site.spec.mjs
index 0627a1eb..20ee528c 100644
--- a/site/browser/site.spec.mjs
+++ b/site/browser/site.spec.mjs
@@ -1,5 +1,31 @@
 import { test, expect } from '@playwright/test';
 import { fileURLToPath } from 'node:url';
+import { readFile } from 'node:fs/promises';
+
+for (const width of [1440, 360]) for (const theme of ['light', 'dark']) {
+  test(`MoonBit design at ${width}px in ${theme}`, async ({ page }, info) => {
+    const base = info.project.metadata.base;
+    await page.setViewportSize({ width, height: 900 });
+    await page.emulateMedia({ colorScheme: theme });
+    await page.goto(base);
+    await expect(page.getByRole('heading', { name: 'Morphir, in Python', exact: true })).toBeVisible();
+    await expect(page.locator('.hero .code-window')).toBeVisible();
+    await expect(page.locator('.code-window pre')).toHaveCSS('background-color', 'rgb(15, 20, 27)');
+    const model = await readFile(new URL('../../examples/model/acme/models.py', import.meta.url), 'utf8');
+    expect((await page.locator('.code-window pre code').textContent()).trimEnd()).toBe(model.trimEnd());
+    await expect(page.locator('.pipeline li')).toHaveCount(3);
+    await expect(page.locator('.features .feature')).toHaveCount(3);
+    await expect(page.locator('.button.primary')).toHaveCSS('background-color', 'rgb(255, 106, 0)');
+    await expect(page.locator('body')).toHaveCSS('background-color', theme === 'dark' ? 'rgb(15, 20, 27)' : 'rgb(255, 255, 255)');
+    const metrics = await page.evaluate(() => ({ width: document.documentElement.scrollWidth, viewport: innerWidth, columns: getComputedStyle(document.querySelector('.hero')).gridTemplateColumns.split(' ').length }));
+    expect(metrics.width).toBeLessThanOrEqual(metrics.viewport + 1);
+    expect(metrics.columns).toBe(width === 360 ? 1 : 2);
+    await page.screenshot({ path: fileURLToPath(new URL(`../../.dev/site-browser/${info.project.name}-home-${width}-${theme}.png`, import.meta.url)), fullPage: true });
+    await page.getByRole('link', { name: 'Start with Python', exact: true }).click();
+    await expect(page.getByRole('heading', { name: 'A Python model round trip', exact: true })).toBeVisible();
+    await expect(page.locator('body')).toHaveCSS('background-color', theme === 'dark' ? 'rgb(15, 20, 27)' : 'rgb(255, 255, 255)');
+  });
+}
 
 for (const width of [1440, 360]) for (const theme of ['light', 'dark']) {
   test(`read and navigate at ${width}px in ${theme}`, async ({ page }, info) => {
diff --git a/site/pages/index.html b/site/pages/index.html
new file mode 100644
index 00000000..4bcf5390
--- /dev/null
+++ b/site/pages/index.html
@@ -0,0 +1,55 @@
+<!-- ---
+title: Morphir Python
+--- -->
+<section class="hero">
+  <div class="hero-text">
+    <h1>Morphir, in <span class="hero-accent">Python</span></h1>
+    <p class="lede">Write domain models in Python, exchange Morphir IR and generate Python libraries.
+      Use the same compiler through the Python API, CLI or Morphir extension.</p>
+    <p class="actions">
+      <a class="button primary" href="/docs/quickstart/">Start with Python</a>
+      <a class="button" href="/docs/python-compiler/">Explore the API</a>
+    </p>
+  </div>
+  <figure class="code-window" aria-label="A Python domain model">
+    <figcaption><span class="code-dot" aria-hidden="true"></span>models.py <span class="code-note">compiles to Morphir IR</span></figcaption>
+    <pre><code class="language-python"><span class="tok-keyword">from</span> __future__ <span class="tok-keyword">import</span> annotations
+
+<span class="tok-keyword">from</span> dataclasses <span class="tok-keyword">import</span> dataclass
+
+
+@dataclass(frozen=<span class="tok-keyword">True</span>)
+<span class="tok-keyword">class</span> <span class="tok-name">Pending</span>:
+    <span class="tok-keyword">pass</span>
+
+
+@dataclass(frozen=<span class="tok-keyword">True</span>)
+<span class="tok-keyword">class</span> <span class="tok-name">Approved</span>:
+    amount: <span class="tok-name">float</span>
+
+
+<span class="tok-keyword">type</span> Decision = Pending | Approved</code></pre>
+  </figure>
+</section>
+<ol class="pipeline" aria-label="How Morphir Python works">
+  <li class="step-source">Python domain model</li>
+  <li class="step-ir">Morphir IR</li>
+  <li class="step-target">Generated Python library</li>
+</ol>
+<section class="features" aria-label="Work with Morphir Python">
+  <article class="feature feature-blue">
+    <span class="feature-icon icon-ir" aria-hidden="true"></span>
+    <h2>Work with Morphir IR</h2>
+    <p>Read, write and migrate versioned models with the dependency-free <a href="/docs/library/">Python library</a>.</p>
+  </article>
+  <article class="feature feature-orange">
+    <span class="feature-icon icon-run" aria-hidden="true"></span>
+    <h2>Compile through Python or the CLI</h2>
+    <p>Compile and generate in memory with the <a href="/docs/python-compiler/">typed API</a>, or follow a complete <a href="/docs/quickstart/">CLI round trip</a>.</p>
+  </article>
+  <article class="feature feature-blue">
+    <span class="feature-icon icon-code" aria-hidden="true"></span>
+    <h2>Connect to Morphir</h2>
+    <p>Install the extension with <a href="/docs/python-extension/">finos/morphir</a>. Check the <a href="/docs/compatibility/">qualified host matrix</a> for MoonBit integration and IR interchange.</p>
+  </article>
+</section>
diff --git a/site/pages/index.md b/site/pages/index.md
deleted file mode 100644
index 0f714217..00000000
--- a/site/pages/index.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Morphir Python
-
-Write a small domain model in Python, compile it to Morphir IR, and generate
-Python from that model. Use the library directly from your application or run
-the same compiler through the CLI.
-
-## Start with a model
-
-Follow the [CLI quickstart](../../docs/quickstart.md) for a complete
-compile, inspect, generate and recompile workflow. The
-[Python API guide](../../docs/python-compiler.md) performs compilation in memory
-and returns typed results and diagnostics.
-
-## Work with existing IR
-
-The dependency-free [library](../../docs/library.md) reads and writes Morphir IR,
-migrates supported formats, and supplies the Morphir SDK.
-[Installation](../../docs/installation.md) explains which package you need.
-
-## Connect an extension
-
-The Python compiler also ships as a WASM extension. Start with the
-[compatibility table](../../docs/compatibility.md), then follow the guide for
-[finos/morphir](../../docs/python-extension.md) or the
-[MoonBit-based CLI](../../docs/moonbit.md). Each guide states what its qualified
-version can do.
-
-## Help improve the guides
-
-These examples are checked against installed packages. The
-[contributor guide](../../docs/site.md) explains how to run those checks and
-preview this site with Telescope.
diff --git a/site/theme/README.md b/site/theme/README.md
new file mode 100644
index 00000000..9ba6f7a2
--- /dev/null
+++ b/site/theme/README.md
@@ -0,0 +1,11 @@
+# Morphir site theme
+
+Adapted from `apps/morphir-site/assets/site.css` in FINOS
+[morphir-moonbit](https://github.com/finos/morphir-moonbit/blob/bd3adc52e6b8f6368fdaee50f76535799732f8d6/apps/morphir-site/assets/site.css),
+revision `bd3adc52e6b8f6368fdaee50f76535799732f8d6`, under Apache-2.0.
+Source SHA-256: `9ade4dbd64887a5c04b4832dc59a1338cb589595a693d6970f46ba28665187ff`.
+
+The blue/orange palette, responsive hero, code window, pipeline and feature
+cards follow that reference. The final aliases connect Telescope shell tokens
+to the same palette. The renderer and browser controls remain stock Telescope.
+The build appends this stylesheet before validation and atomic promotion.
diff --git a/site/theme/morphir.css b/site/theme/morphir.css
new file mode 100644
index 00000000..035f02b0
--- /dev/null
+++ b/site/theme/morphir.css
@@ -0,0 +1,175 @@
+/* Adapted from FINOS morphir-moonbit, Apache-2.0; see README.md. */
+:root {
+  --bg: #ffffff; --fg: #1c1e21; --muted: #606770; --border: #e3e6e9;
+  --accent: #00729e; --accent-fg: #ffffff; --code-bg: #f5f6f7;
+  --radius: 8px; --max: 84rem; --header-h: 3.85rem; --font: system-ui, -apple-system, "Segoe UI", sans-serif;
+  --mono: ui-monospace, "SFMono-Regular", Menlo, monospace;
+  --brand-blue: #00a3e2; --brand-orange: #ff6a00; --orange-text: #d45500;
+  --blue-tint: #e0f4fc; --orange-tint: #ffeede; --ok: #1a7f37; --danger: #b42318; --hero-bg: linear-gradient(180deg, #eef8fd, #fff 85%); --code-window-line: #0f141b;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #0f141b; --fg: #e3e8ef; --muted: #9aa4b2; --border: #2a3340;
+    --accent: #5cb0ff; --accent-fg: #0f141b; --code-bg: #171e27; color-scheme: dark;
+    --orange-text: #ff8a3d; --ok: #3fb950; --danger: #f97066; --blue-tint: rgba(0, 163, 226, .16); --orange-tint: rgba(255, 106, 0, .16);
+    --hero-bg: linear-gradient(180deg, #13212e, #0f141b 85%); --code-window-line: #2a3340;
+  }
+}
+:root[data-theme="dark"] {
+  --bg: #0f141b; --fg: #e3e8ef; --muted: #9aa4b2; --border: #2a3340;
+  --accent: #5cb0ff; --accent-fg: #0f141b; --code-bg: #171e27; color-scheme: dark;
+    --orange-text: #ff8a3d; --ok: #3fb950; --danger: #f97066; --blue-tint: rgba(0, 163, 226, .16); --orange-tint: rgba(255, 106, 0, .16);
+    --hero-bg: linear-gradient(180deg, #13212e, #0f141b 85%); --code-window-line: #2a3340;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg); font: 16px/1.6 var(--font); }
+a { color: var(--accent); text-underline-offset: 3px; }
+a:focus-visible, button:focus-visible, input:focus-visible { outline: 3px solid var(--accent); outline-offset: 3px; }
+.visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+.skip-link { position: absolute; left: -999px; } .skip-link:focus { left: 1rem; top: 1rem; }
+.site-header { position: sticky; top: 0; z-index: 20; display: flex; flex-wrap: wrap; align-items: center; gap: 1rem;
+  padding: .75rem 1.5rem; border-bottom: 1px solid var(--border); background: var(--bg); }
+.brand { display: flex; gap: .5rem; align-items: center; font-weight: 700; color: var(--fg); text-decoration: none; }
+.site-links { display: flex; gap: 1rem; flex-wrap: wrap; }
+.site-links a { color: var(--muted); text-decoration: none; } .site-links a.current { color: var(--fg); font-weight: 600; }
+#site-search { margin-left: auto; position: relative; }
+.search input { width: 16rem; max-width: 60vw; padding: .4rem .6rem; border: 1px solid var(--border);
+  border-radius: var(--radius); background: var(--bg); color: var(--fg); }
+.search-results { position: absolute; right: 0; z-index: 10; width: 22rem; max-width: 90vw; margin: .25rem 0 0;
+  padding: .25rem; list-style: none; background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius); }
+.search-results li a { display: flex; justify-content: space-between; gap: 1rem; padding: .4rem .5rem; text-decoration: none; color: var(--fg); }
+.search-results li.selected a, .search-results li a:hover { background: var(--code-bg); }
+.search-results small { color: var(--muted); }
+.theme-toggle, .menu-toggle { padding: .35rem .6rem; border: 1px solid var(--border); border-radius: var(--radius);
+  background: var(--bg); color: var(--fg); cursor: pointer; }
+.menu-toggle { display: none; }
+.icon-button { display: inline-grid; place-items: center; width: 2.25rem; height: 2.25rem; padding: 0; }
+.theme-icon, .feature-icon::before { display: block; width: 1.15rem; height: 1.15rem; background: currentColor;
+  -webkit-mask: var(--icon) center / contain no-repeat; mask: var(--icon) center / contain no-repeat; }
+.theme-system { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><rect x='2' y='3' width='20' height='14' rx='2'/><path d='M8 21h8M12 17v4'/></svg>"); }
+.theme-light { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round'><circle cx='12' cy='12' r='4'/><path d='M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4'/></svg>"); }
+.theme-dark { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linejoin='round'><path d='M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z'/></svg>"); }
+main { max-width: var(--max); margin: 0 auto; padding: 1.5rem 1rem 3rem; }
+main:has(> .docs-layout) { max-width: none; padding-inline: 1.5rem; }
+.prose { max-width: 46rem; } .prose img { max-width: 100%; }
+.prose [id] { scroll-margin-top: calc(var(--header-h) + 1rem); }
+.prose pre, pre.shiki { overflow-x: auto; padding: 1rem; border-radius: var(--radius); background: var(--code-bg); }
+.prose code { font-family: var(--mono); font-size: .92em; }
+.shiki, .shiki span { color: var(--shiki-light); background-color: var(--shiki-light-bg); }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) .shiki,
+  :root:not([data-theme="light"]) .shiki span { color: var(--shiki-dark); background-color: var(--shiki-dark-bg); } }
+:root[data-theme="dark"] .shiki, :root[data-theme="dark"] .shiki span { color: var(--shiki-dark); background-color: var(--shiki-dark-bg); }
+.prose table { border-collapse: collapse; display: block; overflow-x: auto; }
+.prose th, .prose td { border: 1px solid var(--border); padding: .35rem .6rem; }
+.code-block { position: relative; } .prose .code-block { margin: 1em 0; } .code-block > pre { margin: 0; }
+.copy-button { position: absolute; top: .5rem; right: .5rem; display: grid; place-items: center; width: 2rem; height: 2rem;
+  padding: 0; border: 1px solid var(--border); border-radius: 6px; background: var(--bg); color: var(--muted);
+  cursor: pointer; opacity: 0; transition: opacity .15s; }
+.copy-button::before { content: ""; width: 1rem; height: 1rem; background: currentColor;
+  -webkit-mask: var(--icon) center / contain no-repeat; mask: var(--icon) center / contain no-repeat;
+  --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linejoin='round'><rect x='9' y='9' width='12' height='12' rx='2'/><path d='M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1'/></svg>"); }
+.copy-button[data-state="copied"] { color: var(--ok); }
+.copy-button[data-state="copied"]::before { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'><path d='M20 6L9 17l-5-5'/></svg>"); }
+.copy-button[data-state="failed"] { color: var(--danger); }
+.copy-button::after { content: attr(data-tooltip); position: absolute; top: 50%; right: calc(100% + .4rem); transform: translateY(-50%);
+  padding: .15rem .45rem; border-radius: 4px; background: var(--fg); color: var(--bg); font: 600 .75rem/1.4 var(--font);
+  white-space: nowrap; pointer-events: none; opacity: 0; transition: opacity .15s; }
+.code-block:hover .copy-button, .copy-button:focus-visible, .copy-button:not([data-state="idle"])[data-state] { opacity: 1; }
+.copy-button:hover::after, .copy-button:focus-visible::after, .copy-button:not([data-state="idle"])[data-state]::after { opacity: 1; }
+@media (hover: none) { .copy-button { opacity: 1; } }
+.code-window .copy-button { border-color: #2a3340; background: #171e27; color: #9aa4b2; }
+figure.diagram { margin: 1.5rem 0; overflow-x: auto; } figure.diagram svg { max-width: 100%; height: auto; }
+.docs-layout { display: grid; grid-template-columns: 16rem minmax(0, 1fr); gap: 2.5rem; }
+.docs-article { width: 100%; min-width: 0; }
+.docs-article .prose { max-width: none; }
+.docs-article .prose > *, .docs-article .prose section > * { max-width: 46rem; }
+.docs-article .prose :is(section, pre, table, figure, .code-block) { max-width: none; }
+.docs-article .prose figure { margin-inline: 0; }
+.docs-sidebar nav, .docs-toc { position: sticky; top: calc(var(--header-h) + 1rem);
+  max-height: calc(100vh - var(--header-h) - 2rem); overflow-y: auto; }
+.docs-sidebar ul { list-style: none; padding: 0; margin: 0; }
+.docs-rail { display: none; }
+.docs-toc { padding-left: 1rem; border-left: 1px solid var(--border); font-size: .875rem; }
+.docs-toc .nav-label { margin: 0 0 .5rem; }
+.docs-toc ul { list-style: none; padding: 0; margin: 0; } .docs-toc li { padding: .2rem 0; }
+.docs-toc .depth-1 { padding-left: .75rem; }
+.docs-toc a { color: var(--muted); text-decoration: none; } .docs-toc a:hover { color: var(--fg); }
+.docs-toc a[aria-current] { color: var(--accent); font-weight: 600; }
+@media (min-width: 80rem) {
+  .docs-layout { grid-template-columns: 16rem minmax(0, 1fr) 14rem; }
+  .docs-rail { display: block; }
+}
+.docs-sidebar li { padding: .15rem 0; } .docs-sidebar a { color: var(--muted); text-decoration: none; }
+.docs-sidebar a.current { color: var(--fg); font-weight: 600; }
+.docs-sidebar li:has(> .nav-label):not(:first-child) { margin-top: 1rem; }
+.docs-sidebar .depth-1 { padding-left: 1rem; } .docs-sidebar .depth-2 { padding-left: 2rem; }
+.nav-label { font-weight: 600; font-size: .85rem; text-transform: uppercase; color: var(--muted); }
+.page-source { margin-top: 3rem; font-size: .9rem; }
+.post-meta { color: var(--muted); font-size: .95rem; }
+.post-list { list-style: none; padding: 0; display: grid; gap: 1.25rem; }
+.post-card a { font-size: 1.15rem; font-weight: 600; text-decoration: none; }
+.hero { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1.05fr); gap: 2.5rem; align-items: center;
+  padding: 3rem 2rem; border-radius: calc(var(--radius) * 2); background: var(--hero-bg); }
+.hero h1 { font-size: clamp(2rem, 5vw, 3rem); line-height: 1.1; letter-spacing: -.02em; margin: 0 0 1rem; }
+.hero-accent { color: var(--orange-text); }
+.lede { font-size: 1.2rem; color: var(--muted); max-width: 40rem; }
+.button { display: inline-block; padding: .6rem 1rem; border: 1px solid var(--border); border-radius: var(--radius);
+  font-weight: 600; text-decoration: none; margin: 0 .5rem .5rem 0; }
+.button.primary { background: var(--brand-orange); color: #1c1e21; border-color: var(--brand-orange); }
+.button.primary:hover { background: #ff8a3d; }
+.code-window { margin: 0; overflow: hidden; border: 1px solid var(--code-window-line); border-radius: 12px;
+  background: #0f141b; color: #e3e8ef; box-shadow: 0 12px 32px rgba(11, 37, 64, .25); }
+.code-window figcaption { display: flex; align-items: center; gap: .5rem; padding: .5rem 1rem; background: #171e27;
+  color: #9aa4b2; font: .85rem var(--mono); }
+.code-dot { width: .6rem; height: .6rem; border-radius: 50%; background: var(--brand-orange); }
+.code-note { margin-left: auto; opacity: .75; }
+.code-window pre { margin: 0; padding: 1rem; overflow-x: auto; font: .9rem/1.6 var(--mono); }
+.tok-comment { color: #8b96a5; font-style: italic; } .tok-keyword { color: #5cb0ff; }
+.tok-name { color: #ffb27a; } .tok-number { color: #c792ea; }
+.pipeline { display: flex; flex-wrap: wrap; justify-content: center; align-items: center; gap: .5rem 2.25rem;
+  margin: 2rem 0; padding: 0; list-style: none; font-weight: 600; font-size: .95rem; }
+.pipeline li { position: relative; padding: .4rem .9rem; border-radius: 999px; background: var(--blue-tint); }
+.pipeline li + li::before { content: "→"; position: absolute; left: -1.6rem; color: var(--muted); }
+.pipeline .step-ir { background: var(--orange-tint); }
+.features { display: grid; grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); gap: 1.5rem; margin: 2rem 0; }
+.feature { border: 1px solid var(--border); border-top: 3px solid var(--brand-blue); border-radius: var(--radius);
+  padding: 1.25rem; }
+.feature h2 { font-size: 1.15rem; margin: .75rem 0 .5rem; } .feature p { margin: 0; color: var(--muted); }
+.feature-orange { border-top-color: var(--brand-orange); }
+.feature-icon { display: grid; place-items: center; width: 2.5rem; height: 2.5rem; border-radius: var(--radius);
+  background: var(--blue-tint); color: var(--brand-blue); }
+.feature-orange .feature-icon { background: var(--orange-tint); color: var(--brand-orange); }
+.feature-icon::before { content: ""; width: 1.3rem; height: 1.3rem; }
+.icon-ir { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linejoin='round'><path d='M12 2l9 5v10l-9 5-9-5V7z'/><path d='M12 22V12M21 7l-9 5-9-5'/></svg>"); }
+.icon-run { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linejoin='round'><path d='M7 4l13 8-13 8z'/></svg>"); }
+.icon-code { --icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><path d='M16 18l6-6-6-6M8 6l-6 6 6 6'/></svg>"); }
+.site-footer { border-top: 1px solid var(--border); text-align: center; color: var(--muted); font-size: .9rem; padding: 1.5rem 1rem; }
+@media (max-width: 48rem) {
+  .hero { grid-template-columns: minmax(0, 1fr); padding: 2rem 1rem; }
+  .code-window pre { font-size: .78rem; }
+  .pipeline { flex-direction: column; gap: 1.75rem; }
+  .pipeline li + li::before { content: "↓"; left: 50%; top: -1.6rem; transform: translateX(-50%); }
+}
+@media (max-width: 760px) {
+  .docs-layout { grid-template-columns: minmax(0, 1fr); }
+  .docs-sidebar { order: 2; border-top: 1px solid var(--border); padding-top: 1rem; }
+  .docs-sidebar nav { position: static; max-height: none; }
+  .menu-toggle { display: inline-block; }
+  :root[data-js] .site-links { display: none; width: 100%; flex-direction: column; gap: .5rem; }
+  :root[data-js][data-nav-open] .site-links { display: flex; }
+  .site-header { gap: .5rem 1rem; padding: .5rem 1rem; }
+  #site-theme { margin-left: auto; }
+  #site-search { order: 3; margin-left: 0; width: 100%; } .search input { width: 100%; max-width: none; }
+  .site-links { order: 4; }
+}
+
+/* Bridge Telescope shell tokens to the shared Morphir palette. */
+:root {
+  --page-bg: var(--bg); --page-fg: var(--fg); --surface: var(--code-bg);
+  --line: var(--border); --on-accent: var(--accent-fg);
+  --control-border: var(--muted); --font-sans: var(--font); --font-mono: var(--mono);
+}
+.code-window code { padding: 0; background: transparent; font: inherit; }
+.code-window .code-block { margin: 0; }
+.code-window pre { background: #0f141b; border: 0; border-radius: 0; }
diff --git a/tests/unit/test_site_tool.py b/tests/unit/test_site_tool.py
index dbf11768..63fb276c 100644
--- a/tests/unit/test_site_tool.py
+++ b/tests/unit/test_site_tool.py
@@ -63,3 +63,39 @@ def test_broken_fragment_preserves_checked_output(tmp_path: Path, base: str) ->
     assert failed.returncode == 1
     assert "absent" in failed.stderr + failed.stdout
     assert (tmp_path / "output/docs/guide/index.html").read_bytes() == original
+
+
+@pytest.mark.skipif(
+    not os.environ.get("MORPHIR_SITE_TEST"), reason="explicit site qualification"
+)
+def test_branding_is_checked_before_replacing_the_site(tmp_path: Path) -> None:
+    import json
+
+    from scripts.site_tool import build_site
+
+    (tmp_path / "docs").mkdir()
+    (tmp_path / "docs/guide.md").write_text("# Guide\n")
+    (tmp_path / "site/theme").mkdir(parents=True)
+    (tmp_path / "site/site.json").write_text(
+        json.dumps(
+            {
+                "title": "Fixture",
+                "description": "Fixture",
+                "base_path": "/",
+                "site_url": "https://example.test/",
+                "repo_url": "https://github.com/example/repo",
+                "packages": [],
+                "source_roots": ["docs"],
+            }
+        )
+    )
+    theme = tmp_path / "site/theme/morphir.css"
+    theme.write_text(":root { --brand-blue: #00a3e2; }\n")
+    build_site(setup(), "/", "output", root=tmp_path)
+    css = tmp_path / "output/assets/site.css"
+    checked = css.read_bytes()
+    assert b"--brand-blue: #00a3e2" in checked
+    theme.write_text("body { background: url(missing-brand-image.svg); }\n")
+    with pytest.raises(subprocess.CalledProcessError):
+        build_site(setup(), "/", "output", root=tmp_path)
+    assert css.read_bytes() == checked