diff --git a/src/components/Layout/MDXWrapper.tsx b/src/components/Layout/MDXWrapper.tsx
index 72bd5a5c6b..92192fb923 100644
--- a/src/components/Layout/MDXWrapper.tsx
+++ b/src/components/Layout/MDXWrapper.tsx
@@ -199,7 +199,7 @@ const WrappedCodeSnippet: React.FC<{ activePage: ActivePage } & CodeSnippetProps
         lang={languageOverride || activePage.language}
         sdk={detectedSdkType || sdk}
         onChange={handleLanguageChange}
-        className={cn(props.className, 'mb-5')}
+        className={cn(props.className, 'my-6')}
         languageOrdering={
           activePage.product && languageData[activePage.product] ? Object.keys(languageData[activePage.product]) : []
         }
diff --git a/src/components/Layout/mdx/Admonition.tsx b/src/components/Layout/mdx/Admonition.tsx
index e775d8c563..7afd25d248 100644
--- a/src/components/Layout/mdx/Admonition.tsx
+++ b/src/components/Layout/mdx/Admonition.tsx
@@ -66,7 +66,7 @@ const Admonition: React.FC<AdmonitionProps> = ({ 'data-type': dataType = 'note',
         {...rest}
         data-type={dataType}
         className={cn(
-          'border-l px-6 py-3.5 my-4 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
+          'border-l px-6 py-3.5 my-6 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
           borderColor,
           backgroundColor,
           className,
@@ -84,7 +84,7 @@ const Admonition: React.FC<AdmonitionProps> = ({ 'data-type': dataType = 'note',
       {...rest}
       data-type={dataType}
       className={cn(
-        'border-l px-6 py-4 my-4 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
+        'border-l px-6 py-4 my-6 rounded-r-lg text-neutral-1000 dark:text-neutral-300',
         borderColor,
         backgroundColor,
         className,
diff --git a/src/components/Layout/mdx/PageHeader.tsx b/src/components/Layout/mdx/PageHeader.tsx
index 4099f60b7f..2942e7d4c8 100644
--- a/src/components/Layout/mdx/PageHeader.tsx
+++ b/src/components/Layout/mdx/PageHeader.tsx
@@ -10,11 +10,7 @@ export const PageHeader: React.FC<PageHeaderProps> = ({ title, intro }) => {
   return (
     <div className="my-8 border-b border-neutral-300 dark:border-neutral-1000 pb-8">
       <h1 className={cn('ui-text-h1', intro ? 'mb-4' : 'mb-0')}>{title}</h1>
-      {intro && (
-        <p className="text-neutral-800 dark:text-neutral-500 font-serif italic tracking-tight text-lg leading-normal mb-0">
-          {intro}
-        </p>
-      )}
+      {intro && <p className="ui-text-sub-head mb-0">{intro}</p>}
     </div>
   );
 };
diff --git a/src/components/Layout/mdx/Table.tsx b/src/components/Layout/mdx/Table.tsx
index 104db03c12..13524376d5 100644
--- a/src/components/Layout/mdx/Table.tsx
+++ b/src/components/Layout/mdx/Table.tsx
@@ -8,8 +8,8 @@ export interface TableRootProps extends React.HTMLAttributes<HTMLDivElement> {
 
 const TableRoot: React.FC<TableRootProps> = ({ children, className, ...props }) => {
   return (
-    <div className={cn('overflow-x-auto my-4 rounded-lg overflow-hidden', className)} {...props}>
-      <table className="w-full border-separate border-spacing-0 text-left text-sm">{children}</table>
+    <div className={cn('overflow-x-auto my-6 rounded-lg overflow-hidden', className)} {...props}>
+      <table className="w-full border-separate border-spacing-0 text-left text-p2">{children}</table>
     </div>
   );
 };
diff --git a/src/components/Markdown/MarkdownProvider.tsx b/src/components/Markdown/MarkdownProvider.tsx
index 82b0a9e8ae..d2e1c2cb5a 100644
--- a/src/components/Markdown/MarkdownProvider.tsx
+++ b/src/components/Markdown/MarkdownProvider.tsx
@@ -6,38 +6,46 @@ import Link from 'src/components/Link';
 import { CodeBlock } from './CodeBlock';
 import { checkLinkIsInternal } from 'src/utilities/link-checks';
 
+/**
+ * Vertical rhythm (Figma "Docs Site SSoT" > Vertical spacing).
+ * Asymmetric heading margins: a large margin-top separates a heading from the
+ * preceding content, and a smaller margin-bottom (baking in the 8px paragraph
+ * lead-in) sets the gap to the following text. Objects (code, tables, asides)
+ * carry 24px. Adjacent margins collapse, so e.g. a paragraph's 12px bottom and
+ * a heading's 48px top resolve to 48px.
+ */
 const H1: FC<JSX.IntrinsicElements['h1']> = ({ children, ...props }) => (
-  <h1 className="ui-text-h1 my-10" {...props}>
+  <h1 className="ui-text-h1 mb-6" {...props}>
     {children}
   </h1>
 );
 
 const H2: FC<JSX.IntrinsicElements['h2']> = ({ children, ...props }) => (
-  <h2 className="ui-text-h2 my-8" {...props}>
+  <h2 className="ui-text-h2 mt-12 mb-6" {...props}>
     {children}
   </h2>
 );
 
 const H3: FC<JSX.IntrinsicElements['h3']> = ({ children, ...props }) => (
-  <h3 className="ui-text-h3 my-5" {...props}>
+  <h3 className="ui-text-h3 mt-8 mb-5" {...props}>
     {children}
   </h3>
 );
 
 const H4: FC<JSX.IntrinsicElements['h4']> = ({ children, ...props }) => (
-  <h4 className="ui-text-h4 my-5" {...props}>
+  <h4 className="ui-text-h4 mt-7 mb-4" {...props}>
     {children}
   </h4>
 );
 
 const H5: FC<JSX.IntrinsicElements['h5']> = ({ children, ...props }) => (
-  <h5 className="ui-text-h5 my-5" {...props}>
+  <h5 className="ui-text-h5 mt-6 mb-3" {...props}>
     {children}
   </h5>
 );
 
 const Paragraph: FC<JSX.IntrinsicElements['p']> = ({ children, ...props }) => (
-  <p className="ui-text-p2 mb-5" {...props}>
+  <p className="ui-text-p1 mb-3" {...props}>
     {children}
   </p>
 );
@@ -113,7 +121,7 @@ const Ul: FC<JSX.IntrinsicElements['ul']> = ({ children, ...props }) => (
 );
 
 const Li: FC<JSX.IntrinsicElements['li']> = ({ children, ...props }) => (
-  <li className="ui-text-p2 mb-2" {...props}>
+  <li className="ui-text-p1 mb-2" {...props}>
     {children}
   </li>
 );
@@ -128,7 +136,7 @@ const Pre: FC<JSX.IntrinsicElements['pre']> = ({ children }) => {
   const lang = (children as React.ReactElement)?.props?.className?.replace('language-', '');
 
   return (
-    <div className="mb-5">
+    <div className="my-6">
       <CodeBlock language={lang || 'javascript'}>{children}</CodeBlock>
     </div>
   );
diff --git a/src/styles/global.css b/src/styles/global.css
index e11afbeb08..854413732c 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -108,3 +108,13 @@
     * optimo.ch
     */
 }
+
+/* MDX content images (gatsby-remark-images) join the object vertical rhythm
+   with 24px above and below. Kept outside @layer so it is not purged — the
+   wrapper class is injected at build time and never appears in scanned source.
+   The wrapper is display:block inside its paragraph, so the margins collapse
+   through to sit 24px from the surrounding content. */
+article .gatsby-resp-image-wrapper {
+  margin-top: var(--spacing-24);
+  margin-bottom: var(--spacing-24);
+}
diff --git a/src/styles/ui/core/styles/properties.css b/src/styles/ui/core/styles/properties.css
index b462ff9599..009e207b3b 100644
--- a/src/styles/ui/core/styles/properties.css
+++ b/src/styles/ui/core/styles/properties.css
@@ -172,16 +172,16 @@
     --fs-title: 2.75rem;
     --fs-title-xs: 2.5rem;
     --fs-h1-xl: 2.5rem;
-    --fs-h1: 2.25rem;
+    --fs-h1: 2rem; /* 32px — docs content heading scale */
     --fs-h1-xs: 2rem;
 
     --fs-h2-xl: 2.125rem;
-    --fs-h2: 2rem;
+    --fs-h2: 1.5rem; /* 24px */
     --fs-h2-xs: 1.75rem;
 
-    --fs-h3: 1.5rem;
-    --fs-h4: 1.25rem;
-    --fs-h5: 1rem;
+    --fs-h3: 1.25rem; /* 20px */
+    --fs-h4: 1.125rem; /* 18px */
+    --fs-h5: 1rem; /* 16px */
 
     --fs-p1: 1rem;
     --fs-p2: 0.938rem;
diff --git a/src/styles/ui/core/styles/text.css b/src/styles/ui/core/styles/text.css
index 0682ae6c8b..8036ffdb1c 100644
--- a/src/styles/ui/core/styles/text.css
+++ b/src/styles/ui/core/styles/text.css
@@ -7,48 +7,48 @@
 
   .ui-text-h1 {
     @apply font-sans font-bold text-cool-black;
-    @apply text-h1-xs xs:text-h1 xl:text-h1-xl;
-    @apply tracking-[-0.0125em] xs:tracking-[-0.015em];
+    @apply text-h1;
+    @apply tracking-[-0.02em];
   }
 
   .ui-text-h2 {
     @apply font-sans font-bold text-cool-black;
-    @apply text-h2-xs xs:text-h2 xl:text-h2-xl;
-    @apply tracking-[-0.015em] xs:tracking-[-0.01em];
+    @apply text-h2;
+    @apply tracking-[-0.0175em];
   }
 
   .ui-text-h3 {
     @apply font-sans font-bold text-cool-black;
     @apply text-h3;
-    @apply tracking-[-0.005em];
+    @apply tracking-[-0.015em];
   }
 
   .ui-text-h4 {
     @apply font-sans font-bold text-cool-black;
     @apply text-h4;
-    @apply tracking-[-0.0015em];
+    @apply tracking-[-0.0125em];
   }
 
   .ui-text-h5 {
     @apply font-sans font-bold text-cool-black;
     @apply text-h5;
-    @apply tracking-[-0.0025em];
+    @apply tracking-[-0.01em];
   }
 
   .ui-text-p1 {
-    @apply font-sans font-medium text-charcoal-grey text-p1;
+    @apply font-sans font-medium text-charcoal-grey text-p1 tracking-[-0.01em];
   }
 
   .ui-text-p2 {
-    @apply font-sans font-medium text-charcoal-grey text-p2;
+    @apply font-sans font-medium text-charcoal-grey text-p2 tracking-[-0.0075em];
   }
 
   .ui-text-p3 {
-    @apply font-sans font-medium text-charcoal-grey text-p3;
+    @apply font-sans font-medium text-charcoal-grey text-p3 tracking-[-0.005em];
   }
 
   .ui-text-p4 {
-    @apply font-sans font-medium text-charcoal-grey text-p4;
+    @apply font-sans font-medium text-charcoal-grey text-p4 tracking-[-0.0025em];
   }
 
   .ui-text-standfirst {
@@ -68,6 +68,12 @@
     @apply text-sub-header-xs xs:text-sub-header leading-normal;
   }
 
+  /* Decorative serif sub-head (docs page intro / standfirst). Figma: text-sub-head */
+  .ui-text-sub-head {
+    @apply font-serif font-normal italic text-neutral-800 dark:text-neutral-500;
+    @apply text-sub-header leading-relaxed tracking-[-0.0125em];
+  }
+
   .ui-text-overline1 {
     @apply font-mono font-medium text-active-orange uppercase;
     @apply text-overline1 leading-normal;
@@ -104,15 +110,15 @@
   }
 
   .ui-text-code {
-    @apply font-mono font-normal text-code;
+    @apply font-mono font-medium text-code;
   }
 
   .ui-text-code2 {
-    @apply font-mono font-normal text-code2;
+    @apply font-mono font-medium text-code2;
   }
 
   .ui-text-code-inline {
-    @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;
+    @apply inline-flex items-center font-mono px-1 py-0.5 text-code text-neutral-1000 font-medium bg-neutral-100 border-[0.5px] border-neutral-500 rounded-[4px];
   }
 
   .dark .ui-text-code-inline {
diff --git a/tailwind.config.js b/tailwind.config.js
index 9cb5896926..25e7e8d450 100644
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -169,15 +169,15 @@ module.exports = {
         title: ['var(--fs-title)', 'var(--lh-min-normal)'],
         'title-xl': ['var(--fs-title-xl)', 'var(--lh-min-normal)'],
         'title-xs': ['var(--fs-title-xs)', 'var(--lh-min-normal)'],
-        h1: ['var(--fs-h1)', 'var(--lh-dense)'],
+        h1: ['var(--fs-h1)', '1.25'],
         'h1-xl': ['var(--fs-h1-xl)', 'var(--lh-min-normal)'],
         'h1-xs': ['var(--fs-h1-xs)', 'var(--lh-min-normal)'],
-        h2: ['var(--fs-h2)', 'var(--lh-min-normal)'],
+        h2: ['var(--fs-h2)', '1.33'],
         'h2-xl': ['var(--fs-h2-xl)', 'var(--lh-min-normal)'],
         'h2-xs': ['var(--fs-h2-xs)', 'var(--lh-min-normal)'],
-        h3: ['var(--fs-h3)', 'var(--lh-min-normal)'],
-        h4: ['var(--fs-h4)', 'var(--lh-min-normal)'],
-        h5: ['var(--fs-h5)', 'var(--lh-min-normal)'],
+        h3: ['var(--fs-h3)', '1.4'],
+        h4: ['var(--fs-h4)', '1.44'],
+        h5: ['var(--fs-h5)', '1.5'],
         p1: ['var(--fs-p1)', 'var(--lh-relaxed)'],
         p2: ['var(--fs-p2)', 'var(--lh-relaxed)'],
         p3: ['var(--fs-p3)', 'var(--lh-relaxed)'],