From 62ce70852a085c4d94dc4d1b9960f10cb6e3f62a Mon Sep 17 00:00:00 2001
From: connie-ooi <connieooi@google.com>
Date: Fri, 2 Oct 2026 15:52:44 -0700
Subject: [PATCH 01/14] Add dark mode theme switcher and styles to the Flutter
 blog

---
 .../blog/client/blog_categories.dart          |  47 ++-
 .../lib/components/layout/theme_switcher.dart | 145 +++++++--
 packages/site_shared/lib/server_util.dart     |   1 +
 .../lib/src/layouts/dash_layout.dart          |  20 +-
 .../lib/src/utils/theme_script.dart           |  56 ++++
 sites/www/lib/main.client.options.dart        |   6 +
 sites/www/lib/main.server.options.dart        |   5 +
 .../www/lib/src/components/layout/footer.dart |   7 +
 .../www/lib/src/components/layout/header.dart |   2 +
 sites/www/lib/src/layouts/blog_layout.dart    |  28 ++
 sites/www/lib/src/layouts/default_layout.dart |   8 +-
 sites/www/lib/styles/core/_vars.scss          |   5 +
 sites/www/lib/styles/pages/_blog_page.scss    | 292 +++++++++++++++++-
 sites/www/lib/styles/styles.scss              |   1 +
 14 files changed, 557 insertions(+), 66 deletions(-)
 create mode 100644 packages/site_shared/lib/src/utils/theme_script.dart

diff --git a/packages/site_shared/lib/components/blog/client/blog_categories.dart b/packages/site_shared/lib/components/blog/client/blog_categories.dart
index 2719bde8881..c24de0b78d1 100644
--- a/packages/site_shared/lib/components/blog/client/blog_categories.dart
+++ b/packages/site_shared/lib/components/blog/client/blog_categories.dart
@@ -61,7 +61,7 @@ class _BlogCategoriesState extends State<BlogCategories> {
   void initState() {
     super.initState();
     if (kIsWeb) {
-      _updateCategoryFromUrl();
+      _updateCategoryFromUrl(initial: true);
       _popStateSubscription = web.EventStreamProviders.popStateEvent
           .forTarget(web.window)
           .listen((_) => _updateCategoryFromUrl());
@@ -74,16 +74,26 @@ class _BlogCategoriesState extends State<BlogCategories> {
     super.dispose();
   }
 
-  void _updateCategoryFromUrl() {
+  void _updateCategoryFromUrl({bool initial = false}) {
     final uri = Uri.parse(web.window.location.href);
     final slug = uri.queryParameters['category'];
     final category = component.categories
         .where((c) => c.slug == slug)
         .firstOrNull;
 
-    setState(() {
+    if (initial) {
       selectedCategory = category;
-    });
+      if (category != null) {
+        _applyLayout(category);
+      }
+      return;
+    }
+
+    if (category != selectedCategory) {
+      setState(() {
+        selectedCategory = category;
+      });
+    }
     _applyLayout(category);
   }
 
@@ -107,7 +117,7 @@ class _BlogCategoriesState extends State<BlogCategories> {
     final container = web.document.getElementById('blog-container');
     if (container != null) {
       if (category == null) {
-        container.removeAttribute('data-selected');
+        container.setAttribute('data-selected', 'all');
       } else {
         container.setAttribute('data-selected', category.slug);
       }
@@ -121,22 +131,31 @@ class _BlogCategoriesState extends State<BlogCategories> {
         final cardCategory = card.getAttribute('data-category');
 
         final isVisible = category == null || cardCategory == category.slug;
-
-        // Remove existing layout classes.
-        card.classList.remove('layout-featured');
-        card.classList.remove('layout-grid');
-        card.classList.remove('layout-list');
-
+        String? targetClass;
         if (isVisible) {
           if (visibleCount == 0) {
-            card.classList.add('layout-featured');
+            targetClass = 'layout-featured';
           } else if (visibleCount < 5) {
-            card.classList.add('layout-grid');
+            targetClass = 'layout-grid';
           } else {
-            card.classList.add('layout-list');
+            targetClass = 'layout-list';
           }
           visibleCount++;
         }
+
+        for (final layoutClass in const [
+          'layout-featured',
+          'layout-grid',
+          'layout-list',
+        ]) {
+          if (layoutClass == targetClass) {
+            if (!card.classList.contains(layoutClass)) {
+              card.classList.add(layoutClass);
+            }
+          } else if (card.classList.contains(layoutClass)) {
+            card.classList.remove(layoutClass);
+          }
+        }
       }
     }
   }
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index a06e647c477..a9a0960265e 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:async';
+
 import 'package:jaspr/dom.dart';
 import 'package:jaspr/jaspr.dart';
 import 'package:universal_web/web.dart' as web;
@@ -18,6 +20,15 @@ final class ThemeSwitcher extends StatefulComponent {
   State<StatefulComponent> createState() => _ThemeSwitcherState();
 }
 
+/// A [ThemeSwitcher] variant for use inside an existing `@client` component,
+/// such as a client-hydrated header, to avoid nested `@client` anchors.
+final class NestedThemeSwitcher extends StatefulComponent {
+  const NestedThemeSwitcher({super.key});
+
+  @override
+  State<StatefulComponent> createState() => _ThemeSwitcherState();
+}
+
 enum _Theme {
   light('Light', 'Switch to the light theme.', 'light_mode'),
   dark('Dark', 'Switch to the dark theme.', 'dark_mode'),
@@ -32,46 +43,123 @@ enum _Theme {
   String get id => '$name-mode';
 }
 
-final class _ThemeSwitcherState extends State<ThemeSwitcher> {
+final class _ThemeSwitcherState extends State<StatefulComponent> {
   _Theme _currentTheme = _Theme.light;
+  StreamSubscription<web.Event>? _pageShowSubscription;
+  StreamSubscription<web.StorageEvent>? _storageSubscription;
+  StreamSubscription<web.Event>? _mediaQuerySubscription;
 
   @override
   void initState() {
+    super.initState();
     if (kIsWeb) {
-      final classList = web.document.body!.classList;
-      // If them theme is auto, it and the result will be added as classes.
-      // So it should be checked for first.
-      if (classList.contains(_Theme.auto.id)) {
-        _currentTheme = _Theme.auto;
-      } else if (classList.contains(_Theme.dark.id)) {
-        _currentTheme = _Theme.dark;
-      } else if (classList.contains(_Theme.light.id)) {
-        _currentTheme = _Theme.light;
-      } else {
-        // Default to light mode if no theme is set yet.
-        _currentTheme = _Theme.light;
-        classList.add(_Theme.light.id);
+      _syncThemeFromStorage();
+      _pageShowSubscription =
+          const web.EventStreamProvider<web.Event>(
+                'pageshow',
+              )
+              .forTarget(web.window)
+              .listen(
+                (_) => _syncThemeFromStorage(updateState: true),
+              );
+      _storageSubscription = web.EventStreamProviders.storageEvent
+          .forTarget(web.window)
+          .listen((_) => _syncThemeFromStorage(updateState: true));
+      _mediaQuerySubscription =
+          const web.EventStreamProvider<web.Event>(
+                'change',
+              )
+              .forTarget(web.window.matchMedia('(prefers-color-scheme: dark)'))
+              .listen(
+                (_) {
+                  if (_currentTheme == _Theme.auto) {
+                    _applyThemeToBody(_Theme.auto);
+                  }
+                },
+              );
+    }
+  }
+
+  @override
+  void dispose() {
+    unawaited(_pageShowSubscription?.cancel());
+    unawaited(_storageSubscription?.cancel());
+    unawaited(_mediaQuerySubscription?.cancel());
+    super.dispose();
+  }
+
+  _Theme _themeFromBodyClasses() {
+    final classList =
+        (web.document.body ?? web.document.documentElement)?.classList;
+    if (classList == null) return _Theme.light;
+    if (classList.contains(_Theme.auto.id)) {
+      return _Theme.auto;
+    } else if (classList.contains(_Theme.dark.id)) {
+      return _Theme.dark;
+    } else {
+      return _Theme.light;
+    }
+  }
+
+  void _applyThemeToBody(_Theme theme) {
+    final isAuto = theme == _Theme.auto;
+    final isDark = isAuto
+        ? web.window.matchMedia('(prefers-color-scheme: dark)').matches
+        : theme == _Theme.dark;
+    final resolvedId = isDark ? _Theme.dark.id : _Theme.light.id;
+    final oppositeId = isDark ? _Theme.light.id : _Theme.dark.id;
+
+    for (final element in [
+      web.document.documentElement,
+      web.document.body,
+    ]) {
+      if (element == null) continue;
+      final classList = element.classList;
+      if (classList.contains(resolvedId) &&
+          classList.contains(_Theme.auto.id) == isAuto &&
+          !classList.contains(oppositeId)) {
+        continue;
+      }
+      for (final mode in _Theme.values) {
+        classList.remove(mode.id);
+      }
+      classList.add(resolvedId);
+      if (isAuto) {
+        classList.add(_Theme.auto.id);
       }
     }
+  }
 
-    super.initState();
+  void _syncThemeFromStorage({bool updateState = false}) {
+    String? storedThemeId;
+    try {
+      storedThemeId = web.window.localStorage.getItem('theme');
+    } catch (_) {
+      // localStorage is not available, fall back to body classes.
+    }
+
+    final resolvedTheme = switch (storedThemeId) {
+      'auto-mode' => _Theme.auto,
+      'dark-mode' => _Theme.dark,
+      'light-mode' => _Theme.light,
+      _ => _themeFromBodyClasses(),
+    };
+
+    _applyThemeToBody(resolvedTheme);
+
+    if (updateState && resolvedTheme != _currentTheme) {
+      setState(() {
+        _currentTheme = resolvedTheme;
+      });
+    } else {
+      _currentTheme = resolvedTheme;
+    }
   }
 
   void _setTheme(_Theme newTheme) {
     if (newTheme == _currentTheme) return;
 
-    final classList = web.document.body!.classList;
-    for (final mode in _Theme.values) {
-      classList.remove(mode.id);
-    }
-    classList.add(newTheme.id);
-    if (newTheme == _Theme.auto) {
-      classList.add(
-        web.window.matchMedia('(prefers-color-scheme: dark)').matches
-            ? _Theme.dark.id
-            : _Theme.light.id,
-      );
-    }
+    _applyThemeToBody(newTheme);
 
     try {
       web.window.localStorage.setItem('theme', newTheme.id);
@@ -120,11 +208,12 @@ final class _ThemeButtonEntry extends StatelessComponent {
   final void Function(_Theme) setMode;
 
   @override
-  Component build(BuildContext _) => li([
+  Component build(BuildContext context) => li([
     button(
       events: {
         'click': (_) {
           setMode(mode);
+          context.findAncestorStateOfType<DropdownState>()?.toggle(to: false);
         },
       },
       attributes: {
diff --git a/packages/site_shared/lib/server_util.dart b/packages/site_shared/lib/server_util.dart
index be8240d576f..e8033128825 100644
--- a/packages/site_shared/lib/server_util.dart
+++ b/packages/site_shared/lib/server_util.dart
@@ -6,3 +6,4 @@
 library;
 
 export 'src/utils/cache_busted_build_asset_url.dart';
+export 'src/utils/theme_script.dart';
diff --git a/packages/site_shared/lib/src/layouts/dash_layout.dart b/packages/site_shared/lib/src/layouts/dash_layout.dart
index ddd2b23d172..2553ad6b63a 100644
--- a/packages/site_shared/lib/src/layouts/dash_layout.dart
+++ b/packages/site_shared/lib/src/layouts/dash_layout.dart
@@ -11,6 +11,7 @@ import 'package:jaspr_content/jaspr_content.dart';
 import '../../components/layout/banner.dart';
 import '../../util.dart';
 import '../utils/cache_busted_build_asset_url.dart';
+import '../utils/theme_script.dart';
 
 /// The base Jaspr Content layout for all sites.
 abstract class DashLayout implements PageLayout {
@@ -247,24 +248,7 @@ function glueCookieNotificationBarLoaded() {
           children: [
             // The theme setting logic should remain before other scripts to
             // avoid a flash of the initial theme on load.
-            const script(
-              content: '''
-try {
-  const storedTheme = window.localStorage.getItem('theme') ?? 'light-mode';
-  if (storedTheme === 'auto-mode') {
-    const prefersDarkMode = window.matchMedia('(prefers-color-scheme: dark)');
-    document.body.classList.add(
-        'auto-mode',
-        prefersDarkMode.matches ? 'dark-mode' : 'light-mode',
-    );
-  } else {
-    document.body.classList.add(storedTheme);
-  }
-} catch (e) {
-  // localStorage is not available, do nothing and fall back to default.
-}
-      ''',
-            ),
+            themeInitScript,
             const a(
               id: 'skip-to-main',
               classes: 'filled-button',
diff --git a/packages/site_shared/lib/src/utils/theme_script.dart b/packages/site_shared/lib/src/utils/theme_script.dart
new file mode 100644
index 00000000000..1367c2b9b04
--- /dev/null
+++ b/packages/site_shared/lib/src/utils/theme_script.dart
@@ -0,0 +1,56 @@
+// Copyright 2026, the Flutter authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that
+// can be found in the LICENSE file.
+
+import 'package:jaspr/dom.dart';
+import 'package:jaspr/jaspr.dart';
+
+/// Inline `<script>` component that defines and runs `applyStoredTheme()`
+/// to apply the user's saved theme preference (`light-mode`, `dark-mode`,
+/// or `auto-mode`) before the page paints, and keeps it synced across
+/// back/forward navigation (`pageshow`), tab storage updates (`storage`),
+/// and OS color scheme changes.
+const Component themeInitScript = script(
+  content: '''
+function applyStoredTheme() {
+  try {
+    const storedTheme = window.localStorage.getItem('theme') ?? 'light-mode';
+    const isAuto = storedTheme === 'auto-mode';
+    const isDark = isAuto
+        ? window.matchMedia('(prefers-color-scheme: dark)').matches
+        : storedTheme === 'dark-mode';
+    const resolvedTheme = isDark ? 'dark-mode' : 'light-mode';
+    const oppositeTheme = isDark ? 'light-mode' : 'dark-mode';
+    for (const el of [document.documentElement, document.body]) {
+      if (!el) continue;
+      if (
+        el.classList.contains(resolvedTheme) &&
+        el.classList.contains('auto-mode') === isAuto &&
+        !el.classList.contains(oppositeTheme)
+      ) {
+        continue;
+      }
+      el.classList.remove('light-mode', 'dark-mode', 'auto-mode');
+      if (isAuto) {
+        el.classList.add('auto-mode', resolvedTheme);
+      } else {
+        el.classList.add(resolvedTheme);
+      }
+    }
+  } catch (_) {
+    // localStorage is not available; fall back to default light theme.
+  }
+}
+applyStoredTheme();
+window.addEventListener('pageshow', applyStoredTheme);
+window.addEventListener('storage', applyStoredTheme);
+window
+    .matchMedia('(prefers-color-scheme: dark)')
+    .addEventListener('change', applyStoredTheme);
+''',
+);
+
+/// Inline `<script>` component that runs `applyStoredTheme()` immediately
+/// when `<body>` opens so `document.body` receives theme classes before
+/// any body content renders.
+const Component themeSyncBodyScript = script(content: 'applyStoredTheme();');
diff --git a/sites/www/lib/main.client.options.dart b/sites/www/lib/main.client.options.dart
index 1f8f128ec1c..6c4e57d89d0 100644
--- a/sites/www/lib/main.client.options.dart
+++ b/sites/www/lib/main.client.options.dart
@@ -48,6 +48,8 @@ import 'package:site_shared/components/common/client/copy_button.dart'
     deferred as _copy_button;
 import 'package:site_shared/components/dartpad/dartpad_injector.dart'
     deferred as _dartpad_injector;
+import 'package:site_shared/components/layout/theme_switcher.dart'
+    deferred as _theme_switcher;
 import 'package:site_shared/components/utils/component_ref.dart'
     as _component_ref;
 
@@ -237,5 +239,9 @@ ClientOptions get defaultClientOptions => ClientOptions(
       ),
       loader: _dartpad_injector.loadLibrary,
     ),
+    'site_shared:theme_switcher': ClientLoader(
+      (p) => _theme_switcher.ThemeSwitcher(),
+      loader: _theme_switcher.loadLibrary,
+    ),
   },
 );
diff --git a/sites/www/lib/main.server.options.dart b/sites/www/lib/main.server.options.dart
index 3a2002b0ab6..0784cfb61a0 100644
--- a/sites/www/lib/main.server.options.dart
+++ b/sites/www/lib/main.server.options.dart
@@ -44,6 +44,8 @@ import 'package:site_shared/components/common/client/copy_button.dart'
     as _copy_button;
 import 'package:site_shared/components/dartpad/dartpad_injector.dart'
     as _dartpad_injector;
+import 'package:site_shared/components/layout/theme_switcher.dart'
+    as _theme_switcher;
 
 /// Default [ServerOptions] for use with your Jaspr project.
 ///
@@ -150,6 +152,9 @@ ServerOptions get defaultServerOptions => ServerOptions(
           'site_shared:dartpad_injector',
           params: __dartpad_injectorDartPadInjector,
         ),
+    _theme_switcher.ThemeSwitcher: ClientTarget<_theme_switcher.ThemeSwitcher>(
+      'site_shared:theme_switcher',
+    ),
   },
   styles: () => [..._file_tree.FileTree.styles],
 );
diff --git a/sites/www/lib/src/components/layout/footer.dart b/sites/www/lib/src/components/layout/footer.dart
index 5fb206eaa67..f8d99a8f21d 100644
--- a/sites/www/lib/src/components/layout/footer.dart
+++ b/sites/www/lib/src/components/layout/footer.dart
@@ -17,10 +17,17 @@ class Footer extends StatelessComponent {
         div(classes: 'logo', [
           a(href: '/', [
             img(
+              classes: 'light-mode-visible',
               src: context.asset('/images/flutter-logo.svg'),
               width: 154,
               alt: 'Flutter',
             ),
+            img(
+              classes: 'dark-mode-visible',
+              src: context.asset('/images/flutter-logo-white.svg'),
+              width: 154,
+              alt: 'Flutter',
+            ),
           ]),
         ]),
         const div(classes: 'footer-links', [
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index 687a8eb904e..302f00f5fbf 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -6,6 +6,7 @@ import 'dart:async';
 
 import 'package:jaspr/dom.dart';
 import 'package:jaspr/jaspr.dart';
+import 'package:site_shared/components/layout/theme_switcher.dart';
 import 'package:universal_web/web.dart' as web;
 
 import '../../data/nav_items.dart';
@@ -224,6 +225,7 @@ class _HeaderState extends State<Header> {
                   ),
               ],
             ),
+            if (isBlog) const NestedThemeSwitcher(),
             const a(
               href: 'https://docs.flutter.dev/get-started/quick',
               id: 'get-started__header',
diff --git a/sites/www/lib/src/layouts/blog_layout.dart b/sites/www/lib/src/layouts/blog_layout.dart
index 394a6139076..abb499e616a 100644
--- a/sites/www/lib/src/layouts/blog_layout.dart
+++ b/sites/www/lib/src/layouts/blog_layout.dart
@@ -12,6 +12,7 @@ import 'package:site_shared/components/blog/blog_next_posts.dart';
 import 'package:site_shared/components/blog/post_info.dart';
 import 'package:site_shared/components/common/breadcrumbs.dart';
 import 'package:site_shared/components/common/client/back_to_top_button.dart';
+import 'package:site_shared/server_util.dart';
 import 'package:site_shared/util.dart';
 
 import '../utils/scroll_spy.dart';
@@ -28,6 +29,33 @@ class BlogLayout extends DefaultLayout {
   @override
   List<String> get defaultBodyTags => ['interior', 'blog'];
 
+  @override
+  List<Component> get leadingHeadElements => const [
+    Component.element(
+      tag: 'style',
+      children: [
+        .text(
+          'html.dark-mode, '
+          'html.dark-mode body.blog, '
+          'html.dark-mode body.blog main { '
+          'background-color: #121317; color: #dcdcdc; color-scheme: dark; '
+          '} '
+          'html.dark-mode body.blog '
+          'header.site-header:not(.mobile-nav-open), '
+          'html.dark-mode body.blog .site-footer { '
+          'background-color: #1c1e27; '
+          '}',
+        ),
+      ],
+    ),
+    themeInitScript,
+  ];
+
+  @override
+  List<Component> get leadingBodyElements => const [
+    themeSyncBodyScript,
+  ];
+
   @override
   Component buildLayout(Page page, Component child) {
     final pageData = page.data.page;
diff --git a/sites/www/lib/src/layouts/default_layout.dart b/sites/www/lib/src/layouts/default_layout.dart
index 744847ed3d0..1a1f38e29aa 100644
--- a/sites/www/lib/src/layouts/default_layout.dart
+++ b/sites/www/lib/src/layouts/default_layout.dart
@@ -20,6 +20,10 @@ class DefaultLayout extends PageLayout {
 
   List<String> get defaultBodyTags => const [];
 
+  List<Component> get leadingHeadElements => const [];
+
+  List<Component> get leadingBodyElements => const [];
+
   @override
   Component buildLayout(Page page, Component child) {
     final pageData = page.data.page;
@@ -66,6 +70,7 @@ class DefaultLayout extends PageLayout {
         return Document(
           title: documentTitle,
           head: [
+            ...leadingHeadElements,
             link(rel: 'icon', href: context.asset('/images/favicon.png')),
             link(
               rel: 'apple-touch-icon',
@@ -135,7 +140,7 @@ class DefaultLayout extends PageLayout {
               href:
                   'https://fonts.googleapis.com/css2?'
                   'family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@'
-                  '24,400,0..1,0',
+                  '24,400,0..1,0&display=block',
             ),
 
             const script(
@@ -208,6 +213,7 @@ class DefaultLayout extends PageLayout {
               Document.body(
                 attributes: {'class': bodyTags.join(' ')},
               ),
+            ...leadingBodyElements,
             Header(
               pageUrl: page.url,
               contrastLogoSrc: context.asset('/images/flutter-logo-white.svg'),
diff --git a/sites/www/lib/styles/core/_vars.scss b/sites/www/lib/styles/core/_vars.scss
index d9160e9f5f4..9270277b3db 100644
--- a/sites/www/lib/styles/core/_vars.scss
+++ b/sites/www/lib/styles/core/_vars.scss
@@ -83,9 +83,11 @@
   --site-base-fgColor-lighter: #{color.scale(#212121, $lightness: 20%)};
   --site-base-fgColor-alt: #6a6f71;
   --site-primary-color: #1967d2;
+  --site-primary-color-highlight: #{color.change(#0468d7, $alpha: 0.05)};
   --site-interaction-base-values: 0 0 0;
 
   --site-raised-bgColor: var(--grey-3);
+  --site-header-bgColor: var(--site-base-bgColor);
 
   --site-inset-bgColor: #f9fafb;
   --site-inset-fgColor: var(--site-base-fgColor);
@@ -101,6 +103,9 @@
   --site-secondaryContainer-bgColor: #c2e5ff;
   --site-secondaryContainer-fgColor: var(--site-base-fgColor);
 
+  --site-code-highlight-bgColor: rgba(255, 245, 156, 0.8);
+  --site-diagram-wrap-bgColor: #f8f9fa;
+
   --screen-xl-min: 1280px;
 
   --spacer-sm: 8px;
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index 019b6124c40..eaffc86cc68 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -1,15 +1,118 @@
+@use 'sass:color';
 @use 'package:site_shared/_sass/base/mixins';
 
+body:not(.blog.dark-mode, html.dark-mode .blog) .dark-mode-visible {
+  display: none !important;
+}
+
+body.blog {
+  background-color: var(--site-base-bgColor);
+  color: var(--site-base-fgColor);
+
+  &:is(.dark-mode, html.dark-mode &) {
+    color-scheme: dark;
+    --site-outline: rgba(95, 100, 119, 0.75);
+    --site-outline-variant: #252834;
+
+    --site-interaction-base-values: 255 255 255;
+
+    --site-base-bgColor: #121317;
+    --site-base-fgColor: #dcdcdc;
+    --site-base-fgColor-lighter: #{color.scale(#dcdcdc, $lightness: -25%)};
+    --site-base-fgColor-alt: #a8acad;
+
+    --site-raised-bgColor: #1c1e27;
+    --site-raised-bgColor-translucent: #{color.change(#1c1e27, $alpha: 0.4)};
+
+    --site-primary-color: #0468d7;
+    --site-primary-color-highlight: #{color.change(#0468d7, $alpha: 0.1)};
+
+    --site-secondaryContainer-bgColor: rgb(22 83 153);
+    --site-secondaryContainer-fgColor: var(--site-base-fgColor);
+
+    --site-inset-bgColor: #202731;
+    --site-inset-bgColor-translucent: rgba(32, 39, 49, 0.7);
+    --site-inset-fgColor: var(--site-base-fgColor);
+    --site-inset-borderColor: #485563;
+
+    --site-link-fgColor: #47b0f8;
+    --site-link-fgColor-active: #28a3f7;
+
+    --site-header-bgColor: var(--site-raised-bgColor);
+
+    --site-code-highlight-bgColor: rgba(164, 158, 62, 0.15);
+    --site-diagram-wrap-bgColor: #e1e6ea;
+
+    .opal,
+    .opal span {
+      color: var(--opal-dark-color) !important;
+      font-style: var(--opal-dark-font-style) !important;
+      font-weight: var(--opal-dark-font-weight) !important;
+      text-decoration: var(--opal-dark-text-decoration) !important;
+    }
+
+    .light-mode-visible {
+      display: none !important;
+    }
+
+    .theme-icon {
+      filter: invert(1) brightness(0.8);
+    }
+  }
+}
+
 .blog main {
   display: flex;
   flex-direction: row;
   justify-content: center;
+  background-color: var(--site-base-bgColor);
+  color: var(--site-base-fgColor);
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    color: var(--site-base-fgColor);
+  }
 
   > article {
     width: 60rem;
     max-width: 100%;
     min-width: 8rem;
 
+    img {
+      &.diagram-wrap {
+        background-color: var(--site-diagram-wrap-bgColor);
+        padding: 1rem;
+        border-radius: 1rem;
+      }
+
+      &.small-diagram-wrap {
+        background-color: var(--site-diagram-wrap-bgColor);
+        padding: 0.5rem;
+        border-radius: 0.5rem;
+      }
+    }
+
+    blockquote {
+      background-color: var(--site-inset-bgColor);
+      padding: 0.75rem 1rem;
+      border-left: solid 5px var(--site-inset-borderColor);
+      margin: 0;
+      margin-block-end: 1rem;
+
+      p {
+        margin-bottom: 0;
+      }
+    }
+
+    hr {
+      border: 1px solid var(--site-outline-variant);
+      border-radius: 1rem;
+    }
+
     .post-info .post-info-actions {
       a,
       button {
@@ -22,7 +125,7 @@
 
         &:hover {
           text-decoration: none;
-          background: rgba(0, 0, 0, 0.06);
+          @include mixins.interaction-style(6%);
         }
       }
     }
@@ -41,8 +144,6 @@
 
     // Styles extracted from _button.scss until the www site can import it.
     .code-block-wrapper .code-block-body .copy-button {
-      --site-interaction-base-values: 0 0 0;
-
       display: flex;
       align-items: center;
       width: fit-content;
@@ -86,14 +187,32 @@
 }
 
 :where(.blog main) a {
-  color: var(--site-primary-color);
+  color: var(--site-link-fgColor);
 
   &:hover {
     text-decoration: underline;
   }
+
+  &:active {
+    color: var(--site-link-fgColor-active);
+  }
+}
+
+:where(.blog main) p {
+  color: var(--site-base-fgColor);
+}
+
+body.blog header.site-header:not(.mobile-nav-open) {
+  transition: box-shadow 200ms;
+
+  nav,
+  nav > ul > li a.btn,
+  .icon-btn {
+    transition: none;
+  }
 }
 
-.blog header {
+.blog header.site-header {
   .subtype {
     padding: 0 0.3rem;
     font-size: 1.25rem;
@@ -105,6 +224,169 @@
     margin-left: 0.4rem;
     letter-spacing: normal;
   }
+
+  #theme-switcher {
+    display: inline-flex;
+    align-items: center;
+
+    > button.icon-button {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: var(--ui-btn-height);
+      height: var(--ui-btn-height);
+      border-radius: var(--ui-border-radius);
+      color: var(--grey-6);
+      cursor: pointer;
+      user-select: none;
+      border: none;
+      background: none;
+      padding: 0;
+
+      &:hover,
+      &[aria-expanded='true'] {
+        background-color: var(--grey-1);
+      }
+    }
+
+    > .dropdown-content {
+      font-family: var(--site-ui-fontFamily);
+      font-size: 1rem;
+      top: calc(100% + 0.25rem);
+
+      button {
+        color: var(--site-base-fgColor);
+        border: none;
+        cursor: pointer;
+      }
+    }
+  }
+
+  &.mobile-nav-open,
+  &.searching {
+    #theme-switcher {
+      display: none;
+    }
+  }
+
+  @media (min-width: 1024px) and (any-hover: hover) {
+    .search {
+      margin-right: 0.25rem;
+    }
+
+    #theme-switcher {
+      margin-right: var(--gutter-sm);
+    }
+  }
+}
+
+:is(body.blog.dark-mode, html.dark-mode body.blog) {
+  header.site-header:not(.mobile-nav-open) {
+    background-color: var(--site-header-bgColor);
+    border-bottom: 1px solid var(--site-outline-variant);
+
+    .logo {
+      &.logo-contrast {
+        display: block;
+      }
+
+      &.logo-default {
+        display: none;
+      }
+    }
+
+    nav {
+      color: var(--site-base-fgColor);
+
+      > ul > li {
+        a.btn {
+          color: var(--site-base-fgColor);
+
+          &:hover {
+            background-color: rgb(var(--site-interaction-base-values) / 8%);
+            color: var(--site-link-fgColor);
+          }
+
+          &.active {
+            color: var(--site-link-fgColor);
+          }
+        }
+
+        .dd {
+          background-color: var(--site-raised-bgColor);
+          border: 1px solid var(--site-outline-variant);
+
+          ul li a.btn {
+            color: var(--site-base-fgColor-alt);
+
+            &:hover,
+            &:active {
+              background-color: rgb(var(--site-interaction-base-values) / 8%);
+              color: var(--site-base-fgColor);
+            }
+          }
+        }
+      }
+    }
+
+    .icon-btn,
+    #theme-switcher > button.icon-button {
+      color: var(--site-base-fgColor-alt);
+
+      &:hover,
+      &.active,
+      &[aria-expanded='true'] {
+        background-color: rgb(var(--site-interaction-base-values) / 8%);
+        color: var(--site-base-fgColor);
+      }
+    }
+
+    .search {
+      form input {
+        color: var(--site-base-fgColor);
+
+        &::placeholder {
+          color: var(--site-base-fgColor-alt);
+        }
+      }
+
+      &.active {
+        background-color: var(--site-inset-bgColor);
+      }
+    }
+  }
+
+  .site-footer {
+    background-color: var(--site-raised-bgColor);
+    color: var(--site-base-fgColor-alt);
+
+    ul a {
+      color: var(--site-base-fgColor-alt);
+
+      &:hover {
+        color: var(--site-base-fgColor);
+      }
+    }
+
+    .footer-links ul li:first-child {
+      color: var(--site-base-fgColor);
+    }
+
+    .content.footer-social {
+      border-bottom-color: var(--site-outline-variant);
+
+      > div {
+        a,
+        span {
+          color: var(--site-base-fgColor-alt);
+        }
+
+        a:hover {
+          color: var(--site-base-fgColor);
+        }
+      }
+    }
+  }
 }
 
 .blog .back-to-top {
diff --git a/sites/www/lib/styles/styles.scss b/sites/www/lib/styles/styles.scss
index 966964cb6bd..0e94f1178c4 100644
--- a/sites/www/lib/styles/styles.scss
+++ b/sites/www/lib/styles/styles.scss
@@ -54,3 +54,4 @@
 @use 'package:site_shared/_sass/components/cookie-notice';
 @use 'package:site_shared/_sass/components/dropdown';
 @use 'package:site_shared/_sass/components/mermaid';
+@use 'package:site_shared/_sass/components/theming';

From 4467bf74ef7619f151f5d88976504ba19f2e8de4 Mon Sep 17 00:00:00 2001
From: connie-ooi <connieooi@google.com>
Date: Mon, 5 Oct 2026 11:22:44 -0700
Subject: [PATCH 02/14] Fix dark mode logo

---
 .../lib/components/layout/theme_switcher.dart |  2 ++
 .../www/content/images/flutter-logo-dark.svg  | 35 +++++++++++++++++++
 sites/www/lib/main.client.options.dart        |  1 +
 sites/www/lib/main.server.options.dart        |  1 +
 .../www/lib/src/components/layout/footer.dart |  2 +-
 .../www/lib/src/components/layout/header.dart | 16 ++++++++-
 sites/www/lib/src/layouts/default_layout.dart |  3 ++
 sites/www/lib/styles/pages/_blog_page.scss    | 10 ------
 8 files changed, 58 insertions(+), 12 deletions(-)
 create mode 100644 sites/www/content/images/flutter-logo-dark.svg

diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index a9a0960265e..b7bdd9a3c86 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -82,6 +82,8 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
 
   @override
   void dispose() {
+    // DOM event stream cancellations complete synchronously and don't need to
+    // be awaited in synchronous lifecycle teardown.
     unawaited(_pageShowSubscription?.cancel());
     unawaited(_storageSubscription?.cancel());
     unawaited(_mediaQuerySubscription?.cancel());
diff --git a/sites/www/content/images/flutter-logo-dark.svg b/sites/www/content/images/flutter-logo-dark.svg
new file mode 100644
index 00000000000..2a31ae4c1a5
--- /dev/null
+++ b/sites/www/content/images/flutter-logo-dark.svg
@@ -0,0 +1,35 @@
+<svg width="156" height="44" viewBox="0 0 156 44" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g clip-path="url(#clip0)">
+<path d="M54.9348 9.12305H69.5877V11.9923H57.9155V20.6559H68.4455V23.4973H57.9155V34.473H54.9348V9.12305Z" fill="white"/>
+<path d="M73.1255 9.12305H76.1341V34.4452H73.1255V9.12305Z" fill="white"/>
+<path d="M82.1793 33.1083C81.0372 31.8269 80.4521 30.044 80.4521 27.7598V16.394H83.4607V27.2862C83.4607 29.0133 83.8507 30.2669 84.6307 31.0748C85.4107 31.8826 86.4693 32.2726 87.7786 32.2726C88.7814 32.2726 89.7007 31.994 90.4807 31.4648C91.2607 30.9355 91.8736 30.2112 92.3193 29.3476C92.765 28.484 92.96 27.5648 92.96 26.5898V16.394H95.9964V34.4455H93.1271V31.8269H92.9879C92.4864 32.7183 91.7064 33.4705 90.62 34.0833C89.5336 34.6962 88.3914 35.0026 87.1657 35.0026C84.965 35.0305 83.3214 34.3898 82.1793 33.1083Z" fill="white"/>
+<path d="M105.523 34.668C104.911 34.4173 104.381 34.1109 103.936 33.693C103.462 33.2473 103.1 32.718 102.877 32.1052C102.654 31.4923 102.515 30.768 102.515 29.9045V19.1238H99.3669V16.3938H102.515V11.2959H105.523V16.3938H109.925V19.1238H105.551V29.1802C105.551 30.183 105.746 30.9352 106.108 31.4088C106.554 31.938 107.195 32.2166 108.058 32.2166C108.755 32.2166 109.396 32.0216 110.036 31.6038V34.5288C109.674 34.6959 109.312 34.8073 108.95 34.8909C108.588 34.9745 108.114 35.0023 107.557 35.0023C106.833 35.0302 106.136 34.8909 105.523 34.668Z" fill="white"/>
+<path d="M118.282 34.668C117.669 34.4173 117.14 34.1109 116.694 33.693C116.22 33.2473 115.858 32.718 115.635 32.1052C115.413 31.4923 115.273 30.768 115.273 29.9045V19.1238H112.153V16.3938H115.301V11.2959H118.31V16.3938H122.683V19.1238H118.31V29.1802C118.31 30.183 118.505 30.9352 118.867 31.4088C119.313 31.938 119.953 32.2166 120.817 32.2166C121.513 32.2166 122.154 32.0216 122.795 31.6038V34.5288C122.433 34.6959 122.07 34.8073 121.708 34.8909C121.346 34.9745 120.873 35.0023 120.315 35.0023C119.591 35.0302 118.923 34.8909 118.282 34.668Z" fill="white"/>
+<path d="M128.952 33.7769C127.587 32.9412 126.528 31.8269 125.748 30.3505C124.968 28.9019 124.606 27.2584 124.606 25.4477C124.606 23.6927 124.968 22.1048 125.692 20.6284C126.417 19.1798 127.42 18.0098 128.757 17.1184C130.066 16.2548 131.598 15.8091 133.353 15.8091C135.108 15.8091 136.668 16.1991 137.95 17.0069C139.259 17.7869 140.234 18.9012 140.93 20.2662C141.627 21.6591 141.961 23.2469 141.961 25.0298C141.961 25.3919 141.933 25.6984 141.85 25.9491H127.587C127.67 27.3141 127.977 28.4841 128.59 29.4034C129.175 30.3505 129.927 31.0469 130.846 31.5205C131.765 31.9941 132.712 32.2169 133.687 32.2169C136 32.2169 137.782 31.1305 139.036 28.9577L141.571 30.1834C140.791 31.6319 139.732 32.8019 138.395 33.6377C137.058 34.4734 135.442 34.9191 133.576 34.9191C131.877 35.0305 130.317 34.6127 128.952 33.7769ZM138.785 23.5255C138.73 22.7734 138.535 22.0212 138.145 21.2691C137.755 20.5169 137.17 19.8762 136.362 19.3469C135.554 18.8177 134.523 18.5669 133.297 18.5669C131.877 18.5669 130.679 19.0127 129.704 19.9319C128.729 20.8512 128.088 22.0491 127.782 23.5255H138.785Z" fill="white"/>
+<path d="M145.471 16.4219H148.34V19.3191H148.479C148.841 18.3162 149.51 17.5083 150.541 16.8398C151.544 16.1712 152.602 15.8369 153.716 15.8369C154.552 15.8369 155.249 15.9762 155.834 16.2269V19.4583C155.081 19.0683 154.218 18.9012 153.299 18.9012C152.435 18.9012 151.627 19.1519 150.903 19.6533C150.179 20.1548 149.594 20.8233 149.148 21.6591C148.702 22.4948 148.507 23.4141 148.507 24.3612V34.4733H145.499V16.4219H145.471Z" fill="white"/>
+<rect x="9.89282" y="18.0063" width="31.3277" height="24.4208" fill="url(#pattern0)"/>
+<path d="M37.0631 20.0376H23.7056L12.0195 31.7265L18.6969 38.4038L37.0631 20.0376Z" fill="#54C5F8"/>
+<path d="M8.68014 28.3864L2 21.7063L23.7063 0H37.0638L8.68014 28.3864Z" fill="#54C5F8"/>
+<path d="M18.6975 38.4039L23.7062 43.4126H37.0637L25.3749 31.7266L18.6975 38.4039Z" fill="#01579B"/>
+<path d="M18.6975 38.4039L28.6035 34.9747L25.3749 31.7266L18.6975 38.4039Z" fill="url(#paint0_linear)"/>
+<path d="M18.6966 25.0456L12.019 31.7231L18.6966 38.4007L25.3741 31.7231L18.6966 25.0456Z" fill="#29B6F6"/>
+<path d="M37.0638 20.0376L25.3777 31.7237L37.0638 43.4126H23.7063L18.6976 38.4039L12.0174 31.7237L23.7063 20.0376H37.0638ZM23.7063 0L2 21.7063L8.68014 28.3864L37.0638 0H23.7063Z" fill="url(#paint1_radial)"/>
+</g>
+<defs>
+<pattern id="pattern0" patternContentUnits="objectBoundingBox" width="1" height="1">
+<use xlink:href="#image0"/>
+</pattern>
+<linearGradient id="paint0_linear" x1="20.6447" y1="39.6934" x2="25.6192" y2="34.7189" gradientUnits="userSpaceOnUse">
+<stop stop-color="#1A237E" stop-opacity="0.4"/>
+<stop offset="1" stop-color="#1A237E" stop-opacity="0"/>
+</linearGradient>
+<radialGradient id="paint1_radial" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(2.98664 2.95995) scale(53.1128)">
+<stop stop-color="white" stop-opacity="0.1"/>
+<stop offset="1" stop-color="white" stop-opacity="0"/>
+</radialGradient>
+<clipPath id="clip0">
+<rect width="156" height="43.641" fill="white"/>
+</clipPath>
+<image id="image0" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAABkCAYAAABO6zhfAAAACXBIWXMAAAx0AAAMdAH/P3aRAAAA"/>
+</defs>
+</svg>
diff --git a/sites/www/lib/main.client.options.dart b/sites/www/lib/main.client.options.dart
index 6c4e57d89d0..18af5101b56 100644
--- a/sites/www/lib/main.client.options.dart
+++ b/sites/www/lib/main.client.options.dart
@@ -106,6 +106,7 @@ ClientOptions get defaultClientOptions => ClientOptions(
       (p) => _header.Header(
         contrastLogoSrc: p['contrastLogoSrc'] as String,
         defaultLogoSrc: p['defaultLogoSrc'] as String,
+        darkLogoSrc: p['darkLogoSrc'] as String?,
         banner: _banner_content.BannerContent.fromJson(
           p['banner'] as Map<String, Object?>,
         ),
diff --git a/sites/www/lib/main.server.options.dart b/sites/www/lib/main.server.options.dart
index 0784cfb61a0..f99bbbdf601 100644
--- a/sites/www/lib/main.server.options.dart
+++ b/sites/www/lib/main.server.options.dart
@@ -173,6 +173,7 @@ Map<String, Object?> __tabsTabs(_tabs.Tabs c) => {
 Map<String, Object?> __headerHeader(_header.Header c) => {
   'contrastLogoSrc': c.contrastLogoSrc,
   'defaultLogoSrc': c.defaultLogoSrc,
+  'darkLogoSrc': c.darkLogoSrc,
   'banner': c.banner.toMap(),
   'pageUrl': c.pageUrl,
 };
diff --git a/sites/www/lib/src/components/layout/footer.dart b/sites/www/lib/src/components/layout/footer.dart
index f8d99a8f21d..a15ae54bb8d 100644
--- a/sites/www/lib/src/components/layout/footer.dart
+++ b/sites/www/lib/src/components/layout/footer.dart
@@ -24,7 +24,7 @@ class Footer extends StatelessComponent {
             ),
             img(
               classes: 'dark-mode-visible',
-              src: context.asset('/images/flutter-logo-white.svg'),
+              src: context.asset('/images/flutter-logo-dark.svg'),
               width: 154,
               alt: 'Flutter',
             ),
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index 302f00f5fbf..8227e0240c0 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -22,12 +22,14 @@ class Header extends StatefulComponent {
     super.key,
     required this.contrastLogoSrc,
     required this.defaultLogoSrc,
+    this.darkLogoSrc,
     required this.banner,
     required this.pageUrl,
   });
 
   final String contrastLogoSrc;
   final String defaultLogoSrc;
+  final String? darkLogoSrc;
   final BannerContent banner;
   final String pageUrl;
 
@@ -164,7 +166,19 @@ class _HeaderState extends State<Header> {
             ]),
             div(classes: 'logo logo-default', [
               a(href: '/', [
-                img(src: component.defaultLogoSrc, alt: 'Flutter'),
+                img(
+                  classes: component.darkLogoSrc != null
+                      ? 'light-mode-visible'
+                      : null,
+                  src: component.defaultLogoSrc,
+                  alt: 'Flutter',
+                ),
+                if (component.darkLogoSrc case final darkLogoSrc?)
+                  img(
+                    classes: 'dark-mode-visible',
+                    src: darkLogoSrc,
+                    alt: 'Flutter',
+                  ),
               ]),
             ]),
             if (isBlog)
diff --git a/sites/www/lib/src/layouts/default_layout.dart b/sites/www/lib/src/layouts/default_layout.dart
index 1a1f38e29aa..b68691e5ecf 100644
--- a/sites/www/lib/src/layouts/default_layout.dart
+++ b/sites/www/lib/src/layouts/default_layout.dart
@@ -218,6 +218,9 @@ class DefaultLayout extends PageLayout {
               pageUrl: page.url,
               contrastLogoSrc: context.asset('/images/flutter-logo-white.svg'),
               defaultLogoSrc: context.asset('/images/flutter-logo.svg'),
+              darkLogoSrc: page.url.startsWith('/blog')
+                  ? context.asset('/images/flutter-logo-dark.svg')
+                  : null,
               banner: banner,
             ),
             child,
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index eaffc86cc68..164dc195b17 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -285,16 +285,6 @@ body.blog header.site-header:not(.mobile-nav-open) {
     background-color: var(--site-header-bgColor);
     border-bottom: 1px solid var(--site-outline-variant);
 
-    .logo {
-      &.logo-contrast {
-        display: block;
-      }
-
-      &.logo-default {
-        display: none;
-      }
-    }
-
     nav {
       color: var(--site-base-fgColor);
 

From 743e9a62a64c45b96cd966b0b3e4a3456d9051e5 Mon Sep 17 00:00:00 2001
From: connie-ooi <connieooi@google.com>
Date: Mon, 5 Oct 2026 15:10:27 -0700
Subject: [PATCH 03/14] Add improvements based on feedback

---
 .../lib/_sass/components/_blog.scss           |   8 +-
 .../lib/components/layout/theme_switcher.dart |  41 ++-
 .../lib/src/utils/theme_script.dart           |  58 ++---
 sites/www/lib/main.client.options.dart        |   2 +-
 .../www/lib/src/components/layout/header.dart |  19 +-
 sites/www/lib/src/layouts/blog_layout.dart    |  26 +-
 sites/www/lib/src/layouts/default_layout.dart |  10 +-
 sites/www/lib/styles/components/_footer.scss  |  18 +-
 sites/www/lib/styles/components/_header.scss  |  52 ++--
 .../styles/components/_theme-switcher.scss    |  70 ++++++
 sites/www/lib/styles/core/_base.scss          |   4 +-
 sites/www/lib/styles/core/_vars.scss          |  45 ++++
 sites/www/lib/styles/pages/_blog_page.scss    | 234 ------------------
 sites/www/lib/styles/styles.scss              |   1 +
 14 files changed, 216 insertions(+), 372 deletions(-)
 create mode 100644 sites/www/lib/styles/components/_theme-switcher.scss

diff --git a/packages/site_shared/lib/_sass/components/_blog.scss b/packages/site_shared/lib/_sass/components/_blog.scss
index eb8e688cd25..b5fb65854e7 100644
--- a/packages/site_shared/lib/_sass/components/_blog.scss
+++ b/packages/site_shared/lib/_sass/components/_blog.scss
@@ -163,7 +163,7 @@
       text-decoration: none;
 
       &:hover {
-        color: var(--site-primary-color);
+        color: var(--site-link-fgColor);
       }
     }
   }
@@ -238,7 +238,7 @@
       &:hover {
         transform: translateY(-4px);
         box-shadow: 0 10px 20px -5px rgba(0, 0, 0, 0.1);
-        border-color: var(--site-primary-color);
+        border-color: var(--site-link-fgColor);
       }
 
       .blog-card-image {
@@ -371,7 +371,7 @@
     display: block;
 
     &:hover .post-info-name {
-      color: var(--site-primary-color);
+      color: var(--site-link-fgColor);
     }
   }
 
@@ -485,7 +485,7 @@
         color: var(--site-base-fgColor);
 
         &:hover {
-          color: var(--site-primary-color);
+          color: var(--site-link-fgColor);
         }
       }
     }
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index b7bdd9a3c86..4e025630f8c 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -64,7 +64,11 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
               );
       _storageSubscription = web.EventStreamProviders.storageEvent
           .forTarget(web.window)
-          .listen((_) => _syncThemeFromStorage(updateState: true));
+          .listen((event) {
+            if (event.key == null || event.key == 'theme') {
+              _syncThemeFromStorage(updateState: true);
+            }
+          });
       _mediaQuerySubscription =
           const web.EventStreamProvider<web.Event>(
                 'change',
@@ -91,8 +95,7 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
   }
 
   _Theme _themeFromBodyClasses() {
-    final classList =
-        (web.document.body ?? web.document.documentElement)?.classList;
+    final classList = web.document.body?.classList;
     if (classList == null) return _Theme.light;
     if (classList.contains(_Theme.auto.id)) {
       return _Theme.auto;
@@ -104,6 +107,9 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
   }
 
   void _applyThemeToBody(_Theme theme) {
+    final classList = web.document.body?.classList;
+    if (classList == null) return;
+
     final isAuto = theme == _Theme.auto;
     final isDark = isAuto
         ? web.window.matchMedia('(prefers-color-scheme: dark)').matches
@@ -111,24 +117,17 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
     final resolvedId = isDark ? _Theme.dark.id : _Theme.light.id;
     final oppositeId = isDark ? _Theme.light.id : _Theme.dark.id;
 
-    for (final element in [
-      web.document.documentElement,
-      web.document.body,
-    ]) {
-      if (element == null) continue;
-      final classList = element.classList;
-      if (classList.contains(resolvedId) &&
-          classList.contains(_Theme.auto.id) == isAuto &&
-          !classList.contains(oppositeId)) {
-        continue;
-      }
-      for (final mode in _Theme.values) {
-        classList.remove(mode.id);
-      }
-      classList.add(resolvedId);
-      if (isAuto) {
-        classList.add(_Theme.auto.id);
-      }
+    if (classList.contains(resolvedId) &&
+        classList.contains(_Theme.auto.id) == isAuto &&
+        !classList.contains(oppositeId)) {
+      return;
+    }
+    for (final mode in _Theme.values) {
+      classList.remove(mode.id);
+    }
+    classList.add(resolvedId);
+    if (isAuto) {
+      classList.add(_Theme.auto.id);
     }
   }
 
diff --git a/packages/site_shared/lib/src/utils/theme_script.dart b/packages/site_shared/lib/src/utils/theme_script.dart
index 1367c2b9b04..7ad6459d3d0 100644
--- a/packages/site_shared/lib/src/utils/theme_script.dart
+++ b/packages/site_shared/lib/src/utils/theme_script.dart
@@ -5,52 +5,22 @@
 import 'package:jaspr/dom.dart';
 import 'package:jaspr/jaspr.dart';
 
-/// Inline `<script>` component that defines and runs `applyStoredTheme()`
-/// to apply the user's saved theme preference (`light-mode`, `dark-mode`,
-/// or `auto-mode`) before the page paints, and keeps it synced across
-/// back/forward navigation (`pageshow`), tab storage updates (`storage`),
-/// and OS color scheme changes.
+/// Inline `<script>` component that applies the user's saved theme preference
+/// (`light-mode`, `dark-mode`, or `auto-mode`) to `document.body` before the
+/// page paints.
 const Component themeInitScript = script(
   content: '''
-function applyStoredTheme() {
-  try {
-    const storedTheme = window.localStorage.getItem('theme') ?? 'light-mode';
-    const isAuto = storedTheme === 'auto-mode';
-    const isDark = isAuto
-        ? window.matchMedia('(prefers-color-scheme: dark)').matches
-        : storedTheme === 'dark-mode';
-    const resolvedTheme = isDark ? 'dark-mode' : 'light-mode';
-    const oppositeTheme = isDark ? 'light-mode' : 'dark-mode';
-    for (const el of [document.documentElement, document.body]) {
-      if (!el) continue;
-      if (
-        el.classList.contains(resolvedTheme) &&
-        el.classList.contains('auto-mode') === isAuto &&
-        !el.classList.contains(oppositeTheme)
-      ) {
-        continue;
-      }
-      el.classList.remove('light-mode', 'dark-mode', 'auto-mode');
-      if (isAuto) {
-        el.classList.add('auto-mode', resolvedTheme);
-      } else {
-        el.classList.add(resolvedTheme);
-      }
-    }
-  } catch (_) {
-    // localStorage is not available; fall back to default light theme.
-  }
+try {
+  const storedTheme = window.localStorage.getItem('theme') ?? 'light-mode';
+  const isAuto = storedTheme === 'auto-mode';
+  const isDark = isAuto
+      ? window.matchMedia('(prefers-color-scheme: dark)').matches
+      : storedTheme === 'dark-mode';
+  document.body.classList.remove('light-mode', 'dark-mode', 'auto-mode');
+  document.body.classList.add(isDark ? 'dark-mode' : 'light-mode');
+  if (isAuto) document.body.classList.add('auto-mode');
+} catch (_) {
+  // localStorage is not available; fall back to default light theme.
 }
-applyStoredTheme();
-window.addEventListener('pageshow', applyStoredTheme);
-window.addEventListener('storage', applyStoredTheme);
-window
-    .matchMedia('(prefers-color-scheme: dark)')
-    .addEventListener('change', applyStoredTheme);
 ''',
 );
-
-/// Inline `<script>` component that runs `applyStoredTheme()` immediately
-/// when `<body>` opens so `document.body` receives theme classes before
-/// any body content renders.
-const Component themeSyncBodyScript = script(content: 'applyStoredTheme();');
diff --git a/sites/www/lib/main.client.options.dart b/sites/www/lib/main.client.options.dart
index 18af5101b56..d9c7a5079e5 100644
--- a/sites/www/lib/main.client.options.dart
+++ b/sites/www/lib/main.client.options.dart
@@ -106,7 +106,7 @@ ClientOptions get defaultClientOptions => ClientOptions(
       (p) => _header.Header(
         contrastLogoSrc: p['contrastLogoSrc'] as String,
         defaultLogoSrc: p['defaultLogoSrc'] as String,
-        darkLogoSrc: p['darkLogoSrc'] as String?,
+        darkLogoSrc: p['darkLogoSrc'] as String,
         banner: _banner_content.BannerContent.fromJson(
           p['banner'] as Map<String, Object?>,
         ),
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index 8227e0240c0..3dd7923dc8b 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -22,14 +22,14 @@ class Header extends StatefulComponent {
     super.key,
     required this.contrastLogoSrc,
     required this.defaultLogoSrc,
-    this.darkLogoSrc,
+    required this.darkLogoSrc,
     required this.banner,
     required this.pageUrl,
   });
 
   final String contrastLogoSrc;
   final String defaultLogoSrc;
-  final String? darkLogoSrc;
+  final String darkLogoSrc;
   final BannerContent banner;
   final String pageUrl;
 
@@ -167,18 +167,15 @@ class _HeaderState extends State<Header> {
             div(classes: 'logo logo-default', [
               a(href: '/', [
                 img(
-                  classes: component.darkLogoSrc != null
-                      ? 'light-mode-visible'
-                      : null,
+                  classes: 'light-mode-visible',
                   src: component.defaultLogoSrc,
                   alt: 'Flutter',
                 ),
-                if (component.darkLogoSrc case final darkLogoSrc?)
-                  img(
-                    classes: 'dark-mode-visible',
-                    src: darkLogoSrc,
-                    alt: 'Flutter',
-                  ),
+                img(
+                  classes: 'dark-mode-visible',
+                  src: component.darkLogoSrc,
+                  alt: 'Flutter',
+                ),
               ]),
             ]),
             if (isBlog)
diff --git a/sites/www/lib/src/layouts/blog_layout.dart b/sites/www/lib/src/layouts/blog_layout.dart
index abb499e616a..3d6cb90fdd1 100644
--- a/sites/www/lib/src/layouts/blog_layout.dart
+++ b/sites/www/lib/src/layouts/blog_layout.dart
@@ -29,31 +29,11 @@ class BlogLayout extends DefaultLayout {
   @override
   List<String> get defaultBodyTags => ['interior', 'blog'];
 
-  @override
-  List<Component> get leadingHeadElements => const [
-    Component.element(
-      tag: 'style',
-      children: [
-        .text(
-          'html.dark-mode, '
-          'html.dark-mode body.blog, '
-          'html.dark-mode body.blog main { '
-          'background-color: #121317; color: #dcdcdc; color-scheme: dark; '
-          '} '
-          'html.dark-mode body.blog '
-          'header.site-header:not(.mobile-nav-open), '
-          'html.dark-mode body.blog .site-footer { '
-          'background-color: #1c1e27; '
-          '}',
-        ),
-      ],
-    ),
-    themeInitScript,
-  ];
-
   @override
   List<Component> get leadingBodyElements => const [
-    themeSyncBodyScript,
+    // The theme setting logic should remain before other scripts to
+    // avoid a flash of the initial theme on load.
+    themeInitScript,
   ];
 
   @override
diff --git a/sites/www/lib/src/layouts/default_layout.dart b/sites/www/lib/src/layouts/default_layout.dart
index b68691e5ecf..e6393f9d085 100644
--- a/sites/www/lib/src/layouts/default_layout.dart
+++ b/sites/www/lib/src/layouts/default_layout.dart
@@ -18,10 +18,11 @@ class DefaultLayout extends PageLayout {
   @override
   Pattern get name => 'default';
 
+  /// CSS classes to include on the document `<body>` element by default.
   List<String> get defaultBodyTags => const [];
 
-  List<Component> get leadingHeadElements => const [];
-
+  /// Additional components to insert at the beginning of the document `<body>`,
+  /// before the site header (for example, early initialization scripts).
   List<Component> get leadingBodyElements => const [];
 
   @override
@@ -70,7 +71,6 @@ class DefaultLayout extends PageLayout {
         return Document(
           title: documentTitle,
           head: [
-            ...leadingHeadElements,
             link(rel: 'icon', href: context.asset('/images/favicon.png')),
             link(
               rel: 'apple-touch-icon',
@@ -218,9 +218,7 @@ class DefaultLayout extends PageLayout {
               pageUrl: page.url,
               contrastLogoSrc: context.asset('/images/flutter-logo-white.svg'),
               defaultLogoSrc: context.asset('/images/flutter-logo.svg'),
-              darkLogoSrc: page.url.startsWith('/blog')
-                  ? context.asset('/images/flutter-logo-dark.svg')
-                  : null,
+              darkLogoSrc: context.asset('/images/flutter-logo-dark.svg'),
               banner: banner,
             ),
             child,
diff --git a/sites/www/lib/styles/components/_footer.scss b/sites/www/lib/styles/components/_footer.scss
index 99e51357ded..2dbfb8cfcf3 100644
--- a/sites/www/lib/styles/components/_footer.scss
+++ b/sites/www/lib/styles/components/_footer.scss
@@ -1,14 +1,16 @@
 @use '../core/breakpoints';
 
 .site-footer {
-  background-color: var(--grey-1);
+  background-color: var(--site-footer-bgColor);
+  color: var(--site-base-fgColor-lighter);
   padding: 70px var(--gutter);
 
   ul {
     a {
-      color: var(--grey-6);
+      color: var(--site-base-fgColor-lighter);
 
       &:hover {
+        color: var(--site-base-fgColor);
         text-decoration: underline;
       }
     }
@@ -25,7 +27,7 @@
     }
 
     &.footer-social {
-      border-bottom: 1px solid var(--grey-4);
+      border-bottom: 1px solid var(--site-outline-variant);
       align-items: center;
       padding-bottom: 34px;
 
@@ -35,9 +37,13 @@
 
         a {
           margin-right: 1.25rem;
-          color: var(--grey-6);
+          color: var(--site-base-fgColor-lighter);
           display: inline-flex;
           align-items: center;
+
+          &:hover {
+            color: var(--site-base-fgColor);
+          }
         }
 
         .footer-social-icon {
@@ -48,7 +54,7 @@
         span {
           font-family: var(--font-ui);
           font-size: var(--font-size-heading-5);
-          color: var(--grey-6);
+          color: var(--site-base-fgColor-lighter);
         }
       }
 
@@ -130,7 +136,7 @@
 
       li:first-child {
         margin-bottom: var(--spacer-sm);
-        color: black;
+        color: var(--site-base-fgColor);
         font-weight: var(--font-weight-bold);
         display: block;
       }
diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index aaf358addec..b0056df00e6 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -96,6 +96,18 @@
     }
   }
 
+  .subtype {
+    padding: 0 0.3rem;
+    font-size: 1.25rem;
+    font-weight: 500;
+    line-height: 1.3;
+    border-radius: 0.25rem;
+    background-color: var(--site-secondaryContainer-bgColor);
+    color: var(--site-secondaryContainer-fgColor);
+    margin-left: 0.4rem;
+    letter-spacing: normal;
+  }
+
   --anim-offset: 30px;
   --dd-offset-top: 54px;
 
@@ -485,7 +497,8 @@
         transform: translate(-50%, 0);
         border-radius: 6px;
         box-shadow: var(--ui-drop-shadow);
-        background-color: white;
+        background-color: var(--site-header-bgColor);
+        border: 1px solid var(--site-outline-variant);
         padding: 18px 14px;
         min-width: 190px;
         z-index: var(--site-z-dropdown);
@@ -504,7 +517,7 @@
             }
 
             a.btn {
-              color: var(--grey-6);
+              color: var(--site-base-fgColor-lighter);
               padding: var(--spacer-sm) 16px;
               display: flex;
               justify-content: flex-start;
@@ -518,9 +531,9 @@
 
               &:active,
               &:hover {
-                background-color: var(--grey-2);
+                background-color: rgb(var(--site-interaction-base-values) / 6%);
                 transition: background-color 300ms, color 300ms ease;
-                color: black;
+                color: var(--site-base-fgColor);
               }
             }
 
@@ -584,8 +597,8 @@ body.interior {
 body.interior,
 body.in-content {
   .site-header:not(.mobile-nav-open) {
-    transition: background-color 300ms, box-shadow 200ms, top 300px ease;
-    background-color: white;
+    transition: box-shadow 200ms;
+    background-color: var(--site-header-bgColor);
     box-shadow: 0 1px 6px rgba(0, 0, 0, 0.2);
     top: 0 !important;
     /* Override `.hide`. */
@@ -601,8 +614,7 @@ body.in-content {
     }
 
     nav {
-      transition: color 300ms;
-      color: black;
+      color: var(--site-base-fgColor);
 
       >ul {
         >li {
@@ -613,15 +625,15 @@ body.in-content {
           }
 
           a.btn {
-            color: var(--grey-6);
+            color: var(--site-base-fgColor-lighter);
 
             &:hover {
-              background-color: var(--grey-1);
-              color: var(--blue-6);
+              background-color: rgb(var(--site-interaction-base-values) / 5%);
+              color: var(--site-link-fgColor);
             }
 
             &.active {
-              color: var(--blue-6);
+              color: var(--site-link-fgColor);
             }
           }
         }
@@ -629,37 +641,37 @@ body.in-content {
     }
 
     .icon-btn {
-      color: var(--grey-6);
+      color: var(--site-base-fgColor-lighter);
 
       &:hover,
       &.active {
-        background-color: var(--grey-1);
+        background-color: rgb(var(--site-interaction-base-values) / 5%);
       }
     }
 
     .search {
       &:focus-within {
-        outline: 2px solid var(--primary);
+        outline: 2px solid var(--site-primary-color);
       }
 
       form {
         input {
-          color: black;
+          color: var(--site-base-fgColor);
 
           &::placeholder {
-            color: var(--grey-5);
+            color: var(--site-base-fgColor-alt);
           }
         }
       }
 
       &.active {
-        background-color: var(--grey-2);
+        background-color: var(--site-inset-bgColor);
       }
     }
 
     a.btn#get-started__header {
-      background-color: var(--blue-6);
-      color: white;
+      background-color: var(--site-filledButton-bgColor);
+      color: var(--site-filledButton-fgColor);
     }
   }
 }
diff --git a/sites/www/lib/styles/components/_theme-switcher.scss b/sites/www/lib/styles/components/_theme-switcher.scss
new file mode 100644
index 00000000000..6f93dc5ed8e
--- /dev/null
+++ b/sites/www/lib/styles/components/_theme-switcher.scss
@@ -0,0 +1,70 @@
+body:not(.dark-mode) .dark-mode-visible {
+  display: none !important;
+}
+
+body.dark-mode {
+  .light-mode-visible {
+    display: none !important;
+  }
+
+  .theme-icon {
+    filter: invert(1) brightness(0.8);
+  }
+}
+
+.site-header {
+  #theme-switcher {
+    display: inline-flex;
+    align-items: center;
+
+    > button.icon-button {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: var(--ui-btn-height);
+      height: var(--ui-btn-height);
+      border-radius: var(--ui-border-radius);
+      color: var(--site-base-fgColor-lighter);
+      cursor: pointer;
+      user-select: none;
+      border: none;
+      background: none;
+      padding: 0;
+
+      &:hover,
+      &[aria-expanded='true'] {
+        background-color: rgb(var(--site-interaction-base-values) / 5%);
+        color: var(--site-base-fgColor);
+      }
+    }
+
+    > .dropdown-content {
+      font-family: var(--site-ui-fontFamily);
+      font-size: 1rem;
+      top: calc(100% + 0.25rem);
+
+      button {
+        color: var(--site-base-fgColor);
+        border: none;
+        cursor: pointer;
+      }
+    }
+  }
+
+  &.mobile-nav-open,
+  &.searching {
+    #theme-switcher {
+      display: none;
+    }
+  }
+
+  @media (min-width: 1024px) and (any-hover: hover) {
+    &:has(#theme-switcher) .search {
+      margin-right: 0.25rem;
+    }
+
+    #theme-switcher {
+      margin-right: var(--gutter-sm);
+    }
+  }
+}
diff --git a/sites/www/lib/styles/core/_base.scss b/sites/www/lib/styles/core/_base.scss
index 0633185a17d..f099042e974 100644
--- a/sites/www/lib/styles/core/_base.scss
+++ b/sites/www/lib/styles/core/_base.scss
@@ -4,8 +4,8 @@ html {
 }
 
 body {
-  background-color: white;
-  color: var(--grey-6);
+  background-color: var(--site-base-bgColor);
+  color: var(--site-base-fgColor-lighter);
   display: flex;
   flex-direction: column;
   line-height: inherit;
diff --git a/sites/www/lib/styles/core/_vars.scss b/sites/www/lib/styles/core/_vars.scss
index 9270277b3db..31899136b1f 100644
--- a/sites/www/lib/styles/core/_vars.scss
+++ b/sites/www/lib/styles/core/_vars.scss
@@ -88,6 +88,7 @@
 
   --site-raised-bgColor: var(--grey-3);
   --site-header-bgColor: var(--site-base-bgColor);
+  --site-footer-bgColor: var(--grey-1);
 
   --site-inset-bgColor: #f9fafb;
   --site-inset-fgColor: var(--site-base-fgColor);
@@ -140,6 +141,50 @@
   --site-radius: 0.45rem;
 }
 
+body.dark-mode {
+  color-scheme: dark;
+  --site-outline: rgba(95, 100, 119, 0.75);
+  --site-outline-variant: #252834;
+
+  --site-interaction-base-values: 255 255 255;
+
+  --site-base-bgColor: #121317;
+  --site-base-fgColor: #dcdcdc;
+  --site-base-fgColor-lighter: #{color.scale(#dcdcdc, $lightness: -25%)};
+  --site-base-fgColor-alt: #a8acad;
+
+  --site-raised-bgColor: #1c1e27;
+  --site-raised-bgColor-translucent: #{color.change(#1c1e27, $alpha: 0.4)};
+
+  --site-primary-color: #0468d7;
+  --site-primary-color-highlight: #{color.change(#0468d7, $alpha: 0.1)};
+
+  --site-secondaryContainer-bgColor: rgb(22 83 153);
+  --site-secondaryContainer-fgColor: var(--site-base-fgColor);
+
+  --site-inset-bgColor: #202731;
+  --site-inset-bgColor-translucent: rgba(32, 39, 49, 0.7);
+  --site-inset-fgColor: var(--site-base-fgColor);
+  --site-inset-borderColor: #485563;
+
+  --site-link-fgColor: #47b0f8;
+  --site-link-fgColor-active: #28a3f7;
+
+  --site-header-bgColor: var(--site-raised-bgColor);
+  --site-footer-bgColor: var(--site-raised-bgColor);
+
+  --site-code-highlight-bgColor: rgba(164, 158, 62, 0.15);
+  --site-diagram-wrap-bgColor: #e1e6ea;
+
+  .opal,
+  .opal span {
+    color: var(--opal-dark-color) !important;
+    font-style: var(--opal-dark-font-style) !important;
+    font-weight: var(--opal-dark-font-weight) !important;
+    text-decoration: var(--opal-dark-text-decoration) !important;
+  }
+}
+
 .text-coral {
   color: var(--coral) !important;
 }
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index 164dc195b17..c1852662521 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -1,64 +1,7 @@
-@use 'sass:color';
 @use 'package:site_shared/_sass/base/mixins';
 
-body:not(.blog.dark-mode, html.dark-mode .blog) .dark-mode-visible {
-  display: none !important;
-}
-
 body.blog {
-  background-color: var(--site-base-bgColor);
   color: var(--site-base-fgColor);
-
-  &:is(.dark-mode, html.dark-mode &) {
-    color-scheme: dark;
-    --site-outline: rgba(95, 100, 119, 0.75);
-    --site-outline-variant: #252834;
-
-    --site-interaction-base-values: 255 255 255;
-
-    --site-base-bgColor: #121317;
-    --site-base-fgColor: #dcdcdc;
-    --site-base-fgColor-lighter: #{color.scale(#dcdcdc, $lightness: -25%)};
-    --site-base-fgColor-alt: #a8acad;
-
-    --site-raised-bgColor: #1c1e27;
-    --site-raised-bgColor-translucent: #{color.change(#1c1e27, $alpha: 0.4)};
-
-    --site-primary-color: #0468d7;
-    --site-primary-color-highlight: #{color.change(#0468d7, $alpha: 0.1)};
-
-    --site-secondaryContainer-bgColor: rgb(22 83 153);
-    --site-secondaryContainer-fgColor: var(--site-base-fgColor);
-
-    --site-inset-bgColor: #202731;
-    --site-inset-bgColor-translucent: rgba(32, 39, 49, 0.7);
-    --site-inset-fgColor: var(--site-base-fgColor);
-    --site-inset-borderColor: #485563;
-
-    --site-link-fgColor: #47b0f8;
-    --site-link-fgColor-active: #28a3f7;
-
-    --site-header-bgColor: var(--site-raised-bgColor);
-
-    --site-code-highlight-bgColor: rgba(164, 158, 62, 0.15);
-    --site-diagram-wrap-bgColor: #e1e6ea;
-
-    .opal,
-    .opal span {
-      color: var(--opal-dark-color) !important;
-      font-style: var(--opal-dark-font-style) !important;
-      font-weight: var(--opal-dark-font-weight) !important;
-      text-decoration: var(--opal-dark-text-decoration) !important;
-    }
-
-    .light-mode-visible {
-      display: none !important;
-    }
-
-    .theme-icon {
-      filter: invert(1) brightness(0.8);
-    }
-  }
 }
 
 .blog main {
@@ -202,183 +145,6 @@ body.blog {
   color: var(--site-base-fgColor);
 }
 
-body.blog header.site-header:not(.mobile-nav-open) {
-  transition: box-shadow 200ms;
-
-  nav,
-  nav > ul > li a.btn,
-  .icon-btn {
-    transition: none;
-  }
-}
-
-.blog header.site-header {
-  .subtype {
-    padding: 0 0.3rem;
-    font-size: 1.25rem;
-    font-weight: 500;
-    line-height: 1.3;
-    border-radius: 0.25rem;
-    background-color: var(--site-secondaryContainer-bgColor);
-    color: var(--site-secondaryContainer-fgColor);
-    margin-left: 0.4rem;
-    letter-spacing: normal;
-  }
-
-  #theme-switcher {
-    display: inline-flex;
-    align-items: center;
-
-    > button.icon-button {
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      width: var(--ui-btn-height);
-      height: var(--ui-btn-height);
-      border-radius: var(--ui-border-radius);
-      color: var(--grey-6);
-      cursor: pointer;
-      user-select: none;
-      border: none;
-      background: none;
-      padding: 0;
-
-      &:hover,
-      &[aria-expanded='true'] {
-        background-color: var(--grey-1);
-      }
-    }
-
-    > .dropdown-content {
-      font-family: var(--site-ui-fontFamily);
-      font-size: 1rem;
-      top: calc(100% + 0.25rem);
-
-      button {
-        color: var(--site-base-fgColor);
-        border: none;
-        cursor: pointer;
-      }
-    }
-  }
-
-  &.mobile-nav-open,
-  &.searching {
-    #theme-switcher {
-      display: none;
-    }
-  }
-
-  @media (min-width: 1024px) and (any-hover: hover) {
-    .search {
-      margin-right: 0.25rem;
-    }
-
-    #theme-switcher {
-      margin-right: var(--gutter-sm);
-    }
-  }
-}
-
-:is(body.blog.dark-mode, html.dark-mode body.blog) {
-  header.site-header:not(.mobile-nav-open) {
-    background-color: var(--site-header-bgColor);
-    border-bottom: 1px solid var(--site-outline-variant);
-
-    nav {
-      color: var(--site-base-fgColor);
-
-      > ul > li {
-        a.btn {
-          color: var(--site-base-fgColor);
-
-          &:hover {
-            background-color: rgb(var(--site-interaction-base-values) / 8%);
-            color: var(--site-link-fgColor);
-          }
-
-          &.active {
-            color: var(--site-link-fgColor);
-          }
-        }
-
-        .dd {
-          background-color: var(--site-raised-bgColor);
-          border: 1px solid var(--site-outline-variant);
-
-          ul li a.btn {
-            color: var(--site-base-fgColor-alt);
-
-            &:hover,
-            &:active {
-              background-color: rgb(var(--site-interaction-base-values) / 8%);
-              color: var(--site-base-fgColor);
-            }
-          }
-        }
-      }
-    }
-
-    .icon-btn,
-    #theme-switcher > button.icon-button {
-      color: var(--site-base-fgColor-alt);
-
-      &:hover,
-      &.active,
-      &[aria-expanded='true'] {
-        background-color: rgb(var(--site-interaction-base-values) / 8%);
-        color: var(--site-base-fgColor);
-      }
-    }
-
-    .search {
-      form input {
-        color: var(--site-base-fgColor);
-
-        &::placeholder {
-          color: var(--site-base-fgColor-alt);
-        }
-      }
-
-      &.active {
-        background-color: var(--site-inset-bgColor);
-      }
-    }
-  }
-
-  .site-footer {
-    background-color: var(--site-raised-bgColor);
-    color: var(--site-base-fgColor-alt);
-
-    ul a {
-      color: var(--site-base-fgColor-alt);
-
-      &:hover {
-        color: var(--site-base-fgColor);
-      }
-    }
-
-    .footer-links ul li:first-child {
-      color: var(--site-base-fgColor);
-    }
-
-    .content.footer-social {
-      border-bottom-color: var(--site-outline-variant);
-
-      > div {
-        a,
-        span {
-          color: var(--site-base-fgColor-alt);
-        }
-
-        a:hover {
-          color: var(--site-base-fgColor);
-        }
-      }
-    }
-  }
-}
-
 .blog .back-to-top {
   position: fixed;
   right: 1.5rem;
diff --git a/sites/www/lib/styles/styles.scss b/sites/www/lib/styles/styles.scss
index 0e94f1178c4..7e66cd031a5 100644
--- a/sites/www/lib/styles/styles.scss
+++ b/sites/www/lib/styles/styles.scss
@@ -28,6 +28,7 @@
 @use 'components/stories';
 @use 'components/tabs';
 @use 'components/testimonial';
+@use 'components/theme-switcher';
 
 @use 'pages/brand';
 @use 'pages/blog_page';

From 2db662a330ead2eb8143d46d1e1c927f4faf3d78 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Tue, 6 Oct 2026 20:59:53 +0800
Subject: [PATCH 04/14] Misc clean up

---
 .../blog/client/blog_categories.dart          |  8 +--
 .../lib/components/layout/theme_switcher.dart | 53 +++++++++----------
 sites/www/lib/main.client.options.dart        |  1 +
 sites/www/lib/main.server.options.dart        |  1 +
 .../www/lib/src/components/layout/footer.dart |  2 +
 .../www/lib/src/components/layout/header.dart | 19 ++++---
 sites/www/lib/src/layouts/blog_layout.dart    |  7 +--
 sites/www/lib/src/layouts/default_layout.dart | 13 +++--
 sites/www/lib/styles/components/_header.scss  |  2 +-
 .../styles/components/_theme-switcher.scss    | 10 +---
 sites/www/lib/styles/pages/_blog_page.scss    |  1 -
 11 files changed, 55 insertions(+), 62 deletions(-)

diff --git a/packages/site_shared/lib/components/blog/client/blog_categories.dart b/packages/site_shared/lib/components/blog/client/blog_categories.dart
index c24de0b78d1..327807d3757 100644
--- a/packages/site_shared/lib/components/blog/client/blog_categories.dart
+++ b/packages/site_shared/lib/components/blog/client/blog_categories.dart
@@ -148,13 +148,7 @@ class _BlogCategoriesState extends State<BlogCategories> {
           'layout-grid',
           'layout-list',
         ]) {
-          if (layoutClass == targetClass) {
-            if (!card.classList.contains(layoutClass)) {
-              card.classList.add(layoutClass);
-            }
-          } else if (card.classList.contains(layoutClass)) {
-            card.classList.remove(layoutClass);
-          }
+          card.classList.toggle(layoutClass, layoutClass == targetClass);
         }
       }
     }
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index 4e025630f8c..ab84ef1bc8f 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -45,6 +45,7 @@ enum _Theme {
 
 final class _ThemeSwitcherState extends State<StatefulComponent> {
   _Theme _currentTheme = _Theme.light;
+  web.MediaQueryList? _prefersDarkQuery;
   StreamSubscription<web.Event>? _pageShowSubscription;
   StreamSubscription<web.StorageEvent>? _storageSubscription;
   StreamSubscription<web.Event>? _mediaQuerySubscription;
@@ -53,15 +54,13 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
   void initState() {
     super.initState();
     if (kIsWeb) {
+      final prefersDarkQuery = _prefersDarkQuery = web.window.matchMedia(
+        '(prefers-color-scheme: dark)',
+      );
       _syncThemeFromStorage();
-      _pageShowSubscription =
-          const web.EventStreamProvider<web.Event>(
-                'pageshow',
-              )
-              .forTarget(web.window)
-              .listen(
-                (_) => _syncThemeFromStorage(updateState: true),
-              );
+      _pageShowSubscription = web.EventStreamProviders.pageShowEvent
+          .forTarget(web.window)
+          .listen((_) => _syncThemeFromStorage(updateState: true));
       _storageSubscription = web.EventStreamProviders.storageEvent
           .forTarget(web.window)
           .listen((event) {
@@ -69,18 +68,13 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
               _syncThemeFromStorage(updateState: true);
             }
           });
-      _mediaQuerySubscription =
-          const web.EventStreamProvider<web.Event>(
-                'change',
-              )
-              .forTarget(web.window.matchMedia('(prefers-color-scheme: dark)'))
-              .listen(
-                (_) {
-                  if (_currentTheme == _Theme.auto) {
-                    _applyThemeToBody(_Theme.auto);
-                  }
-                },
-              );
+      _mediaQuerySubscription = web.EventStreamProviders.changeEvent
+          .forTarget(prefersDarkQuery)
+          .listen((_) {
+            if (_currentTheme == _Theme.auto) {
+              _applyThemeToBody(_Theme.auto);
+            }
+          });
     }
   }
 
@@ -112,7 +106,7 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
 
     final isAuto = theme == _Theme.auto;
     final isDark = isAuto
-        ? web.window.matchMedia('(prefers-color-scheme: dark)').matches
+        ? (_prefersDarkQuery?.matches ?? false)
         : theme == _Theme.dark;
     final resolvedId = isDark ? _Theme.dark.id : _Theme.light.id;
     final oppositeId = isDark ? _Theme.light.id : _Theme.dark.id;
@@ -132,19 +126,20 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
   }
 
   void _syncThemeFromStorage({bool updateState = false}) {
-    String? storedThemeId;
+    _Theme? storedTheme;
     try {
-      storedThemeId = web.window.localStorage.getItem('theme');
+      // Match the early theme script, which defaults to light
+      // when no valid theme is stored.
+      storedTheme = switch (web.window.localStorage.getItem('theme')) {
+        'auto-mode' => _Theme.auto,
+        'dark-mode' => _Theme.dark,
+        _ => _Theme.light,
+      };
     } catch (_) {
       // localStorage is not available, fall back to body classes.
     }
 
-    final resolvedTheme = switch (storedThemeId) {
-      'auto-mode' => _Theme.auto,
-      'dark-mode' => _Theme.dark,
-      'light-mode' => _Theme.light,
-      _ => _themeFromBodyClasses(),
-    };
+    final resolvedTheme = storedTheme ?? _themeFromBodyClasses();
 
     _applyThemeToBody(resolvedTheme);
 
diff --git a/sites/www/lib/main.client.options.dart b/sites/www/lib/main.client.options.dart
index d9c7a5079e5..8509e792cdf 100644
--- a/sites/www/lib/main.client.options.dart
+++ b/sites/www/lib/main.client.options.dart
@@ -111,6 +111,7 @@ ClientOptions get defaultClientOptions => ClientOptions(
           p['banner'] as Map<String, Object?>,
         ),
         pageUrl: p['pageUrl'] as String,
+        supportsDarkMode: p['supportsDarkMode'] as bool,
       ),
       loader: _header.loadLibrary,
     ),
diff --git a/sites/www/lib/main.server.options.dart b/sites/www/lib/main.server.options.dart
index f99bbbdf601..fb40d536223 100644
--- a/sites/www/lib/main.server.options.dart
+++ b/sites/www/lib/main.server.options.dart
@@ -176,6 +176,7 @@ Map<String, Object?> __headerHeader(_header.Header c) => {
   'darkLogoSrc': c.darkLogoSrc,
   'banner': c.banner.toMap(),
   'pageUrl': c.pageUrl,
+  'supportsDarkMode': c.supportsDarkMode,
 };
 Map<String, Object?> __consultants_gridConsultantsGrid(
   _consultants_grid.ConsultantsGrid c,
diff --git a/sites/www/lib/src/components/layout/footer.dart b/sites/www/lib/src/components/layout/footer.dart
index a15ae54bb8d..64f6132c6f7 100644
--- a/sites/www/lib/src/components/layout/footer.dart
+++ b/sites/www/lib/src/components/layout/footer.dart
@@ -22,11 +22,13 @@ class Footer extends StatelessComponent {
               width: 154,
               alt: 'Flutter',
             ),
+            // Lazy load the dark logo so it's only fetched when displayed.
             img(
               classes: 'dark-mode-visible',
               src: context.asset('/images/flutter-logo-dark.svg'),
               width: 154,
               alt: 'Flutter',
+              loading: MediaLoading.lazy,
             ),
           ]),
         ]),
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index 3dd7923dc8b..bc3cddcae69 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -25,6 +25,7 @@ class Header extends StatefulComponent {
     required this.darkLogoSrc,
     required this.banner,
     required this.pageUrl,
+    required this.supportsDarkMode,
   });
 
   final String contrastLogoSrc;
@@ -33,6 +34,10 @@ class Header extends StatefulComponent {
   final BannerContent banner;
   final String pageUrl;
 
+  /// Whether the current page supports a dark theme,
+  /// in which case the header includes a theme switcher.
+  final bool supportsDarkMode;
+
   @override
   State<Header> createState() => _HeaderState();
 }
@@ -171,11 +176,13 @@ class _HeaderState extends State<Header> {
                   src: component.defaultLogoSrc,
                   alt: 'Flutter',
                 ),
-                img(
-                  classes: 'dark-mode-visible',
-                  src: component.darkLogoSrc,
-                  alt: 'Flutter',
-                ),
+                // Avoid loading the dark logo on pages without dark mode.
+                if (component.supportsDarkMode)
+                  img(
+                    classes: 'dark-mode-visible',
+                    src: component.darkLogoSrc,
+                    alt: 'Flutter',
+                  ),
               ]),
             ]),
             if (isBlog)
@@ -236,7 +243,7 @@ class _HeaderState extends State<Header> {
                   ),
               ],
             ),
-            if (isBlog) const NestedThemeSwitcher(),
+            if (component.supportsDarkMode) const NestedThemeSwitcher(),
             const a(
               href: 'https://docs.flutter.dev/get-started/quick',
               id: 'get-started__header',
diff --git a/sites/www/lib/src/layouts/blog_layout.dart b/sites/www/lib/src/layouts/blog_layout.dart
index 3d6cb90fdd1..9a95891b82d 100644
--- a/sites/www/lib/src/layouts/blog_layout.dart
+++ b/sites/www/lib/src/layouts/blog_layout.dart
@@ -12,7 +12,6 @@ import 'package:site_shared/components/blog/blog_next_posts.dart';
 import 'package:site_shared/components/blog/post_info.dart';
 import 'package:site_shared/components/common/breadcrumbs.dart';
 import 'package:site_shared/components/common/client/back_to_top_button.dart';
-import 'package:site_shared/server_util.dart';
 import 'package:site_shared/util.dart';
 
 import '../utils/scroll_spy.dart';
@@ -30,11 +29,7 @@ class BlogLayout extends DefaultLayout {
   List<String> get defaultBodyTags => ['interior', 'blog'];
 
   @override
-  List<Component> get leadingBodyElements => const [
-    // The theme setting logic should remain before other scripts to
-    // avoid a flash of the initial theme on load.
-    themeInitScript,
-  ];
+  bool get supportsDarkMode => true;
 
   @override
   Component buildLayout(Page page, Component child) {
diff --git a/sites/www/lib/src/layouts/default_layout.dart b/sites/www/lib/src/layouts/default_layout.dart
index e6393f9d085..237f8546f86 100644
--- a/sites/www/lib/src/layouts/default_layout.dart
+++ b/sites/www/lib/src/layouts/default_layout.dart
@@ -21,9 +21,11 @@ class DefaultLayout extends PageLayout {
   /// CSS classes to include on the document `<body>` element by default.
   List<String> get defaultBodyTags => const [];
 
-  /// Additional components to insert at the beginning of the document `<body>`,
-  /// before the site header (for example, early initialization scripts).
-  List<Component> get leadingBodyElements => const [];
+  /// Whether pages using this layout support switching to a dark theme.
+  ///
+  /// When `true`, the saved theme preference is applied
+  /// before the page paints and the site header includes a theme switcher.
+  bool get supportsDarkMode => false;
 
   @override
   Component buildLayout(Page page, Component child) {
@@ -213,9 +215,12 @@ class DefaultLayout extends PageLayout {
               Document.body(
                 attributes: {'class': bodyTags.join(' ')},
               ),
-            ...leadingBodyElements,
+            // The theme setting logic should remain before other scripts to
+            // avoid a flash of the initial theme on load.
+            if (supportsDarkMode) themeInitScript,
             Header(
               pageUrl: page.url,
+              supportsDarkMode: supportsDarkMode,
               contrastLogoSrc: context.asset('/images/flutter-logo-white.svg'),
               defaultLogoSrc: context.asset('/images/flutter-logo.svg'),
               darkLogoSrc: context.asset('/images/flutter-logo-dark.svg'),
diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index b0056df00e6..aab87fb37c2 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -665,7 +665,7 @@ body.in-content {
       }
 
       &.active {
-        background-color: var(--site-inset-bgColor);
+        background-color: rgb(var(--site-interaction-base-values) / 6%);
       }
     }
 
diff --git a/sites/www/lib/styles/components/_theme-switcher.scss b/sites/www/lib/styles/components/_theme-switcher.scss
index 6f93dc5ed8e..8fa365057de 100644
--- a/sites/www/lib/styles/components/_theme-switcher.scss
+++ b/sites/www/lib/styles/components/_theme-switcher.scss
@@ -2,14 +2,8 @@ body:not(.dark-mode) .dark-mode-visible {
   display: none !important;
 }
 
-body.dark-mode {
-  .light-mode-visible {
-    display: none !important;
-  }
-
-  .theme-icon {
-    filter: invert(1) brightness(0.8);
-  }
+body.dark-mode .light-mode-visible {
+  display: none !important;
 }
 
 .site-header {
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index c1852662521..4a2ceb14ad9 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -9,7 +9,6 @@ body.blog {
   flex-direction: row;
   justify-content: center;
   background-color: var(--site-base-bgColor);
-  color: var(--site-base-fgColor);
 
   h1,
   h2,

From e2df61e0014e14214b5df32260175aa95341d2c3 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 7 Oct 2026 15:42:37 +0800
Subject: [PATCH 05/14] Continue clean up

---
 .../lib/components/blog/blog_index.dart       |  4 +-
 .../blog/client/blog_categories.dart          | 86 +++++++++++--------
 .../lib/components/layout/theme_switcher.dart | 17 +---
 .../www/content/images/flutter-logo-dark.svg  |  7 +-
 .../www/content/images/flutter-logo-white.svg |  7 +-
 sites/www/content/images/flutter-logo.svg     |  7 +-
 sites/www/lib/styles/pages/_blog_page.scss    |  8 +-
 7 files changed, 64 insertions(+), 72 deletions(-)

diff --git a/packages/site_shared/lib/components/blog/blog_index.dart b/packages/site_shared/lib/components/blog/blog_index.dart
index b9b7c3ba05c..c80079349fe 100644
--- a/packages/site_shared/lib/components/blog/blog_index.dart
+++ b/packages/site_shared/lib/components/blog/blog_index.dart
@@ -74,9 +74,7 @@ class BlogIndex extends StatelessComponent {
                 < 5 => BlogCardPriority.high,
                 _ => BlogCardPriority.normal,
               },
-              className: i == 0
-                  ? 'layout-featured'
-                  : (i < 5 ? 'layout-grid' : 'layout-list'),
+              className: BlogCardLayout.forIndex(i).className,
             ),
         ],
       ),
diff --git a/packages/site_shared/lib/components/blog/client/blog_categories.dart b/packages/site_shared/lib/components/blog/client/blog_categories.dart
index 327807d3757..154f77f6e1e 100644
--- a/packages/site_shared/lib/components/blog/client/blog_categories.dart
+++ b/packages/site_shared/lib/components/blog/client/blog_categories.dart
@@ -43,6 +43,40 @@ class BlogCategory {
   };
 }
 
+/// The layout of a card in the blog index,
+/// determined by its position among the visible cards.
+enum BlogCardLayout {
+  /// A full-width card with a large image and title,
+  /// used to highlight the most prominent post.
+  featured,
+
+  /// A bordered tile that's arranged in a grid with other cards.
+  grid,
+
+  /// A full-width row with a small image beside the post details.
+  list,
+  ;
+
+  /// The CSS class applied to a `.blog-card` element to
+  /// style it with this layout.
+  String get className => switch (this) {
+    .featured => 'layout-featured',
+    .grid => 'layout-grid',
+    .list => 'layout-list',
+  };
+
+  /// Returns the layout for the card at the specified [index]
+  /// among the visible cards.
+  ///
+  /// The first card is [featured], the next four are [grid],
+  /// and all remaining cards are [list].
+  static BlogCardLayout forIndex(int index) => switch (index) {
+    0 => featured,
+    < 5 => grid,
+    _ => list,
+  };
+}
+
 @client
 class BlogCategories extends StatefulComponent {
   const BlogCategories({required this.categories, super.key});
@@ -115,41 +149,25 @@ class _BlogCategoriesState extends State<BlogCategories> {
 
   void _applyLayout(BlogCategory? category) {
     final container = web.document.getElementById('blog-container');
-    if (container != null) {
-      if (category == null) {
-        container.setAttribute('data-selected', 'all');
-      } else {
-        container.setAttribute('data-selected', category.slug);
-      }
+    if (container == null) return;
+
+    container.setAttribute('data-selected', category?.slug ?? 'all');
+
+    final cards = container.querySelectorAll('.blog-card');
+    final showFeatured = category?.showFeatured ?? true;
+    var visibleCount = showFeatured ? 0 : 1;
+
+    for (var cardIndex = 0; cardIndex < cards.length; cardIndex += 1) {
+      final card = cards.item(cardIndex) as web.Element;
+      final cardCategory = card.getAttribute('data-category');
+
+      final isVisible = category == null || cardCategory == category.slug;
+      final targetLayout = isVisible
+          ? BlogCardLayout.forIndex(visibleCount++)
+          : null;
 
-      final cards = container.querySelectorAll('.blog-card');
-      final showFeatured = category?.showFeatured ?? true;
-      var visibleCount = showFeatured ? 0 : 1;
-
-      for (var i = 0; i < cards.length; i++) {
-        final card = cards.item(i) as web.Element;
-        final cardCategory = card.getAttribute('data-category');
-
-        final isVisible = category == null || cardCategory == category.slug;
-        String? targetClass;
-        if (isVisible) {
-          if (visibleCount == 0) {
-            targetClass = 'layout-featured';
-          } else if (visibleCount < 5) {
-            targetClass = 'layout-grid';
-          } else {
-            targetClass = 'layout-list';
-          }
-          visibleCount++;
-        }
-
-        for (final layoutClass in const [
-          'layout-featured',
-          'layout-grid',
-          'layout-list',
-        ]) {
-          card.classList.toggle(layoutClass, layoutClass == targetClass);
-        }
+      for (final layout in BlogCardLayout.values) {
+        card.classList.toggle(layout.className, layout == targetLayout);
       }
     }
   }
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index ab84ef1bc8f..b1a24d77eef 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -108,21 +108,10 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
     final isDark = isAuto
         ? (_prefersDarkQuery?.matches ?? false)
         : theme == _Theme.dark;
-    final resolvedId = isDark ? _Theme.dark.id : _Theme.light.id;
-    final oppositeId = isDark ? _Theme.light.id : _Theme.dark.id;
 
-    if (classList.contains(resolvedId) &&
-        classList.contains(_Theme.auto.id) == isAuto &&
-        !classList.contains(oppositeId)) {
-      return;
-    }
-    for (final mode in _Theme.values) {
-      classList.remove(mode.id);
-    }
-    classList.add(resolvedId);
-    if (isAuto) {
-      classList.add(_Theme.auto.id);
-    }
+    classList.toggle(_Theme.light.id, !isDark);
+    classList.toggle(_Theme.dark.id, isDark);
+    classList.toggle(_Theme.auto.id, isAuto);
   }
 
   void _syncThemeFromStorage({bool updateState = false}) {
diff --git a/sites/www/content/images/flutter-logo-dark.svg b/sites/www/content/images/flutter-logo-dark.svg
index 2a31ae4c1a5..8b3a9fcb39d 100644
--- a/sites/www/content/images/flutter-logo-dark.svg
+++ b/sites/www/content/images/flutter-logo-dark.svg
@@ -1,4 +1,4 @@
-<svg width="156" height="44" viewBox="0 0 156 44" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<svg width="156" height="44" viewBox="0 0 156 44" fill="none" xmlns="http://www.w3.org/2000/svg">
 <g clip-path="url(#clip0)">
 <path d="M54.9348 9.12305H69.5877V11.9923H57.9155V20.6559H68.4455V23.4973H57.9155V34.473H54.9348V9.12305Z" fill="white"/>
 <path d="M73.1255 9.12305H76.1341V34.4452H73.1255V9.12305Z" fill="white"/>
@@ -7,7 +7,6 @@
 <path d="M118.282 34.668C117.669 34.4173 117.14 34.1109 116.694 33.693C116.22 33.2473 115.858 32.718 115.635 32.1052C115.413 31.4923 115.273 30.768 115.273 29.9045V19.1238H112.153V16.3938H115.301V11.2959H118.31V16.3938H122.683V19.1238H118.31V29.1802C118.31 30.183 118.505 30.9352 118.867 31.4088C119.313 31.938 119.953 32.2166 120.817 32.2166C121.513 32.2166 122.154 32.0216 122.795 31.6038V34.5288C122.433 34.6959 122.07 34.8073 121.708 34.8909C121.346 34.9745 120.873 35.0023 120.315 35.0023C119.591 35.0302 118.923 34.8909 118.282 34.668Z" fill="white"/>
 <path d="M128.952 33.7769C127.587 32.9412 126.528 31.8269 125.748 30.3505C124.968 28.9019 124.606 27.2584 124.606 25.4477C124.606 23.6927 124.968 22.1048 125.692 20.6284C126.417 19.1798 127.42 18.0098 128.757 17.1184C130.066 16.2548 131.598 15.8091 133.353 15.8091C135.108 15.8091 136.668 16.1991 137.95 17.0069C139.259 17.7869 140.234 18.9012 140.93 20.2662C141.627 21.6591 141.961 23.2469 141.961 25.0298C141.961 25.3919 141.933 25.6984 141.85 25.9491H127.587C127.67 27.3141 127.977 28.4841 128.59 29.4034C129.175 30.3505 129.927 31.0469 130.846 31.5205C131.765 31.9941 132.712 32.2169 133.687 32.2169C136 32.2169 137.782 31.1305 139.036 28.9577L141.571 30.1834C140.791 31.6319 139.732 32.8019 138.395 33.6377C137.058 34.4734 135.442 34.9191 133.576 34.9191C131.877 35.0305 130.317 34.6127 128.952 33.7769ZM138.785 23.5255C138.73 22.7734 138.535 22.0212 138.145 21.2691C137.755 20.5169 137.17 19.8762 136.362 19.3469C135.554 18.8177 134.523 18.5669 133.297 18.5669C131.877 18.5669 130.679 19.0127 129.704 19.9319C128.729 20.8512 128.088 22.0491 127.782 23.5255H138.785Z" fill="white"/>
 <path d="M145.471 16.4219H148.34V19.3191H148.479C148.841 18.3162 149.51 17.5083 150.541 16.8398C151.544 16.1712 152.602 15.8369 153.716 15.8369C154.552 15.8369 155.249 15.9762 155.834 16.2269V19.4583C155.081 19.0683 154.218 18.9012 153.299 18.9012C152.435 18.9012 151.627 19.1519 150.903 19.6533C150.179 20.1548 149.594 20.8233 149.148 21.6591C148.702 22.4948 148.507 23.4141 148.507 24.3612V34.4733H145.499V16.4219H145.471Z" fill="white"/>
-<rect x="9.89282" y="18.0063" width="31.3277" height="24.4208" fill="url(#pattern0)"/>
 <path d="M37.0631 20.0376H23.7056L12.0195 31.7265L18.6969 38.4038L37.0631 20.0376Z" fill="#54C5F8"/>
 <path d="M8.68014 28.3864L2 21.7063L23.7063 0H37.0638L8.68014 28.3864Z" fill="#54C5F8"/>
 <path d="M18.6975 38.4039L23.7062 43.4126H37.0637L25.3749 31.7266L18.6975 38.4039Z" fill="#01579B"/>
@@ -16,9 +15,6 @@
 <path d="M37.0638 20.0376L25.3777 31.7237L37.0638 43.4126H23.7063L18.6976 38.4039L12.0174 31.7237L23.7063 20.0376H37.0638ZM23.7063 0L2 21.7063L8.68014 28.3864L37.0638 0H23.7063Z" fill="url(#paint1_radial)"/>
 </g>
 <defs>
-<pattern id="pattern0" patternContentUnits="objectBoundingBox" width="1" height="1">
-<use xlink:href="#image0"/>
-</pattern>
 <linearGradient id="paint0_linear" x1="20.6447" y1="39.6934" x2="25.6192" y2="34.7189" gradientUnits="userSpaceOnUse">
 <stop stop-color="#1A237E" stop-opacity="0.4"/>
 <stop offset="1" stop-color="#1A237E" stop-opacity="0"/>
@@ -30,6 +26,5 @@
 <clipPath id="clip0">
 <rect width="156" height="43.641" fill="white"/>
 </clipPath>
-<image id="image0" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAABkCAYAAABO6zhfAAAACXBIWXMAAAx0AAAMdAH/P3aRAAAA"/>
 </defs>
 </svg>
diff --git a/sites/www/content/images/flutter-logo-white.svg b/sites/www/content/images/flutter-logo-white.svg
index cef778d6d8f..872478c3935 100644
--- a/sites/www/content/images/flutter-logo-white.svg
+++ b/sites/www/content/images/flutter-logo-white.svg
@@ -1,4 +1,4 @@
-<svg width="154" height="44" viewBox="0 0 154 44" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<svg width="154" height="44" viewBox="0 0 154 44" fill="none" xmlns="http://www.w3.org/2000/svg">
 <g clip-path="url(#clip0)">
 <path d="M52.9346 9.12305H67.5874V11.9923H55.9153V20.6559H66.4453V23.4973H55.9153V34.473H52.9346V9.12305Z" fill="white"/>
 <path d="M71.1252 9.12305H74.1338V34.4452H71.1252V9.12305Z" fill="white"/>
@@ -7,7 +7,6 @@
 <path d="M116.282 34.668C115.669 34.4173 115.14 34.1109 114.694 33.693C114.22 33.2473 113.858 32.718 113.635 32.1052C113.412 31.4923 113.273 30.768 113.273 29.9045V19.1238H110.153V16.3938H113.301V11.2959H116.31V16.3938H120.683V19.1238H116.31V29.1802C116.31 30.183 116.505 30.9352 116.867 31.4088C117.312 31.938 117.953 32.2166 118.817 32.2166C119.513 32.2166 120.154 32.0216 120.794 31.6038V34.5288C120.432 34.6959 120.07 34.8073 119.708 34.8909C119.346 34.9745 118.872 35.0023 118.315 35.0023C117.591 35.0302 116.922 34.8909 116.282 34.668Z" fill="white"/>
 <path d="M126.951 33.7769C125.586 32.9412 124.528 31.8269 123.748 30.3505C122.968 28.9019 122.606 27.2584 122.606 25.4477C122.606 23.6927 122.968 22.1048 123.692 20.6284C124.416 19.1798 125.419 18.0098 126.756 17.1184C128.066 16.2548 129.598 15.8091 131.353 15.8091C133.108 15.8091 134.668 16.1991 135.949 17.0069C137.259 17.7869 138.234 18.9012 138.93 20.2662C139.626 21.6591 139.961 23.2469 139.961 25.0298C139.961 25.3919 139.933 25.6984 139.849 25.9491H125.586C125.67 27.3141 125.976 28.4841 126.589 29.4034C127.174 30.3505 127.926 31.0469 128.846 31.5205C129.765 31.9941 130.712 32.2169 131.687 32.2169C133.999 32.2169 135.782 31.1305 137.036 28.9577L139.571 30.1834C138.791 31.6319 137.732 32.8019 136.395 33.6377C135.058 34.4734 133.442 34.9191 131.576 34.9191C129.876 35.0305 128.316 34.6127 126.951 33.7769ZM136.785 23.5255C136.729 22.7734 136.534 22.0212 136.144 21.2691C135.754 20.5169 135.169 19.8762 134.361 19.3469C133.554 18.8177 132.523 18.5669 131.297 18.5669C129.876 18.5669 128.679 19.0127 127.704 19.9319C126.729 20.8512 126.088 22.0491 125.781 23.5255H136.785Z" fill="white"/>
 <path d="M143.47 16.4219H146.34V19.3191H146.479C146.841 18.3162 147.51 17.5083 148.54 16.8398C149.543 16.1712 150.602 15.8369 151.716 15.8369C152.552 15.8369 153.248 15.9762 153.833 16.2269V19.4583C153.081 19.0683 152.218 18.9012 151.298 18.9012C150.435 18.9012 149.627 19.1519 148.903 19.6533C148.178 20.1548 147.593 20.8233 147.148 21.6591C146.702 22.4948 146.507 23.4141 146.507 24.3612V34.4733H143.498V16.4219H143.47Z" fill="white"/>
-<rect x="7.89282" y="18.0063" width="31.3277" height="24.4208" fill="url(#pattern0)"/>
 <path d="M35.0631 20.0376H21.7056L10.0195 31.7265L16.6969 38.4038L35.0631 20.0376Z" fill="#54C5F8"/>
 <path d="M6.68014 28.3864L0 21.7063L21.7063 0H35.0638L6.68014 28.3864Z" fill="#54C5F8"/>
 <path d="M16.6975 38.4039L21.7062 43.4126H35.0637L23.3749 31.7266L16.6975 38.4039Z" fill="#01579B"/>
@@ -16,9 +15,6 @@
 <path d="M35.0638 20.0376L23.3777 31.7237L35.0638 43.4126H21.7063L16.6976 38.4039L10.0174 31.7237L21.7063 20.0376H35.0638ZM21.7063 0L0 21.7063L6.68014 28.3864L35.0638 0H21.7063Z" fill="white"/>
 </g>
 <defs>
-<pattern id="pattern0" patternContentUnits="objectBoundingBox" width="1" height="1">
-<use xlink:href="#image0"/>
-</pattern>
 <linearGradient id="paint0_linear" x1="18.6447" y1="39.6934" x2="23.6192" y2="34.7189" gradientUnits="userSpaceOnUse">
 <stop stop-color="#1A237E" stop-opacity="0.4"/>
 <stop offset="1" stop-color="#1A237E" stop-opacity="0"/>
@@ -26,6 +22,5 @@
 <clipPath id="clip0">
 <rect width="153.833" height="43.4126" fill="white"/>
 </clipPath>
-<image id="image0" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAABkCAYAAABO6zhfAAAACXBIWXMAAAx0AAAMdAH/P3aRAAAA"/>
 </defs>
 </svg>
diff --git a/sites/www/content/images/flutter-logo.svg b/sites/www/content/images/flutter-logo.svg
index dc7c6a7e461..b2ed6a35730 100644
--- a/sites/www/content/images/flutter-logo.svg
+++ b/sites/www/content/images/flutter-logo.svg
@@ -1,4 +1,4 @@
-<svg width="156" height="44" viewBox="0 0 156 44" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<svg width="156" height="44" viewBox="0 0 156 44" fill="none" xmlns="http://www.w3.org/2000/svg">
 <g clip-path="url(#clip0)">
 <path d="M54.9348 9.12305H69.5877V11.9923H57.9155V20.6559H68.4455V23.4973H57.9155V34.473H54.9348V9.12305Z" fill="#4A4A4A"/>
 <path d="M73.1255 9.12305H76.1341V34.4452H73.1255V9.12305Z" fill="#4A4A4A"/>
@@ -7,7 +7,6 @@
 <path d="M118.282 34.668C117.669 34.4173 117.14 34.1109 116.694 33.693C116.22 33.2473 115.858 32.718 115.635 32.1052C115.413 31.4923 115.273 30.768 115.273 29.9045V19.1238H112.153V16.3938H115.301V11.2959H118.31V16.3938H122.683V19.1238H118.31V29.1802C118.31 30.183 118.505 30.9352 118.867 31.4088C119.313 31.938 119.953 32.2166 120.817 32.2166C121.513 32.2166 122.154 32.0216 122.795 31.6038V34.5288C122.433 34.6959 122.07 34.8073 121.708 34.8909C121.346 34.9745 120.873 35.0023 120.315 35.0023C119.591 35.0302 118.923 34.8909 118.282 34.668Z" fill="#4A4A4A"/>
 <path d="M128.952 33.7769C127.587 32.9412 126.528 31.8269 125.748 30.3505C124.968 28.9019 124.606 27.2584 124.606 25.4477C124.606 23.6927 124.968 22.1048 125.692 20.6284C126.417 19.1798 127.42 18.0098 128.757 17.1184C130.066 16.2548 131.598 15.8091 133.353 15.8091C135.108 15.8091 136.668 16.1991 137.95 17.0069C139.259 17.7869 140.234 18.9012 140.93 20.2662C141.627 21.6591 141.961 23.2469 141.961 25.0298C141.961 25.3919 141.933 25.6984 141.85 25.9491H127.587C127.67 27.3141 127.977 28.4841 128.59 29.4034C129.175 30.3505 129.927 31.0469 130.846 31.5205C131.765 31.9941 132.712 32.2169 133.687 32.2169C136 32.2169 137.782 31.1305 139.036 28.9577L141.571 30.1834C140.791 31.6319 139.732 32.8019 138.395 33.6377C137.058 34.4734 135.442 34.9191 133.576 34.9191C131.877 35.0305 130.317 34.6127 128.952 33.7769ZM138.785 23.5255C138.73 22.7734 138.535 22.0212 138.145 21.2691C137.755 20.5169 137.17 19.8762 136.362 19.3469C135.554 18.8177 134.523 18.5669 133.297 18.5669C131.877 18.5669 130.679 19.0127 129.704 19.9319C128.729 20.8512 128.088 22.0491 127.782 23.5255H138.785Z" fill="#4A4A4A"/>
 <path d="M145.471 16.4219H148.34V19.3191H148.479C148.841 18.3162 149.51 17.5083 150.541 16.8398C151.544 16.1712 152.602 15.8369 153.716 15.8369C154.552 15.8369 155.249 15.9762 155.834 16.2269V19.4583C155.081 19.0683 154.218 18.9012 153.299 18.9012C152.435 18.9012 151.627 19.1519 150.903 19.6533C150.179 20.1548 149.594 20.8233 149.148 21.6591C148.702 22.4948 148.507 23.4141 148.507 24.3612V34.4733H145.499V16.4219H145.471Z" fill="#4A4A4A"/>
-<rect x="9.89282" y="18.0063" width="31.3277" height="24.4208" fill="url(#pattern0)"/>
 <path d="M37.0631 20.0376H23.7056L12.0195 31.7265L18.6969 38.4038L37.0631 20.0376Z" fill="#54C5F8"/>
 <path d="M8.68014 28.3864L2 21.7063L23.7063 0H37.0638L8.68014 28.3864Z" fill="#54C5F8"/>
 <path d="M18.6975 38.4039L23.7062 43.4126H37.0637L25.3749 31.7266L18.6975 38.4039Z" fill="#01579B"/>
@@ -16,9 +15,6 @@
 <path d="M37.0638 20.0376L25.3777 31.7237L37.0638 43.4126H23.7063L18.6976 38.4039L12.0174 31.7237L23.7063 20.0376H37.0638ZM23.7063 0L2 21.7063L8.68014 28.3864L37.0638 0H23.7063Z" fill="url(#paint1_radial)"/>
 </g>
 <defs>
-<pattern id="pattern0" patternContentUnits="objectBoundingBox" width="1" height="1">
-<use xlink:href="#image0"/>
-</pattern>
 <linearGradient id="paint0_linear" x1="20.6447" y1="39.6934" x2="25.6192" y2="34.7189" gradientUnits="userSpaceOnUse">
 <stop stop-color="#1A237E" stop-opacity="0.4"/>
 <stop offset="1" stop-color="#1A237E" stop-opacity="0"/>
@@ -30,6 +26,5 @@
 <clipPath id="clip0">
 <rect width="156" height="43.641" fill="white"/>
 </clipPath>
-<image id="image0" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAABkCAYAAABO6zhfAAAACXBIWXMAAAx0AAAMdAH/P3aRAAAA"/>
 </defs>
 </svg>
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index 4a2ceb14ad9..185568943ba 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -25,14 +25,17 @@ body.blog {
     min-width: 8rem;
 
     img {
-      &.diagram-wrap {
+      &.diagram-wrap,
+      &.small-diagram-wrap {
         background-color: var(--site-diagram-wrap-bgColor);
+      }
+
+      &.diagram-wrap {
         padding: 1rem;
         border-radius: 1rem;
       }
 
       &.small-diagram-wrap {
-        background-color: var(--site-diagram-wrap-bgColor);
         padding: 0.5rem;
         border-radius: 0.5rem;
       }
@@ -72,7 +75,6 @@ body.blog {
       }
     }
 
-
     > .content {
       padding: 1.5rem;
       color: var(--site-base-fgColor);

From fe7a635f4c5dc88d59b7800b450aa9377f9f9368 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 7 Oct 2026 17:50:39 +0800
Subject: [PATCH 06/14] Continue simplifications

---
 .../lib/_sass/components/_theming.scss        |  8 +++++++
 .../lib/components/blog/blog_index.dart       |  8 +++----
 .../blog/client/blog_categories.dart          | 22 +++++++------------
 .../lib/components/layout/theme_switcher.dart | 11 +++++++++-
 sites/docs/lib/_sass/base/_root.scss          |  8 -------
 .../styles/components/_theme-switcher.scss    |  8 -------
 sites/www/lib/styles/pages/_blog_page.scss    |  5 ++++-
 7 files changed, 34 insertions(+), 36 deletions(-)

diff --git a/packages/site_shared/lib/_sass/components/_theming.scss b/packages/site_shared/lib/_sass/components/_theming.scss
index 23458610eaa..c7fc8944eba 100644
--- a/packages/site_shared/lib/_sass/components/_theming.scss
+++ b/packages/site_shared/lib/_sass/components/_theming.scss
@@ -1,3 +1,11 @@
+body:not(.dark-mode) .dark-mode-visible {
+  display: none !important;
+}
+
+body.dark-mode .light-mode-visible {
+  display: none !important;
+}
+
 #theme-switcher {
   position: relative;
 
diff --git a/packages/site_shared/lib/components/blog/blog_index.dart b/packages/site_shared/lib/components/blog/blog_index.dart
index c80079349fe..72d88d5faa0 100644
--- a/packages/site_shared/lib/components/blog/blog_index.dart
+++ b/packages/site_shared/lib/components/blog/blog_index.dart
@@ -69,10 +69,10 @@ class BlogIndex extends StatelessComponent {
             BlogCard(
               post: posts[i].post,
               url: posts[i].url,
-              priority: switch (i) {
-                0 => BlogCardPriority.featured,
-                < 5 => BlogCardPriority.high,
-                _ => BlogCardPriority.normal,
+              priority: switch (BlogCardLayout.forIndex(i)) {
+                .featured => BlogCardPriority.featured,
+                .grid => BlogCardPriority.high,
+                .list => BlogCardPriority.normal,
               },
               className: BlogCardLayout.forIndex(i).className,
             ),
diff --git a/packages/site_shared/lib/components/blog/client/blog_categories.dart b/packages/site_shared/lib/components/blog/client/blog_categories.dart
index 154f77f6e1e..1535b9fe24e 100644
--- a/packages/site_shared/lib/components/blog/client/blog_categories.dart
+++ b/packages/site_shared/lib/components/blog/client/blog_categories.dart
@@ -95,7 +95,7 @@ class _BlogCategoriesState extends State<BlogCategories> {
   void initState() {
     super.initState();
     if (kIsWeb) {
-      _updateCategoryFromUrl(initial: true);
+      _updateCategoryFromUrl();
       _popStateSubscription = web.EventStreamProviders.popStateEvent
           .forTarget(web.window)
           .listen((_) => _updateCategoryFromUrl());
@@ -108,26 +108,20 @@ class _BlogCategoriesState extends State<BlogCategories> {
     super.dispose();
   }
 
-  void _updateCategoryFromUrl({bool initial = false}) {
+  void _updateCategoryFromUrl() {
     final uri = Uri.parse(web.window.location.href);
     final slug = uri.queryParameters['category'];
     final category = component.categories
         .where((c) => c.slug == slug)
         .firstOrNull;
 
-    if (initial) {
-      selectedCategory = category;
-      if (category != null) {
-        _applyLayout(category);
-      }
-      return;
-    }
+    // The cards already have the layout for the selected category,
+    // including the server-rendered layout when no category is selected.
+    if (category == selectedCategory) return;
 
-    if (category != selectedCategory) {
-      setState(() {
-        selectedCategory = category;
-      });
-    }
+    setState(() {
+      selectedCategory = category;
+    });
     _applyLayout(category);
   }
 
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index b1a24d77eef..06b360f689a 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -22,6 +22,8 @@ final class ThemeSwitcher extends StatefulComponent {
 
 /// A [ThemeSwitcher] variant for use inside an existing `@client` component,
 /// such as a client-hydrated header, to avoid nested `@client` anchors.
+// TODO: Remove this variant once
+//  Jaspr fixes nested `@client` components handling.
 final class NestedThemeSwitcher extends StatefulComponent {
   const NestedThemeSwitcher({super.key});
 
@@ -196,9 +198,16 @@ final class _ThemeButtonEntry extends StatelessComponent {
   Component build(BuildContext context) => li([
     button(
       events: {
-        'click': (_) {
+        'click': (event) {
           setMode(mode);
           context.findAncestorStateOfType<DropdownState>()?.toggle(to: false);
+
+          // Closing the menu hides this button, so return focus
+          // to the toggle to keep the user's place in the page.
+          final toggleButton = (event.target as web.Element?)
+              ?.closest('.dropdown')
+              ?.querySelector('.dropdown-button');
+          (toggleButton as web.HTMLElement?)?.focus();
         },
       },
       attributes: {
diff --git a/sites/docs/lib/_sass/base/_root.scss b/sites/docs/lib/_sass/base/_root.scss
index deceb9c3150..678b6484a71 100644
--- a/sites/docs/lib/_sass/base/_root.scss
+++ b/sites/docs/lib/_sass/base/_root.scss
@@ -116,10 +116,6 @@ body {
   --site-tag-amber-bgColor: #A65A16;
   --site-tag-amber-fgColor: #fff;
 
-  &:not(.dark-mode) .dark-mode-visible {
-    display: none !important;
-  }
-
   &.dark-mode {
     color-scheme: dark;
     --site-outline: rgba(95, 100, 119, .75);
@@ -213,9 +209,5 @@ body {
       font-weight: var(--opal-dark-font-weight) !important;
       text-decoration: var(--opal-dark-text-decoration) !important;
     }
-
-    .light-mode-visible {
-      display: none !important;
-    }
   }
 }
diff --git a/sites/www/lib/styles/components/_theme-switcher.scss b/sites/www/lib/styles/components/_theme-switcher.scss
index 8fa365057de..1300d941757 100644
--- a/sites/www/lib/styles/components/_theme-switcher.scss
+++ b/sites/www/lib/styles/components/_theme-switcher.scss
@@ -1,11 +1,3 @@
-body:not(.dark-mode) .dark-mode-visible {
-  display: none !important;
-}
-
-body.dark-mode .light-mode-visible {
-  display: none !important;
-}
-
 .site-header {
   #theme-switcher {
     display: inline-flex;
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index 185568943ba..c0d5e572e3d 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -130,7 +130,10 @@ body.blog {
   }
 }
 
-:where(.blog main) a {
+// Include `p a` to override the base paragraph link color,
+// which is more specific and applies outside of post content.
+:where(.blog main) a,
+:where(.blog main) p a {
   color: var(--site-link-fgColor);
 
   &:hover {

From 0da950b66c6ad1d35d94fbdeee927f9d9be6aecd Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 7 Oct 2026 18:11:13 +0800
Subject: [PATCH 07/14] Don't close on selection

---
 .../site_shared/lib/components/common/dropdown.dart | 13 ++++++++++---
 .../lib/components/layout/theme_switcher.dart       | 12 ++----------
 2 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/packages/site_shared/lib/components/common/dropdown.dart b/packages/site_shared/lib/components/common/dropdown.dart
index 0f55d31ee46..4c28a9feea2 100644
--- a/packages/site_shared/lib/components/common/dropdown.dart
+++ b/packages/site_shared/lib/components/common/dropdown.dart
@@ -79,9 +79,16 @@ final class DropdownState extends State<Dropdown> {
             },
             child: component.toggle,
           ),
-          div(id: '${component.id}-content', classes: 'dropdown-content', [
-            component.content,
-          ]),
+          div(
+            id: '${component.id}-content',
+            classes: 'dropdown-content',
+            // Make the content focusable, but not tabbable,
+            // so clicking an area of it that isn't otherwise focusable keeps
+            // focus within the dropdown rather than triggering the `focusout`
+            // handler above with a null `relatedTarget` and closing it.
+            attributes: const {'tabindex': '-1'},
+            [component.content],
+          ),
         ],
       ),
     );
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index 06b360f689a..d0a6860da3f 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -195,19 +195,11 @@ final class _ThemeButtonEntry extends StatelessComponent {
   final void Function(_Theme) setMode;
 
   @override
-  Component build(BuildContext context) => li([
+  Component build(BuildContext _) => li([
     button(
       events: {
-        'click': (event) {
+        'click': (_) {
           setMode(mode);
-          context.findAncestorStateOfType<DropdownState>()?.toggle(to: false);
-
-          // Closing the menu hides this button, so return focus
-          // to the toggle to keep the user's place in the page.
-          final toggleButton = (event.target as web.Element?)
-              ?.closest('.dropdown')
-              ?.querySelector('.dropdown-button');
-          (toggleButton as web.HTMLElement?)?.focus();
         },
       },
       attributes: {

From eb88a4c828685e0fbf2624bfd62e81b2a2f81d74 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 7 Oct 2026 19:12:59 +0800
Subject: [PATCH 08/14] Simplifications

---
 .../lib/_sass/components/_blog.scss           | 25 +++--------
 .../lib/_sass/components/_code.scss           | 10 +++++
 .../lib/components/blog/blog_card.dart        | 35 ++++-----------
 .../lib/components/blog/blog_index.dart       | 13 ++----
 .../lib/components/blog/blog_next_posts.dart  |  7 ++-
 .../lib/components/common/dropdown.dart       |  4 +-
 .../lib/components/layout/theme_switcher.dart | 43 +++++++++----------
 sites/docs/lib/_sass/base/_root.scss          |  8 ----
 .../www/lib/src/components/layout/header.dart |  2 +-
 sites/www/lib/src/layouts/blog_layout.dart    |  2 +-
 sites/www/lib/styles/components/_header.scss  |  1 +
 .../styles/components/_theme-switcher.scss    |  2 +-
 sites/www/lib/styles/core/_vars.scss          |  8 ----
 sites/www/lib/styles/pages/_blog_page.scss    |  2 +-
 14 files changed, 59 insertions(+), 103 deletions(-)

diff --git a/packages/site_shared/lib/_sass/components/_blog.scss b/packages/site_shared/lib/_sass/components/_blog.scss
index b5fb65854e7..f439d40e2c8 100644
--- a/packages/site_shared/lib/_sass/components/_blog.scss
+++ b/packages/site_shared/lib/_sass/components/_blog.scss
@@ -157,15 +157,10 @@
     margin-top: 0.25rem;
     margin-bottom: 0.5rem;
     color: var(--site-base-fgColor);
+  }
 
-    a {
-      color: inherit;
-      text-decoration: none;
-
-      &:hover {
-        color: var(--site-link-fgColor);
-      }
-    }
+  &:hover .blog-card-title {
+    color: var(--site-link-fgColor);
   }
 
   .blog-card-content {
@@ -365,16 +360,6 @@
     }
   }
 
-  > a {
-    text-decoration: none;
-    color: inherit;
-    display: block;
-
-    &:hover .post-info-name {
-      color: var(--site-link-fgColor);
-    }
-  }
-
   .post-info-author {
     display: flex;
     align-items: center;
@@ -434,6 +419,10 @@
       font-weight: var(--site-fontWeight-bold);
     }
 
+    a:hover {
+      color: var(--site-link-fgColor);
+    }
+
     .post-info-author-name {
       white-space: nowrap;
     }
diff --git a/packages/site_shared/lib/_sass/components/_code.scss b/packages/site_shared/lib/_sass/components/_code.scss
index acc8e2e4170..b931e31b6ee 100644
--- a/packages/site_shared/lib/_sass/components/_code.scss
+++ b/packages/site_shared/lib/_sass/components/_code.scss
@@ -57,6 +57,16 @@ pre {
     --opal-dark-color: var(--site-base-fgColor);
   }
 
+  @at-root body.dark-mode {
+    .opal,
+    .opal span {
+      color: var(--opal-dark-color) !important;
+      font-style: var(--opal-dark-font-style) !important;
+      font-weight: var(--opal-dark-font-weight) !important;
+      text-decoration: var(--opal-dark-text-decoration) !important;
+    }
+  }
+
   a {
     font-family: inherit;
     font-weight: inherit;
diff --git a/packages/site_shared/lib/components/blog/blog_card.dart b/packages/site_shared/lib/components/blog/blog_card.dart
index 73ae6ec4109..36f63358fe6 100644
--- a/packages/site_shared/lib/components/blog/blog_card.dart
+++ b/packages/site_shared/lib/components/blog/blog_card.dart
@@ -9,27 +9,26 @@ import 'package:jaspr_content/jaspr_content.dart';
 
 import '../../blog.dart';
 import '../../util.dart';
+import 'client/blog_categories.dart';
 
 class BlogCard extends StatelessComponent {
   const BlogCard({
     required this.post,
     required this.url,
-    this.className,
-    this.priority = BlogCardPriority.normal,
+    this.layout = .grid,
     super.key,
   });
 
   final Post post;
   final String url;
-  final String? className;
-  final BlogCardPriority priority;
+  final BlogCardLayout layout;
 
   @override
   Component build(BuildContext context) {
     final authors = context.page.authorsByIds(post.authorIds);
     return a(
       href: url,
-      classes: ['blog-card', ?className].toClasses,
+      classes: ['blog-card', layout.className].toClasses,
       attributes: {'data-category': post.category},
       [
         if (post.image case final postImage?)
@@ -37,13 +36,11 @@ class BlogCard extends StatelessComponent {
             img(
               src: postImage,
               alt: post.title,
-              loading: switch (priority) {
-                .featured => MediaLoading.eager,
-                .high => MediaLoading.lazy,
-                .normal => MediaLoading.lazy,
-              },
+              loading: layout == .featured
+                  ? MediaLoading.eager
+                  : MediaLoading.lazy,
               attributes: {
-                if (priority == .featured)
+                if (layout == .featured)
                   'fetchpriority': 'high'
                 else
                   'decoding': 'async',
@@ -95,19 +92,3 @@ class BlogCard extends StatelessComponent {
     );
   }
 }
-
-/// Priority levels for blog cards.
-///
-/// Used to configure loading behavior of their content, particularly images.
-enum BlogCardPriority {
-  /// A featured blog card.
-  featured,
-
-  /// A high-priority blog card.
-  ///
-  /// Often the first 5 or so cards.
-  high,
-
-  /// A normal-priority blog card.
-  normal,
-}
diff --git a/packages/site_shared/lib/components/blog/blog_index.dart b/packages/site_shared/lib/components/blog/blog_index.dart
index 72d88d5faa0..71e2186fb39 100644
--- a/packages/site_shared/lib/components/blog/blog_index.dart
+++ b/packages/site_shared/lib/components/blog/blog_index.dart
@@ -65,16 +65,11 @@ class BlogIndex extends StatelessComponent {
         classes: 'blog-posts-grid',
         attributes: {'data-selected': 'all'},
         [
-          for (var i = 0; i < posts.length; i++)
+          for (final (i, (:post, :url)) in posts.indexed)
             BlogCard(
-              post: posts[i].post,
-              url: posts[i].url,
-              priority: switch (BlogCardLayout.forIndex(i)) {
-                .featured => BlogCardPriority.featured,
-                .grid => BlogCardPriority.high,
-                .list => BlogCardPriority.normal,
-              },
-              className: BlogCardLayout.forIndex(i).className,
+              post: post,
+              url: url,
+              layout: .forIndex(i),
             ),
         ],
       ),
diff --git a/packages/site_shared/lib/components/blog/blog_next_posts.dart b/packages/site_shared/lib/components/blog/blog_next_posts.dart
index 78a640a03f5..9534323d15c 100644
--- a/packages/site_shared/lib/components/blog/blog_next_posts.dart
+++ b/packages/site_shared/lib/components/blog/blog_next_posts.dart
@@ -45,11 +45,10 @@ class BlogNextPosts extends StatelessComponent {
     return section(classes: 'blog-next-posts', [
       h2([.text(nextPostsTitle)]),
       div(classes: 'blog-posts-grid', [
-        for (final post in nextPosts)
+        for (final (:post, :url) in nextPosts)
           BlogCard(
-            post: post.post,
-            url: post.url,
-            className: 'layout-grid',
+            post: post,
+            url: url,
           ),
       ]),
     ]);
diff --git a/packages/site_shared/lib/components/common/dropdown.dart b/packages/site_shared/lib/components/common/dropdown.dart
index 4c28a9feea2..592cf425c5b 100644
--- a/packages/site_shared/lib/components/common/dropdown.dart
+++ b/packages/site_shared/lib/components/common/dropdown.dart
@@ -40,7 +40,7 @@ final class DropdownState extends State<Dropdown> {
     return GlobalEventListener(
       onClick: (event) {
         if (!_expanded) return;
-        final target = event.target as web.HTMLElement?;
+        final target = event.target as web.Element?;
         if (target == null || target.closest('#${component.id}') == null) {
           toggle(to: false);
         }
@@ -58,7 +58,7 @@ final class DropdownState extends State<Dropdown> {
           },
           'focusout': (e) {
             final relatedTarget =
-                (e as web.FocusEvent).relatedTarget as web.HTMLElement?;
+                (e as web.FocusEvent).relatedTarget as web.Element?;
             if (relatedTarget == null ||
                 relatedTarget.closest('#${component.id}') == null) {
               toggle(to: false);
diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index d0a6860da3f..b29042bd2e5 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -14,7 +14,7 @@ import '../common/material_icon.dart';
 
 @client
 final class ThemeSwitcher extends StatefulComponent {
-  const ThemeSwitcher();
+  const ThemeSwitcher({super.key});
 
   @override
   State<StatefulComponent> createState() => _ThemeSwitcherState();
@@ -46,7 +46,7 @@ enum _Theme {
 }
 
 final class _ThemeSwitcherState extends State<StatefulComponent> {
-  _Theme _currentTheme = _Theme.light;
+  _Theme _currentTheme = .light;
   web.MediaQueryList? _prefersDarkQuery;
   StreamSubscription<web.Event>? _pageShowSubscription;
   StreamSubscription<web.StorageEvent>? _storageSubscription;
@@ -62,19 +62,19 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
       _syncThemeFromStorage();
       _pageShowSubscription = web.EventStreamProviders.pageShowEvent
           .forTarget(web.window)
-          .listen((_) => _syncThemeFromStorage(updateState: true));
+          .listen((_) => _syncThemeFromStorage());
       _storageSubscription = web.EventStreamProviders.storageEvent
           .forTarget(web.window)
           .listen((event) {
             if (event.key == null || event.key == 'theme') {
-              _syncThemeFromStorage(updateState: true);
+              _syncThemeFromStorage();
             }
           });
       _mediaQuerySubscription = web.EventStreamProviders.changeEvent
           .forTarget(prefersDarkQuery)
           .listen((_) {
-            if (_currentTheme == _Theme.auto) {
-              _applyThemeToBody(_Theme.auto);
+            if (_currentTheme == .auto) {
+              _applyThemeToBody(.auto);
             }
           });
     }
@@ -92,13 +92,13 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
 
   _Theme _themeFromBodyClasses() {
     final classList = web.document.body?.classList;
-    if (classList == null) return _Theme.light;
+    if (classList == null) return .light;
     if (classList.contains(_Theme.auto.id)) {
-      return _Theme.auto;
+      return .auto;
     } else if (classList.contains(_Theme.dark.id)) {
-      return _Theme.dark;
+      return .dark;
     } else {
-      return _Theme.light;
+      return .light;
     }
   }
 
@@ -106,40 +106,37 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
     final classList = web.document.body?.classList;
     if (classList == null) return;
 
-    final isAuto = theme == _Theme.auto;
+    final isAuto = theme == .auto;
     final isDark = isAuto
         ? (_prefersDarkQuery?.matches ?? false)
-        : theme == _Theme.dark;
+        : theme == .dark;
 
     classList.toggle(_Theme.light.id, !isDark);
     classList.toggle(_Theme.dark.id, isDark);
     classList.toggle(_Theme.auto.id, isAuto);
   }
 
-  void _syncThemeFromStorage({bool updateState = false}) {
-    _Theme? storedTheme;
+  void _syncThemeFromStorage() {
+    _Theme resolvedTheme;
     try {
       // Match the early theme script, which defaults to light
       // when no valid theme is stored.
-      storedTheme = switch (web.window.localStorage.getItem('theme')) {
-        'auto-mode' => _Theme.auto,
-        'dark-mode' => _Theme.dark,
-        _ => _Theme.light,
+      resolvedTheme = switch (web.window.localStorage.getItem('theme')) {
+        'auto-mode' => .auto,
+        'dark-mode' => .dark,
+        _ => .light,
       };
     } catch (_) {
       // localStorage is not available, fall back to body classes.
+      resolvedTheme = _themeFromBodyClasses();
     }
 
-    final resolvedTheme = storedTheme ?? _themeFromBodyClasses();
-
     _applyThemeToBody(resolvedTheme);
 
-    if (updateState && resolvedTheme != _currentTheme) {
+    if (resolvedTheme != _currentTheme) {
       setState(() {
         _currentTheme = resolvedTheme;
       });
-    } else {
-      _currentTheme = resolvedTheme;
     }
   }
 
diff --git a/sites/docs/lib/_sass/base/_root.scss b/sites/docs/lib/_sass/base/_root.scss
index 678b6484a71..a249206cfeb 100644
--- a/sites/docs/lib/_sass/base/_root.scss
+++ b/sites/docs/lib/_sass/base/_root.scss
@@ -201,13 +201,5 @@ body {
     --site-tag-orange-fgColor: #fff;
     --site-tag-amber-bgColor: #A65A16;
     --site-tag-amber-fgColor: #fff;
-
-    .opal,
-    .opal span {
-      color: var(--opal-dark-color) !important;
-      font-style: var(--opal-dark-font-style) !important;
-      font-weight: var(--opal-dark-font-weight) !important;
-      text-decoration: var(--opal-dark-text-decoration) !important;
-    }
   }
 }
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index bc3cddcae69..dec931d761c 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -176,7 +176,7 @@ class _HeaderState extends State<Header> {
                   src: component.defaultLogoSrc,
                   alt: 'Flutter',
                 ),
-                // Avoid loading the dark logo on pages without dark mode.
+                // Don't load the dark logo on pages without dark mode.
                 if (component.supportsDarkMode)
                   img(
                     classes: 'dark-mode-visible',
diff --git a/sites/www/lib/src/layouts/blog_layout.dart b/sites/www/lib/src/layouts/blog_layout.dart
index 9a95891b82d..fd75742f888 100644
--- a/sites/www/lib/src/layouts/blog_layout.dart
+++ b/sites/www/lib/src/layouts/blog_layout.dart
@@ -60,7 +60,7 @@ class BlogLayout extends DefaultLayout {
       main_([
         article(classes: 'content', [
           div(
-            classes: 'content ${isPost ? 'post-content' : ''}',
+            classes: ['content', if (isPost) 'post-content'].toClasses,
             attributes: scroll.spyContent,
             [
               div(id: 'site-content-title', [
diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index aab87fb37c2..bb8a27695f8 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -174,6 +174,7 @@
     background-color: white;
     color: var(--blue-6);
     display: none;
+    white-space: nowrap;
   }
 
   .hamburger {
diff --git a/sites/www/lib/styles/components/_theme-switcher.scss b/sites/www/lib/styles/components/_theme-switcher.scss
index 1300d941757..0615c479830 100644
--- a/sites/www/lib/styles/components/_theme-switcher.scss
+++ b/sites/www/lib/styles/components/_theme-switcher.scss
@@ -45,7 +45,7 @@
   }
 
   @media (min-width: 1024px) and (any-hover: hover) {
-    &:has(#theme-switcher) .search {
+    &:not(.searching):has(#theme-switcher) .search {
       margin-right: 0.25rem;
     }
 
diff --git a/sites/www/lib/styles/core/_vars.scss b/sites/www/lib/styles/core/_vars.scss
index 31899136b1f..bd3acbf7e48 100644
--- a/sites/www/lib/styles/core/_vars.scss
+++ b/sites/www/lib/styles/core/_vars.scss
@@ -175,14 +175,6 @@ body.dark-mode {
 
   --site-code-highlight-bgColor: rgba(164, 158, 62, 0.15);
   --site-diagram-wrap-bgColor: #e1e6ea;
-
-  .opal,
-  .opal span {
-    color: var(--opal-dark-color) !important;
-    font-style: var(--opal-dark-font-style) !important;
-    font-weight: var(--opal-dark-font-weight) !important;
-    text-decoration: var(--opal-dark-text-decoration) !important;
-  }
 }
 
 .text-coral {
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index c0d5e572e3d..43081f634a9 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -99,7 +99,7 @@ body.blog {
 
       font-family: var(--site-ui-fontFamily);
       font-weight: 500;
-      color: var(--site-primary-color);
+      color: var(--site-link-fgColor);
       text-decoration: none;
       cursor: pointer;
       background: none;

From e8ea6e8da9b8dd9dbd6ab35979e224110e0cc49e Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 7 Oct 2026 19:39:41 +0800
Subject: [PATCH 09/14] Organize and increase consistency of updated code

---
 .../lib/_sass/components/_blog.scss           |  6 ++-
 .../lib/_sass/components/_code.scss           | 20 +++++-----
 .../lib/components/blog/blog_card.dart        |  5 ++-
 .../lib/components/blog/blog_card_layout.dart | 37 +++++++++++++++++++
 .../blog/client/blog_categories.dart          | 35 +-----------------
 .../www/lib/src/components/layout/header.dart | 13 ++++---
 6 files changed, 62 insertions(+), 54 deletions(-)
 create mode 100644 packages/site_shared/lib/components/blog/blog_card_layout.dart

diff --git a/packages/site_shared/lib/_sass/components/_blog.scss b/packages/site_shared/lib/_sass/components/_blog.scss
index f439d40e2c8..f132a91fad6 100644
--- a/packages/site_shared/lib/_sass/components/_blog.scss
+++ b/packages/site_shared/lib/_sass/components/_blog.scss
@@ -159,8 +159,10 @@
     color: var(--site-base-fgColor);
   }
 
-  &:hover .blog-card-title {
-    color: var(--site-link-fgColor);
+  &:hover, &:focus-visible {
+    .blog-card-title {
+      color: var(--site-link-fgColor);
+    }
   }
 
   .blog-card-content {
diff --git a/packages/site_shared/lib/_sass/components/_code.scss b/packages/site_shared/lib/_sass/components/_code.scss
index b931e31b6ee..5ad9733d7bf 100644
--- a/packages/site_shared/lib/_sass/components/_code.scss
+++ b/packages/site_shared/lib/_sass/components/_code.scss
@@ -57,16 +57,6 @@ pre {
     --opal-dark-color: var(--site-base-fgColor);
   }
 
-  @at-root body.dark-mode {
-    .opal,
-    .opal span {
-      color: var(--opal-dark-color) !important;
-      font-style: var(--opal-dark-font-style) !important;
-      font-weight: var(--opal-dark-font-weight) !important;
-      text-decoration: var(--opal-dark-text-decoration) !important;
-    }
-  }
-
   a {
     font-family: inherit;
     font-weight: inherit;
@@ -479,3 +469,13 @@ iframe[src^="https://dartpad"] {
     }
   }
 }
+
+body.dark-mode {
+  .opal,
+  .opal span {
+    color: var(--opal-dark-color) !important;
+    font-style: var(--opal-dark-font-style) !important;
+    font-weight: var(--opal-dark-font-weight) !important;
+    text-decoration: var(--opal-dark-text-decoration) !important;
+  }
+}
diff --git a/packages/site_shared/lib/components/blog/blog_card.dart b/packages/site_shared/lib/components/blog/blog_card.dart
index 36f63358fe6..1a5984be424 100644
--- a/packages/site_shared/lib/components/blog/blog_card.dart
+++ b/packages/site_shared/lib/components/blog/blog_card.dart
@@ -9,7 +9,7 @@ import 'package:jaspr_content/jaspr_content.dart';
 
 import '../../blog.dart';
 import '../../util.dart';
-import 'client/blog_categories.dart';
+import 'blog_card_layout.dart';
 
 class BlogCard extends StatelessComponent {
   const BlogCard({
@@ -35,7 +35,8 @@ class BlogCard extends StatelessComponent {
           div(classes: 'blog-card-image', [
             img(
               src: postImage,
-              alt: post.title,
+              // The image is decorative since the title follows it.
+              alt: '',
               loading: layout == .featured
                   ? MediaLoading.eager
                   : MediaLoading.lazy,
diff --git a/packages/site_shared/lib/components/blog/blog_card_layout.dart b/packages/site_shared/lib/components/blog/blog_card_layout.dart
new file mode 100644
index 00000000000..8c417985850
--- /dev/null
+++ b/packages/site_shared/lib/components/blog/blog_card_layout.dart
@@ -0,0 +1,37 @@
+// Copyright 2026, the Flutter authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that
+// can be found in the LICENSE file.
+
+/// The layout of a card in the blog index,
+/// determined by its position among the visible cards.
+enum BlogCardLayout {
+  /// A full-width card with a large image and title,
+  /// used to highlight the most prominent post.
+  featured,
+
+  /// A bordered tile that's arranged in a grid with other cards.
+  grid,
+
+  /// A full-width row with a small image beside the post details.
+  list,
+  ;
+
+  /// The CSS class applied to a `.blog-card` element to
+  /// style it with this layout.
+  String get className => switch (this) {
+    .featured => 'layout-featured',
+    .grid => 'layout-grid',
+    .list => 'layout-list',
+  };
+
+  /// Returns the layout for the card at the specified [index]
+  /// among the visible cards.
+  ///
+  /// The first card is [featured], the next four are [grid],
+  /// and all remaining cards are [list].
+  static BlogCardLayout forIndex(int index) => switch (index) {
+    0 => featured,
+    < 5 => grid,
+    _ => list,
+  };
+}
diff --git a/packages/site_shared/lib/components/blog/client/blog_categories.dart b/packages/site_shared/lib/components/blog/client/blog_categories.dart
index 1535b9fe24e..cf7ec042baf 100644
--- a/packages/site_shared/lib/components/blog/client/blog_categories.dart
+++ b/packages/site_shared/lib/components/blog/client/blog_categories.dart
@@ -10,6 +10,7 @@ import 'package:jaspr/jaspr.dart';
 import 'package:universal_web/web.dart' as web;
 
 import '../../../util.dart';
+import '../blog_card_layout.dart';
 
 class BlogCategory {
   const BlogCategory({
@@ -43,40 +44,6 @@ class BlogCategory {
   };
 }
 
-/// The layout of a card in the blog index,
-/// determined by its position among the visible cards.
-enum BlogCardLayout {
-  /// A full-width card with a large image and title,
-  /// used to highlight the most prominent post.
-  featured,
-
-  /// A bordered tile that's arranged in a grid with other cards.
-  grid,
-
-  /// A full-width row with a small image beside the post details.
-  list,
-  ;
-
-  /// The CSS class applied to a `.blog-card` element to
-  /// style it with this layout.
-  String get className => switch (this) {
-    .featured => 'layout-featured',
-    .grid => 'layout-grid',
-    .list => 'layout-list',
-  };
-
-  /// Returns the layout for the card at the specified [index]
-  /// among the visible cards.
-  ///
-  /// The first card is [featured], the next four are [grid],
-  /// and all remaining cards are [list].
-  static BlogCardLayout forIndex(int index) => switch (index) {
-    0 => featured,
-    < 5 => grid,
-    _ => list,
-  };
-}
-
 @client
 class BlogCategories extends StatefulComponent {
   const BlogCategories({required this.categories, super.key});
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index dec931d761c..9a9a3951c1d 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -7,6 +7,7 @@ import 'dart:async';
 import 'package:jaspr/dom.dart';
 import 'package:jaspr/jaspr.dart';
 import 'package:site_shared/components/layout/theme_switcher.dart';
+import 'package:site_shared/util.dart';
 import 'package:universal_web/web.dart' as web;
 
 import '../../data/nav_items.dart';
@@ -153,7 +154,7 @@ class _HeaderState extends State<Header> {
       if (_isMobile && _navOpen) 'mobile-nav-open',
       if (_searchActive) 'searching',
       'site-header',
-    ].join(' ');
+    ].toClasses;
 
     final isBlog = component.pageUrl.startsWith('/blog');
 
@@ -216,7 +217,7 @@ class _HeaderState extends State<Header> {
                 'icon-btn',
                 'search',
                 if (_navOpen || _searchActive) 'active',
-              ].join(' '),
+              ].toClasses,
               [
                 span(
                   events: {'click': (_) => _toggleSearch()},
@@ -310,7 +311,7 @@ class _NavEntry extends StatelessComponent {
       return li([
         a(
           href: data.href,
-          classes: ['btn', 'top-level', if (isActive) 'active'].join(' '),
+          classes: ['btn', 'top-level', if (isActive) 'active'].toClasses,
           [.text(data.label)],
         ),
       ]);
@@ -321,7 +322,7 @@ class _NavEntry extends StatelessComponent {
       [
         a(
           href: data.href,
-          classes: ['btn', 'top-level', if (isActive) 'active'].join(' '),
+          classes: ['btn', 'top-level', if (isActive) 'active'].toClasses,
           events: {
             'click': ?onMobileClick,
           },
@@ -332,7 +333,7 @@ class _NavEntry extends StatelessComponent {
         ),
         const div(classes: 'dd-connector', []),
         div(
-          classes: ['dd', if (data.secondColumn != null) 'dd-double'].join(' '),
+          classes: ['dd', if (data.secondColumn != null) 'dd-double'].toClasses,
           [
             ul([
               _NavDropdownLink(
@@ -382,7 +383,7 @@ class _NavDropdownLink extends StatelessComponent {
             'btn',
             if (isNested) 'subMenu',
             if (pageUrl == link.href) 'active',
-          ].join(' '),
+          ].toClasses,
           href: link.href,
           target: link.isExternal ? Target.blank : null,
           [.text(link.label)],

From d8bd52887bb31c66666bf6e414baaaa06f75b624 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 7 Oct 2026 20:18:54 +0800
Subject: [PATCH 10/14] Continue clean up and add additional API docs

---
 .../lib/components/layout/theme_switcher.dart | 108 ++++++++++--------
 .../lib/src/utils/theme_script.dart           |   9 +-
 .../www/lib/src/components/layout/header.dart |   4 +-
 sites/www/lib/styles/components/_footer.scss  |  14 +--
 sites/www/lib/styles/core/_base.scss          |   6 +-
 sites/www/lib/styles/core/_structure.scss     |   2 +-
 sites/www/lib/styles/core/_vars.scss          |   8 ++
 sites/www/lib/styles/pages/_blog_page.scss    |  25 +---
 8 files changed, 88 insertions(+), 88 deletions(-)

diff --git a/packages/site_shared/lib/components/layout/theme_switcher.dart b/packages/site_shared/lib/components/layout/theme_switcher.dart
index b29042bd2e5..4456d927192 100644
--- a/packages/site_shared/lib/components/layout/theme_switcher.dart
+++ b/packages/site_shared/lib/components/layout/theme_switcher.dart
@@ -46,89 +46,100 @@ enum _Theme {
 }
 
 final class _ThemeSwitcherState extends State<StatefulComponent> {
+  /// The theme the user selected, which is marked as selected in the menu.
   _Theme _currentTheme = .light;
-  web.MediaQueryList? _prefersDarkQuery;
-  StreamSubscription<web.Event>? _pageShowSubscription;
-  StreamSubscription<web.StorageEvent>? _storageSubscription;
-  StreamSubscription<web.Event>? _mediaQuerySubscription;
+
+  /// The media query for whether the device prefers a dark color scheme,
+  /// used to resolve the [_Theme.auto] theme.
+  late final web.MediaQueryList _prefersDarkQuery;
+
+  /// The subscriptions to window and media query events,
+  /// which are canceled when this state is disposed.
+  final List<StreamSubscription<web.Event>> _subscriptions = [];
 
   @override
   void initState() {
     super.initState();
     if (kIsWeb) {
-      final prefersDarkQuery = _prefersDarkQuery = web.window.matchMedia(
-        '(prefers-color-scheme: dark)',
-      );
+      _prefersDarkQuery = web.window.matchMedia('(prefers-color-scheme: dark)');
       _syncThemeFromStorage();
-      _pageShowSubscription = web.EventStreamProviders.pageShowEvent
-          .forTarget(web.window)
-          .listen((_) => _syncThemeFromStorage());
-      _storageSubscription = web.EventStreamProviders.storageEvent
-          .forTarget(web.window)
-          .listen((event) {
-            if (event.key == null || event.key == 'theme') {
-              _syncThemeFromStorage();
-            }
-          });
-      _mediaQuerySubscription = web.EventStreamProviders.changeEvent
-          .forTarget(prefersDarkQuery)
-          .listen((_) {
-            if (_currentTheme == .auto) {
-              _applyThemeToBody(.auto);
-            }
-          });
+      _subscriptions.addAll([
+        web.EventStreamProviders.pageShowEvent
+            .forTarget(web.window)
+            .listen(_onPageShow),
+        web.EventStreamProviders.storageEvent
+            .forTarget(web.window)
+            .listen(_onStorageChange),
+        web.EventStreamProviders.changeEvent
+            .forTarget(_prefersDarkQuery)
+            .listen(_onPrefersDarkChange),
+      ]);
     }
   }
 
   @override
   void dispose() {
-    // DOM event stream cancellations complete synchronously and don't need to
-    // be awaited in synchronous lifecycle teardown.
-    unawaited(_pageShowSubscription?.cancel());
-    unawaited(_storageSubscription?.cancel());
-    unawaited(_mediaQuerySubscription?.cancel());
+    // DOM event stream cancellations complete synchronously and
+    // don't need to be awaited in synchronous lifecycle teardown.
+    for (final subscription in _subscriptions) {
+      unawaited(subscription.cancel());
+    }
     super.dispose();
   }
 
-  _Theme _themeFromBodyClasses() {
-    final classList = web.document.body?.classList;
-    if (classList == null) return .light;
-    if (classList.contains(_Theme.auto.id)) {
-      return .auto;
-    } else if (classList.contains(_Theme.dark.id)) {
-      return .dark;
-    } else {
-      return .light;
+  /// Resyncs the theme when the page is restored from the back/forward cache,
+  /// as it might have been changed on another page.
+  void _onPageShow(web.Event event) {
+    if ((event as web.PageTransitionEvent).persisted) {
+      _syncThemeFromStorage();
+    }
+  }
+
+  /// Resyncs the theme when another tab or window changes
+  /// the stored theme preference or clears storage.
+  void _onStorageChange(web.StorageEvent event) {
+    if (event.key == null || event.key == 'theme') {
+      _syncThemeFromStorage();
     }
   }
 
+  /// Reapplies the automatic theme when
+  /// the device's preferred color scheme changes.
+  void _onPrefersDarkChange(web.Event _) {
+    if (_currentTheme == .auto) {
+      _applyThemeToBody(.auto);
+    }
+  }
+
+  /// Updates the theme classes on the document body to reflect [theme],
+  /// resolving [_Theme.auto] to light or dark based on the device preference.
   void _applyThemeToBody(_Theme theme) {
     final classList = web.document.body?.classList;
     if (classList == null) return;
 
     final isAuto = theme == .auto;
-    final isDark = isAuto
-        ? (_prefersDarkQuery?.matches ?? false)
-        : theme == .dark;
+    final isDark = isAuto ? _prefersDarkQuery.matches : theme == .dark;
 
     classList.toggle(_Theme.light.id, !isDark);
     classList.toggle(_Theme.dark.id, isDark);
     classList.toggle(_Theme.auto.id, isAuto);
   }
 
+  /// Applies the theme preference saved in local storage
+  /// and updates [_currentTheme] to match it.
   void _syncThemeFromStorage() {
     _Theme resolvedTheme;
     try {
       // Match the early theme script, which defaults to light
       // when no valid theme is stored.
-      resolvedTheme = switch (web.window.localStorage.getItem('theme')) {
-        'auto-mode' => .auto,
-        'dark-mode' => .dark,
-        _ => .light,
-      };
+      final storedTheme = web.window.localStorage.getItem('theme');
+      resolvedTheme = _Theme.values.firstWhere(
+        (theme) => theme.id == storedTheme,
+        orElse: () => .light,
+      );
     } catch (_) {
-      // localStorage is not available, fall back to body classes.
-      resolvedTheme = _themeFromBodyClasses();
+      // localStorage is not available, keep the current theme.
+      resolvedTheme = _currentTheme;
     }
 
     _applyThemeToBody(resolvedTheme);
@@ -140,6 +151,7 @@ final class _ThemeSwitcherState extends State<StatefulComponent> {
     }
   }
 
+  /// Applies [newTheme] and saves it as the user's theme preference.
   void _setTheme(_Theme newTheme) {
     if (newTheme == _currentTheme) return;
 
diff --git a/packages/site_shared/lib/src/utils/theme_script.dart b/packages/site_shared/lib/src/utils/theme_script.dart
index 7ad6459d3d0..5da723e65ea 100644
--- a/packages/site_shared/lib/src/utils/theme_script.dart
+++ b/packages/site_shared/lib/src/utils/theme_script.dart
@@ -5,18 +5,17 @@
 import 'package:jaspr/dom.dart';
 import 'package:jaspr/jaspr.dart';
 
-/// Inline `<script>` component that applies the user's saved theme preference
-/// (`light-mode`, `dark-mode`, or `auto-mode`) to `document.body` before the
-/// page paints.
+/// Inline `<script>` component that
+/// applies the user's saved theme preference to
+/// `document.body` before the page paints.
 const Component themeInitScript = script(
   content: '''
 try {
-  const storedTheme = window.localStorage.getItem('theme') ?? 'light-mode';
+  const storedTheme = window.localStorage.getItem('theme');
   const isAuto = storedTheme === 'auto-mode';
   const isDark = isAuto
       ? window.matchMedia('(prefers-color-scheme: dark)').matches
       : storedTheme === 'dark-mode';
-  document.body.classList.remove('light-mode', 'dark-mode', 'auto-mode');
   document.body.classList.add(isDark ? 'dark-mode' : 'light-mode');
   if (isAuto) document.body.classList.add('auto-mode');
 } catch (_) {
diff --git a/sites/www/lib/src/components/layout/header.dart b/sites/www/lib/src/components/layout/header.dart
index 9a9a3951c1d..fd95a1ea7e6 100644
--- a/sites/www/lib/src/components/layout/header.dart
+++ b/sites/www/lib/src/components/layout/header.dart
@@ -177,12 +177,14 @@ class _HeaderState extends State<Header> {
                   src: component.defaultLogoSrc,
                   alt: 'Flutter',
                 ),
-                // Don't load the dark logo on pages without dark mode.
+                // Don't load the dark logo on pages without dark mode, and
+                // lazy load it otherwise so it's only fetched when displayed.
                 if (component.supportsDarkMode)
                   img(
                     classes: 'dark-mode-visible',
                     src: component.darkLogoSrc,
                     alt: 'Flutter',
+                    loading: MediaLoading.lazy,
                   ),
               ]),
             ]),
diff --git a/sites/www/lib/styles/components/_footer.scss b/sites/www/lib/styles/components/_footer.scss
index 2dbfb8cfcf3..8f65141d5f7 100644
--- a/sites/www/lib/styles/components/_footer.scss
+++ b/sites/www/lib/styles/components/_footer.scss
@@ -5,15 +5,9 @@
   color: var(--site-base-fgColor-lighter);
   padding: 70px var(--gutter);
 
-  ul {
-    a {
-      color: var(--site-base-fgColor-lighter);
-
-      &:hover {
-        color: var(--site-base-fgColor);
-        text-decoration: underline;
-      }
-    }
+  ul a:hover {
+    color: var(--site-base-fgColor);
+    text-decoration: underline;
   }
 
   .content {
@@ -37,7 +31,6 @@
 
         a {
           margin-right: 1.25rem;
-          color: var(--site-base-fgColor-lighter);
           display: inline-flex;
           align-items: center;
 
@@ -54,7 +47,6 @@
         span {
           font-family: var(--font-ui);
           font-size: var(--font-size-heading-5);
-          color: var(--site-base-fgColor-lighter);
         }
       }
 
diff --git a/sites/www/lib/styles/core/_base.scss b/sites/www/lib/styles/core/_base.scss
index f099042e974..24ef94f4776 100644
--- a/sites/www/lib/styles/core/_base.scss
+++ b/sites/www/lib/styles/core/_base.scss
@@ -50,7 +50,7 @@ h6 {
   line-height: 1.2;
   letter-spacing: -0.005em;
   font-weight: var(--font-weight-bold);
-  color: black;
+  color: var(--site-heading-fgColor);
 }
 
 :is(h1, h2, h3, h4, h5, h6):not(:where(.post-content *)) {
@@ -84,10 +84,10 @@ h4.eyebrow {
 
 p:not(:where(.post-content *)) {
   line-height: 1.4;
-  color: var(--grey-6);
+  color: var(--site-paragraph-fgColor);
 
   a {
-    color: var(--blue-6);
+    color: var(--site-paragraph-link-fgColor);
   }
 }
 
diff --git a/sites/www/lib/styles/core/_structure.scss b/sites/www/lib/styles/core/_structure.scss
index 07f3f5fa19e..ce88093d03c 100644
--- a/sites/www/lib/styles/core/_structure.scss
+++ b/sites/www/lib/styles/core/_structure.scss
@@ -1,7 +1,7 @@
 @use 'breakpoints';
 
 main {
-  background-color: white;
+  background-color: var(--site-base-bgColor);
   flex: 1 0 auto;
   overflow: hidden;
 }
diff --git a/sites/www/lib/styles/core/_vars.scss b/sites/www/lib/styles/core/_vars.scss
index bd3acbf7e48..f11dfb5c335 100644
--- a/sites/www/lib/styles/core/_vars.scss
+++ b/sites/www/lib/styles/core/_vars.scss
@@ -98,6 +98,10 @@
   --site-link-fgColor: var(--site-primary-color);
   --site-link-fgColor-active: #0553b1;
 
+  --site-heading-fgColor: black;
+  --site-paragraph-fgColor: var(--grey-6);
+  --site-paragraph-link-fgColor: var(--blue-6);
+
   --site-filledButton-bgColor: var(--blue-6);
   --site-filledButton-fgColor: #fff;
 
@@ -170,6 +174,10 @@ body.dark-mode {
   --site-link-fgColor: #47b0f8;
   --site-link-fgColor-active: #28a3f7;
 
+  --site-heading-fgColor: var(--site-base-fgColor);
+  --site-paragraph-fgColor: var(--site-base-fgColor);
+  --site-paragraph-link-fgColor: var(--site-link-fgColor);
+
   --site-header-bgColor: var(--site-raised-bgColor);
   --site-footer-bgColor: var(--site-raised-bgColor);
 
diff --git a/sites/www/lib/styles/pages/_blog_page.scss b/sites/www/lib/styles/pages/_blog_page.scss
index 43081f634a9..b8121a0bc6b 100644
--- a/sites/www/lib/styles/pages/_blog_page.scss
+++ b/sites/www/lib/styles/pages/_blog_page.scss
@@ -5,19 +5,14 @@ body.blog {
 }
 
 .blog main {
+  // Use the shared base colors rather than the www defaults.
+  --site-heading-fgColor: var(--site-base-fgColor);
+  --site-paragraph-fgColor: var(--site-base-fgColor);
+  --site-paragraph-link-fgColor: var(--site-link-fgColor);
+
   display: flex;
   flex-direction: row;
   justify-content: center;
-  background-color: var(--site-base-bgColor);
-
-  h1,
-  h2,
-  h3,
-  h4,
-  h5,
-  h6 {
-    color: var(--site-base-fgColor);
-  }
 
   > article {
     width: 60rem;
@@ -77,7 +72,6 @@ body.blog {
 
     > .content {
       padding: 1.5rem;
-      color: var(--site-base-fgColor);
     }
 
     @media (min-width: 576px) {
@@ -130,10 +124,7 @@ body.blog {
   }
 }
 
-// Include `p a` to override the base paragraph link color,
-// which is more specific and applies outside of post content.
-:where(.blog main) a,
-:where(.blog main) p a {
+:where(.blog main) a {
   color: var(--site-link-fgColor);
 
   &:hover {
@@ -145,10 +136,6 @@ body.blog {
   }
 }
 
-:where(.blog main) p {
-  color: var(--site-base-fgColor);
-}
-
 .blog .back-to-top {
   position: fixed;
   right: 1.5rem;

From 4f1dc36ca5a9f9f4b3cf0274012eb8abf45c9035 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Thu, 8 Oct 2026 01:14:04 +0800
Subject: [PATCH 11/14] Reduce overflow in header

---
 sites/www/lib/styles/components/_header.scss       | 14 ++++++++++----
 .../www/lib/styles/components/_theme-switcher.scss |  2 +-
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index bb8a27695f8..9ecfc8b29e8 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -158,7 +158,8 @@
           text-align: left;
           display: flex;
           color: white;
-          padding: 13px 16px;
+          padding: 12px 14px;
+          height: 2.25rem;
           transition: background-color 300ms ease;
 
           &:active,
@@ -174,7 +175,8 @@
     background-color: white;
     color: var(--blue-6);
     display: none;
-    white-space: nowrap;
+    padding: .5rem 1.75rem;
+    height: 40px;
   }
 
   .hamburger {
@@ -416,7 +418,11 @@
 
   @media (min-width: 1024px) and (any-hover: hover) {
     .content {
-      padding: 0 var(--gutter);
+      padding: 0 2rem;
+
+      @include breakpoints.screen(xl) {
+        padding: 0 var(--gutter);
+      }
     }
 
     nav {
@@ -429,7 +435,7 @@
       >ul {
         >li {
           display: inline-block;
-          margin-left: var(--spacer-sm);
+          margin-left: 6px;
 
           a .icon,
           .dd li.mobile-only {
diff --git a/sites/www/lib/styles/components/_theme-switcher.scss b/sites/www/lib/styles/components/_theme-switcher.scss
index 0615c479830..4b6802bd3a7 100644
--- a/sites/www/lib/styles/components/_theme-switcher.scss
+++ b/sites/www/lib/styles/components/_theme-switcher.scss
@@ -50,7 +50,7 @@
     }
 
     #theme-switcher {
-      margin-right: var(--gutter-sm);
+      margin-right: var(--spacer-sm);
     }
   }
 }

From d7aab6473ea94d3ba37adbf76e61b0a259019938 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Thu, 8 Oct 2026 01:14:32 +0800
Subject: [PATCH 12/14] Avoid button backgrounds in dropdowns

---
 sites/www/lib/styles/components/_header.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index 9ecfc8b29e8..048904357a8 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -445,7 +445,7 @@
           &:hover {
 
             /* keep li highlighted while over dropdown */
-            a.btn {
+            > a.btn {
               background-color: rgba(250, 250, 250, 0.15);
             }
 

From 199b6de016ea9045377462f192504563c573622a Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Thu, 8 Oct 2026 01:21:21 +0800
Subject: [PATCH 13/14] Fix positioning of header logo

---
 sites/www/lib/styles/components/_header.scss | 1 +
 1 file changed, 1 insertion(+)

diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index 048904357a8..54d6bedc130 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -84,6 +84,7 @@
     z-index: var(--site-z-floating);
 
     img {
+      display: block;
       width: 100%;
     }
 

From ae56abb78b48950bd64d262b7c448bb635e786b7 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Thu, 8 Oct 2026 01:34:24 +0800
Subject: [PATCH 14/14] Fix header transition

---
 sites/www/lib/styles/components/_header.scss | 1 -
 1 file changed, 1 deletion(-)

diff --git a/sites/www/lib/styles/components/_header.scss b/sites/www/lib/styles/components/_header.scss
index 54d6bedc130..a54b7331e36 100644
--- a/sites/www/lib/styles/components/_header.scss
+++ b/sites/www/lib/styles/components/_header.scss
@@ -605,7 +605,6 @@ body.interior {
 body.interior,
 body.in-content {
   .site-header:not(.mobile-nav-open) {
-    transition: box-shadow 200ms;
     background-color: var(--site-header-bgColor);
     box-shadow: 0 1px 6px rgba(0, 0, 0, 0.2);
     top: 0 !important;