@takazudo/zudo-doc 3.2.0 → 3.3.0

package/dist/plugins/routes.js

@@ -41,6 +41,27 @@ function deriveRoutes(settings) {
   }
   return routes;
 }
+function resolveHostModuleOverride(projectRoot, settingName, settingValue, hints) {
+  if (typeof settingValue === "string" && settingValue.trim() === "") {
+    throw new Error(
+      `zudo-doc: settings.${settingName} is set to an empty string \u2014 set it to a project-root-relative module path (e.g. "${hints.examplePath}") or remove the setting.`
+    );
+  }
+  const modulePath = typeof settingValue === "string" ? settingValue : void 0;
+  if (!modulePath) return void 0;
+  const resolved = join(projectRoot, modulePath).split("\\").join("/");
+  if (!existsSync(resolved)) {
+    throw new Error(
+      `zudo-doc: settings.${settingName} is set to "${modulePath}", which resolves to "${resolved}" \u2014 that file does not exist. Create it (must export a named \`${hints.mustExport}\`) or remove the setting.`
+    );
+  }
+  if (!statSync(resolved).isFile()) {
+    throw new Error(
+      `zudo-doc: settings.${settingName} is set to "${modulePath}", which resolves to "${resolved}" \u2014 that path is a directory, not a module file. Point it at a module file (e.g. "${hints.examplePath}") or remove the setting.`
+    );
+  }
+  return resolved;
+}
 const plugin = definePlugin({
   name: "@takazudo/zudo-doc/plugins/routes",
   setup(ctx) {
@@ -59,31 +80,34 @@ const plugin = definePlugin({
       })};
 `
     );
-    if (typeof settings.chromeBindingsModule === "string" && settings.chromeBindingsModule.trim() === "") {
-      throw new Error(
-        'zudo-doc: settings.chromeBindingsModule is set to an empty string \u2014 set it to a project-root-relative module path (e.g. "./src/chrome-bindings.tsx") or remove the setting.'
-      );
-    }
-    const chromeBindingsModule = typeof settings.chromeBindingsModule === "string" ? settings.chromeBindingsModule : void 0;
-    let chromeBindingsAbsPath;
-    if (chromeBindingsModule) {
-      const resolved = join(ctx.projectRoot, chromeBindingsModule).split("\\").join("/");
-      if (!existsSync(resolved)) {
-        throw new Error(
-          `zudo-doc: settings.chromeBindingsModule is set to "${chromeBindingsModule}", which resolves to "${resolved}" \u2014 that file does not exist. Create it (must export a named \`chromeBindings: ChromeHostBindings\`) or remove the setting.`
-        );
+    const chromeBindingsAbsPath = resolveHostModuleOverride(
+      ctx.projectRoot,
+      "chromeBindingsModule",
+      settings.chromeBindingsModule,
+      {
+        examplePath: "./src/chrome-bindings.tsx",
+        mustExport: "chromeBindings: ChromeHostBindings"
       }
-      if (!statSync(resolved).isFile()) {
-        throw new Error(
-          `zudo-doc: settings.chromeBindingsModule is set to "${chromeBindingsModule}", which resolves to "${resolved}" \u2014 that path is a directory, not a module file. Point it at a module file (e.g. "./src/chrome-bindings.tsx") or remove the setting.`
-        );
-      }
-      chromeBindingsAbsPath = resolved;
-    }
+    );
     ctx.addVirtualModule(
       "virtual:zudo-doc-chrome-bindings",
       () => chromeBindingsAbsPath ? `export { chromeBindings } from ${JSON.stringify(chromeBindingsAbsPath)};
 ` : `export const chromeBindings = {};
+`
+    );
+    const designTokenPanelConfigAbsPath = resolveHostModuleOverride(
+      ctx.projectRoot,
+      "designTokenPanelConfigModule",
+      settings.designTokenPanelConfigModule,
+      {
+        examplePath: "./src/design-token-panel-config.ts",
+        mustExport: 'buildDesignTokenPanelConfig(mode: "light" | "dark")'
+      }
+    );
+    ctx.addVirtualModule(
+      "virtual:zudo-doc-design-token-panel-config",
+      () => designTokenPanelConfigAbsPath ? `export { buildDesignTokenPanelConfig } from ${JSON.stringify(designTokenPanelConfigAbsPath)};
+` : `export { buildDesignTokenPanelConfig } from "@takazudo/zudo-doc/design-token-panel-config";
 `
     );
     const require2 = createRequire(import.meta.url);

package/dist/preset.d.ts

@@ -105,6 +105,15 @@ export interface PresetSettings {
      * package-default stubs (byte-identical to today).
      */
     chromeBindingsModule?: string;
+    /**
+     * Project-root-relative path to a host module exporting a named
+     * `buildDesignTokenPanelConfig(mode: "light" | "dark")` (#2658). Only
+     * consumed when `packageOwnedRoutes` is on and `designTokenPanel` is true
+     * — see `settings.ts` for the full contract. Omit to use the package
+     * default design-token-panel config (derived from the shipped token
+     * manifest + bundled color schemes).
+     */
+    designTokenPanelConfigModule?: string;
     /** Gate for the `/docs/tags` + `/docs/tags/[tag]` injected routes. */
     docTags?: boolean;
     /** Gate for the SSR `/api/ai-chat` injected route (`prerender: false`). */

package/dist/routes/_chrome.js

@@ -1,9 +1,10 @@
 import { routeCtx } from "./_context.js";
 import { createChrome } from "../chrome/index.js";
 import { DocHistory } from "../doc-history/index.js";
+import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
 import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
 const chrome = createChrome(routeCtx, {
-  DocHistory,
+  ...defineChromeBindings({ DocHistory }),
   ...chromeBindings
 });
 const {

package/dist/safelist.css

@@ -1,2 +1,2 @@
 /* generated by gen-safelist.mjs — do not edit by hand */
-@source inline("-link -mb-px -ml-hsp-sm -noscript -open -translate-x-full 2xl:w-[24px] [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [data-admonition] [data-kbd-shortcut] [doc-history-meta] [doc-history] [doc-layout] [llms-txt] [zudo-doc] a a2 abbr about above absent absolute accent accent:accent- across activated active actual added admonition admonition- admonition-body admonition-title admonition/callout after after-breadcrumb after-content after-navigate after-sidebar after-title against agent agents ai-chat ai-chat-md ai-chat-trigger alert align-top all allow-same-origin allow-scripts alone already already-executed already-multiline already-picked an anchor anchored and and/or animate-spin announce antialiased any application/json application/xml applies apply-css-vars approach are area arg aria-atomic aria-busy aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow arm arms array arrows article as asc aside aspect-[1200/630] aspect-square asset- assets assistant async at attach attribute attributes authored auto autogenerated available avoid await away b back backdrop:bg-bg/30 backdrop:bg-bg/80 backdrop:bg-overlay/60 backdrop:z-modal-backdrop background background-color backtick backticks baked banner bare base base64 base:base- based baseline batch be because before below best between bg bg-[#fff] bg-accent bg-bg bg-chat-assistant-bg bg-chat-user-bg bg-code-bg bg-fg bg-info/10 bg-info/5 bg-muted bg-overlay/30 bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blank blanks blob block blockquote blocks blur body body-end-components body-end-scripts bold boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-bg/30 border-collapse border-danger border-dashed border-fg border-info/30 border-l border-l-0 border-l-[3px] border-left-width border-muted border-none border-r border-radius border-solid border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 border-width border-y both bottom-vsp-xl boundaries box-border br brand breadcrumb:end breadcrumb:start break-words browser browsers btn bug build bundler but button buttons by bypassed byte-identical bytes cached call caller calls can cancellation cannot canonical canvas caption card card-grid carry cases cat-nav- catch category catppuccin-latte caught caution center center/contain ch chains change changed changelog changelogs changes checkbox child chrome ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars clearing click client client-router client-side clip clobbering close closed closing code code-block-sr-announce code-group code-group-panel col col-resize colgroup collapses collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colorization colors column comma command commands comment commit compare component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher compute computed concrete configuration configure configured confuse connect const construction consumer consumes container containers containing content content-admonition content-link content-type content-wrapper:end content-wrapper:start contents context controller controls converts copy corners correct correctly corrupt count covered covers cp crashes created cross-component crumb- cs css ctx cur current cursor-not-allowed cursor-pointer custom danger dark data data-active data-admonition data-base data-close-search data-current-locale data-default-locale data-group-id data-header data-header-logo data-header-nav data-header-right data-kbd-shortcut data-language-switcher data-loading-index data-mermaid-enlarge-ready data-mermaid-rendered data-mermaid-src data-nav-active data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-no-results data-open-search data-pan-active data-processed data-result-count-template data-search-count data-search-count-narrow data-search-dialog data-search-input data-search-placeholder data-search-results data-search-unavailable data-sidebar-hidden data-sidebar-resizer data-site-nav data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-theme/style data-trailing-slash data-variant data-version-banner data-version-latest data-version-menu data-version-rewire data-version-slug data-version-switcher data-version-toggle data-version-trigger-label data-zd-nosidebar data-zd-toc data-zd-wide data-zfb-transition-persist dd decimal declare decoration decoration-muted default defaults del delegated dependency depth desc description design design-token design-token-panel design-token-trigger desktop desktop-sidebar desktop-sidebar-toggle desktop-sidebar-toggle-island destructive detach detached details detected deterministic develop dfn diagram diagrams dialog dieser diff diff-line-added diff-line-content diff-line-empty diff-line-num diff-line-removed diff-row dir directly directories directory disabled disabled:opacity-50 disc display:none dist distinct div dl do doc doc-card- doc-content-band doc-history doc-history-generate doc-history-panel doc-history-trigger doc-page doc-pager doc-prose doc-title docs docs- docs-v- document document-level documented does double-registration drag draggable drop dropdown dropdown-child dropdown-parent dropdowns dt duration-150 duration-200 during dynamically e2e each ease-in-out edge eject ejected el element elements els else em embedded emit emitting empty empty/undefined en enable end enlarged entire entities entries entry error escape escaped even eventually every exactly excerpt excludes existing exists exit expected export extends factories failed faithful fall fallback fallbacks falls false family fast feature feed fg fields fieldset figcaption figure file fill fills finally find fire fires first fixed fixed-width fixtures flag flash flat flex flex-1 flex-col flex-wrap flip flipping flips flush-left focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:border-accent focus:outline-none focus:underline font font-bold font-family font-medium font-mono font-semibold font-weight footer footer- for form format found free fresh from frontmatter frontmatter-preview frozen fs-extra full fully function further g gap-[0.3em] gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-md gap-hsp-sm gap-hsp-xl gap-hsp-xs gap-vsp-2xs gap-vsp-lg gap-vsp-md gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps gate generate generated generation genuine geometry get github github-link go got graph gray-matter grid grid-cols-1 grid-cols-2 group group-focus-visible:text-accent group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-accent group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.625rem] h-[0.875rem] h-[1.125rem] h-[1.25rem] h-[1.575rem] h-[14px] h-[1em] h-[1lh] h-[2rem] h-[3.5rem] h-[3rem] h-[90vh] h-[calc(100%-3rem)] h-[calc(100vh-3.5rem)] h-dvh h-full h-icon-lg h-icon-md h-icon-sm h-icon-xs h1 h1s h2 h2s h3 h4 h5 h6 half hand hand-copied handle handled handler handlers has hash-link have head head-links head-scripts header header- header-call:end header-call:start heading heading-h2 heading-h3 heading-h4 headings height here hex hidden highlight highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:bg-surface hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr href hrefs html i i18n/theme. i2 i3 i4 icon identical idle idx if iframe image image-enlarge image/png img implementation import important imports in inactive inbox includes index info inherit inherited initial initialised injected inline inline-block inline-flex inner input input-clear ins inset-0 inside install instance instanceof instead instructions intended intent into invalid inverse inversion invoke is issues it italic item item- items items-baseline items-center items-start its itself javascript justify-between justify-center justify-end justify-start katex kbd keep keeps kept keyboard keyboard-shortcut keydown keystroke keywords khroma label landing language-switcher last:border-b-0 later launch layout leading-relaxed leading-snug leading-tight leaf- leak leaves left left-0 left:calc legend legitimate letter-spacing lg lg:block lg:border lg:border-fg lg:border-solid lg:flex lg:flex-col lg:flex-row lg:gap-hsp-xl lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:h-[90vh] lg:hidden lg:justify-start lg:m-auto lg:max-h-[90vh] lg:max-w-[52.5rem] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl lg:text-left lg:w-[90vw] lg:w-[clamp(16rem,25%,22rem)] li li2 library light like likely line line/statement linger link link- links list-disc list-none listener literal literals lives llms llms-txt load local locale locales log longest-match look lostpointercapture lower luminance m m-0 m21 m6 main major make malformed malicious maps mark marks matches matching math math-display math-inline max max-h-[80vh] max-h-[85vh] max-h-[90vh] max-h-full max-h-none max-w-[46rem] max-w-[85%] max-w-[85vw] max-w-[90vw] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none max-width may mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs measures measuring mechanism menu merged mermaid message messages meta meta-knob metadata migration min-h-[60vh] min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] minifier minor mirror mirrors missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode module mounted mouseenter mouseleave mr-hsp-sm mt-0 mt-vsp-2xl mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-md mt-vsp-sm mt-vsp-xl must mutates mutation mutations muted mx-auto my-vsp-lg my-vsp-md name named native nav nav-active nav-card- nav/doc navigating navigation navigations near needs nested new newly-swapped next no no-enlarge no-op no-repeat no-underline node node:buffer node:fs node:fs/promises node:module node:path nodes nofollow noindex non-empty non-light-dark non-persisted none noopener noreferrer normal noscript not not-object notable note notes now null number numeric object object-contain observe observer occurred of off og:description og:image og:image:alt og:image:height og:image:width og:title og:type og:url oklch ol old older on once one only onto opacity-60 open open/close option or original other others out outline-none over overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto overwrite own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl package package-owned packages padding page page-loading page-loading-overlay page-loading-spinner page-navigate-end page-title pages pages/. paint paint-and-read palette pan panel panels paren-balance-aware parent parse parsed pass passed passes patch path paths pattern pb-[50vh] pb-vsp-md pb-vsp-xl pb-vsp-xs per per-link permanently persisted pi pick picked picks picocolors pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place placeholder placeholder:text-muted plain plural plus pnpm pointer-events-none pointercancel pointerdown pointermove pointerup polite polygon polyline populates port position position:fixed pr-[4px] pr-hsp-lg pr-hsp-md pr-hsp-sm pr-hsp-xl pre pre-lowercased preact preact/compat preact/hooks preact/jsx-runtime preconnect prefix preload pres preserving print produce produced produces production project project-root-relative properties property props prose provided proxy pt-[0.15rem] pt-[2px] pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-2xl px-hsp-2xs px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-[2px] py-[calc(var(--spacing-vsp-xs)+0.15rem)] py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-lg py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q query question r radius ramp range raw re-encode/decode re-querying re-render re-renders re-run re-running re-selects reach reached reaches read reading ready real real-value received receives recorded recovers redefine ref- references refetch refreshes regenerate regenerates regex reinit reinits relative release reload relying remove removed render rendered renders reorder repaint repair repeated repeating replaced replaces repopulate requires reserved reset resize resize-x resolve resolved resolves response restore restores result result-click results results-area retry return returns revision revisions rewrite right right- right-0 ro robots role roles root rotate-180 rotate-90 round round-trip rounded rounded-[0.75rem] rounded-bl-[0.25rem] rounded-bl-[1rem] rounded-br-[0.25rem] rounded-br-[1rem] rounded-full rounded-lg rounded-t-[1rem] rounds route router routes routes-src running runs runtime s safe safer same same-locale samp scale scanned schema-mismatch schema-missing scheme scored script script- script-eval script-evaluation script-injection scripts scroll scrollbar scrolled scrollend search search-index section section- see select select-none selection-bg selection-fg self self-start semibold sentinel separator serialised serialize server server-rendered set sets setting setup shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shape share shared sharing shiki ship shipped ships short shortcut should show shown shrink-0 sidebar sidebar- sidebar-toggle-island sidebar-tree-island signal similarity single single-line singular site-search site-tree-nav-island sitemap- sites size skill skills skipping skips slash slug sm:border sm:border-muted sm:flex-row sm:grid-cols-2 sm:h-auto sm:items-center sm:justify-between sm:max-h-[80vh] sm:max-w-[52rem] sm:mx-auto sm:my-[10vh] sm:rounded-lg small smooth snapshot snapshots so soft soft-nav solid some somehow source sources space-y-vsp-2xs spacing span spans spec specifier specifiers splitter square sr-only src stale start state state:state- status stay staying sticky still stop stored stray string strings strip stripe stroke-linecap stroke-linejoin stroke-width strong stronger style style-attribute styled styles stylesheet sub subagents subsequent success successful summary sup surface surfaces survives svg swap swapped swaps synchronous synchronously syntactically syntect t tab tab-item tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag tag- tag-item- tags tags:audit take tbody td temp-element template temporary temporary-element terminal terms test-results tested text text-accent text-bg text-body text-caption text-center text-chat-assistant-text text-chat-user-text text-code-fg text-danger text-decoration text-display text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-right text-small text-title text-warning text/plain textarea tfoot th that the thead their them theme theme-color theme-toggle theme/token then there these they this through throw tighten time tip title to toc toggle toggle-ai-chat toggle-design-token-panel toggles token tokens tolerates too toolbar top-0 top-[3.5rem] top-full top-level total touches tp tr tracked tracking-wider trade-off transition transition-[background,color,border-color] transition-[left,color] transition-colors transition-transform translate-x-0 translations transparent treats tree tree-child- tree-item- tree-top- trigger trigger:ai-chat trigger:design-token-panel triggers true truncate truncated try turn twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two type typography u ul unavailable unchanged undefined under underline underlines understand unit-tested unknown unmaintained unobserve unreadable unrelated unreleased unset up uppercase usage use used user uses utf-8 utf8 utilities utility v v1 v2 val valid value value-reader values var variable variant verbatim version version- version-menu version-switcher vertical via video viewport virtual:zudo-doc-chrome-bindings virtual:zudo-doc-route-context visible vitesse-dark vocabulary w w-1/2 w-[0.5rem] w-[0.625rem] w-[0.875rem] w-[1.125rem] w-[1.575rem] w-[1.5rem] w-[1.75rem] w-[14px] w-[16px] w-[16rem] w-[18px] w-[1em] w-[280px] w-[2rem] w-[320px] w-[90vw] w-[var(--zd-sidebar-w)] w-dvw w-full w-icon-lg w-icon-md w-icon-sm w-icon-xs want warning was watching wbr wbr- we website weight went were what when where whereas whether which while whitespace-nowrap whitespace-pre whole wide-gamut width will with without word working worktrees would wrap wrapper wrappers written wrong wrote xl:flex xl:hidden y-scrollbar yet you your z-dropdown z-local-1 z-modal z-modal-backdrop z-sidebar z-toolbar zd-content zd-desktop-sidebar-toggle zd-doc-content-band zd-enlarge-btn zd-enlarge-dialog zd-enlarge-dialog-close zd-enlargeable zd-html-preview-code zd-mermaid-dialog zd-mermaid-enlargeable zd-mermaid-tool-btn zd-mermaid-toolbar zd-mermaid-transform zd-mermaid-viewport zd-sidebar-content-wrapper zd-sidebar-open zfb zfb:after-swap zfb:before-preparation zod zoom zudo-doc-design-tokens/v1 zudo-doc-design-tokens/v2 zudo-doc-design-tokens/v3 zudo-doc-sidebar-visible zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge");
+@source inline("-link -mb-px -ml-hsp-sm -noscript -open -translate-x-full 2xl:w-[24px] [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [data-admonition] [data-kbd-shortcut] [doc-history-meta] [doc-history] [doc-layout] [llms-txt] [zudo-doc] a a2 abbr about above absent absolute accent accent- accent:accent- across activated active actual added admonition admonition- admonition-body admonition-title admonition/callout after after-breadcrumb after-content after-navigate after-sidebar after-title against agent agents ai-chat ai-chat-md ai-chat-trigger alert align-top all allow-same-origin allow-scripts alone already already-executed already-multiline already-picked an anchor anchored and and/or animate-spin announce ansehen antialiased any anywhere anzeigen application/json application/xml applies apply-css-vars approach are area arg aria-atomic aria-busy aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow arm arms array arrows article as asc aside aspect-[1200/630] aspect-square asset- assets assistant async at attach attribute attributes auf authored auto autogenerated available avoid await away b back backdrop:bg-bg/30 backdrop:bg-bg/80 backdrop:bg-overlay/60 backdrop:z-modal-backdrop background background-color backtick backticks baked banner bare base base- base64 base:base- based baseline batch be bearbeiten because been before below best between bg bg-[#fff] bg-accent bg-bg bg-chat-assistant-bg bg-chat-user-bg bg-code-bg bg-fg bg-info/10 bg-info/5 bg-muted bg-overlay/30 bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blank blanks blob block blockquote blocks blur body body-end-components body-end-scripts bold boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-bg/30 border-collapse border-danger border-dashed border-fg border-info/30 border-l border-l-0 border-l-[3px] border-left-width border-muted border-none border-r border-radius border-solid border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 border-width border-y both bottom-vsp-xl boundaries box-border br brand breadcrumb:end breadcrumb:start break-words browser browsers btn bug build bundler but button buttons by bypassed byte-identical bytes cached call caller calls can cancellation cannot canonical canvas caption card card-grid carry cases cat-nav- catch category catppuccin-latte caught caution center center/contain ch chains change changed changelog changelogs changes checkbox child chrome ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars clearing click client client-router client-side clip clobbering close closed closing code code-block-sr-announce code-group code-group-panel col col-resize colgroup collapses collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colorization colors column comma command commands comment commit compare component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher compute computed concrete configuration configure configured confuse connect const construction consumer consumes container containers containing content content-admonition content-link content-type content-wrapper:end content-wrapper:start contents context controller controls converts copy corners correct correctly corrupt count covered covers cp crashes created cross-component crumb- cs css ctx cur current cursor-not-allowed cursor-pointer custom danger dark data data-active data-admonition data-base data-close-search data-current-locale data-default-locale data-find-active data-find-match data-group-id data-header data-header-logo data-header-nav data-header-right data-kbd-shortcut data-language-switcher data-loading-index data-mermaid-enlarge-ready data-mermaid-rendered data-mermaid-src data-nav-active data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-no-results data-open-search data-pan-active data-processed data-result-count-template data-search-count data-search-count-narrow data-search-dialog data-search-input data-search-placeholder data-search-results data-search-unavailable data-sidebar-hidden data-sidebar-resizer data-site-nav data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-theme/style data-trailing-slash data-variant data-version-banner data-version-latest data-version-menu data-version-rewire data-version-slug data-version-switcher data-version-toggle data-version-trigger-label data-zd-nosidebar data-zd-toc data-zd-wide data-zfb-transition-persist dd decimal declare decoration decoration-muted default default-transition-duration defaults del delegated delete dependency depth der desc description design design-token design-token-panel design-token-trigger desktop desktop-sidebar desktop-sidebar-toggle desktop-sidebar-toggle-island destructive detach detached details detected deterministic develop dfn diagram diagrams dialog die dieser diff diff-line-added diff-line-content diff-line-empty diff-line-num diff-line-removed diff-row dir directly directories directory disabled disabled:opacity-50 disc display:none dist distinct div dl do doc doc-card- doc-content-band doc-history doc-history-generate doc-history-panel doc-history-trigger doc-page doc-pager doc-prose doc-title docs docs- docs-v- document document-level documentation documented does double-registration draft drag draggable drop dropdown dropdown-child dropdown-parent dropdowns dt duration-150 duration-200 during dynamically e2e each ease-in-out edge einer eject ejected el element elements els else em embedded emit emitting empty empty/undefined en enable end enlarged entire entities entries entry error escape escaped even eventually every exactly excerpt excludes existing exists exit expected export extends f factories failed faithful fall fallback fallbacks falling falls false family fast feature feed fg fields fieldset figcaption figure file fill fills finally find find-match find-match-active fire fires first fixed fixed-width fixtures flag flash flat flex flex-1 flex-col flex-wrap flip flipping flips flush-left focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:border-accent focus:outline-none focus:underline font font-bold font-family font-medium font-mono font-sans font-scale font-semibold font-size font-weight font-weight-bold font-weight-medium font-weight-normal font-weight-semibold footer footer- for form format found free fresh from frontmatter frontmatter-preview frozen fs-extra full fully function further g gap-[0.3em] gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-md gap-hsp-sm gap-hsp-xl gap-hsp-xs gap-vsp-2xs gap-vsp-lg gap-vsp-md gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps gate geladen2026 generate generated generation genuine geometry get github github-dark github-link go got graph gray-matter grid grid-cols-1 grid-cols-2 group group-focus-visible:text-accent group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-accent group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.625rem] h-[0.875rem] h-[1.125rem] h-[1.25rem] h-[1.575rem] h-[14px] h-[1em] h-[1lh] h-[2rem] h-[3.5rem] h-[3rem] h-[90vh] h-[calc(100%-3rem)] h-[calc(100vh-3.5rem)] h-dvh h-full h-icon-lg h-icon-md h-icon-sm h-icon-xs h1 h1s h2 h2s h3 h4 h5 h6 half hand hand-copied handle handled handler handlers has hash-link have head head-links head-scripts header header- header-call:end header-call:start heading heading-h2 heading-h3 heading-h4 headings height here hex hidden hierarchical highlight highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:bg-surface hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr href hrefs hsp hsp-2xl hsp-2xs hsp-lg hsp-md hsp-sm hsp-xl hsp-xs html i i18n/theme. i2 i3 i4 icon icon-lg icon-md icon-sm icon-xs identical idle idx if iframe image image-enlarge image-overlay-inset image/png img implementation import important imports in inactive inbox includes index index2026 info inherit inherited initial initialised injected inline inline-block inline-flex inner input input-clear ins inset-0 inside install instance instanceof instead instructions intended intent into invalid inverse inversion invoke is issues it italic item item- items items-baseline items-center items-start its itself javascript justify-between justify-center justify-end justify-start katex kbd keep keeps kept keyboard keyboard-shortcut keydown keystroke keywords khroma kopieren label landing language-switcher last:border-b-0 later latest launch layout leading-normal leading-relaxed leading-snug leading-tight leaf- leak leaves left left-0 left:calc legend legitimate length letter-spacing lg lg:block lg:border lg:border-fg lg:border-solid lg:flex lg:flex-col lg:flex-row lg:gap-hsp-xl lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:h-[90vh] lg:hidden lg:justify-start lg:m-auto lg:max-h-[90vh] lg:max-w-[52.5rem] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl lg:text-left lg:w-[90vw] lg:w-[clamp(16rem,25%,22rem)] li li2 library light like likely line line-height line/statement linger link link- links list-disc list-none listener literal literals lives llms llms-txt load local local-1 local-2 local-3 locale locales log longest-match look lostpointercapture lower luminance m m-0 m21 m6 main major make malformed malicious maps mark marks matches matching math math-display math-inline max max-h-[80vh] max-h-[85vh] max-h-[90vh] max-h-full max-h-none max-w-[46rem] max-w-[85%] max-w-[85vw] max-w-[90vw] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none max-width may mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs measures measuring mechanism menu merged mermaid message messages meta meta-knob metadata migration min-h-[60vh] min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[3rem] min-w-[8rem] minifier minor mirror mirrors missing mit ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod modal modal-backdrop mode module monospace most mounted mouseenter mouseleave mr-hsp-sm ms mt-0 mt-vsp-2xl mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-md mt-vsp-sm mt-vsp-xl must mutates mutation mutations muted mx-auto my-vsp-lg my-vsp-md name named native nav nav-active nav-card- nav/doc navigating navigation navigations near needs nested neutral new newly-swapped next nicht no no-enlarge no-op no-repeat no-underline noch node node:buffer node:fs node:fs/promises node:module node:path nodes nofollow noindex non-empty non-light-dark non-persisted none noopener noreferrer normal noscript not not-object notable note notes now null number numeric object object-contain observe observer occurred of off og:description og:image og:image:alt og:image:height og:image:width og:title og:type og:url oklch ol old older on once one only onto opacity-60 open open/close option or original other others out outline-none over overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto overwrite own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl package package-owned packages padding page page-loading page-loading-overlay page-loading-spinner page-navigate-end page-title pages pages/. paint paint-and-read palette pan panel panels paren-balance-aware parent parse parsed pass passed passes patch path paths pattern pb-[50vh] pb-vsp-md pb-vsp-xl pb-vsp-xs per per-link permanently persisted pi pick picked picks picocolors pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place placeholder placeholder:text-muted plain plural plus pnpm pointer-events-none pointercancel pointerdown pointermove pointerup polite polygon polyline popover populates port position position:fixed pr-[4px] pr-hsp-lg pr-hsp-md pr-hsp-sm pr-hsp-xl pre pre-lowercased preact preact/compat preact/hooks preact/jsx-runtime preconnect prefix preload pres preserving previously print produce produced produces production project project-root-relative properties property props prose provided proxy pt-[0.15rem] pt-[2px] pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-2xl px-hsp-2xs px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-[2px] py-[4px] py-[calc(var(--spacing-vsp-xs)+0.15rem)] py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-lg py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q query question r radius radius-full radius-lg ramp range raw re-encode/decode re-querying re-render re-renders re-run re-running re-selects reach reached reaches read reading ready real real-value received receives recorded recovers redefine ref- references refetch refreshes regenerate regenerates regex reinit reinits relative release released reload relying rem remove removed render rendered renders reorder repaint repair repeated repeating replaced replaces repopulate repository requires reserved reset resize resize-x resolve resolved resolves response restore restores result result-click results results-area retry return returns revision revisions rewrite right right- right-0 ro robots role roles root rotate-180 rotate-90 round round-trip rounded rounded-[0.75rem] rounded-bl-[0.25rem] rounded-bl-[1rem] rounded-bl-lg rounded-br-[0.25rem] rounded-br-[1rem] rounded-full rounded-lg rounded-t-[1rem] rounds route router routes routes-src running runs runtime s safe safer same same-locale samp sans-serif scale scanned schema-mismatch schema-missing scheme scored script script- script-eval script-evaluation script-injection scripts scroll scrollbar scrolled scrollend search search-index section section- see sehen select select-none selection-bg selection-fg self self-start semantic semibold sentinel separator serialised serialize server server-rendered set sets setting setup shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shadow-md shape share shared sharing shiki ship shipped ships short shortcut should show shown shrink-0 sidebar sidebar- sidebar-toggle-island sidebar-tree-island sidebar-w signal similarity single single-line singular site-search site-tree-nav-island sitemap- sites size skill skills skipping skips slash slug sm:border sm:border-muted sm:flex-row sm:grid-cols-2 sm:h-auto sm:items-center sm:justify-between sm:max-h-[80vh] sm:max-w-[52rem] sm:mx-auto sm:my-[10vh] sm:rounded-lg small smooth snapshot snapshots so soft soft-nav solid some somehow source sources space-y-vsp-2xs spacing spacing-0 spacing-px span spans spec specifier specifiers splitter square sr-only src stable stale standalone start state state- state:state- status stay staying sticky still stop stored stray strict string strings strip stripe stroke-linecap stroke-linejoin stroke-width strong stronger style style-attribute styled styles stylesheet sub subagents subsequent success successful summary sup surface surfaces survives svg swap swapped swaps synchronous synchronously syntactically syntect t tab tab-item tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag tag- tag-item- tagged tags tags:audit take tbody td temp-element template temporary temporary-element terminal terms test-results tested text text-accent text-bg text-body text-caption text-center text-chat-assistant-text text-chat-user-text text-code-fg text-danger text-decoration text-display text-fg text-fg/60 text-heading text-info text-left text-micro text-muted text-muted/50 text-right text-scale-2xl text-scale-2xs text-scale-lg text-scale-md text-scale-sm text-scale-xl text-scale-xs text-small text-title text-warning text/plain textarea tfoot th that the thead their them theme theme-color theme-toggle theme/token then there these they this through throw tighten time tip title to toast toc toggle toggle-ai-chat toggle-design-token-panel toggles token tokens tolerates too toolbar tooltip top-0 top-[3.5rem] top-full top-level total touches tp tr tracked tracking-wider trade-off transition transition-[background,color,border-color] transition-[left,color] transition-colors transition-transform translate-x-0 translated translations transparent treats tree tree-child- tree-item- tree-top- trigger trigger:ai-chat trigger:design-token-panel triggers true truncate truncated try turn twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two type typography u ul umschalten unavailable unchanged und undefined under underline underlines understand unit-tested unknown unlisted unmaintained unobserve unreadable unrelated unreleased unset up up-to-date uppercase usage use used user uses utf-8 utf8 utilities utility v v1 v2 val valid value value-reader values var variable variant verbatim version version- version-menu version-switcher versions vertical via video viewing viewport virtual:zudo-doc-chrome-bindings virtual:zudo-doc-design-token-panel-config virtual:zudo-doc-route-context visible vitesse-dark vocabulary von vsp vsp-2xl vsp-2xs vsp-3xs vsp-lg vsp-md vsp-sm vsp-xl vsp-xs w w-1/2 w-48 w-[0.5rem] w-[0.625rem] w-[0.875rem] w-[1.125rem] w-[1.575rem] w-[1.5rem] w-[1.75rem] w-[14px] w-[16px] w-[16rem] w-[18px] w-[1em] w-[280px] w-[2rem] w-[320px] w-[90vw] w-[var(--zd-sidebar-w)] w-dvw w-full w-icon-lg w-icon-md w-icon-sm w-icon-xs want warn warning was watching wbr wbr- we website weight went were what when where whereas whether which while whitespace-nowrap whitespace-pre whole wide wide-gamut width will wird with without word working worktrees would wrap wrapper wrappers written wrong wrote wurde xl:flex xl:hidden y-scrollbar yet you your z-dropdown z-local-1 z-modal z-modal-backdrop z-sidebar z-toolbar zd-content zd-desktop-sidebar-toggle zd-doc-content-band zd-enlarge-btn zd-enlarge-dialog zd-enlarge-dialog-close zd-enlargeable zd-html-preview-code zd-mermaid-dialog zd-mermaid-enlargeable zd-mermaid-tool-btn zd-mermaid-toolbar zd-mermaid-transform zd-mermaid-viewport zd-sidebar-content-wrapper zd-sidebar-open zfb zfb:after-swap zfb:before-preparation zod zoom zudo-design-tokens/v3 zudo-doc zudo-doc-design-token-panel-modal zudo-doc-design-tokens zudo-doc-design-tokens/v1 zudo-doc-design-tokens/v2 zudo-doc-design-tokens/v3 zudo-doc-sidebar-visible zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge zudo-doc-tweak zum");

package/dist/settings.d.ts

@@ -305,6 +305,12 @@ export interface Settings {
     sidebarResizer: boolean;
     sidebarToggle: boolean;
     imageEnlarge: boolean;
+    /**
+     * Mount the `FindInPageInit` island (Cmd/Ctrl+F find bar). Self-gates on
+     * `window.__TAURI_INTERNALS__` — a no-op outside a Tauri shell even when
+     * `true`, since the OS/browser already own that shortcut elsewhere.
+     */
+    findInPage: boolean;
     dynamicPageTransition: boolean;
     frontmatterPreview: FrontmatterPreviewConfig | false;
     docHistory: boolean;
@@ -371,4 +377,35 @@ export interface Settings {
      * graph — see the ADR for detail).
      */
     chromeBindingsModule?: string;
+    /**
+     * Project-root-relative path to a host module that exports a named
+     * `buildDesignTokenPanelConfig(mode: "light" | "dark")` zdtp PanelConfig
+     * builder (#2658, epic Minimal Scaffold #2651). Only consumed when
+     * `packageOwnedRoutes` is on: the routes plugin registers a third virtual
+     * module (`virtual:zudo-doc-design-token-panel-config`) that RE-EXPORTS
+     * this module — identical mechanics to {@link chromeBindingsModule}
+     * (mirrors the `chromeBindingsModule` contract exactly).
+     *
+     * When `designTokenPanel` is `true` and this setting is omitted (the
+     * default), the injected `DesignTokenPanelBootstrap` island uses the
+     * PACKAGE-DEFAULT builder (`@takazudo/zudo-doc/design-token-panel-config`)
+     * — derived from the shipped token manifest (`@takazudo/zudo-doc/theme.css`)
+     * and the bundled "Default Light"/"Default Dark" color schemes — so the
+     * panel works with NO host config file.
+     *
+     * - Absent (the default) → the virtual module re-exports the package
+     *   default builder — behavior is a fully working panel with the shipped
+     *   defaults.
+     * - Explicitly empty string → build fails loudly at plugin setup.
+     * - Present but the resolved file does not exist → the build fails loudly
+     *   at plugin setup, naming the resolved absolute path (never a silent
+     *   fallback to the package default).
+     * - Present but the resolved path is a directory → the build fails loudly
+     *   at plugin setup, naming the resolved path.
+     *
+     * Only the PATH travels through `settings` (a string is serializable
+     * data) — the bundler imports the actual builder from the re-exported
+     * module. Irrelevant when `designTokenPanel` is `false`.
+     */
+    designTokenPanelConfigModule?: string;
 }

package/dist/theme.css

@@ -0,0 +1,319 @@
+/* ============================================================================
+ * @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).
+ *
+ * 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.
+   * ======================================== */
+  --color-*: initial;
+
+  /* ========================================
+   * 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;
+}
+
+/* ========================================
+ * 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 {
+  --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/z-index-defaults/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Default z-index tiers — 13 tiers, `content` (0) through `drag` (90).
+ *
+ * Ported from the `create-zudo-doc` base template's
+ * `src/config/z-index-tokens.ts` `Z_INDEX_TIERS` export (epic
+ * zudolab/zudo-doc#2651, S4 #2654). Consumed by the theme-CSS default
+ * (#2655) for the shipped `@theme` z-index block; a project's own
+ * `gen-z-index` codegen (from `@takazudo/zudo-doc`'s `gen-z-index` bin)
+ * becomes opt-in customization on top of this default rather than the only
+ * source.
+ *
+ * Only `name`/`value` are carried in the exported shape — `purpose`/`kind`
+ * were documentation-only in the template and are preserved below as source
+ * comments instead.
+ *
+ * Strategy (from zudolab/zudo-css-wisdom z-index-strategy): semantic single-
+ * namespace tokens — names describe ROLES, never magnitudes. One flat ordered
+ * list. Values are deliberately gapped but otherwise arbitrary: renaming and
+ * reordering is cheap, which is the whole point. Tailwind v4 reads the
+ * `--z-index-<name>` theme key and generates a `z-<name>` utility, so e.g.
+ * `@theme { --z-index-toolbar: 20 }` produces `.z-toolbar { z-index: 20 }`.
+ *
+ * `local-1`/`local-2`/`local-3` ("local" kind in the template) are anonymous
+ * reusable helpers for promoting a child WITHIN a parent stacking context
+ * (`isolation: isolate` / `position: relative`), not a position on the
+ * global stacking scale. Every other tier is "global".
+ *
+ * Rationale for the two zudo-doc-specific additions (NOT in the generic
+ * overlay-centric strategy scale):
+ *   - `sidebar` — persistent layout chrome (desktop sidebar, TOC, sidebar-toggle
+ *     handle, resizer handle). The strategy's scale has no persistent-sidebar/TOC
+ *     tier. `toolbar` (the sticky header) is deliberately placed ABOVE `sidebar`
+ *     to preserve the existing header-wins ordering; they do not overlap
+ *     spatially, but the historical relationship is kept explicit.
+ *   - `drag` — transient drag affordance (sidebar-resizer ghost line). Replaces
+ *     the old `z-9999` anti-pattern with a named top-of-steady-UI tier.
+ *
+ * `popover`, `toast`, and `tooltip` are reserved canonical tiers from the
+ * strategy's scale — kept for completeness (and so downstream `create-zudo-doc`
+ * users inherit the full scale) even though zudo-doc does not use them yet.
+ */
+export declare const defaultZIndexTiers: ReadonlyArray<{
+    name: string;
+    value: number;
+}>;

package/dist/z-index-defaults/index.js

@@ -0,0 +1,34 @@
+const defaultZIndexTiers = [
+  // global — default in-flow content (implicit baseline)
+  { name: "content", value: 0 },
+  // local — child promotion inside an isolated parent stacking context
+  { name: "local-1", value: 1 },
+  // local — child promotion inside an isolated parent stacking context
+  { name: "local-2", value: 2 },
+  // local — child promotion inside an isolated parent stacking context
+  { name: "local-3", value: 3 },
+  // global — persistent layout chrome: desktop sidebar, TOC, sidebar-toggle
+  // handle, resizer handle
+  { name: "sidebar", value: 10 },
+  // global — sticky top header (sits above sidebar chrome)
+  { name: "toolbar", value: 20 },
+  // global — header menus, version/language switchers
+  { name: "dropdown", value: 30 },
+  // global — reserved: inline popovers (canonical scale; not yet used)
+  { name: "popover", value: 40 },
+  // global — mobile drawer backdrop, <dialog> ::backdrop
+  { name: "modal-backdrop", value: 50 },
+  // global — mobile sidebar drawer panel, search <dialog>
+  { name: "modal", value: 60 },
+  // global — reserved: transient notifications (canonical scale; not yet used)
+  { name: "toast", value: 70 },
+  // global — reserved: highest steady UI layer, below only the transient drag
+  // tier (canonical scale; not yet used)
+  { name: "tooltip", value: 80 },
+  // global — transient drag affordance: sidebar-resizer ghost line (replaces
+  // the z-9999 anti-pattern)
+  { name: "drag", value: 90 }
+];
+export {
+  defaultZIndexTiers
+};