Refine documentation typography hierarchy

site/styles.css

@@ -1,9 +1,10 @@
 /* Fix ValidMind logo size and alignment */
 @font-face {
   font-family: 'Inter';
-  src: url('assets/fonts/Inter/static/Inter-Regular.ttf') format('truetype');
-  font-weight: normal;
+  src: url('assets/fonts/Inter/Inter-VariableFont_slnt,wght.ttf') format('truetype-variations');
+  font-weight: 100 900;
   font-style: normal;
+  font-display: swap;
 }
 
 /* This breaks Font Awesome and all the icons we use — DO NOT UNCOMMENT */
@@ -20,6 +21,59 @@ html {
 
 body {
   color: #1A202C;
+  line-height: 1.6;
+}
+
+/* Match the ValidMind product's compact heading rhythm. */
+h1 {
+  letter-spacing: -0.04rem;
+}
+
+h2 {
+  letter-spacing: -0.02rem;
+}
+
+h3 {
+  letter-spacing: -0.01rem;
+}
+
+#title-block-header .quarto-title h1.title {
+  font-size: 1.875rem;
+  letter-spacing: -0.04rem;
+}
+
+/*
+ * Quarto already renders the page title as h1. Visually step authored page
+ * sections down one level so a document reads as a hierarchy instead of a
+ * series of equally prominent titles, while preserving the source markup.
+ */
+#quarto-document-content > section.level1 > h1 {
+  font-size: 1.5rem;
+  letter-spacing: -0.02rem;
+}
+
+#quarto-document-content > section.level1 > section.level2 > h2 {
+  font-size: 1.25rem;
+  letter-spacing: -0.01rem;
+  border-bottom-color: #d8dede;
+}
+
+#quarto-document-content section.level3 > h3 {
+  font-size: 1.125rem;
+  letter-spacing: normal;
+}
+
+/* Keep prose comfortably readable even on wide, full-layout pages. */
+#quarto-document-content p,
+#quarto-document-content li {
+  max-width: 75ch;
+}
+
+#quarto-document-content .callout p,
+#quarto-document-content .callout li,
+#quarto-document-content .card p,
+#quarto-document-content .card li {
+  max-width: none;
 }
 
 

site/theme.scss

@@ -1,4 +1,17 @@
 /*-- scss:defaults --*/
+// Typography follows the ValidMind product scale while retaining a larger,
+// long-form reading size for documentation body copy.
+$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+$headings-font-family: $font-family-sans-serif;
+$headings-font-weight: 600;
+$headings-line-height: 1.2;
+$h1-font-size: 1.875rem;
+$h2-font-size: 1.5rem;
+$h3-font-size: 1.25rem;
+$h4-font-size: 1.125rem;
+$h5-font-size: 1rem;
+$h6-font-size: 0.875rem;
+
 // Base ValidMind colors
 $body-color: #222425;
 $link-color: #DE257E;
@@ -75,4 +88,3 @@ $mermaid-label-fg-color: #36454F;
 @import 'assets/styles/callouts';
 @import 'assets/styles/links';
 @import 'assets/styles/pagination';
-