From 60da68905cc00076a4e8925a39b94a0a820e89ad Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 11:53:09 -0700
Subject: [PATCH 1/2] swift logo and name with link to swift.org in header

---
 common/README      | 15 ++++++++++++---
 common/header.html | 21 +++++++++++++++++++--
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/common/README b/common/README
index cce65f4b..c47009cd 100644
--- a/common/README
+++ b/common/README
@@ -8,9 +8,18 @@ The common files need to be copied, or perhaps linked, into each of the DocC cat
 
 Both files are intentionally minimal:
 
-- `header.html` has no visible content. It's a reserved hook (DocC's
-  `custom-header` template) for a future documentation-version switcher —
-  add the switcher UI to the `#version-switcher` div when that lands.
+- `header.html` renders a thin bar above the DocC app itself — logo, "Swift"
+  wordmark, and a link to swift.org — via DocC's `custom-header` template
+  hook. swift-docc-render mounts the `custom-header` custom element as the
+  first child of `#app`, ahead of DocC's own masthead/navigator, so this
+  never needs to reach into DocC's rendered DOM (unlike an approach that
+  edits the masthead's `.pre-title`/`.nav-title` after the fact) — it's
+  purely static markup, no JS. It's styled with DocC's own CSS custom
+  properties (`var(--color-text)`, `var(--color-grid)`), which pierce the
+  Shadow DOM `custom-header` renders into, so it flips with light/dark mode
+  the same way the footer does. It also still reserves the
+  `#version-switcher` div for a future documentation-version switcher — add
+  the switcher UI there when that lands.
 - `footer.html` carries the copyright/trademark notice, the same legal links
   (License, Security, Privacy Policy, Cookies) swift.org's footer has, and
   an Adobe Analytics page-activation snippet mirroring swift.org's
diff --git a/common/header.html b/common/header.html
index ef1d844f..ad43df7f 100644
--- a/common/header.html
+++ b/common/header.html
@@ -7,5 +7,22 @@
   See https://swift.org/LICENSE.txt for license information
   See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
 -->
-<!-- Reserved for a future documentation-version switcher. Intentionally empty until that exists. -->
-<div id="version-switcher"></div>
+<style>
+header.minimal-header{display:flex;align-items:center;justify-content:space-between;gap:1rem;padding:0.6rem 1rem;border-bottom:1px solid var(--color-grid);}
+header.minimal-header .home-link{display:flex;align-items:center;gap:0.5rem;color:var(--color-text);text-decoration:none;font-size:15px;font-weight:600;}
+header.minimal-header .home-link:hover{text-decoration:underline;}
+header.minimal-header svg{display:block;flex-shrink:0;}
+</style>
+
+<header class="minimal-header">
+  <a class="home-link" href="https://www.swift.org" aria-label="Swift.org">
+    <!--
+      Sourced from developer.apple.com/swift/resources/images/swift_logo_color.svg,
+      the official full-color Swift mark.
+    -->
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 106.1 106.1" width="20" height="20" aria-hidden="true"><path fill="#f05138" d="m106.1 29.4c0-1.1 0-2.1 0-3.2-.1-2.3-.2-4.7-.6-7s-1.1-4.5-2.2-6.6-2.4-4-4.1-5.6c-1.7-1.7-3.6-3-5.6-4.1-2.1-1.1-4.3-1.8-6.6-2.2s-4.6-.6-7-.6c-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8 0h-28.1-11.6c-1.3 0-2.5 0-3.8 0-1.1 0-2.1 0-3.2 0-.6 0-1.2 0-1.7.1-1.7.1-3.5.2-5.2.5s-3.4.8-5 1.4c-.5.2-1.1.5-1.6.7-1.6.8-3 1.8-4.4 2.9-.4.4-.9.8-1.3 1.2-1.7 1.7-3 3.6-4.1 5.6-1.1 2.1-1.8 4.3-2.2 6.6s-.5 4.6-.6 7v3.2 3.8 17.3 22.4 3.8 3.2c.1 2.3.2 4.7.6 7s1.1 4.5 2.2 6.6 2.4 4 4.1 5.6c1.7 1.7 3.6 3 5.6 4.1 2.1 1.1 4.3 1.8 6.6 2.2s4.6.6 7 .6h3.2 3.8 39.7 3.8 3.2c2.3-.1 4.7-.2 7-.6s4.5-1.1 6.6-2.2 4-2.4 5.6-4.1c1.7-1.7 3-3.6 4.1-5.6 1.1-2.1 1.8-4.3 2.2-6.6s.6-4.6.6-7c0-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8v-39.7c-0-1.2-0-2.4-0-3.7z"/><path fill="#fff" d="m84 65.5c.1-.4.2-.8.3-1.2 4.4-17.5-6.3-38.3-24.5-49.2 8 10.8 11.5 23.9 8.4 35.3-.3 1-.6 2-1 3-.4-.3-.9-.6-1.6-.9 0 0-18.1-11.2-37.7-30.9-.5-.5 10.5 15.7 22.9 28.8-5.9-3.3-22.2-15.2-32.6-24.6 1.3 2.1 2.8 4.2 4.4 6.1 8.6 11 19.9 24.5 33.4 34.9-9.5 5.8-22.9 6.3-36.2 0-3.3-1.5-6.4-3.4-9.3-5.5 5.6 9 14.3 16.8 24.9 21.4 12.6 5.4 25.2 5.1 34.5.1s.1 0 .1-.1c.4-.2.8-.5 1.2-.7 4.5-2.3 13.3-4.6 18.1 4.6 1.4 2.1 3.9-9.9-5.3-21.1z"/></svg>
+    <span>Swift</span>
+  </a>
+  <!-- Reserved for a future documentation-version switcher. Intentionally empty until that exists. -->
+  <div id="version-switcher"></div>
+</header>

From cb91955f2c2677fe8af5867cef0479c6951302c2 Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 12:07:11 -0700
Subject: [PATCH 2/2] using the same sizing as swift.org, not the compressed
 sizing from the interior-to-docc attempts earlier

---
 common/header.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/common/header.html b/common/header.html
index ad43df7f..f72cd9d1 100644
--- a/common/header.html
+++ b/common/header.html
@@ -9,9 +9,9 @@
 -->
 <style>
 header.minimal-header{display:flex;align-items:center;justify-content:space-between;gap:1rem;padding:0.6rem 1rem;border-bottom:1px solid var(--color-grid);}
-header.minimal-header .home-link{display:flex;align-items:center;gap:0.5rem;color:var(--color-text);text-decoration:none;font-size:15px;font-weight:600;}
+header.minimal-header .home-link{display:flex;align-items:center;gap:0.625rem;color:var(--color-text);text-decoration:none;font-size:28px;font-weight:700;}
 header.minimal-header .home-link:hover{text-decoration:underline;}
-header.minimal-header svg{display:block;flex-shrink:0;}
+header.minimal-header svg{display:block;flex-shrink:0;width:36px;height:36px;}
 </style>
 
 <header class="minimal-header">
@@ -20,7 +20,7 @@
       Sourced from developer.apple.com/swift/resources/images/swift_logo_color.svg,
       the official full-color Swift mark.
     -->
-    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 106.1 106.1" width="20" height="20" aria-hidden="true"><path fill="#f05138" d="m106.1 29.4c0-1.1 0-2.1 0-3.2-.1-2.3-.2-4.7-.6-7s-1.1-4.5-2.2-6.6-2.4-4-4.1-5.6c-1.7-1.7-3.6-3-5.6-4.1-2.1-1.1-4.3-1.8-6.6-2.2s-4.6-.6-7-.6c-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8 0h-28.1-11.6c-1.3 0-2.5 0-3.8 0-1.1 0-2.1 0-3.2 0-.6 0-1.2 0-1.7.1-1.7.1-3.5.2-5.2.5s-3.4.8-5 1.4c-.5.2-1.1.5-1.6.7-1.6.8-3 1.8-4.4 2.9-.4.4-.9.8-1.3 1.2-1.7 1.7-3 3.6-4.1 5.6-1.1 2.1-1.8 4.3-2.2 6.6s-.5 4.6-.6 7v3.2 3.8 17.3 22.4 3.8 3.2c.1 2.3.2 4.7.6 7s1.1 4.5 2.2 6.6 2.4 4 4.1 5.6c1.7 1.7 3.6 3 5.6 4.1 2.1 1.1 4.3 1.8 6.6 2.2s4.6.6 7 .6h3.2 3.8 39.7 3.8 3.2c2.3-.1 4.7-.2 7-.6s4.5-1.1 6.6-2.2 4-2.4 5.6-4.1c1.7-1.7 3-3.6 4.1-5.6 1.1-2.1 1.8-4.3 2.2-6.6s.6-4.6.6-7c0-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8v-39.7c-0-1.2-0-2.4-0-3.7z"/><path fill="#fff" d="m84 65.5c.1-.4.2-.8.3-1.2 4.4-17.5-6.3-38.3-24.5-49.2 8 10.8 11.5 23.9 8.4 35.3-.3 1-.6 2-1 3-.4-.3-.9-.6-1.6-.9 0 0-18.1-11.2-37.7-30.9-.5-.5 10.5 15.7 22.9 28.8-5.9-3.3-22.2-15.2-32.6-24.6 1.3 2.1 2.8 4.2 4.4 6.1 8.6 11 19.9 24.5 33.4 34.9-9.5 5.8-22.9 6.3-36.2 0-3.3-1.5-6.4-3.4-9.3-5.5 5.6 9 14.3 16.8 24.9 21.4 12.6 5.4 25.2 5.1 34.5.1s.1 0 .1-.1c.4-.2.8-.5 1.2-.7 4.5-2.3 13.3-4.6 18.1 4.6 1.4 2.1 3.9-9.9-5.3-21.1z"/></svg>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 106.1 106.1" width="36" height="36" aria-hidden="true"><path fill="#f05138" d="m106.1 29.4c0-1.1 0-2.1 0-3.2-.1-2.3-.2-4.7-.6-7s-1.1-4.5-2.2-6.6-2.4-4-4.1-5.6c-1.7-1.7-3.6-3-5.6-4.1-2.1-1.1-4.3-1.8-6.6-2.2s-4.6-.6-7-.6c-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8 0h-28.1-11.6c-1.3 0-2.5 0-3.8 0-1.1 0-2.1 0-3.2 0-.6 0-1.2 0-1.7.1-1.7.1-3.5.2-5.2.5s-3.4.8-5 1.4c-.5.2-1.1.5-1.6.7-1.6.8-3 1.8-4.4 2.9-.4.4-.9.8-1.3 1.2-1.7 1.7-3 3.6-4.1 5.6-1.1 2.1-1.8 4.3-2.2 6.6s-.5 4.6-.6 7v3.2 3.8 17.3 22.4 3.8 3.2c.1 2.3.2 4.7.6 7s1.1 4.5 2.2 6.6 2.4 4 4.1 5.6c1.7 1.7 3.6 3 5.6 4.1 2.1 1.1 4.3 1.8 6.6 2.2s4.6.6 7 .6h3.2 3.8 39.7 3.8 3.2c2.3-.1 4.7-.2 7-.6s4.5-1.1 6.6-2.2 4-2.4 5.6-4.1c1.7-1.7 3-3.6 4.1-5.6 1.1-2.1 1.8-4.3 2.2-6.6s.6-4.6.6-7c0-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8v-39.7c-0-1.2-0-2.4-0-3.7z"/><path fill="#fff" d="m84 65.5c.1-.4.2-.8.3-1.2 4.4-17.5-6.3-38.3-24.5-49.2 8 10.8 11.5 23.9 8.4 35.3-.3 1-.6 2-1 3-.4-.3-.9-.6-1.6-.9 0 0-18.1-11.2-37.7-30.9-.5-.5 10.5 15.7 22.9 28.8-5.9-3.3-22.2-15.2-32.6-24.6 1.3 2.1 2.8 4.2 4.4 6.1 8.6 11 19.9 24.5 33.4 34.9-9.5 5.8-22.9 6.3-36.2 0-3.3-1.5-6.4-3.4-9.3-5.5 5.6 9 14.3 16.8 24.9 21.4 12.6 5.4 25.2 5.1 34.5.1s.1 0 .1-.1c.4-.2.8-.5 1.2-.7 4.5-2.3 13.3-4.6 18.1 4.6 1.4 2.1 3.9-9.9-5.3-21.1z"/></svg>
     <span>Swift</span>
   </a>
   <!-- Reserved for a future documentation-version switcher. Intentionally empty until that exists. -->