docs(style[headings]): refine heading hierarchy — scale, spacing, eye…

…brow labels why: Furo headings are large and bold, crowding the page and flattening visual hierarchy. Biome-inspired medium-weight scale uses size and spacing — not boldness — to convey structure. what: - Set all article headings to font-weight: 500 - Scale: h1 1.8em, h2 1.6em, h3 1.15em, h4-h6 eyebrow treatment - Add uppercase + letter-spacing + muted color for h4-h6 - Add changelog heading extras for #history section - Revert TOC variables from body back to :root
vcs-python · tony · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026
commit 693a880567305bf2d9a40cb3f0c88787bd1a64ca
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -1,20 +1,3 @@
-h2 {
-  margin-bottom: 1.25rem;
-  margin-top: 1.25rem;
-  scroll-margin-top: 0.5rem;
-}
-
-h3 {
-  margin-bottom: 1.25rem;
-  margin-top: 1.25rem;
-  scroll-margin-top: 0.5rem;
-}
-
-h4 {
-  margin-bottom: 1.25rem;
-  scroll-margin-top: 0.5rem;
-}
-
 .sidebar-tree p.indented-block {
   padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0
     var(--sidebar-item-spacing-horizontal);
@@ -36,14 +19,94 @@ h4 {
   font-weight: bold;
 }
 
+
+/* ── Global heading refinements ─────────────────────────────
+ * Biome-inspired scale: medium weight (500) throughout — size
+ * and spacing carry hierarchy, not boldness. H4-H6 add eyebrow
+ * treatment (uppercase, muted). `article` prefix overrides
+ * Furo's bare h1-h6 selectors.
+ * ────────────────────────────────────────────────────────── */
+article h1 {
+  font-size: 1.8em;
+  font-weight: 500;
+  margin-top: 1.5rem;
+  margin-bottom: 0.75rem;
+}
+
+article h2 {
+  font-size: 1.6em;
+  font-weight: 500;
+  margin-top: 2.5rem;
+  margin-bottom: 0.5rem;
+}
+
+article h3 {
+  font-size: 1.15em;
+  font-weight: 500;
+  margin-top: 1.5rem;
+  margin-bottom: 0.375rem;
+}
+
+article h4 {
+  font-size: 0.85em;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-foreground-secondary);
+  margin-top: 1rem;
+  margin-bottom: 0.25rem;
+}
+
+article h5 {
+  font-size: 0.8em;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-foreground-secondary);
+}
+
+article h6 {
+  font-size: 0.75em;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-foreground-secondary);
+}
+
+/* ── Changelog heading extras ───────────────────────────────
+ * Vertical spacing separates consecutive version entries.
+ * Category headings (h3) are muted. Item headings (h4) are
+ * subtle. Targets #history section from CHANGES markdown.
+ * ────────────────────────────────────────────────────────── */
+
+/* Spacing between consecutive version entries */
+#history > section + section {
+  margin-top: 2.5rem;
+}
+
+/* Category headings — muted secondary color */
+#history h3 {
+  color: var(--color-foreground-secondary);
+  margin-top: 1.25rem;
+}
+
+/* Item headings — subtle, same size as body */
+#history h4 {
+  font-size: 1em;
+  margin-top: 1rem;
+  text-transform: none;
+  letter-spacing: normal;
+  color: inherit;
+}
+
 /* ── Right-panel TOC refinements ────────────────────────────
  * Adjust Furo's table-of-contents proportions for better
  * readability. Inspired by Starlight defaults (Biome docs).
  * Uses Furo CSS variable overrides where possible.
  * ────────────────────────────────────────────────────────── */
 
 /* TOC font sizes: override Furo defaults (75% → 87.5%) */
-body {
+:root {
   --toc-font-size: var(--font-size--small);         /* 87.5% = 14px */
   --toc-title-font-size: var(--font-size--small);   /* 87.5% = 14px */
 }