From 81f8f9873615362aaace7c3243d2a1207d388ff7 Mon Sep 17 00:00:00 2001
From: Dave Lester <18080+davelester@users.noreply.github.com>
Date: Mon, 10 Aug 2026 07:56:07 -0700
Subject: [PATCH 1/6] Inserts Swift logo above consolidated docc navigation.

---
 common/README      | 13 ++++++++++---
 common/header.html | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/common/README b/common/README
index cce65f4b..505c2f2e 100644
--- a/common/README
+++ b/common/README
@@ -8,9 +8,16 @@ 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` uses DocC's `custom-header` template hook to inject a Swift
+  logo linking to swift.org above the sidebar's link list. Because the
+  custom-header element renders in its own shadow root while the Navigator
+  sidebar it targets lives in the app's regular (light) DOM, the logo can't
+  be placed there via markup/slots alone — a script waits for
+  `.navigator .head-wrapper` to mount (via MutationObserver, since it's
+  rendered client-side by swift-docc-render) and prepends the logo link to
+  it. 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..8ac24b6f 100644
--- a/common/header.html
+++ b/common/header.html
@@ -9,3 +9,42 @@
 -->
 <!-- Reserved for a future documentation-version switcher. Intentionally empty until that exists. -->
 <div id="version-switcher"></div>
+
+<script>
+(function () {
+  var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 25 25" width="22" height="22" aria-hidden="true"><path fill="currentColor" fill-rule="evenodd" d="M12.5.5a12,12,0,1,0,12,12A12,12,0,0,0,12.5.5ZM1.525,13H6.014a20.83,20.83,0,0,0,.469,4.031h-4A10.924,10.924,0,0,1,1.525,13ZM13,6.969V1.552c1.734.339,3.32,2.417,4.222,5.417Zm4.49,1a19.808,19.808,0,0,1,.5,4.031H13V7.969ZM12,1.552V6.969H7.778C8.68,3.969,10.266,1.891,12,1.552Zm0,6.417V12H7.013a19.808,19.808,0,0,1,.5-4.031ZM6.014,12H1.525a10.924,10.924,0,0,1,.96-4.031h4A20.83,20.83,0,0,0,6.014,12Zm1,1H12v4.031H7.51A19.808,19.808,0,0,1,7.013,13ZM12,18.031v5.417c-1.734-.339-3.32-2.417-4.222-5.417Zm1,5.417V18.031h4.222C16.32,21.031,14.734,23.109,13,23.448Zm0-6.417V13h4.987a19.808,19.808,0,0,1-.5,4.031ZM18.986,13h4.489a10.924,10.924,0,0,1-.96,4.031h-4A20.83,20.83,0,0,0,18.986,13Zm0-1a20.83,20.83,0,0,0-.469-4.031h4A10.924,10.924,0,0,1,23.475,12ZM22,6.969H18.265A11.6,11.6,0,0,0,15.6,1.951,11.007,11.007,0,0,1,22,6.969ZM9.4,1.951A11.6,11.6,0,0,0,6.735,6.969H3A11.007,11.007,0,0,1,9.4,1.951ZM3,18.031H6.735A11.6,11.6,0,0,0,9.4,23.049,11.007,11.007,0,0,1,3,18.031Zm12.6,5.018a11.6,11.6,0,0,0,2.665-5.018H22A11.007,11.007,0,0,1,15.6,23.049Z"/></svg>';
+
+  // The Navigator sidebar is rendered client-side by swift-docc-render (Vue),
+  // not present in this page's initial HTML, so it may not exist yet when
+  // this script runs — retry via MutationObserver until it mounts.
+  function insertLogoLink() {
+    var headWrapper = document.querySelector('.navigator .head-wrapper');
+    if (!headWrapper || headWrapper.querySelector('.sidebar-swift-logo')) {
+      return false;
+    }
+    var link = document.createElement('a');
+    link.href = 'https://www.swift.org';
+    link.className = 'sidebar-swift-logo';
+    link.setAttribute('aria-label', 'Swift.org');
+    link.innerHTML = LOGO_SVG;
+    headWrapper.insertBefore(link, headWrapper.firstChild);
+    return true;
+  }
+
+  // Styled on the main document, not this template's own shadow root: the
+  // Navigator sidebar this targets lives outside this custom element's
+  // shadow tree, in the app's regular (light) DOM.
+  var style = document.createElement('style');
+  style.textContent = '.sidebar-swift-logo{display:flex;flex-shrink:0;align-items:center;color:var(--color-text);padding-block-start:10px;}';
+  document.head.appendChild(style);
+
+  if (!insertLogoLink()) {
+    var observer = new MutationObserver(function () {
+      if (insertLogoLink()) {
+        observer.disconnect();
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  }
+})();
+</script>

From e051780dc8de3b40c6495a8a527383ade4f2a71f Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 10:00:21 -0700
Subject: [PATCH 2/6] Move Swift logo into the masthead and use the official
 icon-swift.svg mark
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The original approach targeted the Navigator sidebar's `.head-wrapper`,
which swift-docc-render tears down and rebuilds once the navigator
index data finishes loading, discarding whatever a script had inserted
into the loading-skeleton version — so the logo never stuck around.
The masthead's `.pre-title` has no such swap: it mounts once from data
already known at page load, so the logo (appended there, between the
sidebar toggle and the page title) stays visible regardless of the
sidebar's own shown/hidden/drawer state.

Also swaps the placeholder mark for the official currentColor icon from
swiftlang/swift-org-website's assets/images/icon-swift.svg.
---
 common/README      | 24 +++++++++++++++--------
 common/header.html | 48 ++++++++++++++++++++++++++++++----------------
 2 files changed, 48 insertions(+), 24 deletions(-)

diff --git a/common/README b/common/README
index 505c2f2e..f5db85ac 100644
--- a/common/README
+++ b/common/README
@@ -8,14 +8,22 @@ The common files need to be copied, or perhaps linked, into each of the DocC cat
 
 Both files are intentionally minimal:
 
-- `header.html` uses DocC's `custom-header` template hook to inject a Swift
-  logo linking to swift.org above the sidebar's link list. Because the
-  custom-header element renders in its own shadow root while the Navigator
-  sidebar it targets lives in the app's regular (light) DOM, the logo can't
-  be placed there via markup/slots alone — a script waits for
-  `.navigator .head-wrapper` to mount (via MutationObserver, since it's
-  rendered client-side by swift-docc-render) and prepends the logo link to
-  it. It also still reserves the `#version-switcher` div for a future
+- `header.html` uses DocC's `custom-header` template hook to add a Swift logo
+  linking to swift.org to the masthead, between the sidebar-toggle control
+  and the page title. It targets the masthead rather than the Navigator
+  sidebar itself because the masthead mounts once from data already known at
+  page load and never gets torn down and rebuilt — unlike the sidebar, which
+  swift-docc-render swaps from a loading-skeleton state to the real,
+  populated one once the navigator index data has loaded, discarding
+  whatever a script had inserted into the skeleton. The logo is appended as
+  the last child of `.pre-title` (the toggle's own wrapper) rather than
+  inserted as a sibling before `.nav-title`, because swift-docc-render's CSS
+  assigns the title its grid placement via the adjacent-sibling selector
+  `.pre-title + .nav-title`, which requires them to stay immediate siblings.
+  Because it's part of the persistent masthead rather than the sidebar, the
+  logo stays visible regardless of whether the sidebar is shown, hidden, or
+  a mobile drawer, with no extra positioning or z-index logic needed. 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
diff --git a/common/header.html b/common/header.html
index 8ac24b6f..bb6c0204 100644
--- a/common/header.html
+++ b/common/header.html
@@ -12,38 +12,54 @@
 
 <script>
 (function () {
-  var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 25 25" width="22" height="22" aria-hidden="true"><path fill="currentColor" fill-rule="evenodd" d="M12.5.5a12,12,0,1,0,12,12A12,12,0,0,0,12.5.5ZM1.525,13H6.014a20.83,20.83,0,0,0,.469,4.031h-4A10.924,10.924,0,0,1,1.525,13ZM13,6.969V1.552c1.734.339,3.32,2.417,4.222,5.417Zm4.49,1a19.808,19.808,0,0,1,.5,4.031H13V7.969ZM12,1.552V6.969H7.778C8.68,3.969,10.266,1.891,12,1.552Zm0,6.417V12H7.013a19.808,19.808,0,0,1,.5-4.031ZM6.014,12H1.525a10.924,10.924,0,0,1,.96-4.031h4A20.83,20.83,0,0,0,6.014,12Zm1,1H12v4.031H7.51A19.808,19.808,0,0,1,7.013,13ZM12,18.031v5.417c-1.734-.339-3.32-2.417-4.222-5.417Zm1,5.417V18.031h4.222C16.32,21.031,14.734,23.109,13,23.448Zm0-6.417V13h4.987a19.808,19.808,0,0,1-.5,4.031ZM18.986,13h4.489a10.924,10.924,0,0,1-.96,4.031h-4A20.83,20.83,0,0,0,18.986,13Zm0-1a20.83,20.83,0,0,0-.469-4.031h4A10.924,10.924,0,0,1,23.475,12ZM22,6.969H18.265A11.6,11.6,0,0,0,15.6,1.951,11.007,11.007,0,0,1,22,6.969ZM9.4,1.951A11.6,11.6,0,0,0,6.735,6.969H3A11.007,11.007,0,0,1,9.4,1.951ZM3,18.031H6.735A11.6,11.6,0,0,0,9.4,23.049,11.007,11.007,0,0,1,3,18.031Zm12.6,5.018a11.6,11.6,0,0,0,2.665-5.018H22A11.007,11.007,0,0,1,15.6,23.049Z"/></svg>';
+  // Sourced from swiftlang/swift-org-website's assets/images/icon-swift.svg
+  // (the currentColor variant, meant for light/dark masthead use — the
+  // upstream asset intentionally leaves fill unset so consumers apply their
+  // own; fill="currentColor" below is added here to do that).
+  var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="22" height="22" aria-hidden="true"><path fill="currentColor" fill-rule="nonzero" transform="matrix(.351937 0 0 .351937 -1.96558 -2.00601)" d="m46.955 36.578c-.002-.002-.003-.003-.005-.005.066-.223.134-.445.191-.673 2.46-9.799-3.543-21.384-13.701-27.484 4.452 6.035 6.42 13.344 4.671 19.735-.156.571-.343 1.118-.55 1.65-.225-.148-.509-.316-.889-.526 0 0-10.104-6.238-21.055-17.273-.288-.29 5.839 8.757 12.793 16.104-3.276-1.839-12.406-8.482-18.186-13.772.71 1.185 1.555 2.325 2.483 3.423 4.827 6.121 11.121 13.673 18.662 19.473-5.298 3.242-12.785 3.494-20.239.003-1.844-.864-3.577-1.907-5.182-3.091 3.156 5.047 8.015 9.401 13.93 11.943 7.054 3.032 14.068 2.826 19.292.05l-.004.006c.024-.015.054-.031.079-.047.214-.115.427-.232.636-.356 2.51-1.303 7.467-2.625 10.129 2.553.651 1.267 2.036-5.448-3.055-11.713z"/></svg>';
 
-  // The Navigator sidebar is rendered client-side by swift-docc-render (Vue),
-  // not present in this page's initial HTML, so it may not exist yet when
-  // this script runs — retry via MutationObserver until it mounts.
+  // The masthead (.nav-content > .pre-title, .nav-title, .nav-menu) is
+  // rendered client-side by swift-docc-render (Vue), not present in this
+  // page's initial HTML, so it may not exist yet when this script runs —
+  // retry via MutationObserver until it mounts. Unlike the Navigator
+  // sidebar, the masthead has no loading-skeleton/real-content swap to
+  // race against: it mounts once from data already known at page load and
+  // stays, so this observer keeps running (harmlessly, guarded by the
+  // .masthead-swift-logo check below) rather than needing to disconnect at
+  // a precise moment.
+  //
+  // Appended as the last child of `.pre-title` rather than inserted as a
+  // sibling between `.pre-title` and `.nav-title`: swift-docc-render's own
+  // CSS assigns `.nav-title` its grid placement via the adjacent-sibling
+  // selector `.pre-title + .nav-title`, which requires them to stay
+  // immediate siblings. Landing inside `.pre-title` keeps that intact while
+  // still sitting visually between the sidebar toggle and the title text —
+  // and, being part of the persistent masthead rather than the sidebar
+  // itself, it stays visible regardless of whether the sidebar is shown,
+  // hidden, or a mobile drawer.
   function insertLogoLink() {
-    var headWrapper = document.querySelector('.navigator .head-wrapper');
-    if (!headWrapper || headWrapper.querySelector('.sidebar-swift-logo')) {
+    var preTitle = document.querySelector('.pre-title');
+    if (!preTitle || preTitle.querySelector('.masthead-swift-logo')) {
       return false;
     }
     var link = document.createElement('a');
     link.href = 'https://www.swift.org';
-    link.className = 'sidebar-swift-logo';
+    link.className = 'masthead-swift-logo';
     link.setAttribute('aria-label', 'Swift.org');
     link.innerHTML = LOGO_SVG;
-    headWrapper.insertBefore(link, headWrapper.firstChild);
+    preTitle.appendChild(link);
     return true;
   }
 
   // Styled on the main document, not this template's own shadow root: the
-  // Navigator sidebar this targets lives outside this custom element's
-  // shadow tree, in the app's regular (light) DOM.
+  // masthead this targets lives outside this custom element's shadow tree,
+  // in the app's regular (light) DOM.
   var style = document.createElement('style');
-  style.textContent = '.sidebar-swift-logo{display:flex;flex-shrink:0;align-items:center;color:var(--color-text);padding-block-start:10px;}';
+  style.textContent = '.masthead-swift-logo{display:flex;align-items:center;padding-inline:8px;color:var(--color-text);}';
   document.head.appendChild(style);
 
   if (!insertLogoLink()) {
-    var observer = new MutationObserver(function () {
-      if (insertLogoLink()) {
-        observer.disconnect();
-      }
-    });
+    var observer = new MutationObserver(insertLogoLink);
     observer.observe(document.body, { childList: true, subtree: true });
   }
 })();

From 77417260b5437429b08e8a66e7df1453f79868c1 Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 10:09:52 -0700
Subject: [PATCH 3/6] updating comments about how this works

---
 common/README      | 25 ++++++++++---------------
 common/header.html | 33 ++++++++++-----------------------
 2 files changed, 20 insertions(+), 38 deletions(-)

diff --git a/common/README b/common/README
index f5db85ac..6ba140fd 100644
--- a/common/README
+++ b/common/README
@@ -11,21 +11,16 @@ Both files are intentionally minimal:
 - `header.html` uses DocC's `custom-header` template hook to add a Swift logo
   linking to swift.org to the masthead, between the sidebar-toggle control
   and the page title. It targets the masthead rather than the Navigator
-  sidebar itself because the masthead mounts once from data already known at
-  page load and never gets torn down and rebuilt — unlike the sidebar, which
-  swift-docc-render swaps from a loading-skeleton state to the real,
-  populated one once the navigator index data has loaded, discarding
-  whatever a script had inserted into the skeleton. The logo is appended as
-  the last child of `.pre-title` (the toggle's own wrapper) rather than
-  inserted as a sibling before `.nav-title`, because swift-docc-render's CSS
-  assigns the title its grid placement via the adjacent-sibling selector
-  `.pre-title + .nav-title`, which requires them to stay immediate siblings.
-  Because it's part of the persistent masthead rather than the sidebar, the
-  logo stays visible regardless of whether the sidebar is shown, hidden, or
-  a mobile drawer, with no extra positioning or z-index logic needed. It
-  also still reserves the `#version-switcher` div for a future
-  documentation-version switcher — add the switcher UI there when that
-  lands.
+  sidebar because the sidebar gets torn down and rebuilt once its data
+  loads (discarding anything inserted into its loading-skeleton state),
+  while the masthead mounts once and stays. The logo is appended inside
+  `.pre-title` rather than inserted as a sibling before `.nav-title`, since
+  swift-docc-render positions the title via the adjacent-sibling CSS rule
+  `.pre-title + .nav-title`, which needs them to stay adjacent. Being part
+  of the masthead rather than the sidebar, it stays visible regardless of
+  the sidebar's shown/hidden/drawer state. 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 bb6c0204..f44161fe 100644
--- a/common/header.html
+++ b/common/header.html
@@ -12,31 +12,18 @@
 
 <script>
 (function () {
-  // Sourced from swiftlang/swift-org-website's assets/images/icon-swift.svg
-  // (the currentColor variant, meant for light/dark masthead use — the
-  // upstream asset intentionally leaves fill unset so consumers apply their
-  // own; fill="currentColor" below is added here to do that).
+  // Sourced from swiftlang/swift-org-website's assets/images/icon-swift.svg,
+  // the currentColor variant — fill="currentColor" below is added here since
+  // the upstream asset leaves it unset for consumers to apply.
   var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="22" height="22" aria-hidden="true"><path fill="currentColor" fill-rule="nonzero" transform="matrix(.351937 0 0 .351937 -1.96558 -2.00601)" d="m46.955 36.578c-.002-.002-.003-.003-.005-.005.066-.223.134-.445.191-.673 2.46-9.799-3.543-21.384-13.701-27.484 4.452 6.035 6.42 13.344 4.671 19.735-.156.571-.343 1.118-.55 1.65-.225-.148-.509-.316-.889-.526 0 0-10.104-6.238-21.055-17.273-.288-.29 5.839 8.757 12.793 16.104-3.276-1.839-12.406-8.482-18.186-13.772.71 1.185 1.555 2.325 2.483 3.423 4.827 6.121 11.121 13.673 18.662 19.473-5.298 3.242-12.785 3.494-20.239.003-1.844-.864-3.577-1.907-5.182-3.091 3.156 5.047 8.015 9.401 13.93 11.943 7.054 3.032 14.068 2.826 19.292.05l-.004.006c.024-.015.054-.031.079-.047.214-.115.427-.232.636-.356 2.51-1.303 7.467-2.625 10.129 2.553.651 1.267 2.036-5.448-3.055-11.713z"/></svg>';
 
-  // The masthead (.nav-content > .pre-title, .nav-title, .nav-menu) is
-  // rendered client-side by swift-docc-render (Vue), not present in this
-  // page's initial HTML, so it may not exist yet when this script runs —
-  // retry via MutationObserver until it mounts. Unlike the Navigator
-  // sidebar, the masthead has no loading-skeleton/real-content swap to
-  // race against: it mounts once from data already known at page load and
-  // stays, so this observer keeps running (harmlessly, guarded by the
-  // .masthead-swift-logo check below) rather than needing to disconnect at
-  // a precise moment.
-  //
-  // Appended as the last child of `.pre-title` rather than inserted as a
-  // sibling between `.pre-title` and `.nav-title`: swift-docc-render's own
-  // CSS assigns `.nav-title` its grid placement via the adjacent-sibling
-  // selector `.pre-title + .nav-title`, which requires them to stay
-  // immediate siblings. Landing inside `.pre-title` keeps that intact while
-  // still sitting visually between the sidebar toggle and the title text —
-  // and, being part of the persistent masthead rather than the sidebar
-  // itself, it stays visible regardless of whether the sidebar is shown,
-  // hidden, or a mobile drawer.
+  // Appended inside `.pre-title` rather than inserted as a sibling before
+  // `.nav-title`: swift-docc-render positions the title via the CSS rule
+  // `.pre-title + .nav-title`, which needs them to stay adjacent siblings.
+  // This keeps that intact while still landing between the sidebar toggle
+  // and the title — and, being part of the masthead rather than the
+  // sidebar, it stays visible regardless of the sidebar's own
+  // shown/hidden/drawer state.
   function insertLogoLink() {
     var preTitle = document.querySelector('.pre-title');
     if (!preTitle || preTitle.querySelector('.masthead-swift-logo')) {

From 2fa2bcb77533c9455ee5807ccb5746f9c0406997 Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 11:14:50 -0700
Subject: [PATCH 4/6] exploring variations of the logo and presentation

---
 common/header.html          | 10 ++++-----
 common/swift-logo-black.svg | 42 +++++++++++++++++++++++++++++++++++++
 common/swift-logo-color.svg |  4 ++++
 common/swift-logo-white.svg | 42 +++++++++++++++++++++++++++++++++++++
 4 files changed, 93 insertions(+), 5 deletions(-)
 create mode 100644 common/swift-logo-black.svg
 create mode 100644 common/swift-logo-color.svg
 create mode 100644 common/swift-logo-white.svg

diff --git a/common/header.html b/common/header.html
index f44161fe..8df356f2 100644
--- a/common/header.html
+++ b/common/header.html
@@ -12,10 +12,10 @@
 
 <script>
 (function () {
-  // Sourced from swiftlang/swift-org-website's assets/images/icon-swift.svg,
-  // the currentColor variant — fill="currentColor" below is added here since
-  // the upstream asset leaves it unset for consumers to apply.
-  var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="22" height="22" aria-hidden="true"><path fill="currentColor" fill-rule="nonzero" transform="matrix(.351937 0 0 .351937 -1.96558 -2.00601)" d="m46.955 36.578c-.002-.002-.003-.003-.005-.005.066-.223.134-.445.191-.673 2.46-9.799-3.543-21.384-13.701-27.484 4.452 6.035 6.42 13.344 4.671 19.735-.156.571-.343 1.118-.55 1.65-.225-.148-.509-.316-.889-.526 0 0-10.104-6.238-21.055-17.273-.288-.29 5.839 8.757 12.793 16.104-3.276-1.839-12.406-8.482-18.186-13.772.71 1.185 1.555 2.325 2.483 3.423 4.827 6.121 11.121 13.673 18.662 19.473-5.298 3.242-12.785 3.494-20.239.003-1.844-.864-3.577-1.907-5.182-3.091 3.156 5.047 8.015 9.401 13.93 11.943 7.054 3.032 14.068 2.826 19.292.05l-.004.006c.024-.015.054-.031.079-.047.214-.115.427-.232.636-.356 2.51-1.303 7.467-2.625 10.129 2.553.651 1.267 2.036-5.448-3.055-11.713z"/></svg>';
+  // Sourced from developer.apple.com/swift/resources/images/swift_logo_color.svg,
+  // the official full-color Swift mark. Sized to 22x22 to match the space
+  // the previous mono glyph occupied in the masthead.
+  var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 106.1 106.1" width="22" height="22" 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>';
 
   // Appended inside `.pre-title` rather than inserted as a sibling before
   // `.nav-title`: swift-docc-render positions the title via the CSS rule
@@ -42,7 +42,7 @@
   // masthead this targets lives outside this custom element's shadow tree,
   // in the app's regular (light) DOM.
   var style = document.createElement('style');
-  style.textContent = '.masthead-swift-logo{display:flex;align-items:center;padding-inline:8px;color:var(--color-text);}';
+  style.textContent = '.masthead-swift-logo{display:flex;align-items:center;padding-inline:8px;}';
   document.head.appendChild(style);
 
   if (!insertLogoLink()) {
diff --git a/common/swift-logo-black.svg b/common/swift-logo-black.svg
new file mode 100644
index 00000000..cf2cbb14
--- /dev/null
+++ b/common/swift-logo-black.svg
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 18.1.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="106.063px" height="106.063px" viewBox="0 0 106.063 106.063" enable-background="new 0 0 106.063 106.063"
+	 xml:space="preserve">
+<g>
+	<path fill="#000000" d="M106.059,29.378c-0.006-1.067-0.018-2.133-0.047-3.201c-0.062-2.323-0.199-4.667-0.612-6.966
+		c-0.419-2.334-1.104-4.504-2.183-6.625c-1.06-2.082-2.445-3.988-4.097-5.64c-1.652-1.652-3.557-3.037-5.64-4.097
+		c-2.118-1.078-4.289-1.763-6.621-2.182c-2.3-0.414-4.644-0.551-6.969-0.613c-1.067-0.029-2.134-0.041-3.201-0.048
+		C75.421,0,74.154,0,72.887,0H44.81H33.179c-1.267,0-2.534,0-3.8,0.007c-1.067,0.007-2.135,0.019-3.201,0.048
+		c-0.581,0.016-1.163,0.036-1.746,0.064c-1.748,0.084-3.499,0.239-5.222,0.549c-1.749,0.314-3.407,0.778-5.021,1.445
+		c-0.538,0.222-1.071,0.467-1.6,0.737c-1.562,0.795-3.025,1.773-4.355,2.909C7.789,6.138,7.361,6.534,6.948,6.947
+		C5.295,8.6,3.91,10.505,2.85,12.587c-1.079,2.12-1.763,4.291-2.183,6.625c-0.413,2.298-0.55,4.643-0.612,6.966
+		c-0.029,1.068-0.042,2.134-0.049,3.201C-0.001,30.645,0,31.912,0,33.179V50.47v22.418c0,1.268-0.001,2.534,0.007,3.802
+		c0.007,1.067,0.019,2.133,0.049,3.199c0.062,2.324,0.2,4.669,0.612,6.966c0.419,2.333,1.103,4.505,2.183,6.625
+		c1.06,2.083,2.445,3.988,4.097,5.639c1.651,1.653,3.557,3.038,5.641,4.099c2.119,1.078,4.289,1.762,6.621,2.181
+		c2.298,0.414,4.644,0.551,6.968,0.613c1.066,0.028,2.134,0.041,3.201,0.047c1.266,0.009,2.532,0.008,3.8,0.008h39.709
+		c1.266,0,2.534,0.001,3.8-0.008c1.067-0.006,2.133-0.019,3.201-0.047c2.325-0.062,4.669-0.2,6.969-0.613
+		c2.332-0.419,4.502-1.103,6.621-2.181c2.083-1.061,3.988-2.446,5.64-4.099c1.652-1.652,3.038-3.556,4.097-5.639
+		c1.079-2.12,1.764-4.292,2.183-6.625c0.413-2.297,0.55-4.642,0.612-6.966c0.029-1.066,0.041-2.132,0.047-3.199
+		c0.008-1.268,0.008-2.534,0.008-3.802V33.179C106.066,31.912,106.067,30.645,106.059,29.378z"/>
+	<path fill="#FFFFFF" d="M84.038,65.464c0.117-0.399,0.238-0.796,0.341-1.205c4.402-17.539-6.342-38.275-24.523-49.193
+		c7.968,10.801,11.49,23.883,8.36,35.324c-0.279,1.02-0.615,2-0.986,2.952c-0.403-0.264-0.91-0.565-1.591-0.94
+		c0,0-18.086-11.167-37.688-30.918c-0.514-0.519,10.453,15.675,22.899,28.824C44.987,47.016,28.646,35.126,18.3,25.658
+		c1.271,2.12,2.783,4.161,4.444,6.126c8.64,10.956,19.906,24.475,33.404,34.855c-9.484,5.804-22.885,6.255-36.227,0.006
+		c-3.3-1.547-6.403-3.413-9.274-5.533c5.648,9.034,14.347,16.828,24.934,21.379c12.625,5.426,25.18,5.058,34.531,0.089l-0.007,0.011
+		c0.032-0.02,0.067-0.041,0.1-0.061c0.42-0.225,0.836-0.457,1.242-0.7c4.517-2.319,13.331-4.607,18.067,4.609
+		c1.166,2.268,3.645-9.752-5.468-20.965C84.043,65.469,84.041,65.467,84.038,65.464z"/>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+</svg>
diff --git a/common/swift-logo-color.svg b/common/swift-logo-color.svg
new file mode 100644
index 00000000..8e8315cb
--- /dev/null
+++ b/common/swift-logo-color.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 106.1 106.1" width="22" height="22" 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>
diff --git a/common/swift-logo-white.svg b/common/swift-logo-white.svg
new file mode 100644
index 00000000..78122115
--- /dev/null
+++ b/common/swift-logo-white.svg
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 18.1.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="106.063px" height="106.063px" viewBox="0 0 106.063 106.063" enable-background="new 0 0 106.063 106.063"
+	 xml:space="preserve">
+<g>
+	<path fill="#FFFFFF" d="M106.059,29.378c-0.006-1.067-0.018-2.133-0.047-3.201c-0.062-2.323-0.199-4.667-0.612-6.966
+		c-0.419-2.334-1.104-4.504-2.183-6.625c-1.06-2.082-2.445-3.988-4.097-5.64c-1.652-1.652-3.557-3.037-5.64-4.097
+		c-2.118-1.078-4.289-1.763-6.621-2.182c-2.3-0.414-4.644-0.551-6.969-0.613c-1.067-0.029-2.134-0.041-3.201-0.048
+		C75.421,0,74.154,0,72.887,0H44.81H33.179c-1.267,0-2.534,0-3.8,0.007c-1.067,0.007-2.135,0.019-3.201,0.048
+		c-0.581,0.016-1.163,0.036-1.746,0.064c-1.748,0.084-3.499,0.239-5.222,0.549c-1.749,0.314-3.407,0.778-5.021,1.445
+		c-0.538,0.222-1.071,0.467-1.6,0.737c-1.562,0.795-3.025,1.773-4.355,2.909C7.789,6.138,7.361,6.534,6.948,6.947
+		C5.295,8.6,3.91,10.505,2.85,12.587c-1.079,2.12-1.763,4.291-2.183,6.625c-0.413,2.298-0.55,4.643-0.612,6.966
+		c-0.029,1.068-0.042,2.134-0.049,3.201C-0.001,30.645,0,31.912,0,33.179V50.47v22.418c0,1.268-0.001,2.534,0.007,3.802
+		c0.007,1.067,0.019,2.133,0.049,3.199c0.062,2.324,0.2,4.669,0.612,6.966c0.419,2.333,1.103,4.505,2.183,6.625
+		c1.06,2.083,2.445,3.988,4.097,5.639c1.651,1.653,3.557,3.038,5.641,4.099c2.119,1.078,4.289,1.762,6.621,2.181
+		c2.298,0.414,4.644,0.551,6.968,0.613c1.066,0.028,2.134,0.041,3.201,0.047c1.266,0.009,2.532,0.008,3.8,0.008h39.709
+		c1.266,0,2.534,0.001,3.8-0.008c1.067-0.006,2.133-0.019,3.201-0.047c2.325-0.062,4.669-0.2,6.969-0.613
+		c2.332-0.419,4.502-1.103,6.621-2.181c2.083-1.061,3.988-2.446,5.64-4.099c1.652-1.652,3.038-3.556,4.097-5.639
+		c1.079-2.12,1.764-4.292,2.183-6.625c0.413-2.297,0.55-4.642,0.612-6.966c0.029-1.066,0.041-2.132,0.047-3.199
+		c0.008-1.268,0.008-2.534,0.008-3.802V33.179C106.066,31.912,106.067,30.645,106.059,29.378z"/>
+	<path d="M84.038,65.464c0.117-0.399,0.238-0.796,0.341-1.205c4.402-17.539-6.342-38.275-24.523-49.193
+		c7.968,10.801,11.49,23.883,8.36,35.324c-0.279,1.02-0.615,2-0.986,2.952c-0.403-0.264-0.91-0.565-1.591-0.94
+		c0,0-18.086-11.167-37.688-30.918c-0.514-0.519,10.453,15.675,22.899,28.824C44.987,47.016,28.646,35.126,18.3,25.658
+		c1.271,2.12,2.783,4.161,4.444,6.126c8.64,10.956,19.906,24.475,33.404,34.855c-9.484,5.804-22.885,6.255-36.227,0.006
+		c-3.3-1.547-6.403-3.413-9.274-5.533c5.648,9.034,14.347,16.828,24.934,21.379c12.625,5.426,25.18,5.058,34.531,0.089l-0.007,0.011
+		c0.032-0.02,0.067-0.041,0.1-0.061c0.42-0.225,0.836-0.457,1.242-0.7c4.517-2.319,13.331-4.607,18.067,4.609
+		c1.166,2.268,3.645-9.752-5.468-20.965C84.043,65.469,84.041,65.467,84.038,65.464z"/>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+<g>
+</g>
+</svg>

From 75b3a6198a61701cab0bf084d66e8c7cdc4a7b3e Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 11:29:05 -0700
Subject: [PATCH 5/6] ignore the .svg in the license header checks

---
 .gitignore     | 1 +
 .licenseignore | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 184eff81..080debc2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,4 @@ Package.resolved
 **/*.docc/header.html
 **/*.docc/footer.html
 scripts/__pycache__/
+.playwright-cli/
diff --git a/.licenseignore b/.licenseignore
index 1a6520c1..2b8601ab 100644
--- a/.licenseignore
+++ b/.licenseignore
@@ -1,4 +1,5 @@
 **/*.gitkeep
 **/*.html
+**/*.svg
 **/Package.swift
 common/README

From e7cc9c198b4bcfefa000f7a479be1f25e2413b5e Mon Sep 17 00:00:00 2001
From: Joe Heck <j_heck@apple.com>
Date: Mon, 10 Aug 2026 11:39:06 -0700
Subject: [PATCH 6/6] Relabel the masthead nav-title from "Documentation" to
 "Swift"

swift-docc-render hardcodes this text to the documentation.title
locale string with no theme-settings.json or DocC metadata override
point, so it's rewritten client-side the same way the logo is inserted.
---
 common/header.html | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/common/header.html b/common/header.html
index 8df356f2..e0096ef3 100644
--- a/common/header.html
+++ b/common/header.html
@@ -38,6 +38,19 @@
     return true;
   }
 
+  // swift-docc-render hardcodes this text to the `documentation.title`
+  // locale string ("Documentation") in DocumentationTopic.vue — there's no
+  // theme-settings.json or DocC metadata hook for it, so it's overwritten
+  // here after render, the same way the logo above is inserted.
+  function relabelNavTitle() {
+    var navTitle = document.querySelector('.nav-title');
+    if (!navTitle || navTitle.textContent.trim() === 'Swift') {
+      return false;
+    }
+    navTitle.textContent = 'Swift';
+    return true;
+  }
+
   // Styled on the main document, not this template's own shadow root: the
   // masthead this targets lives outside this custom element's shadow tree,
   // in the app's regular (light) DOM.
@@ -45,8 +58,14 @@
   style.textContent = '.masthead-swift-logo{display:flex;align-items:center;padding-inline:8px;}';
   document.head.appendChild(style);
 
-  if (!insertLogoLink()) {
-    var observer = new MutationObserver(insertLogoLink);
+  function applyMastheadTweaks() {
+    var logoInserted = insertLogoLink();
+    var titleRelabeled = relabelNavTitle();
+    return logoInserted && titleRelabeled;
+  }
+
+  if (!applyMastheadTweaks()) {
+    var observer = new MutationObserver(applyMastheadTweaks);
     observer.observe(document.body, { childList: true, subtree: true });
   }
 })();