@takazudo/zudo-doc 5.19.0 → 5.20.0

package/dist/theme-no-reset.css

@@ -0,0 +1,379 @@
+/* ============================================================================
+ * @takazudo/zudo-doc — default design tokens + project-agnostic base rules
+ *
+ * Shipped to consumers as `@takazudo/zudo-doc/theme.css` (copied to
+ * `dist/theme.css` by scripts/copy-theme-css.mjs on build). Single source of
+ * truth for the default `@theme` token block (colors, spacing, icon sizes,
+ * elevation, typography, radius, breakpoints, z-index) plus the small set of
+ * project-agnostic base rules (scroll-margin, selection color, focus ring,
+ * search / find-in-page highlight, version-switcher visibility) every
+ * zudo-doc project needs. See zudolab/zudo-doc#2655.
+ *
+ * ── @import order (load-bearing) ────────────────────────────────────────────
+ * The consumer's global.css MUST import this file:
+ *   1. AFTER `@layer zd-preflight, zd-flow;` and the two Tailwind imports
+ *      (`tailwindcss/preflight` layer(zd-preflight), `tailwindcss/utilities`).
+ *      Those three lines stay project-side — path-relative `@source`/`@layer`
+ *      resolution requires them to live in the consumer's own CSS file (see
+ *      packages/create-zudo-doc/templates/base/src/styles/global.css).
+ *   2. BEFORE `@takazudo/zudo-doc/safelist.css`, `content.css`,
+ *      `page-loading.css`, and `features.css` — all four consume the
+ *      `@theme` tokens defined here (colors, spacing, typography, z-index),
+ *      and `content.css`'s `@layer zd-flow` rule depends on the cascade
+ *      layer order already being established by the time it loads.
+ *   3. BEFORE the project's own token-override `@theme { … }` block — Tailwind
+ *      v4 `@theme` resolution is last-declaration-wins per custom property,
+ *      so a later project block can redefine any default declared here.
+ *
+ * ── Consumer contract ────────────────────────────────────────────────────────
+ * The consumer must inject the `--zd-*` ramp/role custom properties this file
+ * aliases into `--color-*` tokens (`ColorSchemeProvider`, see
+ * `@takazudo/zudo-doc/theme`). Without them every `--color-*` token below
+ * resolves to nothing (the tight-token guardrail below wipes Tailwind's
+ * default palette; only `--zd-*`-backed aliases repopulate it).
+ *
+ * Namespace contract: zudo-doc reserves the 23 bare `--color-*` alias names
+ * declared in the first block plus the `--color-zd-*` prefix. Every other
+ * `--color-*` name, such as `--color-acme-*`, belongs to the embedder. A
+ * second `@theme` block that defines any reserved bare name in the same
+ * document is unsupported: Tailwind merges every `@theme` block reached from
+ * the entry, last declaration wins, and no error is reported. Embedders must
+ * namespace their own tokens (`--color-<theirs>-*`), import this file before
+ * their own `@theme` block so this reset cannot reach their tokens, or import
+ * `@takazudo/zudo-doc/theme-no-reset.css` (#4055) when import order is outside
+ * their control. Consume zudo-doc colors through `--color-zd-*` / `bg-zd-*`.
+ *
+ * Deliberately NOT shipped here: `--color-page-loading-overlay`. That scrim
+ * token stays feature-injected by a project's `dynamicPageTransition` wiring
+ * (its default depends on `--color-overlay`, which IS defined below) — do
+ * not add it to this base block.
+ *
+ * ── Z-index defaults ─────────────────────────────────────────────────────────
+ * The 13 `--z-index-*` entries below are the package DEFAULT tiers (mirrors
+ * `defaultZIndexTiers` from `@takazudo/zudo-doc/z-index-defaults`, #2654).
+ * A project only needs its own `src/config/z-index-tokens.ts` +
+ * `gen:z-index`/`check:z-index` codegen wiring if it OVERRIDES a tier — its
+ * own `@theme` block (declared after this file's import) simply redefines
+ * the specific `--z-index-<name>` it wants to change.
+ * ============================================================================ */
+
+@theme {
+  /* ========================================
+   * Tight-token color reset
+   *
+   * Wipes all Tailwind default color tokens (`--color-*`) so only
+   * project-defined palette and semantic tokens remain. This enforces
+   * zudo-doc's tight-token policy: "NEVER use Tailwind default colors"
+   * (documented per-project in src/CLAUDE.md's Color Rules). Semantic color
+   * tokens (defined below) are added back after this reset.
+   *
+   * The upstream split-import fix (zfb#159 / 9e37551, shipped in f68a9ba)
+   * eliminated the original leak cause (zfb no longer prepends the full
+   * @import "tailwindcss" bundle). The reset is retained as an explicit
+   * design guardrail — it prevents accidental default palette bleed from any
+   * future upstream change and keeps the color surface intentional.
+   *
+   * NOT reset: `--spacing` (the base spacing scale, default 0.25rem).
+   * Tailwind spacing utilities compute as calc(var(--spacing) * N); wiping
+   * `--spacing` collapses them to zero (observed in Wave 4 Sub-7 #1403).
+   * This guardrail resets ONLY the color namespace — never widen it.
+   * ======================================== */
+  /* theme-no-reset.css: the --color-*: initial guardrail is intentionally omitted — see theme.css and zudolab/zudo-doc#4051 */
+
+  /* ========================================
+   * Colors — Three-tier token system
+   * ======================================== */
+
+  /* ── Base ── */
+  --color-bg: var(--zd-bg);
+  --color-fg: var(--zd-fg);
+  --color-sel-bg: var(--zd-selection-bg);
+  --color-sel-fg: var(--zd-selection-fg);
+
+  /* ── Semantic aliases ── */
+  --color-surface: var(--zd-surface);
+  --color-muted: var(--zd-muted);
+  --color-accent: var(--zd-accent);
+  --color-accent-hover: var(--zd-accent-hover);
+  --color-code-bg: var(--zd-code-bg);
+  --color-code-fg: var(--zd-code-fg);
+  --color-success: var(--zd-success);
+  --color-danger: var(--zd-danger);
+  --color-warning: var(--zd-warning);
+  --color-info: var(--zd-info);
+  /* Overlay is intentionally theme-independent (always dark, not scheme-driven) */
+  --color-overlay: #000;
+  --color-image-overlay-bg: var(--zd-image-overlay-bg);
+  --color-image-overlay-fg: var(--zd-image-overlay-fg);
+  --color-chat-user-bg: var(--zd-chat-user-bg);
+  --color-chat-user-text: var(--zd-chat-user-text);
+  --color-chat-assistant-bg: var(--zd-chat-assistant-bg);
+  --color-chat-assistant-text: var(--zd-chat-assistant-text);
+  --color-matched-keyword-bg: var(--zd-matched-keyword-bg);
+  --color-matched-keyword-fg: var(--zd-matched-keyword-fg);
+
+  /* ========================================
+   * Spacing — hsp (horizontal) + vsp (vertical)
+   * ======================================== */
+  --spacing-0: 0;
+  --spacing-px: 1px;
+
+  /* Horizontal spacing (7 steps) */
+  --spacing-hsp-2xs: 0.125rem;   /* 2px  — tight inline */
+  --spacing-hsp-xs: 0.375rem;   /* 6px  — compact inline */
+  --spacing-hsp-sm: 0.5rem;     /* 8px  — small padding */
+  --spacing-hsp-md: 0.75rem;    /* 12px — default gaps */
+  --spacing-hsp-lg: 1rem;       /* 16px — standard padding */
+  --spacing-hsp-xl: 1.5rem;     /* 24px — generous padding */
+  --spacing-hsp-2xl: 2rem;      /* 32px — large padding */
+
+  /* Vertical spacing (8 steps) */
+  --spacing-vsp-3xs: 0.25rem;     /* 4px — hairline gap */
+  --spacing-vsp-2xs: 0.4375rem;   /* 7px — tight gap */
+  --spacing-vsp-xs: 0.875rem;    /* 14px — small gap */
+  --spacing-vsp-sm: 1.25rem;     /* 20px — compact gap */
+  --spacing-vsp-md: 1.5rem;      /* 24px — standard gap */
+  --spacing-vsp-lg: 1.75rem;     /* 28px — section gap */
+  --spacing-vsp-xl: 2.5rem;      /* 40px — large section gap */
+  --spacing-vsp-2xl: 3.5rem;     /* 56px — page-level gap */
+
+  /* ========================================
+   * Element sizes — semantic icon dimensions
+   * ======================================== */
+  --spacing-icon-xs: 0.75rem;    /* 12px — inline meta icons, chevrons */
+  --spacing-icon-sm: 1rem;       /* 16px — standard UI icons */
+  --spacing-icon-md: 1.25rem;    /* 20px — medium emphasis icons */
+  --spacing-icon-lg: 1.5rem;     /* 24px — large / mobile icons */
+
+  /* Image overlay button chrome */
+  --spacing-image-overlay-inset: 0.5rem;  /* 8px — overlay button corner inset + internal padding */
+
+  /* ========================================
+   * Elevation — the tight `@import "tailwindcss/utilities"` (no default
+   * @theme) drops Tailwind's default shadow scale, so `shadow-*` utilities
+   * generate nothing. Re-add the one elevation the components use: header
+   * and version-switcher dropdown panels apply `shadow-lg`. Value is
+   * Tailwind v4's default shadow-lg; the black is intentionally
+   * theme-independent (a drop shadow is absence of light, not a themed color).
+   * ======================================== */
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+
+  /* ========================================
+   * Typography
+   * ======================================== */
+
+  /* ── Tier 2: Semantic font-size tokens (reference Tier 1 scale only) ── */
+  --text-micro:      var(--text-scale-2xs);  /* 12px — compact panel labels, color swatch annotations */
+  --text-caption:    var(--text-scale-xs);   /* labels, timestamps */
+  --text-small:      var(--text-scale-sm);   /* secondary text, nav items */
+  --text-body:       var(--text-scale-md);   /* paragraphs, default */
+  --text-title:      var(--text-scale-lg);   /* card titles, section labels */
+  --text-heading:    var(--text-scale-xl);   /* page headings */
+  --text-display:    var(--text-scale-2xl);  /* hero text */
+
+  /* Font families */
+  --font-sans: system-ui, sans-serif;
+  --font-mono: ui-monospace, monospace;
+
+  /* Font weights (4 steps) */
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* Line heights (4 steps) */
+  --leading-tight: 1.25;
+  --leading-snug: 1.375;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.625;
+
+  /* Letter spacing / tracking (4 steps) */
+  --tracking-tight: -0.025em;   /* headings, display text */
+  --tracking-normal: normal;    /* browser default — resets any inherited tracking */
+  --tracking-wide: 0.05em;      /* labels, UI text */
+  --tracking-wider: 0.1em;      /* small caps, decorative */
+
+  /* ========================================
+   * Border radius (3 steps)
+   * ======================================== */
+  --radius-DEFAULT: 0.25rem;    /* 4px — rounded */
+  --radius-lg: 0.5rem;          /* 8px — rounded-lg */
+  --radius-full: 9999px;        /* rounded-full */
+
+  /* ========================================
+   * Breakpoints (3 steps)
+   * ======================================== */
+  --breakpoint-sm: 640px;
+  --breakpoint-lg: 1024px;
+  --breakpoint-xl: 1280px;
+}
+
+/* ==========================================================================
+ * Tailwind-facing zudo-doc namespace aliases
+ *
+ * zudolab/zudo-doc#4051 needs a collision-free surface for code outside
+ * zudo-doc. An embedder's own components can use `bg-zd-*` / `var(--color-zd-*)`
+ * without touching the bare tier consumed by the package chrome.
+ *
+ * This block is `static` because Tailwind v4 emits a plain `@theme` token into
+ * `:root` only when something in its own scan consumes it. zudo-doc never
+ * scans the code that consumes these aliases, so the variables must always be
+ * emitted. `static` guarantees the variables; `bg-zd-*` utilities are still
+ * generated only when the consumer's own Tailwind scan sees those classes.
+ *
+ * Keep this block after the reset: `--color-*: initial` clears every
+ * `--color-*` declared before it in the merged theme, regardless of the file
+ * that declared it. The package chrome deliberately continues consuming the
+ * bare tier; do not migrate call sites ad hoc.
+ *
+ * The raw tier is prefix-first (`--zd-*`) outside `@theme`; this semantic tier
+ * is category-first (`--color-zd-*`) inside `@theme`. A third ordering that
+ * puts the namespace before the category is disconnected from both tiers and
+ * must never be introduced.
+ * ========================================================================== */
+@theme static {
+  --color-zd-bg: var(--zd-bg);
+  --color-zd-fg: var(--zd-fg);
+  --color-zd-sel-bg: var(--zd-selection-bg);
+  --color-zd-sel-fg: var(--zd-selection-fg);
+  --color-zd-surface: var(--zd-surface);
+  --color-zd-muted: var(--zd-muted);
+  --color-zd-accent: var(--zd-accent);
+  --color-zd-accent-hover: var(--zd-accent-hover);
+  --color-zd-code-bg: var(--zd-code-bg);
+  --color-zd-code-fg: var(--zd-code-fg);
+  --color-zd-success: var(--zd-success);
+  --color-zd-danger: var(--zd-danger);
+  --color-zd-warning: var(--zd-warning);
+  --color-zd-info: var(--zd-info);
+  --color-zd-overlay: #000;
+  --color-zd-image-overlay-bg: var(--zd-image-overlay-bg);
+  --color-zd-image-overlay-fg: var(--zd-image-overlay-fg);
+  --color-zd-chat-user-bg: var(--zd-chat-user-bg);
+  --color-zd-chat-user-text: var(--zd-chat-user-text);
+  --color-zd-chat-assistant-bg: var(--zd-chat-assistant-bg);
+  --color-zd-chat-assistant-text: var(--zd-chat-assistant-text);
+  --color-zd-matched-keyword-bg: var(--zd-matched-keyword-bg);
+  --color-zd-matched-keyword-fg: var(--zd-matched-keyword-fg);
+}
+
+/* ========================================
+ * Z-index tiers — semantic, single-namespace default scale.
+ *
+ * The 13 tokens below are the package DEFAULTS (mirrors defaultZIndexTiers
+ * from @takazudo/zudo-doc/z-index-defaults, #2654). Tailwind v4 reads each
+ * --z-index-<name> theme key and generates a `z-<name>` utility, so e.g.
+ * --z-index-toolbar: 20 produces `.z-toolbar { z-index: 20 }`; raw CSS can
+ * also reference `z-index: var(--z-index-<name>)`.
+ *
+ * A project only needs its own src/config/z-index-tokens.ts +
+ * gen:z-index/check:z-index codegen if it OVERRIDES a tier — the
+ * GENERATED:Z_INDEX block that used to live in every project's global.css is
+ * now opt-in customization only, not a mandatory per-project artifact.
+ * ======================================== */
+@theme inline {
+  --z-index-content: 0;
+  --z-index-local-1: 1;
+  --z-index-local-2: 2;
+  --z-index-local-3: 3;
+  --z-index-sidebar: 10;
+  --z-index-toolbar: 20;
+  --z-index-dropdown: 30;
+  --z-index-popover: 40;
+  --z-index-modal-backdrop: 50;
+  --z-index-modal: 60;
+  --z-index-toast: 70;
+  --z-index-tooltip: 80;
+  --z-index-drag: 90;
+}
+
+:root {
+  /* Default responsive range; sidebar-resizer.ts allows 192–448px for explicit resizing. */
+  --zd-sidebar-w: clamp(14rem, 20vw, 22rem);
+
+  /* ── Tier 1: Abstract font-size scale (raw values — NOT for direct component use) ── */
+  /* Used only as a source of truth for Tier 2 semantic tokens above. */
+  --text-scale-2xs: 0.75rem;    /* 12px */
+  --text-scale-xs:  0.875rem;   /* 14px */
+  --text-scale-sm:  1rem;       /* 16px */
+  --text-scale-md:  1.2rem;     /* 19.2px */
+  --text-scale-lg:  1.4rem;     /* 22.4px */
+  --text-scale-xl:  3rem;       /* 48px */
+  --text-scale-2xl: 3.75rem;    /* 60px */
+
+  --default-transition-duration: 150ms; /* consumed by image-enlarge and hash-link opacity fade */
+  --zd-transition-slow: 200ms;          /* sidebar transform/visibility and content-band max-width */
+  --zd-transition-slower: 300ms;        /* view-transition fade-in (contentFadeIn animation) */
+  --zd-header-h: 80px;                  /* sticky header height; consumed by scroll-margin-top on [id] anchors */
+}
+
+/* ========================================
+ * Base styles
+ * ======================================== */
+
+[id] {
+  scroll-margin-top: var(--zd-header-h);
+}
+
+body {
+  background-color: var(--color-bg);
+  color: var(--color-fg);
+}
+
+::selection {
+  background-color: var(--color-sel-bg);
+  color: var(--color-sel-fg);
+}
+
+@layer base {
+  a {
+    text-underline-offset: 4px;
+  }
+  button {
+    cursor: pointer;
+  }
+  :focus-visible {
+    outline: 2px solid var(--color-accent);
+    outline-offset: 2px;
+  }
+}
+
+/* ── Search highlight ── */
+[data-search-results] mark {
+  background-color: var(--color-matched-keyword-bg);
+  color: var(--color-matched-keyword-fg);
+  padding: 0;
+  border-radius: 2px;
+}
+
+/* Version-switcher responsive visibility (was an inline <style> child of
+ * the data-version-switcher <div>; moved to global.css to avoid the
+ * <style>-inside-<div> HTML5 content-model violation flagged by
+ * html-validate — see zudolab/zudo-doc#1505).
+ *
+ * Pins onto the `.hidden` baseline that Tailwind always generates so
+ * consumers wrapping <VersionSwitcher> in `<div class="hidden lg:block">`
+ * still get the desktop override even when the content scanner did not
+ * generate `.lg:block`. Mobile (<64rem) falls through to `.hidden`'s
+ * `display: none`. Inert when no version-switcher is on the page. */
+@media (min-width: 64rem) {
+  .hidden:has(> [data-version-switcher]) {
+    display: block;
+  }
+}
+
+/* ── Find-in-page highlight ── */
+/* Deliberate ephemeral-vs-persistent split: find-in-page uses color-mix(warning)
+ * because it is a transient browser-controlled overlay that appears and disappears
+ * without page navigation. Search results use --color-matched-keyword-bg/fg because
+ * they are persistent semantic highlights tied to the current query state.
+ * Do NOT unify these two highlight strategies — the visual distinction is intentional. */
+.find-match {
+  background-color: color-mix(in oklch, var(--color-warning) 40%, transparent);
+  border-radius: 2px;
+}
+.find-match-active {
+  background-color: color-mix(in oklch, var(--color-warning) 70%, transparent);
+  border-radius: 2px;
+  outline: 2px solid color-mix(in oklch, var(--color-warning) 90%, transparent);
+}

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

@@ -395,7 +395,13 @@ html[data-theme-pack="academia"] [data-nav-item] {
   font-size: 1rem;
   letter-spacing: 0.08em;
 }
-html[data-theme-pack="academia"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text to the accent would sit bright-on-bright.
+   Two shapes exist (header.tsx): a plain `a[data-nav-item]`, and a dropdown
+   whose data-nav-item sits on the wrapper div while aria-current + the
+   colors live on its child anchor — target the anchor in both. */
+html[data-theme-pack="academia"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="academia"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration: none;
 }
@@ -411,7 +417,11 @@ html[data-theme-pack="academia"] aside[data-zd-mobile-sidebar] {
   background-color: var(--zd-bg);
   border-right-color: color-mix(in srgb, var(--zd-fg) 25%, transparent);
 }
-html[data-theme-pack="academia"] #desktop-sidebar a:hover {
+/* Exclude the current page: root/branch current nodes carry
+   aria-current="page" without data-nav-active and keep the base
+   inverted `bg-fg text-bg` fill — recoloring their text to the
+   accent on hover would sit accent-on-fg (~1:1). */
+html[data-theme-pack="academia"] #desktop-sidebar a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration: none;
 }

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

@@ -297,7 +297,13 @@ html[data-theme-pack="blueprint"] [data-nav-item] {
   letter-spacing: 0.11em;
   border-radius: 0;
 }
-html[data-theme-pack="blueprint"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text to fg would sit fg-on-fg. Two shapes exist
+   (header.tsx): a plain `a[data-nav-item]`, and a dropdown whose
+   data-nav-item sits on the wrapper div while aria-current + the colors
+   live on its child anchor — target the anchor in both. */
+html[data-theme-pack="blueprint"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="blueprint"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-fg);
   text-decoration: underline dashed;
   text-underline-offset: 4px;

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

@@ -212,7 +212,13 @@ html[data-theme-pack="broadsheet"] [data-nav-item] {
   letter-spacing: 0.1em;
   font-weight: 600;
 }
-html[data-theme-pack="broadsheet"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text to the accent would sit bright-on-bright.
+   Two shapes exist (header.tsx): a plain `a[data-nav-item]`, and a dropdown
+   whose data-nav-item sits on the wrapper div while aria-current + the
+   colors live on its child anchor — target the anchor in both. */
+html[data-theme-pack="broadsheet"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="broadsheet"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration-thickness: 2px;
 }

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

@@ -386,13 +386,31 @@ html[data-theme-pack="brutalist"] .zd-content blockquote a {
   text-underline-offset: 3px;
   font-weight: 500;
 }
+/* Card-style prose links (e.g. the note-tray IndexList rank/label/
+   description spans) put their own color on group-hover: utility
+   classes (group-hover:text-fg / group-hover:text-accent), which beats
+   the anchor's inherited `color` — so the anchor-level color below
+   never reached that text. Measured 2.63:1 (rgb(245 245 245) on
+   rgb(255 106 31), dark) / 4.06:1 (rgb(0 0 0) on rgb(194 65 12), light)
+   against the prior var(--zd-accent)/var(--zd-bg) pair, because the
+   rendered ink was actually --zd-fg (the descendant spans' own
+   resting/hover color), not --zd-bg. Darken the background (same hue,
+   not the shared --zd-accent token) and force white ink on every
+   descendant so the fix reaches those spans too. */
 html[data-theme-pack="brutalist"] .zd-content p a:hover,
 html[data-theme-pack="brutalist"] .zd-content li a:not([aria-label]):hover,
 html[data-theme-pack="brutalist"] .zd-content td a:hover,
 html[data-theme-pack="brutalist"] .zd-content blockquote a:hover {
-  background-color: var(--zd-accent);
-  color: var(--zd-bg);
-  text-decoration-color: var(--zd-bg);
+  background-color: color-mix(in srgb, var(--zd-accent) 70%, black);
+  color: #ffffff;
+  text-decoration-color: #ffffff;
+}
+html[data-theme-pack="brutalist"] .zd-content p a:hover *,
+html[data-theme-pack="brutalist"] .zd-content li a:not([aria-label]):hover *,
+html[data-theme-pack="brutalist"] .zd-content td a:hover *,
+html[data-theme-pack="brutalist"] .zd-content blockquote a:hover * {
+  color: #ffffff;
+  text-decoration-color: #ffffff;
 }
 
 /* prose furniture */

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

@@ -288,7 +288,11 @@ html[data-theme-pack="drift"] #desktop-sidebar a {
 html[data-theme-pack="drift"] #desktop-sidebar a[aria-current="page"]:not([data-nav-active]) {
   border-radius: 0;
 }
-html[data-theme-pack="drift"] #desktop-sidebar a:hover {
+/* Exclude the active item: aria-current="page" carries the base
+   `bg-fg text-bg` inverted fill (or the glow pill below); an
+   unconditional hover background would replace that fill while the
+   inverted ink survives, sitting bg-on-bg. */
+html[data-theme-pack="drift"] #desktop-sidebar a:not([aria-current="page"]):hover {
   text-decoration: none;
   background: color-mix(in oklch, var(--zd-accent) 10%, transparent);
 }

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

@@ -127,13 +127,24 @@ html[data-theme-pack="foundry"] .zd-content code:not(pre code) {
 html[data-theme-pack="foundry"] [data-nav-item] {
   border-radius: 6px;
 }
-html[data-theme-pack="foundry"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — the hover wash would replace that fill (bg-on-bg, ~1:1) since
+   `text-bg` ink survives underneath it. Two shapes exist (header.tsx): a
+   plain `a[data-nav-item]`, and a dropdown whose data-nav-item sits on the
+   wrapper div while aria-current + the colors live on its child anchor —
+   target the anchor in both. */
+html[data-theme-pack="foundry"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="foundry"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   text-decoration: none;
   background: color-mix(in srgb, var(--zd-muted) 8%, transparent);
 }
 
 /* sidebar: gray hover wash; active item = subtle fill + Primer-blue bar */
-html[data-theme-pack="foundry"] #desktop-sidebar a:hover {
+/* Exclude the current page: root/branch current nodes carry
+   aria-current="page" without data-nav-active and keep the base
+   inverted `bg-fg text-bg` fill — the hover wash would replace that
+   fill (bg-on-bg, ~1:1) since `text-bg` ink survives underneath it. */
+html[data-theme-pack="foundry"] #desktop-sidebar a:not([aria-current="page"]):hover {
   text-decoration: none;
   background: color-mix(in srgb, var(--zd-muted) 8%, transparent);
 }

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

@@ -197,7 +197,13 @@ html[data-theme-pack="hearth"] [data-header-logo] {
   font-weight: 620;
   color: var(--zd-accent);
 }
-html[data-theme-pack="hearth"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text to the accent would sit bright-on-bright.
+   Two shapes exist (header.tsx): a plain `a[data-nav-item]`, and a dropdown
+   whose data-nav-item sits on the wrapper div while aria-current + the
+   colors live on its child anchor — target the anchor in both. */
+html[data-theme-pack="hearth"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="hearth"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration-color: color-mix(in oklch, var(--zd-accent) 50%, transparent);
   text-underline-offset: 4px;

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

@@ -214,7 +214,13 @@ html[data-theme-pack="ledger"] [data-nav-item] {
   font-variant-caps: all-small-caps;
   letter-spacing: 0.09em;
 }
-html[data-theme-pack="ledger"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text to the accent would sit bright-on-bright.
+   Two shapes exist (header.tsx): a plain `a[data-nav-item]`, and a dropdown
+   whose data-nav-item sits on the wrapper div while aria-current + the
+   colors live on its child anchor — target the anchor in both. */
+html[data-theme-pack="ledger"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="ledger"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration: none;
 }
@@ -225,7 +231,11 @@ html[data-theme-pack="ledger"] [data-nav-item]:hover {
 html[data-theme-pack="ledger"] #desktop-sidebar {
   border-right-color: color-mix(in srgb, var(--zd-fg) 22%, transparent);
 }
-html[data-theme-pack="ledger"] #desktop-sidebar a:hover {
+/* Exclude the current page: root/branch current nodes carry
+   aria-current="page" without data-nav-active and keep the base
+   inverted `bg-fg text-bg` fill — recoloring their text to the
+   accent on hover would sit accent-on-fg (~1:1). */
+html[data-theme-pack="ledger"] #desktop-sidebar a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration: none;
 }

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

@@ -340,7 +340,11 @@ html[data-theme-pack="observatory"] #desktop-sidebar {
 html[data-theme-pack="observatory"] #desktop-sidebar a {
   border-radius: 0;
 }
-html[data-theme-pack="observatory"] #desktop-sidebar a:not([data-nav-active]):hover {
+/* :not([data-nav-active]) was incomplete: an active root/category node
+   carries aria-current="page" without data-nav-active, so hover still
+   repainted it and collapsed the gold-plate contrast. Guard the actual
+   active marker, aria-current="page", instead. */
+html[data-theme-pack="observatory"] #desktop-sidebar a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
 }
 /* active item: the gold indicator token fills it; square plate */

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

@@ -265,12 +265,15 @@ html[data-theme-pack="riso"] [data-nav-item]:hover {
 html[data-theme-pack="riso"] #desktop-sidebar {
   border-right: 2px solid light-dark(rgb(13 92 148 / 0.35), rgb(88 184 232 / 0.35));
 }
-/* :not([data-nav-active]) is load-bearing, not cosmetic: the bare ID
-   selector would out-rank the active chip below and repaint its blue
-   fill with the pale wash on hover — leaving paper-colored text on a
-   paper-colored wash (invisible). Narrow, single-hook :not — not a
-   broad recolor chain. */
-html[data-theme-pack="riso"] #desktop-sidebar a:hover:not([data-nav-active]) {
+/* The exclusion is load-bearing, not cosmetic: the bare ID selector
+   would out-rank the active chip below and repaint its blue fill with
+   the pale wash on hover — leaving paper-colored text on a paper-
+   colored wash (invisible). Narrow, single-hook :not — not a broad
+   recolor chain. :not([data-nav-active]) was incomplete: an active
+   root/category node carries aria-current="page" without
+   data-nav-active, so hover still repainted it. Guard
+   aria-current="page" instead. */
+html[data-theme-pack="riso"] #desktop-sidebar a:hover:not([aria-current="page"]) {
   text-decoration: none;
   background: light-dark(#e6e7df, #1a3343);
 }

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

@@ -256,8 +256,12 @@ html[data-theme-pack="sakura"] #desktop-sidebar a[aria-current="page"]:not([data
 html[data-theme-pack="sakura"] aside[data-zd-mobile-sidebar] a[aria-current="page"]:not([data-nav-active]) {
   border-radius: 0;
 }
-html[data-theme-pack="sakura"] #desktop-sidebar a:not([data-nav-active]):hover,
-html[data-theme-pack="sakura"] aside[data-zd-mobile-sidebar] a:not([data-nav-active]):hover {
+/* :not([data-nav-active]) was incomplete: an active root/category node
+   carries aria-current="page" without data-nav-active, so hover could
+   still repaint it. Guard aria-current="page" instead (latent hole —
+   fixed here for consistency with the other packs). */
+html[data-theme-pack="sakura"] #desktop-sidebar a:not([aria-current="page"]):hover,
+html[data-theme-pack="sakura"] aside[data-zd-mobile-sidebar] a:not([aria-current="page"]):hover {
   text-decoration: none;
   color: var(--zd-accent);
   background: color-mix(in srgb, var(--zd-accent) 10%, transparent);

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

@@ -265,7 +265,13 @@ html[data-theme-pack="sumi"] [data-header-logo]::after {
   background: light-dark(#c2242f, #d9333f);
   margin-left: 0.45em;
 }
-html[data-theme-pack="sumi"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text to the accent would sit fg-on-fg. Two DOM
+   shapes exist (header.tsx): a plain `a[data-nav-item]`, and a dropdown
+   whose data-nav-item sits on the wrapper div while aria-current + the
+   colors live on its child anchor — target the anchor in both. */
+html[data-theme-pack="sumi"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="sumi"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-accent);
   text-decoration-thickness: 2px;
   text-underline-offset: 3px;

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

@@ -223,7 +223,13 @@ html[data-theme-pack="swissgrid"] [data-nav-item] {
   font-weight: 700;
   letter-spacing: 0.1em;
 }
-html[data-theme-pack="swissgrid"] [data-nav-item]:hover {
+/* Exclude the current page: it carries the base `bg-fg text-bg` inverted
+   fill — recoloring its text would sit fg-on-fg. Two DOM shapes exist
+   (header.tsx): a plain `a[data-nav-item]`, and a dropdown whose
+   data-nav-item sits on the wrapper div while aria-current + the colors
+   live on its child anchor — target the anchor in both. */
+html[data-theme-pack="swissgrid"] a[data-nav-item]:not([aria-current="page"]):hover,
+html[data-theme-pack="swissgrid"] [data-nav-item-dropdown] > a:not([aria-current="page"]):hover {
   color: var(--zd-fg);
   text-decoration-line: underline;
   text-decoration-color: #ff0000;