diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index b7b75d6..5fc57af 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -6,6 +6,7 @@ import "./storybook.css"; /* Storybook CSS override */
 import { ThemeProvider } from "../src";
 import { GenericTheme, DiamondTheme, DiamondDSTheme } from "../src";
 import { ThemeSwapper, TextLight, TextDark, TextSystem } from "./ThemeSwapper";
+import { DocsContainer } from "@storybook/blocks";
 import "../src/styles/diamondDS/diamond-ds-roles.css";
 
 const TextThemeBase = "Theme: Generic";
@@ -91,6 +92,26 @@ const preview: Preview = {
         date: /Date$/i,
       },
     },
+    docs: {
+      container: ({ children, context }) => {
+        const selectedThemeMode = context.store.userGlobals.globals.themeMode;
+
+        const resolvedMode =
+          selectedThemeMode === TextLight
+            ? "light"
+            : selectedThemeMode === TextDark
+              ? "dark"
+              : window.matchMedia("(prefers-color-scheme: dark)").matches
+                ? "dark"
+                : "light";
+
+        React.useEffect(() => {
+          document.documentElement.setAttribute("data-mode", resolvedMode);
+        }, [resolvedMode]);
+
+        return <DocsContainer context={context}>{children}</DocsContainer>;
+      },
+    },
     backgrounds: { disable: true },
     layout: "fullscreen",
     options: {
diff --git a/.storybook/storybook.css b/.storybook/storybook.css
index 3ceb267..9f5fb9a 100644
--- a/.storybook/storybook.css
+++ b/.storybook/storybook.css
@@ -1,58 +1,125 @@
 :root {
-    --ds-font-body: 'Inter', system-ui, -apple-system, BlinkMacSystemFont,
-      'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
-  
-    --ds-font-heading: 'Outfit', system-ui, -apple-system, BlinkMacSystemFont,
-      'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
-  
-    --ds-font-mono: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, Monaco,
-      Consolas, 'Liberation Mono', 'Courier New', monospace;
-  }
-  
-  /* Docs root */
-  .sbdocs, .sbdocs p, .sbdocs li,.sb-unstyled, .sb-unstyled ul, .sb-unstyled li {
-    font-family: var(--ds-font-body);
-    font-size: 16px !important;
-    line-height: 1.6;
-  }
-  
-  /* Lists */
-  .sbdocs li {
-    font-size: 16px !important;
-  }
-  
-  /* Headings use Outfit or Inter */
-  
-  .sbdocs h1 {
-    font-family: var(--ds-font-heading);
-  }
-  
-  .sbdocs h3,
-  .sbdocs h4,
-  .sbdocs h5,
-  .sbdocs h6 {
-    font-family: var(--ds-font-body);
-  }
-  
-  /* Code uses IBM Plex Mono */
-  .sbdocs code,
-  .sbdocs pre,
-  .sbdocs kbd,
-  .sbdocs samp,
-  .token {
-    font-family: var(--ds-font-mono);
-    font-size: 1em;
-  }
-  
-  /* Neutralise Storybook Docs inline preview background wrapper */
-  .sbdocs-preview div[style*="background-color"], #storybook-root div[style*="background-color"] {
-    background-color: transparent !important;
-  }
-  
-  .light .sbdocs-preview div[style*="background-color"] {
-    background-color: #f6f6f6 !important;
-  }
-  
-  .dark .sbdocs-preview div[style*="background-color"]{
-    background-color: #212121   !important;
-  }
+  --ds-font-body:
+    "Inter", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    Helvetica, Arial, sans-serif;
+
+  --ds-font-heading:
+    "Outfit", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    Helvetica, Arial, sans-serif;
+
+  --ds-font-mono:
+    "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace;
+}
+
+body .sbdocs {
+  background-color: var(--ds-surface);
+}
+
+/* Docs root */
+.sbdocs,
+.sbdocs p,
+.sbdocs li,
+.sb-unstyled,
+.sb-unstyled ul,
+.sb-unstyled li {
+  font-family: var(--ds-font-body);
+  font-size: 16px !important;
+  line-height: 1.6;
+  color: var(--ds-on-surface);
+}
+
+/* Lists */
+.sbdocs li {
+  font-size: 16px !important;
+}
+
+/* Headings use Outfit or Inter */
+
+.sbdocs h1 {
+  font-family: var(--ds-font-heading);
+  color: var(--ds-on-surface);
+}
+
+.sbdocs h2 {
+  font-family: var(--ds-font-body);
+  color: var(--ds-on-surface);
+  border-bottom: 1px solid var(--ds-border-subtle);
+}
+
+.sbdocs h3,
+.sbdocs h4,
+.sbdocs h5,
+.sbdocs h6 {
+  font-family: var(--ds-font-body);
+  color: var(--ds-on-surface);
+}
+
+.sbdocs .docblock-source {
+  /* code blocks in Storybook Docs */
+}
+
+.sbdocs code {
+  background-color: var(--ds-surface-container) !important;
+  color: var(--ds-on-surface-variant) !important;
+  border: 1px solid var(--ds-border-subtle) !important;
+}
+/* Code uses IBM Plex Mono */
+.sbdocs code,
+.sbdocs pre,
+.sbdocs kbd,
+.sbdocs samp,
+.token {
+  font-family: var(--ds-font-mono);
+  font-size: 1em;
+}
+
+/* Neutralise Storybook Docs inline preview background wrapper */
+.sbdocs-preview div[style*="background-color"],
+#storybook-root div[style*="background-color"] {
+  background-color: transparent !important;
+}
+
+.light .sbdocs-preview div[style*="background-color"] {
+  background-color: #f6f6f6 !important;
+}
+
+.dark .sbdocs-preview div[style*="background-color"] {
+  background-color: #212121 !important;
+}
+
+/* MDX file styling */
+.ds-docs {
+  max-width: 100ch;
+}
+
+.ds-docs p {
+  max-width: 78ch;
+}
+
+.ds-toc {
+  display: grid;
+  gap: 6px;
+  border: 1px solid var(--ds-border-subtle);
+  background: var(--ds-surface-container);
+  border-radius: 12px;
+  padding: 16px;
+  margin: 16px 0 32px;
+}
+
+.ds-toc a {
+  color: var(--ds-fg-link, var(--ds-primary));
+  text-decoration: none;
+}
+
+.ds-toc a:hover {
+  text-decoration: underline;
+}
+
+.ds-note {
+  border: 1px solid var(--ds-border-subtle);
+  background: var(--ds-surface-container);
+  border-radius: 12px;
+  padding: 16px;
+  margin: 16px 0 24px;
+}
diff --git a/src/storybook/Overview.mdx b/src/storybook/Overview.mdx
index 45b4fb1..f8ee6d8 100644
--- a/src/storybook/Overview.mdx
+++ b/src/storybook/Overview.mdx
@@ -2,16 +2,6 @@ import { Meta } from "@storybook/blocks";
 
 <Meta title="Overview" />
 
-<style>{`
-  .ds-docs {
-    max-width: 100ch;
-  }
-
-  .ds-docs p {
-    max-width: 78ch;
-  }
-`}</style>
-
 <div className="ds-docs">
 
 # Diamond Design System ❖