From 83172731ad133ec36680332a4ce2f4e9f8aa5983 Mon Sep 17 00:00:00 2001
From: Julien Danjou <julien@danjou.info>
Date: Thu, 30 Apr 2026 10:05:05 +0200
Subject: [PATCH] refactor(design): align MDX heading rules with typography
 utilities

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Change-Id: I785859253cda418f0d6d2cc1f5ed31c33c1c228d
---
 src/styles/index.css | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/src/styles/index.css b/src/styles/index.css
index f01f04ac8f..811f0d04af 100644
--- a/src/styles/index.css
+++ b/src/styles/index.css
@@ -859,47 +859,53 @@ pre {
   outline-offset: 2px;
 }
 
+/* Heading rules for MDX-rendered content. Properties match the
+   typography utilities in typography.css — keep in sync. */
+#main-content h1,
 .content-title {
-  font-size: var(--text-4xl);
+  font-size: 2rem;
   font-weight: 500;
   line-height: 1.2;
   letter-spacing: -0.025em;
+  text-wrap: balance;
   margin-bottom: 0.25em;
 }
 
+#main-content h2.content-subtitle,
 .content-subtitle {
-  font-size: var(--text-lg);
+  font-size: 1.125rem;
   font-weight: 400;
   line-height: 1.5;
   text-wrap: balance;
+  color: var(--theme-text-muted);
 }
 
-#main-content .content-subtitle {
-  font-size: var(--text-lg);
-  color: var(--theme-text-lighter);
-}
-
-#main-content h2 {
+#main-content h2:not(.content-subtitle):not(.home-title) {
+  font-size: 1.5rem;
   font-weight: 500;
-  font-size: var(--text-2xl);
+  line-height: 1.3;
   letter-spacing: -0.025em;
+  text-wrap: balance;
 }
 
 #main-content h3 {
+  font-size: 1.25rem;
   font-weight: 500;
-  font-size: var(--text-xl);
+  line-height: 1.3;
   letter-spacing: -0.01em;
 }
 
 #main-content h4 {
+  font-size: 1.125rem;
   font-weight: 500;
-  font-size: var(--text-lg);
+  line-height: 1.4;
 }
 
 #main-content h5,
 #main-content h6 {
+  font-size: 1rem;
   font-weight: 500;
-  font-size: var(--text-base);
+  line-height: 1.4;
 }
 
 header .nav-wrapper {