@takazudo/zudo-doc 8.1.2 → 8.1.3

package/CHANGELOG.md

@@ -8,6 +8,16 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [8.1.3] - 2026-10-26
+
+### Features
+
+- Polish the document heading hierarchy in nine theme packs (drift, fjord, hollow, manuscript, matcha, nocturne, observatory, sakura, solar): h2 gets a 2px top rule with line-height 1.3, h3 a quieter 1px muted rule with line-height 1.4, and h4 no rule with line-height 1.45, with per-pack sizes and weights. Each pack keeps its rule inks, fonts, small caps and motifs; the rules apply only to document headings, so home and compact-prose headings are unchanged. (f0ac53df)
+
+### Bug Fixes
+
+- Observatory: the constellation star nodes now follow the same document-h2 selector as the constellation line, so they never appear without it. (d72441b4)
+
 ## [8.1.2] - 2026-10-26
 
 ### Other Changes

package/dist/theme-packs/drift/pack.css

@@ -307,27 +307,62 @@ html[data-theme-pack="drift"] a[data-nav-active] {
     0 0 18px -4px color-mix(in oklch, var(--zd-accent) 45%, transparent);
 }
 
-/* headings: quiet luminance instead of heavy rules. The h2 keeps a
-   gradient bar but fades it into the accent glow — !important
-   defeats the SSR-inlined `style="border-image:linear-gradient(...)"`
-   (Decision 6.6's sole allowlisted carve-out). */
+/* headings: quiet luminance plus a top-only rule hierarchy. h2 carries
+   a 2px accent rule, h3 a quieter 1px muted rule, h4 no rule at all.
+   The rules are top-anchored background gradients; border-image none
+   !important (Decision 6.6's sole allowlisted carve-out) keeps the
+   SSR-inlined `style="border-image:linear-gradient(...)"` from painting
+   a second bar. */
 html[data-theme-pack="drift"] .zd-content h1 {
   text-shadow: 0 0 34px color-mix(in oklch, var(--zd-accent) 32%, transparent);
 }
 html[data-theme-pack="drift"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
-  font-size: 1.6rem;
-}
-html[data-theme-pack="drift"] .zd-content h2 {
-  border-top-width: 1px;
-  border-image: linear-gradient(
-      to right,
-      color-mix(in oklch, var(--zd-accent) 55%, transparent),
-      transparent 72%
-    )
-    1 !important;
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 1.75rem;
+  font-weight: 600;
+  line-height: 1.3;
+  background-image: linear-gradient(
+    to right,
+    var(--zd-accent) 0%,
+    var(--zd-accent) 32%,
+    color-mix(in oklch, var(--zd-accent) 58%, transparent) 72%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
 }
 html[data-theme-pack="drift"] .zd-content h3:where(:not(.zd-compact-prose *)) {
-  border-top-width: 1px;
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="drift"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
 }
 
 /* links: airy underline that brightens on approach */

package/dist/theme-packs/fjord/pack.css

@@ -232,21 +232,62 @@ html[data-theme-pack="fjord"] a[data-nav-active] {
   box-shadow: 0 0 16px -4px color-mix(in oklch, var(--zd-accent) 55%, transparent);
 }
 
-/* headings: aurora rule over every h2 instead of the default fg
-   fade. The SSR-inlined `style="border-image:linear-gradient(...)"`
-   is defeated with !important (Decision 6.6's sole allowlisted
-   carve-out) — here it is REPLACED by the aurora ribbon, not
-   removed. */
-html[data-theme-pack="fjord"] .zd-content h2 {
-  border-top-width: 2px;
-  border-image: linear-gradient(
-      to right,
-      light-dark(oklch(0.6 0.1 195), oklch(0.78 0.11 185)),
-      light-dark(oklch(0.58 0.09 250), oklch(0.66 0.1 255)) 42%,
-      transparent 88%
-    )
-    1 !important;
+/* headings: a top-only rule hierarchy. h2 carries the 2px aurora
+   ribbon (cyan into blue) instead of the default fg fade, h3 a quieter
+   1px muted rule, h4 no rule. The rules are top-anchored background
+   gradients; border-image none !important (Decision 6.6's sole
+   allowlisted carve-out) keeps the SSR-inlined
+   `style="border-image:linear-gradient(...)"` from painting a second
+   bar. */
+html[data-theme-pack="fjord"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.3;
+  background-image: linear-gradient(
+    to right,
+    light-dark(oklch(0.6 0.1 195), oklch(0.78 0.11 185)) 0%,
+    light-dark(oklch(0.6 0.1 195), oklch(0.78 0.11 185)) 24%,
+    light-dark(oklch(0.58 0.09 250), oklch(0.66 0.1 255)) 64%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
 }
+html[data-theme-pack="fjord"] .zd-content h3:where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="fjord"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
+}
+
 html[data-theme-pack="fjord"] .zd-content h1 {
   color: color-mix(in oklch, var(--zd-accent) 10%, var(--zd-fg));
 }

package/dist/theme-packs/hollow/pack.css

@@ -261,23 +261,58 @@ html[data-theme-pack="hollow"] .zd-content h1 {
   text-shadow: 0 0 22px light-dark(transparent, oklch(0.7 0.19 348 / 0.38));
 }
 
-/* h2: the SSR-inlined gradient bar is re-pointed at a fading pink
-   rule (Decision 6.6's sole allowlisted !important carve-out —
-   border-image only) */
+/* top-only rule hierarchy: h2 carries a 2px fading pink rule, h3 a
+   quieter 1px muted rule, h4 no rule. The rules are top-anchored
+   background gradients; border-image none !important (Decision 6.6's
+   sole allowlisted carve-out) keeps the SSR-inlined gradient bar from
+   painting a second rule. */
 html[data-theme-pack="hollow"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
-  font-size: 1.5rem;
-}
-html[data-theme-pack="hollow"] .zd-content h2 {
-  border-image: linear-gradient(
-      to right,
-      color-mix(
-        in oklch,
-        light-dark(oklch(0.52 0.2 350), oklch(0.78 0.17 348)) 62%,
-        transparent
-      ),
-      transparent 72%
-    )
-    1 !important;
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.3;
+  background-image: linear-gradient(
+    to right,
+    light-dark(oklch(0.52 0.2 350), oklch(0.78 0.17 348)) 0%,
+    light-dark(oklch(0.52 0.2 350), oklch(0.78 0.17 348)) 32%,
+    color-mix(in oklch, light-dark(oklch(0.52 0.2 350), oklch(0.78 0.17 348)) 58%, transparent) 72%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="hollow"] .zd-content h3:where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="hollow"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
 }
 
 /* links: violet, quiet underline that ignites on hover */

package/dist/theme-packs/manuscript/pack.css

@@ -204,20 +204,15 @@ html[data-theme-pack="manuscript"] nav[data-zd-toc] a {
   font-size: 0.95rem;
 }
 
-/* the signature: letterspaced small-capital subheads. The real h2/h3 carry
-   an SSR-inlined `style="border-image:linear-gradient(...)"` bar: the h2
-   replaces it with a hairline rule (border-image none !important is
-   Decision 6.6's sole allowlisted carve-out); the h3 wants NO bar, which
-   zeroing the class-level border-top-width achieves without !important
-   (a zero-width border area leaves the inline border-image nothing to
-   paint on). */
+/* the signature: letterspaced small-capital subheads over a top-only rule
+   hierarchy. Document h2 carries a 2px ink rule, h3 a quieter 1px muted
+   rule, h4 no rule. The rules are top-anchored background gradients;
+   border-image none !important (Decision 6.6's sole allowlisted carve-out)
+   keeps the SSR-inlined `style="border-image:linear-gradient(...)"` from
+   painting a second bar. The unscoped rules keep the small caps (and the
+   compact-prose h3 voice) everywhere else. */
 html[data-theme-pack="manuscript"] .zd-content h2 {
-  border-image: none !important;
-  border-top-width: 1px;
-  border-top-color: color-mix(in oklch, var(--zd-fg) 28%, transparent);
-  padding-top: 1.35rem;
   font-variant-caps: small-caps;
-  font-size: 1.55rem;
 }
 html[data-theme-pack="manuscript"] .zd-content h3 {
   border-top-width: 0;
@@ -225,6 +220,56 @@ html[data-theme-pack="manuscript"] .zd-content h3 {
   letter-spacing: 0.09em;
   font-size: 1.28rem;
 }
+html[data-theme-pack="manuscript"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 2rem;
+  font-weight: 600;
+  line-height: 1.3;
+  letter-spacing: 0.055em;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-fg) 72%, var(--zd-accent)) 0%,
+    color-mix(in oklch, var(--zd-fg) 72%, var(--zd-accent)) 32%,
+    color-mix(in oklch, color-mix(in oklch, var(--zd-fg) 72%, var(--zd-accent)) 58%, transparent) 72%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="manuscript"] .zd-content h3:where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.5rem;
+  font-weight: 500;
+  line-height: 1.4;
+  letter-spacing: 0.045em;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="manuscript"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.25rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
+}
 
 /* rubricated drop cap on the opening paragraph. The prototype's `.lead + p`
    has no stable-DOM equivalent (the frontmatter-description <p> carries only

package/dist/theme-packs/matcha/pack.css

@@ -208,30 +208,63 @@ html[data-theme-pack="matcha"] .zd-content > p[data-doc-description] {
   line-height: 1.75;
 }
 
-/* h2 rule: a chashaku scoop of matcha, then the line dissolves like
-   foam. `border-image: none !important` defeats the SSR-inlined
-   `style="border-image:linear-gradient(...)"` (Decision 6.6's sole
-   allowlisted carve-out); the scoop itself is a 1px background
-   gradient so no border-image fight remains. */
-html[data-theme-pack="matcha"] .zd-content h2 {
+/* h2 rule: a chashaku scoop of matcha, then the 2px line dissolves like
+   foam; h3 takes a quieter 1px muted rule and h4 none. The rules are
+   top-anchored background gradients; `border-image: none !important`
+   (Decision 6.6's sole allowlisted carve-out) defeats the SSR-inlined
+   `style="border-image:linear-gradient(...)"`. Mincho h2 uses the bundled
+   700 face; the Zen Kaku h3/h4 use the bundled 500 face rather than a
+   synthetic 600. */
+html[data-theme-pack="matcha"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
   border-image: none !important;
   border-top-width: 0;
-  padding-top: 1.35rem;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 2rem;
+  font-weight: 700;
+  line-height: 1.3;
   background-image: linear-gradient(
     to right,
     var(--zd-accent) 0,
-    var(--zd-accent) 2.75rem,
-    color-mix(in oklch, var(--zd-muted) 32%, transparent) 2.75rem,
+    var(--zd-accent) 5rem,
+    color-mix(in oklch, var(--zd-accent) 44%, transparent) 5rem,
+    color-mix(in oklch, var(--zd-accent) 30%, transparent) 70%,
     transparent 100%
   );
+  background-size: 100% 2px;
   background-repeat: no-repeat;
-  background-size: 100% 1px;
+  background-position: top left;
 }
-
-/* h3: quiet, slightly tracked (weight 600 rides --zdc-doc-h3-weight) */
 html[data-theme-pack="matcha"] .zd-content h3:where(:not(.zd-compact-prose *)) {
-  border-top-width: 1px;
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 500;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
 }
+html[data-theme-pack="matcha"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
+}
+
 html[data-theme-pack="matcha"] .zd-content h3 {
   letter-spacing: 0.01em;
 }

package/dist/theme-packs/nocturne/pack.css

@@ -322,25 +322,61 @@ html[data-theme-pack="nocturne"] .zd-content > p[data-doc-description] {
   color: color-mix(in oklch, var(--zd-fg) 62%, var(--zd-muted));
 }
 
-/* h2: gold fading rule. The SSR-inlined
-   `style="border-image:linear-gradient(...)"` bar is defeated with
-   border-image none !important (Decision 6.6's sole allowlisted
-   carve-out) + a zeroed border-top; the fading gold hairline is then
-   painted as a 1px top-anchored background gradient instead. */
-html[data-theme-pack="nocturne"] .zd-content h2 {
+/* h2: the original gold fading rule, now 2px and kept distinct from the
+   lavender link ink; h3 takes a quieter 1px muted rule and h4 none. The
+   SSR-inlined `style="border-image:linear-gradient(...)"` bar is
+   defeated with border-image none !important (Decision 6.6's sole
+   allowlisted carve-out) + zeroed borders; each rule is a top-anchored
+   background gradient instead. */
+html[data-theme-pack="nocturne"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
   border-image: none !important;
   border-top-width: 0;
-  font-size: 1.9rem;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 2.125rem;
+  font-weight: 700;
+  line-height: 1.3;
   background-image: linear-gradient(
     to right,
-    light-dark(oklch(0.53 0.105 85), oklch(0.78 0.105 87)),
-    light-dark(oklch(0.53 0.105 85 / 0.3), oklch(0.78 0.105 87 / 0.3)) 60%,
-    transparent
+    light-dark(oklch(0.53 0.105 85), oklch(0.78 0.105 87)) 0%,
+    light-dark(oklch(0.53 0.105 85), oklch(0.78 0.105 87)) 32%,
+    color-mix(in oklch, light-dark(oklch(0.53 0.105 85), oklch(0.78 0.105 87)) 58%, transparent) 72%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="nocturne"] .zd-content h3:where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
   );
   background-size: 100% 1px;
   background-repeat: no-repeat;
   background-position: top left;
 }
+html[data-theme-pack="nocturne"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
+}
+
 html[data-theme-pack="nocturne"] .zd-content h3 {
   letter-spacing: 0.01em;
 }

package/dist/theme-packs/observatory/pack.css

@@ -416,47 +416,84 @@ html[data-theme-pack="observatory"] .zd-content > p[data-doc-description] {
   font-weight: 300;
 }
 
-/* h2 — chart-label caps over a constellation line with star nodes.
-   The SSR-inlined `style="border-image:linear-gradient(...)"` bar is
-   defeated with border-image none !important (Decision 6.6's sole
-   allowlisted carve-out) + a zeroed border-top; the node-to-line rule
-   is then painted as a top-anchored background gradient, with the two
-   glowing star nodes as pseudo-element dots. */
+/* h2 — chart-label caps over a 2px constellation line with star nodes;
+   h3 — a quieter 1px muted rule; h4 — no rule. The SSR-inlined
+   `style="border-image:linear-gradient(...)"` bar is defeated with
+   border-image none !important (Decision 6.6's sole allowlisted
+   carve-out) + zeroed borders; each rule is a top-anchored background
+   gradient, with the two glowing star nodes as pseudo-element dots
+   centred on the h2 line. */
+html[data-theme-pack="observatory"] .zd-content h2 {
+  position: relative;
+  text-transform: uppercase;
+}
 html[data-theme-pack="observatory"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
-  font-size: 1.75rem;
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 1.875rem;
+  font-weight: 500;
+  line-height: 1.3;
+  letter-spacing: 0.065em;
+  background-image: linear-gradient(
+    to right,
+    light-dark(oklch(0.5 0.105 78), oklch(0.87 0.13 88)) 0%,
+    light-dark(oklch(0.5 0.105 78), oklch(0.87 0.13 88)) 32%,
+    color-mix(in oklch, light-dark(oklch(0.5 0.105 78), oklch(0.87 0.13 88)) 58%, transparent) 72%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
 }
-html[data-theme-pack="observatory"] .zd-content h2 {
+html[data-theme-pack="observatory"] .zd-content h3:where(:not(.zd-compact-prose *)) {
   border-image: none !important;
   border-top-width: 0;
-  position: relative;
-  text-transform: uppercase;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 400;
+  line-height: 1.4;
   background-image: linear-gradient(
     to right,
-    light-dark(oklch(0.5 0.105 78), oklch(0.87 0.13 88)),
-    light-dark(oklch(0.33 0.05 268 / 0.4), oklch(0.86 0.05 265 / 0.34)) 45%,
-    transparent 85%
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
   );
   background-size: 100% 1px;
   background-repeat: no-repeat;
   background-position: top left;
 }
-html[data-theme-pack="observatory"] .zd-content h2::before,
-html[data-theme-pack="observatory"] .zd-content h2::after {
+html[data-theme-pack="observatory"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
+}
+
+html[data-theme-pack="observatory"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *))::before,
+html[data-theme-pack="observatory"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *))::after {
   content: "";
   position: absolute;
   border-radius: 50%;
   background: light-dark(oklch(0.5 0.105 78), oklch(0.87 0.13 88));
   box-shadow: 0 0 6px light-dark(oklch(0.52 0.11 80 / 0.35), oklch(0.86 0.13 88 / 0.55));
 }
-html[data-theme-pack="observatory"] .zd-content h2::before {
-  top: -3px;
+html[data-theme-pack="observatory"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *))::before {
+  top: -1.5px;
   left: 0;
   width: 5px;
   height: 5px;
 }
-html[data-theme-pack="observatory"] .zd-content h2::after {
-  top: -2.5px;
-  left: 38%;
+html[data-theme-pack="observatory"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *))::after {
+  top: -1px;
+  left: 58%;
   width: 4px;
   height: 4px;
   opacity: 0.85;
@@ -474,6 +511,10 @@ html[data-theme-pack="observatory"] .zd-content h3::before {
   font-size: 0.75em;
   vertical-align: 0.12em;
 }
+html[data-theme-pack="observatory"] .zd-content h3:where(:not(.zd-compact-prose *))::before {
+  font-size: 0.65em;
+  opacity: 0.65;
+}
 
 /* links — gilt underlines */
 html[data-theme-pack="observatory"] .zd-content a {

package/dist/theme-packs/sakura/pack.css

@@ -57,7 +57,7 @@
 }
 
 /* ---- Shippori Mincho — display serif for the title, h2 and the
-        wordmark (static 600 heading weight + 700 logo weight).
+        wordmark (static 600 title weight + 700 h2/logo weight).
         Latin subsets only; the bare serif generic supplies CJK. ---- */
 
 @font-face {
@@ -280,22 +280,59 @@ html[data-theme-pack="sakura"] a[data-nav-active] {
     );
 }
 
-/* signature move #2 — the h2 petal rule: a rose stroke that loosens
-   into drifting transparency. Re-points the SSR-inlined
-   `style="border-image:linear-gradient(...)"` gradient — the
-   border-image !important carve-out (Decision 6.6). */
+/* signature move #2 — the h2 petal rule: a 2px rose stroke that loosens
+   into drifting transparency; h3 takes a quieter 1px muted rule and h4
+   none. The rules are top-anchored background gradients; border-image
+   none !important (the Decision 6.6 carve-out) keeps the SSR-inlined
+   `style="border-image:linear-gradient(...)"` from painting a second
+   bar. */
 html[data-theme-pack="sakura"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
-  font-size: 1.6rem;
-}
-html[data-theme-pack="sakura"] .zd-content h2 {
-  border-top-width: 2px;
-  border-image: linear-gradient(
-      to right,
-      var(--zd-accent) 0 2.5rem,
-      color-mix(in srgb, var(--zd-accent) 30%, transparent) 55%,
-      transparent
-    )
-    1 !important;
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 2rem;
+  font-weight: 700;
+  line-height: 1.3;
+  background-image: linear-gradient(
+    to right,
+    var(--zd-accent) 0,
+    var(--zd-accent) 4rem,
+    color-mix(in oklch, var(--zd-accent) 68%, transparent) 62%,
+    transparent 100%
+  );
+  background-size: 100% 2px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="sakura"] .zd-content h3:where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="sakura"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
 }
 
 /* h3 — a round blossom bud before the heading */
@@ -309,6 +346,11 @@ html[data-theme-pack="sakura"] .zd-content h3::before {
   margin-right: 0.5em;
   vertical-align: 0.12em;
 }
+html[data-theme-pack="sakura"] .zd-content h3:where(:not(.zd-compact-prose *))::before {
+  width: 0.3em;
+  height: 0.3em;
+  opacity: 0.7;
+}
 
 /* the lead — airy, one breath rosier than body ink (10.9:1+) */
 html[data-theme-pack="sakura"] .zd-content > p[data-doc-description] {

package/dist/theme-packs/solar/pack.css

@@ -211,26 +211,59 @@ html[data-theme-pack="solar"] main nav[aria-label="Breadcrumb"] li > span {
 }
 
 /* h2 rule: a precise 2px blue→cyan fade instead of the default fg
-   gradient. The SSR-inlined `style="border-image:linear-gradient(...)"`
-   bar is defeated with border-image none !important (Decision 6.6's
-   sole allowlisted carve-out) + a zeroed border-top; the fade is then
-   painted as a 2px top-anchored background gradient. */
+   gradient; h3 takes a quieter 1px muted rule and h4 none. The
+   SSR-inlined `style="border-image:linear-gradient(...)"` bar is
+   defeated with border-image none !important (Decision 6.6's sole
+   allowlisted carve-out) + zeroed borders; each rule is painted as a
+   top-anchored background gradient. */
 html[data-theme-pack="solar"] .zd-content h2:where(:not(.zd-home-heading)):where(:not(.zd-compact-prose *)) {
-  font-size: 1.5rem;
-}
-html[data-theme-pack="solar"] .zd-content h2 {
   border-image: none !important;
   border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 1.25rem;
+  padding-bottom: 0;
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.3;
   background-image: linear-gradient(
     to right,
-    var(--zd-accent),
-    var(--zd-accent-hover) 45%,
-    transparent 88%
+    var(--zd-accent) 0%,
+    var(--zd-accent) 24%,
+    var(--zd-accent-hover) 65%,
+    transparent 100%
   );
   background-size: 100% 2px;
   background-repeat: no-repeat;
   background-position: top left;
 }
+html[data-theme-pack="solar"] .zd-content h3:where(:not(.zd-compact-prose *)) {
+  border-image: none !important;
+  border-top-width: 0;
+  border-bottom-width: 0;
+  padding-top: 0.875rem;
+  padding-bottom: 0;
+  font-size: 1.375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  background-image: linear-gradient(
+    to right,
+    color-mix(in oklch, var(--zd-muted) 42%, transparent),
+    color-mix(in oklch, var(--zd-muted) 22%, transparent) 40%,
+    transparent 76%
+  );
+  background-size: 100% 1px;
+  background-repeat: no-repeat;
+  background-position: top left;
+}
+html[data-theme-pack="solar"] .zd-content h4:where(:not(.zd-compact-prose *)) {
+  border-width: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: 1.2rem;
+  font-weight: 500;
+  line-height: 1.45;
+  background-image: none;
+}
 
 /* prose links: quiet underline that sharpens to cyan on hover */
 html[data-theme-pack="solar"] .zd-content a {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "8.1.2",
+  "version": "8.1.3",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -808,7 +808,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "8.1.2"
+    "@takazudo/zudo-doc-history-server": "8.1.3"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",