diff --git a/gatsby-browser.tsx b/gatsby-browser.tsx
index 4b57943ba5..60e613143d 100644
--- a/gatsby-browser.tsx
+++ b/gatsby-browser.tsx
@@ -6,6 +6,7 @@ import { PostHogProvider } from 'posthog-js/react';
 import posthog from 'posthog-js';
 
 import UserContextWrapper from './src/contexts/user-context/wrap-with-provider';
+import { ThemeProvider } from './src/contexts/theme-context';
 import { useSiteMetadata } from './src/hooks/use-site-metadata';
 
 const onClientEntry: GatsbyBrowser['onClientEntry'] = () => {
@@ -56,9 +57,11 @@ const InsightsWrapper = ({ children }) => {
 
 export const wrapRootElement = ({ element }) => {
   return (
-    <InsightsWrapper>
-      <UserContextWrapper element={element} />
-    </InsightsWrapper>
+    <ThemeProvider>
+      <InsightsWrapper>
+        <UserContextWrapper element={element} />
+      </InsightsWrapper>
+    </ThemeProvider>
   );
 };
 
diff --git a/gatsby-ssr.tsx b/gatsby-ssr.tsx
index c34c350f36..a7e7c24e50 100644
--- a/gatsby-ssr.tsx
+++ b/gatsby-ssr.tsx
@@ -1,10 +1,15 @@
 import React from 'react';
 import type { GatsbySSR } from 'gatsby';
 import { getSandpackCssText } from '@codesandbox/sandpack-react';
+import { THEME_NO_FLASH_SCRIPT } from './src/utilities/theme';
 
 const onRenderBody: GatsbySSR['onRenderBody'] = ({ setHeadComponents }) => {
   const inlineScripts: React.ReactNode[] = [];
 
+  // Set the theme class on <html> before first paint to avoid a flash of the
+  // wrong theme. Runs first so the class is present before any styles apply.
+  inlineScripts.push(<script key="theme-no-flash" dangerouslySetInnerHTML={{ __html: THEME_NO_FLASH_SCRIPT }} />);
+
   // OneTrust consent management, inspiration taken from gatsby-google-tagmanager implementation
   if (process.env.ONE_TRUST_ENABLED === 'true' && !!process.env.ONE_TRUST_DOMAIN) {
     let domainId = process.env.ONE_TRUST_DOMAIN;
@@ -117,9 +122,16 @@ const onPreRenderHTML: GatsbySSR['onPreRenderHTML'] = ({ getHeadComponents, repl
 };
 
 /**
- * Load our user state
+ * Load our user state, wrapped in the theme provider so useTheme is available
+ * everywhere (including pages that don't use the docs Layout).
  */
 import UserContextWrapper from './src/contexts/user-context/wrap-with-provider';
-const wrapRootElement = UserContextWrapper;
+import { ThemeProvider } from './src/contexts/theme-context';
+
+const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => (
+  <ThemeProvider>
+    <UserContextWrapper element={element} />
+  </ThemeProvider>
+);
 
 export { onRenderBody, onPreRenderHTML, wrapRootElement };
diff --git a/src/components/Examples/ExamplesContent.tsx b/src/components/Examples/ExamplesContent.tsx
index 4ed10e4457..7bd553cc46 100644
--- a/src/components/Examples/ExamplesContent.tsx
+++ b/src/components/Examples/ExamplesContent.tsx
@@ -80,7 +80,7 @@ const ExamplesContent = ({ exampleImages }: { exampleImages: ImageProps[] }) =>
         width={660}
         height={282}
         alt="Grid Pattern"
-        className="!absolute -z-10 right-0 top-16 !hidden sm:!block w-[60%] md:w-[40%]"
+        className="!absolute -z-10 right-0 top-16 !hidden sm:!block dark:!hidden w-[60%] md:w-[40%]"
       />
 
       <StaticImage
@@ -88,7 +88,7 @@ const ExamplesContent = ({ exampleImages }: { exampleImages: ImageProps[] }) =>
         placeholder="blurred"
         width={260}
         alt="Grid Pattern"
-        className="-z-10 right-0 top-16 !absolute !block sm:!hidden"
+        className="-z-10 right-0 top-16 !absolute !block sm:!hidden dark:!hidden"
       />
     </>
   );
diff --git a/src/components/Examples/ExamplesGrid.tsx b/src/components/Examples/ExamplesGrid.tsx
index abb033eeab..127d0be897 100644
--- a/src/components/Examples/ExamplesGrid.tsx
+++ b/src/components/Examples/ExamplesGrid.tsx
@@ -65,7 +65,7 @@ const ExamplesGrid = ({
 
       return text.split(searchRegex).map((part, index) =>
         part.toLowerCase() === searchTerm.toLowerCase() ? (
-          <span key={index} className="bg-yellow-200">
+          <span key={index} className="bg-yellow-200 dark:bg-yellow-800">
             {part}
           </span>
         ) : (
@@ -86,19 +86,19 @@ const ExamplesGrid = ({
           role="button"
           aria-label={`View ${name} example`}
         >
-          <div className="z-0 bg-neutral-100 overflow-hidden h-64 sm:h-[12.5rem] relative flex justify-center items-center ">
+          <div className="z-0 bg-neutral-100 dark:bg-neutral-1200 overflow-hidden h-64 sm:h-[12.5rem] relative flex justify-center items-center ">
             <div className="group-hover/examples-index-card:scale-105 transition-transform">
               {exampleImages ? displayExampleImage(exampleImages, id, name) : null}
             </div>
-            <div className="flex bg-neutral-000 gap-x-1.5 py-1.5 px-2 absolute right-3 bottom-3 rounded border border-neutral-200 z-10">
+            <div className="flex bg-neutral-000 dark:bg-neutral-1300 gap-x-1.5 py-1.5 px-2 absolute right-3 bottom-3 rounded border border-neutral-200 dark:border-neutral-1000 z-10">
               {(languages ?? DEFAULT_EXAMPLE_LANGUAGES).map((language) => (
                 <Icon key={language} name={`icon-tech-${language}` as IconName} size="18px" />
               ))}
             </div>
           </div>
           <div className="z-10 pt-4">
-            <p className="ui-text-h4 text-neutral-1300">{highlightSearchTerm(name)}</p>
-            <p className="ui-text-p3 mt-2 text-neutral-900">{highlightSearchTerm(description)}</p>
+            <p className="ui-text-h4 text-neutral-1300 dark:text-neutral-000">{highlightSearchTerm(name)}</p>
+            <p className="ui-text-p3 mt-2 text-neutral-900 dark:text-neutral-500">{highlightSearchTerm(description)}</p>
             <div className="mt-4 flex gap-x-1">
               {products ? products.map((product) => displayProductLabel(product as ProductName, dataProducts)) : null}
               {/* {useCases ? useCases.map((useCase) => displayUseCaseLabel(useCase)) : null} */}
diff --git a/src/components/Examples/ExamplesRenderer.tsx b/src/components/Examples/ExamplesRenderer.tsx
index 8ff34448aa..33a4a2c135 100644
--- a/src/components/Examples/ExamplesRenderer.tsx
+++ b/src/components/Examples/ExamplesRenderer.tsx
@@ -1,7 +1,8 @@
-import React, { PropsWithChildren, useMemo } from 'react';
+import React, { PropsWithChildren, useEffect, useMemo, useState } from 'react';
 import { SandpackProvider, SandpackPreview } from '@codesandbox/sandpack-react';
 import { githubLight } from '@codesandbox/sandpack-themes';
-import { CodeEditor } from 'src/components/CodeEditor';
+import { CodeEditor, sandpackTheme } from 'src/components/CodeEditor';
+import { useTheme } from 'src/contexts/theme-context';
 import { LanguageKey } from 'src/data/languages/types';
 import { ExampleFiles, ExampleWithContent } from 'src/data/examples/types';
 import { updateAblyConnectionKey } from 'src/utilities/update-ably-connection-keys';
@@ -74,6 +75,14 @@ const ExamplesRenderer = ({
   children,
 }: PropsWithChildren<ExamplesRendererProps>) => {
   const { id, files, visibleFiles, layout, products } = example;
+  const { resolvedTheme } = useTheme();
+  // Sandpack/Chrome take the theme as JS values (not CSS `dark:` variants), so
+  // gate on mount: render light (matching the server) until hydrated, then
+  // follow the resolved theme. Avoids a hydration mismatch for dark-mode users
+  // when the editor is server-rendered.
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  const editorTheme = mounted ? resolvedTheme : 'light';
 
   const rewrittenFiles = useMemo<ExampleFiles>(() => {
     const result: ExampleFiles = {};
@@ -149,7 +158,7 @@ const ExamplesRenderer = ({
             : []),
         ],
       }}
-      theme={githubLight}
+      theme={editorTheme === 'dark' ? sandpackTheme : githubLight}
       template={determineSandpackTemplate(activeLanguage as LanguageKey)}
     >
       <div
@@ -181,7 +190,7 @@ const ExamplesRenderer = ({
         >
           <div className={cn('min-w-0 overflow-hidden', isVerticalLayout && 'md:flex-1')}>
             <CodeEditor
-              theme="light"
+              theme={editorTheme}
               editor={{
                 className: '',
                 showLineNumbers: true,
diff --git a/src/components/Homepage/ExamplesSection.tsx b/src/components/Homepage/ExamplesSection.tsx
index dd2995ccc5..3f7eb53dcd 100644
--- a/src/components/Homepage/ExamplesSection.tsx
+++ b/src/components/Homepage/ExamplesSection.tsx
@@ -8,9 +8,9 @@ export const ExamplesSection = ({ section, images }: { section: ExamplesSectionD
   const backgroundGrid = getImageFromList(images, 'examples_grid.png');
 
   return (
-    <div className="relative overflow-hidden flex flex-col rounded-lg border border-neutral-300 dark:border-neutral-1000 pt-6 pl-6 md:p-6 lg:p-8 bg-gradient-to-b from-[#fff] to-[#F6F8FA]">
+    <div className="relative overflow-hidden flex flex-col rounded-lg border border-neutral-300 dark:border-neutral-1000 pt-6 pl-6 md:p-6 lg:p-8 bg-gradient-to-b from-[#fff] to-[#F6F8FA] dark:bg-none">
       {backgroundGrid && (
-        <div className="w-full h-full absolute top-0 right-0 z-0">
+        <div className="w-full h-full absolute top-0 right-0 z-0 dark:hidden">
           <Image image={backgroundGrid} />
         </div>
       )}
diff --git a/src/components/Homepage/HomepageContent.tsx b/src/components/Homepage/HomepageContent.tsx
index b7c6168a08..a48fd7e0e4 100644
--- a/src/components/Homepage/HomepageContent.tsx
+++ b/src/components/Homepage/HomepageContent.tsx
@@ -23,14 +23,14 @@ export const HomepageContent = ({
       {mobileImage && (
         <Image
           image={mobileImage}
-          className="absolute top-[3.9375rem] right-0 z-[-1] block sm:hidden w-auto h-auto pointer-events-none"
+          className="absolute top-[3.9375rem] right-0 z-[-1] block sm:hidden dark:hidden w-auto h-auto pointer-events-none"
           aria-hidden="true"
         />
       )}
       {desktopImage && (
         <Image
           image={desktopImage}
-          className="absolute top-[3.9375rem] right-0 z-[-1] hidden sm:block w-auto h-auto pointer-events-none"
+          className="absolute top-[3.9375rem] right-0 z-[-1] hidden sm:block dark:hidden w-auto h-auto pointer-events-none"
           aria-hidden="true"
         />
       )}
diff --git a/src/components/Layout/Footer.tsx b/src/components/Layout/Footer.tsx
index 530a6df72c..ad0cbbf1f3 100644
--- a/src/components/Layout/Footer.tsx
+++ b/src/components/Layout/Footer.tsx
@@ -7,6 +7,7 @@ import cn from 'src/utilities/cn';
 import type { PageContextType } from './Layout';
 import { useLayoutContext } from 'src/contexts/layout-context';
 import Button from 'src/components/ui/Button';
+import ThemeToggle from './ThemeToggle';
 import { HandRaisedIcon, HandThumbDownIcon, HandThumbUpIcon } from '@heroicons/react/24/outline';
 import {
   HandRaisedIcon as HandRaisedSolidIcon,
@@ -329,11 +330,14 @@ const Footer: React.FC<{ pageContext: PageContextType }> = ({ pageContext }) =>
             </div>
           ))}
         </div>
-        <Status
-          additionalCSS="px-4 py-3 rounded-lg border border-neutral-300 dark:border-neutral-1000 hover:border-neutral-500 dark:hover:border-neutral-800 transition-colors"
-          statusUrl={StatusUrl}
-          showDescription
-        />
+        <div className="flex flex-col items-end gap-3">
+          <Status
+            additionalCSS="px-4 py-3 rounded-lg border border-neutral-300 dark:border-neutral-1000 hover:border-neutral-500 dark:hover:border-neutral-800 transition-colors"
+            statusUrl={StatusUrl}
+            showDescription
+          />
+          <ThemeToggle />
+        </div>
       </div>
     </footer>
   );
diff --git a/src/components/Layout/Header.test.tsx b/src/components/Layout/Header.test.tsx
index f3e38f0964..49e68c1fcf 100644
--- a/src/components/Layout/Header.test.tsx
+++ b/src/components/Layout/Header.test.tsx
@@ -81,7 +81,8 @@ describe('Header', () => {
 
   it('renders the header with logo and links', () => {
     render(<Header />);
-    expect(screen.getByAltText('Ably')).toBeInTheDocument();
+    // Two logo variants render (light + dark, CSS-toggled); both carry the alt.
+    expect(screen.getAllByAltText('Ably').length).toBeGreaterThan(0);
 
     expect(screen.getByText('Docs')).toBeInTheDocument();
     expect(screen.getByText('Platform')).toBeInTheDocument();
diff --git a/src/components/Layout/Header.tsx b/src/components/Layout/Header.tsx
index 5cb107262e..7bcc1df835 100644
--- a/src/components/Layout/Header.tsx
+++ b/src/components/Layout/Header.tsx
@@ -8,6 +8,7 @@ import cn from 'src/utilities/cn';
 import Icon from 'src/components/Icon';
 import TabMenu from 'src/components/ui/TabMenu';
 import Logo from 'src/images/ably-logo.svg';
+import LogoDark from 'src/images/ably-logo-dark.svg';
 import { track } from '@ably/ui/core/insights';
 import { componentMaxHeight, HEADER_BOTTOM_MARGIN, HEADER_HEIGHT } from 'src/utilities/heights';
 import LeftSidebar from './LeftSidebar';
@@ -228,7 +229,8 @@ const Header: React.FC = () => {
       <div className="flex items-center justify-between h-16 px-5 max-w-[1600px] mx-auto">
         <div className="flex items-center shrink-0">
           <a href="/docs" className="flex items-center gap-2 focus-base px-5 py-2 rounded -ml-5">
-            <img src={Logo} width="96px" alt="Ably" />
+            <img src={Logo} width="96px" alt="Ably" className="dark:hidden" />
+            <img src={LogoDark} width="96px" alt="Ably" className="hidden dark:block" />
             <span className="bg-neutral-000 dark:bg-neutral-1300 border border-neutral-300 dark:border-neutral-1000 text-[10px] font-bold text-neutral-1000 dark:text-neutral-400 px-1.5 py-[3px] rounded-md uppercase">
               Docs
             </span>
diff --git a/src/components/Layout/ThemeToggle.tsx b/src/components/Layout/ThemeToggle.tsx
new file mode 100644
index 0000000000..0644a9af0e
--- /dev/null
+++ b/src/components/Layout/ThemeToggle.tsx
@@ -0,0 +1,57 @@
+import React, { useEffect, useState } from 'react';
+import { ComputerDesktopIcon, MoonIcon, SunIcon } from '@heroicons/react/24/outline';
+import { track } from '@ably/ui/core/insights';
+import cn from 'src/utilities/cn';
+import { useTheme } from 'src/contexts/theme-context';
+import { DEFAULT_THEME, type Theme } from 'src/utilities/theme';
+
+const OPTIONS: { value: Theme; label: string; icon: typeof SunIcon }[] = [
+  { value: 'system', label: 'System theme', icon: ComputerDesktopIcon },
+  { value: 'dark', label: 'Dark theme', icon: MoonIcon },
+  { value: 'light', label: 'Light theme', icon: SunIcon },
+];
+
+const ThemeToggle: React.FC = () => {
+  const { theme, setTheme } = useTheme();
+  // `theme` comes from localStorage (client-only), so match the server's default
+  // until mounted to avoid a hydration mismatch on which cell is highlighted.
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  const selected = mounted ? theme : DEFAULT_THEME;
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Theme"
+      className="inline-flex items-center gap-0.5 p-0.5 rounded-lg border border-neutral-300 dark:border-neutral-1000"
+    >
+      {OPTIONS.map(({ value, label, icon: OptionIcon }) => {
+        const isActive = selected === value;
+        return (
+          <button
+            key={value}
+            type="button"
+            role="radio"
+            aria-checked={isActive}
+            aria-label={label}
+            title={label}
+            onClick={() => {
+              setTheme(value);
+              track('docs_theme_selected', { theme: value });
+            }}
+            className={cn(
+              'focus-base flex items-center justify-center size-8 rounded-md transition-colors',
+              isActive
+                ? 'bg-neutral-100 dark:bg-neutral-1100 text-neutral-1300 dark:text-neutral-000'
+                : 'text-neutral-800 dark:text-neutral-500 hover:bg-neutral-100 dark:hover:bg-neutral-1200 hover:text-neutral-1300 dark:hover:text-neutral-000',
+            )}
+          >
+            <OptionIcon className="size-[18px]" aria-hidden />
+          </button>
+        );
+      })}
+    </div>
+  );
+};
+
+export default ThemeToggle;
diff --git a/src/components/Layout/utils/styles.ts b/src/components/Layout/utils/styles.ts
index 0cb34120ae..e71d458d9c 100644
--- a/src/components/Layout/utils/styles.ts
+++ b/src/components/Layout/utils/styles.ts
@@ -1,7 +1,9 @@
 import cn from 'src/utilities/cn';
 
+// Tooltips stay a dark chip in both themes (dark surface, light text) rather
+// than inverting to a light chip in dark mode.
 export const tooltipContentClassName = cn(
-  'px-2 py-1 bg-neutral-1000 dark:bg-neutral-300 text-neutral-200 dark:text-neutral-1100 ui-text-p3 font-medium rounded-lg relative z-50 mt-2',
+  'px-2 py-1 bg-neutral-1000 dark:bg-neutral-1100 text-neutral-200 dark:text-neutral-200 ui-text-p3 font-medium rounded-lg relative z-50 mt-2',
   'data-[state=closed]:animate-[tooltipExit_0.25s_ease-in-out]',
   'data-[state=delayed-open]:animate-[tooltipEntry_0.25s_ease-in-out]',
 );
diff --git a/src/components/Redoc/Loader.tsx b/src/components/Redoc/Loader.tsx
index 107027a449..49bce977d0 100644
--- a/src/components/Redoc/Loader.tsx
+++ b/src/components/Redoc/Loader.tsx
@@ -1,58 +1,142 @@
+import { useEffect, useRef } from 'react';
 import { scriptLoader } from '../../external-scripts/utils';
 import './redoc.module.css';
 import { GoTopButton } from './GoTopButton';
 import { overrideMenuItemNavigation } from './utils';
+import { useTheme } from 'src/contexts/theme-context';
 
-export const Loader = ({ specUrl }: { specUrl: string }) => {
-  const redocDependencyScript = '//cdn.redoc.ly/redoc/v2.4.0/bundles/redoc.standalone.js';
-  const options = {
-    hideDownloadButton: true,
-    scrollYOffset: 64,
-    /* AblyUI variables doesn't work on this theme settings  */
-    theme: {
-      spacing: {
-        sectionHorizontal: 24,
-        sectionVertical: 16,
-      },
-      typography: {
-        fontSize: '1rem',
-        fontFamily: 'NEXT Book, Arial, Helvetica, sans-serif',
-        fontWeightRegular: 300,
-        fontWeightBold: 500,
-        headings: {
-          fontFamily: 'NEXT Book, Arial, Helvetica, sans-serif',
-          fontWeight: 500,
-        },
-        links: {
-          color: '#006EDC', // gui-default
-          hover: '#2894FF', // gui-hover
-          visited: '#4887c2', // gui-visited
-        },
-        code: {
-          fontSize: '0.875rem',
-          fontWeight: 400,
-          fontFamily: 'JetBrains Mono',
-        },
-      },
-      sidebar: {
-        backgroundColor: '#F4F8FB', // light grey
-        textColor: '#03020D', // ably black
-      },
-      colors: {
-        primary: {
-          main: '#03020D', // ably black
-        },
-      },
+const REDOC_SCRIPT_URL = '//cdn.redoc.ly/redoc/v2.4.0/bundles/redoc.standalone.js';
+
+// Redoc doesn't resolve CSS custom properties in its theme object, so these are
+// literal Ably neutral/gui hex values rather than var(--color-*) references.
+const baseTheme = {
+  spacing: {
+    sectionHorizontal: 24,
+    sectionVertical: 16,
+  },
+  typography: {
+    fontSize: '1rem',
+    fontFamily: 'NEXT Book, Arial, Helvetica, sans-serif',
+    fontWeightRegular: 300,
+    fontWeightBold: 500,
+    headings: {
+      fontFamily: 'NEXT Book, Arial, Helvetica, sans-serif',
+      fontWeight: 500,
+    },
+    code: {
+      fontSize: '0.875rem',
+      fontWeight: 400,
+      fontFamily: 'JetBrains Mono',
     },
-  };
-  if (typeof window !== 'undefined') {
-    scriptLoader(document, redocDependencyScript, {
-      onload: () => {
-        // @ts-ignore
-        Redoc.init(specUrl, options, document.getElementById('redoc-container'), overrideMenuItemNavigation);
-      },
+  },
+};
+
+const lightTheme = {
+  ...baseTheme,
+  typography: {
+    ...baseTheme.typography,
+    links: { color: '#006EDC', hover: '#2894FF', visited: '#4887c2' }, // gui-*
+  },
+  sidebar: {
+    backgroundColor: '#F4F8FB', // light grey
+    textColor: '#03020D', // ably black
+  },
+  colors: {
+    primary: { main: '#03020D' }, // ably black
+  },
+};
+
+const darkTheme = {
+  ...baseTheme,
+  typography: {
+    ...baseTheme.typography,
+    links: { color: '#4da6ff', hover: '#2894ff', visited: '#80b9f2' }, // gui-*-dark
+    code: { ...baseTheme.typography.code, color: '#e6eaf0', backgroundColor: '#141924' },
+  },
+  sidebar: {
+    backgroundColor: '#141924', // neutral-1200
+    textColor: '#e6eaf0', // neutral-300
+    activeTextColor: '#ff5416', // orange-600
+  },
+  rightPanel: {
+    backgroundColor: '#03020d', // neutral-1300
+    textColor: '#e6eaf0', // neutral-300
+  },
+  colors: {
+    primary: { main: '#eef1f6' }, // neutral-200
+    text: { primary: '#e6eaf0', secondary: '#8992a4' }, // neutral-300 / neutral-700
+    border: { dark: '#3f4555', light: '#2c3344' }, // neutral-1000 / neutral-1100
+    gray: { '50': '#141924', '100': '#2c3344' }, // neutral-1200 / neutral-1100
+  },
+  schema: {
+    nestedBackground: '#141924', // neutral-1200
+  },
+  codeBlock: {
+    backgroundColor: '#03020d', // neutral-1300
+  },
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const getRedoc = (): any =>
+  typeof window !== 'undefined' ? (window as unknown as { Redoc?: unknown }).Redoc : undefined;
+
+// Load the Redoc CDN bundle at most once across mounts and re-inits. Memoising
+// the load prevents attaching a second onload handler (and a second Redoc.init)
+// if the theme is toggled while the script is still downloading.
+let redocScriptPromise: Promise<void> | null = null;
+const loadRedoc = (): Promise<void> => {
+  if (getRedoc()) {
+    return Promise.resolve();
+  }
+  if (!redocScriptPromise) {
+    redocScriptPromise = new Promise<void>((resolve) => {
+      scriptLoader(document, REDOC_SCRIPT_URL, { onload: () => resolve() });
     });
   }
+  return redocScriptPromise;
+};
+
+export const Loader = ({ specUrl }: { specUrl: string }) => {
+  const { resolvedTheme } = useTheme();
+  // overrideMenuItemNavigation attaches document/body listeners + a
+  // MutationObserver and returns a disposer; hold it so each init is torn down
+  // before the next (theme toggle) and on unmount, rather than accumulating.
+  const cleanupRef = useRef<(() => void) | null>(null);
+
+  // (Re-)render Redoc for the current theme. Redoc bakes the theme in at init,
+  // so a theme change re-inits into a cleared container.
+  useEffect(() => {
+    if (typeof window === 'undefined' || !specUrl) {
+      return undefined;
+    }
+    let cancelled = false;
+    const options = {
+      hideDownloadButton: true,
+      scrollYOffset: 64,
+      theme: resolvedTheme === 'dark' ? darkTheme : lightTheme,
+    };
+
+    void loadRedoc().then(() => {
+      const Redoc = getRedoc();
+      const container = document.getElementById('redoc-container');
+      if (cancelled || !Redoc || !container) {
+        return;
+      }
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+      container.innerHTML = '';
+      Redoc.init(specUrl, options, container, () => {
+        cleanupRef.current = overrideMenuItemNavigation();
+      });
+    });
+
+    return () => {
+      cancelled = true;
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+    };
+  }, [specUrl, resolvedTheme]);
+
   return (
     <>
       <GoTopButton />
diff --git a/src/components/Redoc/redoc.module.css b/src/components/Redoc/redoc.module.css
index 66b786efe5..d355c173b2 100644
--- a/src/components/Redoc/redoc.module.css
+++ b/src/components/Redoc/redoc.module.css
@@ -11,6 +11,15 @@
   @apply font-medium;
 }
 
+/* Redoc colours its section sub-headers (h5, e.g. "path Parameters") with its
+   own muted dark token that the theme object's text.primary override doesn't
+   reach, leaving them dark-on-dark. Give them the same light treatment as the
+   rest of the Redoc text in dark mode. :global keeps the class names literal
+   (this is a CSS module) so they match Redoc's runtime-rendered DOM. */
+:global(.ui-theme-dark .redoc-content) h5 {
+  color: var(--color-neutral-300);
+}
+
 .redoc-content input.search-input {
   @apply font-medium px-6 py-2;
 }
diff --git a/src/components/Redoc/utils.ts b/src/components/Redoc/utils.ts
index f7e441185f..c821c51d8d 100644
--- a/src/components/Redoc/utils.ts
+++ b/src/components/Redoc/utils.ts
@@ -68,7 +68,15 @@ export const overrideMenuItemNavigation = () => {
     targetItem.addEventListener('click', clickHandler);
   });
 
-  // Clean up function to remove all event listeners
+  // Watch for URL changes so the listeners get torn down on navigation. The
+  // callback references cleanup (defined below); both exist by the time it fires.
+  const observer = new MutationObserver(() => {
+    if (window.location.pathname !== '/docs/api/control-api') {
+      cleanup();
+    }
+  });
+
+  // Clean up function: remove all event listeners and stop observing.
   const cleanup = () => {
     document.removeEventListener('scroll', scrollHandler);
     menuItems.forEach((item) => {
@@ -78,15 +86,9 @@ export const overrideMenuItemNavigation = () => {
       }
     });
     clickHandlers.clear();
+    observer.disconnect();
   };
 
-  // Watch for URL changes
-  const observer = new MutationObserver(() => {
-    if (window.location.pathname !== '/docs/api/control-api') {
-      cleanup();
-    }
-  });
-
   const body = document.querySelector('body');
   if (body) {
     observer.observe(body, { childList: true, subtree: true });
diff --git a/src/components/blocks/dividers/Aside.tsx b/src/components/blocks/dividers/Aside.tsx
index 3dce02cdc8..1302f279cd 100644
--- a/src/components/blocks/dividers/Aside.tsx
+++ b/src/components/blocks/dividers/Aside.tsx
@@ -34,7 +34,7 @@ const Aside = ({ children, attribs }: AsideProps) => {
           <span className={`${leftSideElement} ${pitfallElement}`}>&nbsp;</span>
           <strong className={tipTitleElement}>
             <ExclamationTriangleIcon className="size-[1rem] mr-3" aria-hidden />
-            <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">Important</span>
+            <span className="ui-text-p2 font-bold text-neutral-1300 dark:text-neutral-000 mb-12">Important</span>
           </strong>
         </>
       ) : attribs && attribs[`data-type`] === `further-reading` ? (
@@ -42,7 +42,7 @@ const Aside = ({ children, attribs }: AsideProps) => {
           <span className={`${leftSideElement} ${furtherReadingElement}`}>&nbsp;</span>
           <strong className={tipTitleElement}>
             <Icon name="icon-gui-resources" size="1rem" additionalCSS="mr-3" />
-            <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">Further Reading</span>
+            <span className="ui-text-p2 font-bold text-neutral-1300 dark:text-neutral-000 mb-12">Further Reading</span>
           </strong>
         </>
       ) : attribs && isVersioningInfo ? (
@@ -62,7 +62,7 @@ const Aside = ({ children, attribs }: AsideProps) => {
           <span className={`${leftSideElement} ${noteElement}`}>&nbsp;</span>
           <strong className={tipTitleElement}>
             <DocumentTextIcon className="size-[1rem] mr-3" aria-hidden />
-            <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">Note</span>
+            <span className="ui-text-p2 font-bold text-neutral-1300 dark:text-neutral-000 mb-12">Note</span>
           </strong>
         </>
       )}
diff --git a/src/components/blocks/dividers/dividers.module.css b/src/components/blocks/dividers/dividers.module.css
index c11886aace..4f14408427 100644
--- a/src/components/blocks/dividers/dividers.module.css
+++ b/src/components/blocks/dividers/dividers.module.css
@@ -47,9 +47,9 @@ div.inline-content-container {
 aside.inline-grid-paragraph {
   display: inline-grid;
   border-radius: 0.5em;
-  background-color: #fafafb;
+  background-color: var(--color-neutral-100);
   border-width: 1px;
-  border-color: #d9d9da;
+  border-color: var(--color-neutral-300);
   grid-template-rows: auto auto;
   margin-bottom: 24px;
   font-size: 16px;
@@ -58,6 +58,11 @@ aside.inline-grid-paragraph {
   width: 100%;
 }
 
+:global(.ui-theme-dark) aside.inline-grid-paragraph {
+  background-color: var(--color-neutral-1200);
+  border-color: var(--color-neutral-1000);
+}
+
 span.versioningTitleElement {
   display: inline-flex;
   font-size: 10px;
@@ -72,7 +77,7 @@ div.versioningContainer {
   padding-top: var(--spacing-8);
   padding-left: var(--spacing-8);
   border-left: solid 1px;
-  color: #89929f;
+  color: var(--color-neutral-700);
 }
 
 div.versioningContainer * {
@@ -83,5 +88,5 @@ div.versioningContainer code {
   padding: 0;
   background-color: transparent;
   border: none;
-  color: #89929f;
+  color: var(--color-neutral-700);
 }
diff --git a/src/components/blocks/software/Code/ApiKeyIndicator.tsx b/src/components/blocks/software/Code/ApiKeyIndicator.tsx
index 5e7a9091ed..486be70770 100644
--- a/src/components/blocks/software/Code/ApiKeyIndicator.tsx
+++ b/src/components/blocks/software/Code/ApiKeyIndicator.tsx
@@ -20,8 +20,8 @@ const APIKeyIndicator = ({ tooltip }: ApiKeyIndicatorProps) => {
       {tooltipHover ? (
         <aside
           className="w-60 max-w-60 absolute -mt-[8.75rem] box-border
-          whitespace-pre-wrap bg-white shadow-tooltip rounded border border-light-grey
-          text-cool-black font-sans p-4 text-center text-p3 leading-5 cursor-default"
+          whitespace-pre-wrap bg-white dark:bg-neutral-1200 shadow-tooltip rounded border border-light-grey dark:border-neutral-1000
+          text-cool-black dark:text-neutral-000 font-sans p-4 text-center text-p3 leading-5 cursor-default"
         >
           {tooltip}
         </aside>
diff --git a/src/contexts/theme-context.test.tsx b/src/contexts/theme-context.test.tsx
new file mode 100644
index 0000000000..9e6a182193
--- /dev/null
+++ b/src/contexts/theme-context.test.tsx
@@ -0,0 +1,90 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ThemeProvider, useTheme } from './theme-context';
+import { THEME_STORAGE_KEY } from 'src/utilities/theme';
+
+const mockMatchMedia = (prefersDark: boolean) => {
+  window.matchMedia = jest.fn().mockImplementation((query: string) => ({
+    matches: prefersDark,
+    media: query,
+    onchange: null,
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  }));
+};
+
+const Probe = () => {
+  const { theme, resolvedTheme, setTheme } = useTheme();
+  return (
+    <div>
+      <span data-testid="theme">{theme}</span>
+      <span data-testid="resolved">{resolvedTheme}</span>
+      <button onClick={() => setTheme('dark')}>set dark</button>
+      <button onClick={() => setTheme('system')}>set system</button>
+    </div>
+  );
+};
+
+const renderWithProvider = () =>
+  render(
+    <ThemeProvider>
+      <Probe />
+    </ThemeProvider>,
+  );
+
+describe('ThemeProvider', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    document.documentElement.classList.remove('ui-theme-light', 'ui-theme-dark');
+    mockMatchMedia(false);
+  });
+
+  it('defaults to light and sets ui-theme-light on <html>', () => {
+    renderWithProvider();
+    expect(screen.getByTestId('theme')).toHaveTextContent('light');
+    expect(screen.getByTestId('resolved')).toHaveTextContent('light');
+    expect(document.documentElement).toHaveClass('ui-theme-light');
+  });
+
+  it('persists the choice and swaps the <html> class when it changes', () => {
+    renderWithProvider();
+    fireEvent.click(screen.getByText('set dark'));
+    expect(localStorage.getItem(THEME_STORAGE_KEY)).toBe('dark');
+    expect(screen.getByTestId('resolved')).toHaveTextContent('dark');
+    expect(document.documentElement).toHaveClass('ui-theme-dark');
+    expect(document.documentElement).not.toHaveClass('ui-theme-light');
+  });
+
+  it('resolves "system" to the OS preference', () => {
+    mockMatchMedia(true); // OS prefers dark
+    renderWithProvider();
+    fireEvent.click(screen.getByText('set system'));
+    expect(screen.getByTestId('theme')).toHaveTextContent('system');
+    expect(screen.getByTestId('resolved')).toHaveTextContent('dark');
+    expect(document.documentElement).toHaveClass('ui-theme-dark');
+  });
+
+  it('reads the persisted choice on mount', () => {
+    localStorage.setItem(THEME_STORAGE_KEY, 'dark');
+    renderWithProvider();
+    expect(screen.getByTestId('theme')).toHaveTextContent('dark');
+    expect(document.documentElement).toHaveClass('ui-theme-dark');
+  });
+
+  it('falls back to the default when the persisted value is invalid', () => {
+    localStorage.setItem(THEME_STORAGE_KEY, 'not-a-theme');
+    renderWithProvider();
+    expect(screen.getByTestId('theme')).toHaveTextContent('light');
+    expect(document.documentElement).toHaveClass('ui-theme-light');
+    expect(document.documentElement).not.toHaveClass('ui-theme-dark');
+  });
+
+  it('throws if useTheme is used without a provider', () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => render(<Probe />)).toThrow('useTheme must be used within a ThemeProvider');
+    spy.mockRestore();
+  });
+});
diff --git a/src/contexts/theme-context.tsx b/src/contexts/theme-context.tsx
new file mode 100644
index 0000000000..4a8388ecdf
--- /dev/null
+++ b/src/contexts/theme-context.tsx
@@ -0,0 +1,116 @@
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import {
+  DEFAULT_THEME,
+  THEME_CLASS_DARK,
+  THEME_CLASS_LIGHT,
+  THEME_STORAGE_KEY,
+  normalizeTheme,
+  type ResolvedTheme,
+  type Theme,
+} from 'src/utilities/theme';
+
+/**
+ * ThemeContext
+ *
+ * Site-wide light/dark/system theming. The choice is persisted to localStorage
+ * and reflected as `ui-theme-light` / `ui-theme-dark` on <html>, which drives
+ * Tailwind's `dark:` variants (see tailwind.config.js `darkMode`).
+ *
+ * `theme` is the user's choice; `resolvedTheme` is the concrete light/dark it
+ * resolves to (following the OS when set to 'system'). JS-driven consumers that
+ * can't use CSS `dark:` variants — e.g. the Sandpack editor — read `resolvedTheme`.
+ */
+
+type ThemeContextValue = {
+  theme: Theme;
+  resolvedTheme: ResolvedTheme;
+  setTheme: (theme: Theme) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+const systemPrefersDark = (): boolean => {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+  try {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches;
+  } catch {
+    return false;
+  }
+};
+
+const resolveTheme = (theme: Theme): ResolvedTheme =>
+  theme === 'system' ? (systemPrefersDark() ? 'dark' : 'light') : theme;
+
+// Read the persisted choice. localStorage access can throw where storage is
+// blocked (privacy modes, partitioned/sandboxed iframes); since ThemeProvider
+// is the root wrapper, an unhandled throw here would crash the whole app, so
+// fall back to the default.
+const readStoredTheme = (): Theme => {
+  if (typeof window === 'undefined') {
+    return DEFAULT_THEME;
+  }
+  try {
+    return normalizeTheme(localStorage.getItem(THEME_STORAGE_KEY));
+  } catch {
+    return DEFAULT_THEME;
+  }
+};
+
+const applyThemeClass = (resolved: ResolvedTheme): void => {
+  const { classList } = document.documentElement;
+  classList.remove(THEME_CLASS_LIGHT, THEME_CLASS_DARK);
+  classList.add(`ui-theme-${resolved}`);
+};
+
+export const ThemeProvider: React.FC<React.PropsWithChildren> = ({ children }) => {
+  const [theme, setThemeState] = useState<Theme>(readStoredTheme);
+  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(() => resolveTheme(theme));
+
+  const syncResolvedTheme = useCallback((resolved: ResolvedTheme) => {
+    applyThemeClass(resolved);
+    setResolvedTheme(resolved);
+  }, []);
+
+  // Reflect the current choice onto <html>. The pre-paint script in gatsby-ssr
+  // sets this before hydration; here we keep it in sync as the choice changes.
+  useEffect(() => {
+    syncResolvedTheme(resolveTheme(theme));
+  }, [theme, syncResolvedTheme]);
+
+  // When following the system preference, react to OS-level changes live.
+  useEffect(() => {
+    if (theme !== 'system' || typeof window === 'undefined') {
+      return undefined;
+    }
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const handleChange = () => syncResolvedTheme(mediaQuery.matches ? 'dark' : 'light');
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, [theme, syncResolvedTheme]);
+
+  const setTheme = useCallback((next: Theme) => {
+    try {
+      localStorage.setItem(THEME_STORAGE_KEY, next);
+    } catch {
+      // Ignore write failures (e.g. Safari private mode).
+    }
+    setThemeState(next);
+  }, []);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({ theme, resolvedTheme, setTheme }),
+    [theme, resolvedTheme, setTheme],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+};
+
+export const useTheme = (): ThemeContextValue => {
+  const context = useContext(ThemeContext);
+  if (context === undefined) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+};
diff --git a/src/images/ably-logo-dark.svg b/src/images/ably-logo-dark.svg
new file mode 100644
index 0000000000..caba263812
--- /dev/null
+++ b/src/images/ably-logo-dark.svg
@@ -0,0 +1,23 @@
+<svg width="204" height="64" viewBox="0 0 204 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M125.844 49.9572V8.17627H133.387V23.3024C135.942 20.87 139.233 19.5209 142.708 19.5209C150.864 19.5209 158.1 25.7349 158.1 35.0967C158.1 44.4586 150.864 50.693 142.708 50.693C139.049 50.693 135.594 49.2417 133.019 46.6049V49.9572H125.844ZM150.557 35.0967C150.557 29.8639 146.837 26.205 141.972 26.205C137.23 26.205 133.571 29.6799 133.387 34.7288V35.0967C133.387 40.3296 137.107 43.9885 141.972 43.9885C146.837 43.9885 150.557 40.3296 150.557 35.0967ZM161.595 49.9572V8.17627H169.138V49.9572H161.595ZM179.685 60.7908L184.08 50.3047L172.142 20.2568H180.298L187.902 41.2494L195.629 20.2568H203.907L187.718 60.8112H179.685V60.7908ZM113.866 20.2568V24.0383C111.249 21.1766 107.59 19.5413 103.829 19.5413C95.6735 19.5413 88.4374 25.7553 88.4374 35.1172C88.4374 44.4995 95.6735 50.693 103.829 50.693C107.734 50.693 111.433 48.9965 114.111 45.9508V49.9776H120.693V20.2568H113.866ZM113.13 35.0967C113.13 40.2683 109.41 43.9885 104.545 43.9885C99.6799 43.9885 95.9596 40.2683 95.9596 35.0967C95.9596 29.9252 99.6799 26.205 104.545 26.205C109.287 26.205 112.946 29.7413 113.13 34.7288V35.0967Z" fill="#FFFFFF"/>
+<path d="M38.5717 0L6.29575 59.0738L0 54.6586L29.8639 0H38.5717ZM39.0214 0L71.2973 59.0738L77.5931 54.6586L47.7292 0H39.0214Z" fill="url(#paint0_linear_991_548)"/>
+<path d="M70.8476 59.4213L38.7965 34.3201L6.74542 59.4213L13.2865 64L38.7965 44.0294L64.3066 64L70.8476 59.4213Z" fill="url(#paint1_linear_991_548)"/>
+<defs>
+<linearGradient id="paint0_linear_991_548" x1="10.9472" y1="74.8439" x2="64.9206" y2="14.9005" gradientUnits="userSpaceOnUse">
+<stop stop-color="#FF5416"/>
+<stop offset="0.2535" stop-color="#FF5115"/>
+<stop offset="0.461" stop-color="#FF4712"/>
+<stop offset="0.6523" stop-color="#FF350E"/>
+<stop offset="0.8327" stop-color="#FF1E08"/>
+<stop offset="1" stop-color="#FF0000"/>
+</linearGradient>
+<linearGradient id="paint1_linear_991_548" x1="21.4168" y1="78.7187" x2="53.3166" y2="43.2904" gradientUnits="userSpaceOnUse">
+<stop stop-color="#FF5416"/>
+<stop offset="0.2535" stop-color="#FF5115"/>
+<stop offset="0.461" stop-color="#FF4712"/>
+<stop offset="0.6523" stop-color="#FF350E"/>
+<stop offset="0.8327" stop-color="#FF1E08"/>
+<stop offset="1" stop-color="#FF0000"/>
+</linearGradient>
+</defs>
+</svg>
diff --git a/src/styles/global.css b/src/styles/global.css
index e11afbeb08..30e16fbf8f 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -46,10 +46,19 @@
     margin: 0;
     font-size: 16px;
     color: #161616;
+    background-color: var(--color-neutral-000);
     -webkit-font-smoothing: antialiased;
     min-width: 320px;
   }
 
+  /* Paint the page canvas for dark mode. Without this the body is transparent
+     and the browser's default white shows through behind themed sections. The
+     text colour is a fallback for any content lacking an explicit dark variant. */
+  .ui-theme-dark body {
+    color: var(--color-neutral-200);
+    background-color: var(--color-neutral-1300);
+  }
+
   code {
     font-family: inherit;
     font-weight: inherit;
diff --git a/src/styles/ui/core/styles/text.css b/src/styles/ui/core/styles/text.css
index 0682ae6c8b..93ba0d1d4d 100644
--- a/src/styles/ui/core/styles/text.css
+++ b/src/styles/ui/core/styles/text.css
@@ -103,6 +103,21 @@
     @apply text-neutral-300;
   }
 
+  /* Headings and body copy hardcode dark colours above (text-cool-black /
+     text-charcoal-grey). Flip them for dark mode so any ui-text-* element is
+     legible without every call site needing an explicit dark: variant. Wrapped
+     in :where() so these contribute no specificity: they still override the
+     hardcoded base (equal specificity, later in source) but any element that
+     sets its own dark:text-* (e.g. a tooltip on a light surface) wins. */
+  .ui-theme-dark
+    :where(.ui-text-title, .ui-text-h1, .ui-text-h2, .ui-text-h3, .ui-text-h4, .ui-text-h5, .ui-text-quote) {
+    @apply text-neutral-000;
+  }
+
+  .ui-theme-dark :where(.ui-text-p1, .ui-text-p2, .ui-text-p3, .ui-text-p4) {
+    @apply text-neutral-300;
+  }
+
   .ui-text-code {
     @apply font-mono font-normal text-code;
   }
@@ -115,7 +130,7 @@
     @apply inline-flex font-mono px-[0.1875rem] py-1 text-code text-neutral-1000 font-medium bg-neutral-200 border border-neutral-400 rounded-md;
   }
 
-  .dark .ui-text-code-inline {
+  .ui-theme-dark .ui-text-code-inline {
     @apply text-neutral-300 bg-neutral-1000 border-neutral-900;
   }
 
diff --git a/src/utilities/theme.ts b/src/utilities/theme.ts
new file mode 100644
index 0000000000..2ab7bd2eb2
--- /dev/null
+++ b/src/utilities/theme.ts
@@ -0,0 +1,49 @@
+// Shared theme constants and the pre-paint init script. Kept framework-agnostic
+// (no React) so it can be imported by both the theme context and gatsby-ssr.
+
+export type Theme = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+
+// Persisted user choice. The docs site is its own origin, so this is scoped to
+// docs; a future cross-property theme would move this to a shared cookie.
+export const THEME_STORAGE_KEY = 'ably.docs.theme';
+
+// Default until the user chooses. Deliberately 'light' (not 'system') while
+// content imagery is still light-only (see DX-1518 phase 4); flip to 'system'
+// once dark-mode imagery lands.
+export const DEFAULT_THEME: Theme = 'light';
+
+export const THEME_CLASS_LIGHT = 'ui-theme-light';
+export const THEME_CLASS_DARK = 'ui-theme-dark';
+
+const THEMES: readonly Theme[] = ['light', 'dark', 'system'];
+
+export const isTheme = (value: unknown): value is Theme => THEMES.includes(value as Theme);
+
+// Coerce an unknown/legacy persisted value to a known theme so a corrupt entry
+// can never produce a `ui-theme-<garbage>` class with no light/dark fallback.
+export const normalizeTheme = (value: string | null): Theme => (isTheme(value) ? value : DEFAULT_THEME);
+
+/**
+ * Inline script injected into <head> by gatsby-ssr so the theme class is set on
+ * <html> before first paint, preventing a flash of the wrong theme on the
+ * static build. It runs pre-hydration, so it must be self-contained and mirror
+ * the resolution logic in theme-context (including the stored-value validation).
+ */
+export const THEME_NO_FLASH_SCRIPT = `
+(function () {
+  try {
+    var stored = localStorage.getItem('${THEME_STORAGE_KEY}');
+    var theme = stored === 'light' || stored === 'dark' || stored === 'system' ? stored : '${DEFAULT_THEME}';
+    var resolved =
+      theme === 'system'
+        ? window.matchMedia('(prefers-color-scheme: dark)').matches
+          ? 'dark'
+          : 'light'
+        : theme;
+    document.documentElement.classList.add('ui-theme-' + resolved);
+  } catch (e) {
+    document.documentElement.classList.add('${THEME_CLASS_LIGHT}');
+  }
+})();
+`;
