@takazudo/zudo-doc 4.2.1 → 4.4.0

package/dist/doc-history-area/index.d.ts

@@ -14,6 +14,7 @@ export interface DocHistoryMetaEntry {
 /** Settings subset read by the DocHistoryArea factory. */
 export interface DocHistoryAreaSettings {
     docHistory: boolean;
+    docHistoryExclude?: string[];
     bodyFootUtilArea: {
         viewSourceLink?: boolean;
     } | false | undefined;

package/dist/doc-history-area/index.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { Island } from "@takazudo/zfb";
+import { compileExclude } from "@takazudo/zudo-doc-history-server/exclude";
 import { BodyFootUtilArea } from "../body-foot-util/index.js";
 import { toHistorySlug } from "../slug/index.js";
 import { buildGitHubSourceUrl as buildGitHubSourceUrlBase } from "../github-helpers/index.js";
@@ -8,6 +9,7 @@ import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocHistoryArea(ctx) {
   assertChromeContext(ctx, "createDocHistoryArea");
   const settings = ctx.settings;
+  const isHistoryExcluded = compileExclude(settings.docHistoryExclude ?? []);
   const defaultLocale = ctx.defaultLocale;
   const docHistoryMeta = ctx.hostBindings.docHistoryMeta ?? {};
   const t = ctx.t;
@@ -28,6 +30,7 @@ function createDocHistoryArea(ctx) {
   }) {
     if (!settings.docHistory) return null;
     const historySlug = toHistorySlug(slug);
+    if (isHistoryExcluded(historySlug)) return null;
     const effectiveHistoryLocale = isFallback ? defaultLocale : locale;
     const composedSlug = effectiveHistoryLocale === defaultLocale ? historySlug : `${effectiveHistoryLocale}/${historySlug}`;
     const meta = docHistoryMeta[composedSlug];

package/dist/doc-page-shell/index.js

@@ -133,7 +133,7 @@ function createDocPageShell(ctx) {
              Fragment (not <div>) so children become direct children of
              <article class="zd-content">, picking up the flow-space rule. */
           /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-xs", children: autoIndexLabel }),
+            /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold border-b border-fg pb-vsp-xs mb-vsp-xs", children: autoIndexLabel }),
             metainfoSlot,
             description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", "data-doc-description": true, children: description }),
             /* @__PURE__ */ jsx(NavCardGrid, { children: autoIndexChildren ?? [] })

package/dist/doc-pager/index.js

@@ -12,7 +12,7 @@ function createDocPager(ctx) {
           href: prev.href,
           class: "group border border-muted rounded-lg p-hsp-lg hover:border-accent",
           children: [
-            /* @__PURE__ */ jsxs("div", { class: "flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs", children: [
+            /* @__PURE__ */ jsxs("div", { class: "flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs group-hover:text-accent group-focus-visible:text-accent", children: [
               /* @__PURE__ */ jsx(ChevronLeft, { className: "h-[1.125rem] w-[1.125rem]" }),
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.previous", locale) })
             ] }),
@@ -26,7 +26,7 @@ function createDocPager(ctx) {
           href: next.href,
           class: "group border border-muted rounded-lg p-hsp-lg hover:border-accent text-right",
           children: [
-            /* @__PURE__ */ jsxs("div", { class: "flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs", children: [
+            /* @__PURE__ */ jsxs("div", { class: "flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs group-hover:text-accent group-focus-visible:text-accent", children: [
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.next", locale) }),
               /* @__PURE__ */ jsx(ChevronRight, { className: "h-[1.125rem] w-[1.125rem]" })
             ] }),

package/dist/eject-logo/config-parse.d.ts

@@ -0,0 +1,25 @@
+import { type TopLevelMember } from "../theme-cli/config-scanner.js";
+export interface ParsedZudoDocConfig {
+    ok: true;
+    members: TopLevelMember[];
+    /** Index of the zudoDoc({ ... }) call's opening `{`. */
+    braceOpenIdx: number;
+    /** Index of the matching closing `}`. */
+    braceCloseIdx: number;
+}
+export interface ParsedZudoDocConfigRefusal {
+    ok: false;
+    /** Human-readable WHY, with no field-specific hint appended — callers own
+     *  wording their own remediation (a read-only lookup vs. a write refusal
+     *  need different follow-up text). */
+    reason: string;
+}
+export type ParseZudoDocConfigResult = ParsedZudoDocConfig | ParsedZudoDocConfigRefusal;
+/**
+ * Locate and validate the project's `zfb.config.ts` canonical shape — a
+ * single `zudoDoc({ ... })` call whose sole argument is a literal,
+ * non-spread object — and return its top-level members. Mirrors
+ * `theme-cli/config-rewriter.ts#applyThemePackToConfigSource`'s validation
+ * exactly, generalized to any caller field.
+ */
+export declare function parseZudoDocConfigMembers(source: string): ParseZudoDocConfigResult;

package/dist/eject-logo/config-parse.js

@@ -0,0 +1,68 @@
+import {
+  ConfigSyntaxError,
+  findMatchingBrace,
+  findZudoDocCallParens,
+  skipWhitespaceAndComments,
+  splitTopLevelMembers
+} from "../theme-cli/config-scanner.js";
+function parseZudoDocConfigMembers(source) {
+  let calls;
+  try {
+    calls = findZudoDocCallParens(source);
+  } catch (err) {
+    return { ok: false, reason: `could not parse zfb.config.ts (${err.message}).` };
+  }
+  if (calls.length === 0) {
+    return {
+      ok: false,
+      reason: "no zudoDoc(...) call found in zfb.config.ts. This CLI only reads/rewrites the canonical generated shape: export default defineConfig(zudoDoc({ ... }))."
+    };
+  }
+  if (calls.length > 1) {
+    return {
+      ok: false,
+      reason: `found ${calls.length} zudoDoc(...) call sites in zfb.config.ts \u2014 cannot safely determine which one to use.`
+    };
+  }
+  const openParenIdx = calls[0];
+  let braceOpenIdx;
+  let braceCloseIdx;
+  let afterBrace;
+  try {
+    braceOpenIdx = skipWhitespaceAndComments(source, openParenIdx + 1);
+    if (source[braceOpenIdx] !== "{") {
+      return {
+        ok: false,
+        reason: "zudoDoc(...) is not called with a plain object literal (found a computed or non-literal argument instead of zudoDoc({ ... })). This CLI only reads/rewrites the canonical generated shape."
+      };
+    }
+    braceCloseIdx = findMatchingBrace(source, braceOpenIdx);
+    afterBrace = skipWhitespaceAndComments(source, braceCloseIdx + 1);
+  } catch (err) {
+    return { ok: false, reason: `could not parse zfb.config.ts (${err.message}).` };
+  }
+  const afterOptionalComma = source[afterBrace] === "," ? skipWhitespaceAndComments(source, afterBrace + 1) : afterBrace;
+  if (source[afterOptionalComma] !== ")") {
+    return {
+      ok: false,
+      reason: "zudoDoc(...) is called with more than one argument \u2014 not the canonical single-object-literal shape."
+    };
+  }
+  let members;
+  try {
+    members = splitTopLevelMembers(source, braceOpenIdx + 1, braceCloseIdx);
+  } catch (err) {
+    return { ok: false, reason: `could not parse zfb.config.ts (${err.message}).` };
+  }
+  const spread = members.find((m) => m.isSpread);
+  if (spread) {
+    return {
+      ok: false,
+      reason: "zudoDoc({ ...spread }) uses a spread argument \u2014 not the canonical generated shape. This CLI only reads/rewrites a literal, hand-editable field list."
+    };
+  }
+  return { ok: true, members, braceOpenIdx, braceCloseIdx };
+}
+export {
+  parseZudoDocConfigMembers
+};

package/dist/eject-logo/config-rewriter.d.ts

@@ -0,0 +1,22 @@
+export declare const EJECTED_LOGO_VALUE = "/img/logo.svg";
+export interface ApplyLogoFieldToSourceOk {
+    ok: true;
+    /** The full rewritten file contents. Identical to the input when
+     *  `changed` is false (idempotent re-run of an already-ejected logo). */
+    source: string;
+    changed: boolean;
+    mode: "replaced" | "inserted-after-site-name" | "inserted-first";
+}
+export interface ApplyLogoFieldToSourceRefusal {
+    ok: false;
+    /** Human-readable WHY, ending with the manual one-liner to add by hand.
+     *  The input source is never touched when this is returned. */
+    reason: string;
+}
+export type ApplyLogoFieldToSourceResult = ApplyLogoFieldToSourceOk | ApplyLogoFieldToSourceRefusal;
+/**
+ * Apply `logo: "/img/logo.svg"` to a `zfb.config.ts` source string. Pure and
+ * filesystem-free — callers own reading/writing the actual file (see
+ * `eject.ts`).
+ */
+export declare function applyLogoFieldToConfigSource(source: string): ApplyLogoFieldToSourceResult;

package/dist/eject-logo/config-rewriter.js

@@ -0,0 +1,68 @@
+import { isPlainStringLiteralSpan } from "../theme-cli/config-scanner.js";
+import { parseZudoDocConfigMembers } from "./config-parse.js";
+const EJECTED_LOGO_VALUE = "/img/logo.svg";
+function manualHint() {
+  return `Add the field manually inside your zudoDoc({ ... }) call: logo: ${JSON.stringify(EJECTED_LOGO_VALUE)},`;
+}
+function refuse(reason) {
+  return { ok: false, reason: `${reason} ${manualHint()}` };
+}
+function isPlainFalseLiteralSpan(source, start, end) {
+  return source.slice(start, end).trim() === "false";
+}
+function detectIndent(source, members) {
+  const ref = members[0];
+  const refPos = ref ? ref.keyStart ?? ref.memberStart : null;
+  if (refPos !== null && refPos !== void 0) {
+    const newlineIdx = source.lastIndexOf("\n", refPos);
+    const lineStart = newlineIdx === -1 ? 0 : newlineIdx + 1;
+    const line = source.slice(lineStart, refPos);
+    if (/^[ \t]*$/.test(line) && line.length > 0) return line;
+  }
+  return "  ";
+}
+function applyLogoFieldToConfigSource(source) {
+  const parsed = parseZudoDocConfigMembers(source);
+  if (!parsed.ok) return refuse(parsed.reason);
+  const { members, braceOpenIdx } = parsed;
+  const newValueLiteral = JSON.stringify(EJECTED_LOGO_VALUE);
+  const logoMembers = members.filter((m) => m.key === "logo");
+  if (logoMembers.length > 1) {
+    return refuse(
+      'zfb.config.ts declares "logo" more than once inside zudoDoc({ ... }). This CLI only rewrites a single canonical field; remove the duplicate and re-run.'
+    );
+  }
+  const logoMember = logoMembers[0];
+  if (logoMember) {
+    if (logoMember.valueStart === null || logoMember.valueEnd === null) {
+      return refuse('the existing "logo" field in zfb.config.ts is not a simple `key: value` property this CLI understands.');
+    }
+    const isReplaceableLiteral = isPlainStringLiteralSpan(source, logoMember.valueStart, logoMember.valueEnd) || isPlainFalseLiteralSpan(source, logoMember.valueStart, logoMember.valueEnd);
+    if (!isReplaceableLiteral) {
+      return refuse(
+        'the existing "logo" field\'s value is not a plain string literal or `false` \u2014 cannot safely rewrite it without risking corruption.'
+      );
+    }
+    const newSource2 = source.slice(0, logoMember.valueStart) + newValueLiteral + source.slice(logoMember.valueEnd);
+    return { ok: true, source: newSource2, changed: newSource2 !== source, mode: "replaced" };
+  }
+  const siteNameMember = members.find((m) => m.key === "siteName");
+  const indent = detectIndent(source, members);
+  if (siteNameMember) {
+    const insertAt2 = siteNameMember.commaIndex !== null ? siteNameMember.commaIndex + 1 : siteNameMember.memberEnd;
+    const prefix = siteNameMember.commaIndex !== null ? "" : ",";
+    const insertText2 = `${prefix}
+${indent}logo: ${newValueLiteral},`;
+    const newSource2 = source.slice(0, insertAt2) + insertText2 + source.slice(insertAt2);
+    return { ok: true, source: newSource2, changed: true, mode: "inserted-after-site-name" };
+  }
+  const insertAt = braceOpenIdx + 1;
+  const insertText = `
+${indent}logo: ${newValueLiteral},`;
+  const newSource = source.slice(0, insertAt) + insertText + source.slice(insertAt);
+  return { ok: true, source: newSource, changed: true, mode: "inserted-first" };
+}
+export {
+  EJECTED_LOGO_VALUE,
+  applyLogoFieldToConfigSource
+};

package/dist/eject-logo/eject.d.ts

@@ -0,0 +1,18 @@
+export interface EjectLogoOptions {
+    cwd?: string;
+    /** Explicit seed override (already validated non-empty by the CLI arg
+     *  parser in bin/zudo-doc.mjs). When omitted, the seed is resolved from
+     *  zfb.config.ts's siteName field. */
+    seed?: string;
+    force?: boolean;
+}
+export interface EjectLogoResult {
+    ok: boolean;
+    /** Human-readable outcome message (success confirmation, or a refusal
+     *  explaining WHY). */
+    message: string;
+    /** True when the SVG was written but the config rewrite was refused — a
+     *  nonzero-exit partial success, not a total failure. */
+    partial?: boolean;
+}
+export declare function ejectLogo(options?: EjectLogoOptions): Promise<EjectLogoResult>;

package/dist/eject-logo/eject.js

@@ -0,0 +1,66 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { renderAutoLogoStandaloneSvg } from "../auto-logo/standalone.js";
+import { applyLogoFieldToConfigSource } from "./config-rewriter.js";
+import { resolveSiteNameFromConfigSource } from "./site-name.js";
+const ZFB_CONFIG_FILENAME = "zfb.config.ts";
+const LOGO_RELATIVE_PATH = path.join("public", "img", "logo.svg");
+const DEFAULT_SEED = "Docs";
+async function ejectLogo(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const force = options.force ?? false;
+  const configPath = path.join(cwd, ZFB_CONFIG_FILENAME);
+  if (!await fs.pathExists(configPath)) {
+    return {
+      ok: false,
+      message: `zfb.config.ts not found at ${configPath}.
+Run this command from your project root.`
+    };
+  }
+  const source = await fs.readFile(configPath, "utf8");
+  let seed;
+  if (options.seed) {
+    seed = options.seed;
+  } else {
+    const resolution = resolveSiteNameFromConfigSource(source);
+    if (resolution.kind === "unresolvable") {
+      return {
+        ok: false,
+        message: `Could not determine a logo seed from zfb.config.ts: ${resolution.reason}
+Pass --seed <name> to specify the logo seed explicitly.`
+      };
+    }
+    seed = resolution.kind === "literal" ? resolution.value : DEFAULT_SEED;
+  }
+  const rewriteResult = applyLogoFieldToConfigSource(source);
+  const svgPath = path.join(cwd, LOGO_RELATIVE_PATH);
+  if (!force && await fs.pathExists(svgPath)) {
+    return {
+      ok: false,
+      message: `${LOGO_RELATIVE_PATH} already exists.
+Pass --force to overwrite it.`
+    };
+  }
+  const svg = renderAutoLogoStandaloneSvg(seed);
+  await fs.ensureDir(path.dirname(svgPath));
+  await fs.writeFile(svgPath, svg, "utf8");
+  if (!rewriteResult.ok) {
+    return {
+      ok: false,
+      partial: true,
+      message: `Wrote ${LOGO_RELATIVE_PATH}, but could not update zfb.config.ts: ${rewriteResult.reason}`
+    };
+  }
+  if (rewriteResult.changed) {
+    await fs.writeFile(configPath, rewriteResult.source, "utf8");
+  }
+  const verb = rewriteResult.changed ? "Ejected logo" : "Ejected logo (field already set)";
+  return {
+    ok: true,
+    message: `${verb} \u2192 ${LOGO_RELATIVE_PATH}
+Updated zfb.config.ts's logo field.`
+  };
+}
+export {
+  ejectLogo
+};

package/dist/eject-logo/index.d.ts

@@ -0,0 +1,4 @@
+export { ejectLogo, type EjectLogoOptions, type EjectLogoResult } from "./eject.js";
+export { applyLogoFieldToConfigSource, EJECTED_LOGO_VALUE, type ApplyLogoFieldToSourceOk, type ApplyLogoFieldToSourceRefusal, type ApplyLogoFieldToSourceResult, } from "./config-rewriter.js";
+export { resolveSiteNameFromConfigSource, type SiteNameResolution } from "./site-name.js";
+export { parseZudoDocConfigMembers, type ParsedZudoDocConfig, type ParsedZudoDocConfigRefusal, type ParseZudoDocConfigResult, } from "./config-parse.js";

package/dist/eject-logo/index.js

@@ -0,0 +1,16 @@
+import { ejectLogo } from "./eject.js";
+import {
+  applyLogoFieldToConfigSource,
+  EJECTED_LOGO_VALUE
+} from "./config-rewriter.js";
+import { resolveSiteNameFromConfigSource } from "./site-name.js";
+import {
+  parseZudoDocConfigMembers
+} from "./config-parse.js";
+export {
+  EJECTED_LOGO_VALUE,
+  applyLogoFieldToConfigSource,
+  ejectLogo,
+  parseZudoDocConfigMembers,
+  resolveSiteNameFromConfigSource
+};

package/dist/eject-logo/site-name.d.ts

@@ -0,0 +1,21 @@
+export type SiteNameResolution = {
+    kind: "literal";
+    value: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+/**
+ * Resolve `siteName` from a `zfb.config.ts` source string.
+ *
+ * - Literal `siteName: "..."` → `{ kind: "literal", value }`.
+ * - Canonical literal config with no `siteName` field → `{ kind: "absent" }`
+ *   (the runtime default `"Docs"` genuinely applies — this IS a confirmed
+ *   reading, the caller decides the default value).
+ * - Anything else (no/duplicate zudoDoc call, spread argument, computed or
+ *   duplicate `siteName`, non-string value) → `{ kind: "unresolvable",
+ *   reason }`; the caller must require `--seed`.
+ */
+export declare function resolveSiteNameFromConfigSource(source: string): SiteNameResolution;

package/dist/eject-logo/site-name.js

@@ -0,0 +1,31 @@
+import { isPlainStringLiteralSpan, unquoteStringLiteralSpan } from "../theme-cli/config-scanner.js";
+import { parseZudoDocConfigMembers } from "./config-parse.js";
+function resolveSiteNameFromConfigSource(source) {
+  const parsed = parseZudoDocConfigMembers(source);
+  if (!parsed.ok) return { kind: "unresolvable", reason: parsed.reason };
+  const siteNameMembers = parsed.members.filter((m) => m.key === "siteName");
+  if (siteNameMembers.length > 1) {
+    return {
+      kind: "unresolvable",
+      reason: 'zfb.config.ts declares "siteName" more than once inside zudoDoc({ ... }) \u2014 cannot safely determine which one the runtime reads.'
+    };
+  }
+  const member = siteNameMembers[0];
+  if (!member) return { kind: "absent" };
+  if (member.valueStart === null || member.valueEnd === null) {
+    return {
+      kind: "unresolvable",
+      reason: 'the "siteName" field in zfb.config.ts is not a simple `key: value` property this CLI understands.'
+    };
+  }
+  if (!isPlainStringLiteralSpan(source, member.valueStart, member.valueEnd)) {
+    return {
+      kind: "unresolvable",
+      reason: `the "siteName" field's value in zfb.config.ts is not a plain string literal.`
+    };
+  }
+  return { kind: "literal", value: unquoteStringLiteralSpan(source, member.valueStart, member.valueEnd) };
+}
+export {
+  resolveSiteNameFromConfigSource
+};

package/dist/features.css

@@ -179,31 +179,10 @@ header[data-header] {
   --zfb-hi-hd: var(--zd-syntax-keyword);
 }
 
-/* HTML Preview remains on Shiki until #2742. Its dual-theme variables resolve
- * through color-scheme. These selectors intentionally exclude `.hi-root`,
- * whose colors come from the semantic bridge above. */
-[data-theme] .shiki,
-[data-theme] .shiki span {
-  color: light-dark(var(--shiki-light), var(--shiki-dark));
-  font-style: light-dark(
-    var(--shiki-light-font-style, inherit),
-    var(--shiki-dark-font-style, inherit)
-  );
-}
-
-/* Background only on the <pre> wrapper — deliberately NOT on token spans. The
- * --shiki-*-bg vars are set inline on the <pre> and inherit down to spans;
- * painting them per-span would lay an opaque base background over the
- * translucent line-/word-highlight backgrounds that sit on the enclosing
- * .line span (see .line.highlighted below). */
-[data-theme] .shiki {
-  background-color: light-dark(var(--shiki-light-bg), var(--shiki-dark-bg));
-}
-
-/* HtmlPreview component — Shiki code blocks
- * Token colors inherit from the global [data-theme] .shiki rule above.
- * These rules only adjust layout and background for the preview context. */
-.zd-html-preview-code pre.shiki {
+/* HtmlPreview component — zfb semantic code blocks. Token colors and the root
+ * surface resolve through the shared class-mode bridge above; these rules only
+ * adjust layout for the preview context. */
+.zd-html-preview-code pre.hi-root {
   margin: 0;
   padding: var(--spacing-hsp-md);
   font-size: var(--text-caption);
@@ -211,7 +190,7 @@ header[data-header] {
   overflow-x: auto;
 }
 
-.zd-html-preview-code pre.shiki code {
+.zd-html-preview-code pre.hi-root code {
   font-family: var(--font-mono);
   white-space: pre;
 }
@@ -266,9 +245,9 @@ pre.hi-root .line .highlighted-word {
  * zfb's :::code-group emits <CodeGroup tabs={[...]}> with one
  * <pre data-lang="…">{RAW text}</pre> child per fence. These <pre> elements
  * are NOT syntax-highlighted (the Rust pipeline doesn't highlight inside
- * code-group fences), so they get no `.hi-root` class. Apply explicit
- * code-block visual treatment via tokens to match the highlighted code blocks
- * surrounding them.
+ * code-group fences), so they get no `.hi-root` class.
+ * Apply explicit code-block visual treatment via tokens to match the
+ * highlighted code blocks surrounding them.
  * ======================================== */
 
 .code-group-panel pre[data-lang] {

package/dist/header/header.js

@@ -6,6 +6,14 @@ import {
   pathForMatch
 } from "./nav-active.js";
 import { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-script.js";
+import {
+  NAV_CHEVRON_ACTIVE,
+  NAV_CHEVRON_INACTIVE,
+  NAV_CHILD_ACTIVE,
+  NAV_CHILD_INACTIVE,
+  NAV_TOP_ACTIVE,
+  NAV_TOP_INACTIVE
+} from "./nav-class-tokens.js";
 import { LANGUAGE_SWITCHER_INIT_SCRIPT } from "../i18n-version/language-switcher.js";
 import { VERSION_SWITCHER_REWIRE_SCRIPT } from "../i18n-version/version-switcher.js";
 import { GitHub as GitHubIcon } from "../icons/index.js";
@@ -81,7 +89,7 @@ function Header(props) {
                   "button",
                   {
                     type: "button",
-                    class: "px-hsp-md py-vsp-2xs text-small font-medium text-muted hover:underline cursor-pointer",
+                    class: "px-hsp-md py-vsp-2xs text-small font-medium text-muted hover:text-accent hover:underline focus-visible:text-accent focus-visible:underline cursor-pointer",
                     "data-nav-more-toggle": true,
                     "aria-expanded": "false",
                     children: "\xB7\xB7\xB7"
@@ -177,7 +185,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
               "aria-expanded": "false",
               class: [
                 "flex items-center gap-x-hsp-xs px-hsp-md py-vsp-2xs text-small font-medium transition-colors",
-                isActive ? "bg-fg text-bg" : "text-muted hover:underline focus:underline"
+                isActive ? NAV_TOP_ACTIVE.join(" ") : NAV_TOP_INACTIVE.join(" ")
               ].join(" "),
               children: [
                 label,
@@ -186,7 +194,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
                   {
                     class: [
                       "h-[0.5rem] w-[0.5rem] shrink-0",
-                      isActive ? "text-bg" : "text-muted"
+                      isActive ? NAV_CHEVRON_ACTIVE.join(" ") : NAV_CHEVRON_INACTIVE.join(" ")
                     ].join(" "),
                     fill: "none",
                     viewBox: "0 0 24 24",
@@ -216,8 +224,8 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
                 href: childHref,
                 "data-active": childActive ? "" : void 0,
                 class: [
-                  "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline",
-                  childActive ? "font-bold text-accent" : "text-fg"
+                  "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline",
+                  childActive ? NAV_CHILD_ACTIVE.join(" ") : NAV_CHILD_INACTIVE.join(" ")
                 ].join(" "),
                 children: childLabel
               }
@@ -235,7 +243,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
       "data-nav-item": true,
       class: [
         "px-hsp-md py-vsp-2xs text-small font-medium transition-colors shrink-0",
-        isActive ? "bg-fg text-bg" : "text-muted hover:underline focus:underline"
+        isActive ? NAV_TOP_ACTIVE.join(" ") : NAV_TOP_INACTIVE.join(" ")
       ].join(" "),
       children: label
     }

package/dist/header/nav-class-tokens.d.ts

@@ -0,0 +1,12 @@
+export declare const NAV_TOP_ACTIVE: readonly string[];
+export declare const NAV_TOP_INACTIVE: readonly string[];
+export declare const NAV_CHEVRON_ACTIVE: readonly string[];
+export declare const NAV_CHEVRON_INACTIVE: readonly string[];
+export declare const NAV_CHILD_ACTIVE: readonly string[];
+export declare const NAV_CHILD_INACTIVE: readonly string[];
+export declare const NAV_MENU_PARENT: readonly string[];
+export declare const NAV_MENU_PARENT_ACTIVE_SUFFIX: readonly string[];
+export declare const NAV_MENU_PLAIN: readonly string[];
+export declare const NAV_MENU_PLAIN_ACTIVE_SUFFIX: readonly string[];
+export declare const NAV_MENU_CHILD_ACTIVE: readonly string[];
+export declare const NAV_MENU_CHILD_INACTIVE: readonly string[];

package/dist/header/nav-class-tokens.js

@@ -0,0 +1,80 @@
+const NAV_TOP_ACTIVE = ["bg-fg", "text-bg"];
+const NAV_TOP_INACTIVE = [
+  "text-muted",
+  "hover:text-accent",
+  "hover:underline",
+  "focus:underline",
+  "focus:text-accent"
+];
+const NAV_CHEVRON_ACTIVE = ["text-bg"];
+const NAV_CHEVRON_INACTIVE = ["text-muted"];
+const NAV_CHILD_ACTIVE = ["font-bold", "text-accent"];
+const NAV_CHILD_INACTIVE = [
+  "text-fg",
+  "hover:text-accent",
+  "focus-visible:text-accent"
+];
+const MENU_ROW_BASE = [
+  "block",
+  "px-hsp-md",
+  "py-vsp-2xs",
+  "text-small"
+];
+const MENU_CHILD_BASE = [
+  "block",
+  "pl-hsp-xl",
+  "pr-hsp-md",
+  "py-vsp-2xs",
+  "text-small"
+];
+const MENU_ROW_RESTING = [
+  "hover:bg-accent/10",
+  "hover:underline",
+  "focus-visible:underline",
+  "focus-visible:text-accent",
+  "text-fg",
+  "hover:text-accent"
+];
+const NAV_MENU_PARENT = [
+  ...MENU_ROW_BASE,
+  "font-bold",
+  ...MENU_ROW_RESTING
+];
+const NAV_MENU_PARENT_ACTIVE_SUFFIX = ["text-accent"];
+const NAV_MENU_PLAIN = [
+  ...MENU_ROW_BASE,
+  ...MENU_ROW_RESTING
+];
+const NAV_MENU_PLAIN_ACTIVE_SUFFIX = [
+  ...NAV_CHILD_ACTIVE
+];
+const NAV_MENU_CHILD_ACTIVE = [
+  ...MENU_CHILD_BASE,
+  ...NAV_CHILD_ACTIVE,
+  "hover:bg-accent/10",
+  "hover:underline",
+  "focus-visible:underline"
+];
+const NAV_MENU_CHILD_INACTIVE = [
+  ...MENU_CHILD_BASE,
+  "text-fg",
+  "hover:bg-accent/10",
+  "hover:text-accent",
+  "hover:underline",
+  "focus-visible:underline",
+  "focus-visible:text-accent"
+];
+export {
+  NAV_CHEVRON_ACTIVE,
+  NAV_CHEVRON_INACTIVE,
+  NAV_CHILD_ACTIVE,
+  NAV_CHILD_INACTIVE,
+  NAV_MENU_CHILD_ACTIVE,
+  NAV_MENU_CHILD_INACTIVE,
+  NAV_MENU_PARENT,
+  NAV_MENU_PARENT_ACTIVE_SUFFIX,
+  NAV_MENU_PLAIN,
+  NAV_MENU_PLAIN_ACTIVE_SUFFIX,
+  NAV_TOP_ACTIVE,
+  NAV_TOP_INACTIVE
+};