@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/design-token-panel-bootstrap.d.ts

@@ -1,28 +1,48 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
 /**
- * Design-token panel (zdtp) WIRING MECHANISM.
+ * Design-token panel (zdtp) WIRING MECHANISM + PACKAGE-DEFAULT ISLAND (#2658,
+ * epic Minimal Scaffold #2651).
  *
- * A side-effect module that configures zdtp's panel and wires its lifecycle
- * hooks to zfb's navigation events via `setLifecycleAdapter()`. Projects import
- * this with their own PanelConfig DATA — which stays project-side.
+ * `bootstrapDesignTokenPanel` is a callable that configures zdtp's panel and
+ * wires its lifecycle hooks to zfb's navigation events via
+ * `setLifecycleAdapter()`. It receives a mode-scoped PanelConfig builder —
+ * either a project override or the package default from
+ * `@takazudo/zudo-doc/design-token-panel-config`.
  *
- * Two calling shapes (both supported):
+ * The current call shape is a mode-scoped builder. It rebuilds the panel per
+ * light/dark mode on every `color-scheme-changed` toggle:
  *
- *   // Mode-scoped builder (showcase host) — rebuilds the panel per light/dark
- *   // mode on every `color-scheme-changed` toggle:
  *   import { bootstrapDesignTokenPanel } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
  *   import { buildDesignTokenPanelConfig } from "@/config/design-token-panel-config";
  *   bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);
  *
- *   // Plain config (back-compat — generated projects on the old shape):
- *   import { designTokenPanelConfig } from "@/config/design-token-panel-config";
- *   bootstrapDesignTokenPanel(designTokenPanelConfig);
+ * `DesignTokenPanelBootstrap` (below) is the PACKAGE-OWNED island component
+ * that wires the mode-scoped builder for package-owned routes with no host
+ * config file — the #2658 "Approach (a)" package default. It resolves its
+ * builder from the `virtual:zudo-doc-design-token-panel-config` virtual
+ * module the routes plugin registers (`../plugins/routes.ts`): absent a host
+ * `designTokenPanelConfigModule` override, that resolves to
+ * `@takazudo/zudo-doc/design-token-panel-config`'s `buildDesignTokenPanelConfig`.
+ * `packages/zudo-doc/src/chrome/derive.tsx` statically imports it so zfb's
+ * island scanner walks route → chrome → derive → here (mirrors the DocHistory
+ * #2480 static-import contract). A host that ejects entirely can call
+ * `bootstrapDesignTokenPanel` with its own builder, but current package-owned
+ * routes use this component directly.
  *
- * A plain-config caller gets NO toggle listener (a static config has nothing to
- * rebuild), so existing generated projects keep working with zero changes.
+ * KNOWN COUPLING: `DesignTokenPanelBootstrap`'s top-level import of
+ * `virtual:zudo-doc-design-token-panel-config` requires the routes plugin
+ * (`settings.packageOwnedRoutes`, default `true`) to be active in the
+ * consuming project, since that plugin is what registers the virtual module.
+ * A project that explicitly sets `packageOwnedRoutes: false` AND wants to
+ * reuse the bare `bootstrapDesignTokenPanel` export for its own component is
+ * unaffected — that import graph never reaches `DesignTokenPanelBootstrap` —
+ * but a `packageOwnedRoutes: false` project must not import the package island
+ * component itself.
  *
- * Moved from the host's `src/lib/design-token-panel-bootstrap.ts` as part of
- * the package-first migration (S9a zudolab/zudo-doc#2333); mode-scoped rebuild
- * wiring added in zudolab/zudo-doc#2610.
+ * Package-first wiring landed in S9a zudolab/zudo-doc#2333; mode-scoped rebuild
+ * wiring was added in zudolab/zudo-doc#2610 and the package-default island in
+ * #2658.
  *
  * CSS is pulled via `@import "@takazudo/zdtp/styles.css"` in the project's
  * `src/styles/global.css` so the panel chrome lands in the main page CSS
@@ -30,30 +50,65 @@
  * import from the emitted JS, so the explicit CSS-side import is the
  * required pull point. See @takazudo/zdtp PORTABLE-CONTRACT.md §7.
  */
+import type { JSX } from "preact";
 import { type PanelConfig } from "@takazudo/zdtp";
 /** Active color-scheme mode, read from `<html data-theme>`. */
 type ColorSchemeMode = "light" | "dark";
 /**
- * A per-mode PanelConfig factory. Supplied by hosts that want the panel's
- * defaults to follow the live light/dark mode (see `buildDesignTokenPanelConfig`
- * in the host's `design-token-panel-config.ts`).
+ * A per-mode PanelConfig factory. The package default and host overrides use
+ * this same shape so panel defaults follow the live light/dark mode.
  */
 export type PanelConfigBuilder = (mode: ColorSchemeMode) => PanelConfig;
+/**
+ * Theme-pack storage-prefix rule (ADR theme-packs.md Decision 4), enforced
+ * CENTRALLY here — never per-builder, so host builders supplied via
+ * `designTokenPanelConfigModule` cannot cross-contaminate namespaces even if
+ * unaware of packs:
+ *
+ * - active pack `default` → the builder's `storagePrefix` stays BYTE-UNCHANGED
+ *   (the existing-user carry-over guarantee: `zudo-doc-tweak` keys keep
+ *   working on the stock look).
+ * - any other pack → `${storagePrefix}--<slug>` (double hyphen avoids
+ *   colliding with zdtp's own `-open`/version suffixes). zdtp derives every
+ *   key — including the `${prefix}-open` open-state mirror — from the prefix,
+ *   so tweaks saved under pack A are invisible under pack B and restored
+ *   verbatim on switch-back.
+ *
+ * The `PanelConfigBuilder` signature stays `(mode) => PanelConfig` — this is a
+ * post-process of the RETURNED config, not a builder-contract change.
+ */
+export declare function withPackScopedStoragePrefix(config: PanelConfig, activePack: string): PanelConfig;
 /**
  * Bootstrap zdtp for a project. Configures the panel, drains any pre-hydration
  * click queue, and wires the zdtp lifecycle adapter to zfb's navigation events
  * so persisted token overrides re-apply on every soft navigation.
  *
- * When passed a `PanelConfigBuilder`, also wires a `color-scheme-changed`
- * listener that rebuilds the panel per light/dark mode (see the toggle sequence
- * below). When passed a plain `PanelConfig`, no toggle listener is registered.
+ * Wires a `color-scheme-changed` listener that rebuilds the panel per
+ * light/dark mode (see the toggle sequence below), and a parallel
+ * `theme-pack-changed` listener that rebuilds it per theme pack with a
+ * pack-scoped storage prefix (ADR theme-packs.md Decision 4, #2822).
  *
- * Call this once, as a side-effect import from the project's island wrapper
- * (`src/components/design-token-panel-bootstrap.tsx`).
+ * @param buildConfig - The project's `(mode) => PanelConfig` builder for
+ *   mode-scoped rebuilds.
+ */
+export declare function bootstrapDesignTokenPanel(buildConfig: PanelConfigBuilder): void;
+/**
+ * The package-default `<DesignTokenPanelBootstrap/>` island: mounted (via
+ * `Island({ when: "load" })`, no `ssrFallback` — it renders nothing on either
+ * side) by `../doc-body-end-islands/index.tsx` when `settings.designTokenPanel`
+ * is on, gated the same way `AiChatModal`/`ImageEnlarge`/`MermaidEnlarge` are.
+ * On first render, calls `bootstrapDesignTokenPanel` with the mode-scoped
+ * `buildDesignTokenPanelConfig` builder resolved from
+ * `virtual:zudo-doc-design-token-panel-config` (package default, or the
+ * host's `designTokenPanelConfigModule` override).
  *
- * @param configOrBuilder - The project's `PanelConfig`, or a `(mode) =>
- *   PanelConfig` builder for mode-scoped rebuilds. DATA stays project-side in
- *   `src/config/design-token-panel-config.ts`.
+ * `displayName` pinned explicitly (belt-and-braces, matching
+ * `AiChatModal`/`ImageEnlarge`/`MermaidEnlarge`/`DocHistory`) so zfb's
+ * `captureComponentName` emits a stable `data-zfb-island="DesignTokenPanelBootstrap"`
+ * marker independent of minification.
  */
-export declare function bootstrapDesignTokenPanel(configOrBuilder: PanelConfig | PanelConfigBuilder): void;
+export declare function DesignTokenPanelBootstrap(): JSX.Element | null;
+export declare namespace DesignTokenPanelBootstrap {
+    var displayName: string;
+}
 export {};

package/dist/design-token-panel-bootstrap.js

@@ -1,5 +1,7 @@
+"use client";
 import {
   configurePanel,
+  reapplyPersistedOverrides,
   setLifecycleAdapter,
   showDesignTokenPanel
 } from "@takazudo/zdtp";
@@ -7,36 +9,112 @@ import {
   BEFORE_NAVIGATE_EVENT,
   AFTER_NAVIGATE_EVENT
 } from "./transitions/page-events.js";
+import {
+  DEFAULT_THEME_PACK_SLUG,
+  THEME_PACK_CHANGED_EVENT,
+  readThemePackFromDom
+} from "./theme-pack-switcher/theme-pack-sync.js";
+import { buildDesignTokenPanelConfig } from "virtual:zudo-doc-design-token-panel-config";
 const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
 function openStateKey(instancePrefix) {
   return `${instancePrefix}-open`;
 }
+function readOpenState(instancePrefix) {
+  try {
+    return localStorage.getItem(openStateKey(instancePrefix)) === "1";
+  } catch {
+    return false;
+  }
+}
 function readMode() {
   return document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light";
 }
-function bootstrapDesignTokenPanel(configOrBuilder) {
-  if (typeof window === "undefined" || typeof document === "undefined") {
+function withPackScopedStoragePrefix(config, activePack) {
+  if (activePack === DEFAULT_THEME_PACK_SLUG) return config;
+  return { ...config, storagePrefix: `${config.storagePrefix}--${activePack}` };
+}
+function collectDeclaredTokenNames(config) {
+  const names = [];
+  for (const tab of config.tabs ?? []) {
+    for (const tier of tab.tiers ?? []) {
+      for (const item of tier.items ?? []) {
+        names.push(item.cssVar);
+      }
+    }
+    const baseRoles = tab.colorExtras?.baseRoles;
+    if (baseRoles) {
+      for (const cssVar of Object.values(baseRoles)) {
+        if (typeof cssVar === "string" && cssVar.length > 0) {
+          names.push(cssVar);
+        }
+      }
+    }
+  }
+  return names;
+}
+function clearAppliedTokenOverrides(config) {
+  const names = collectDeclaredTokenNames(config);
+  if (config.applySink) {
+    try {
+      config.applySink.clear(names);
+    } catch (err) {
+      console.warn(
+        "[zudo-doc] applySink.clear threw during theme-pack switch; outgoing overrides may linger.",
+        err
+      );
+    }
     return;
   }
-  const isBuilder = typeof configOrBuilder === "function";
-  const builder = isBuilder ? configOrBuilder : () => configOrBuilder;
-  let handle = configurePanel(builder(readMode()));
-  if (isBuilder) {
-    let pendingMode = readMode();
-    let timer = null;
-    window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, () => {
-      pendingMode = readMode();
-      if (timer !== null) return;
-      timer = setTimeout(() => {
-        timer = null;
-        const mode = pendingMode;
-        const wasOpen = localStorage.getItem(openStateKey(handle.instanceId)) === "1";
-        handle.destroy();
-        handle = configurePanel(builder(mode));
-        if (wasOpen) showDesignTokenPanel();
-      }, 0);
-    });
+  const style = document.documentElement.style;
+  for (const name of names) {
+    style.removeProperty(name);
+  }
+}
+function bootstrapDesignTokenPanel(buildConfig) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
   }
+  let currentConfig = withPackScopedStoragePrefix(
+    buildConfig(readMode()),
+    readThemePackFromDom()
+  );
+  let handle = configurePanel(currentConfig);
+  let pendingMode = readMode();
+  let timer = null;
+  window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, () => {
+    pendingMode = readMode();
+    if (timer !== null) return;
+    timer = setTimeout(() => {
+      timer = null;
+      const mode = pendingMode;
+      const wasOpen = readOpenState(handle.instanceId);
+      handle.destroy();
+      currentConfig = withPackScopedStoragePrefix(
+        buildConfig(mode),
+        readThemePackFromDom()
+      );
+      handle = configurePanel(currentConfig);
+      if (wasOpen) showDesignTokenPanel();
+    }, 0);
+  });
+  let pendingPack = readThemePackFromDom();
+  let packTimer = null;
+  window.addEventListener(THEME_PACK_CHANGED_EVENT, () => {
+    pendingPack = readThemePackFromDom();
+    if (packTimer !== null) return;
+    packTimer = setTimeout(() => {
+      packTimer = null;
+      const pack = pendingPack;
+      const wasOpen = readOpenState(handle.instanceId);
+      const outgoingConfig = currentConfig;
+      handle.destroy();
+      clearAppliedTokenOverrides(outgoingConfig);
+      currentConfig = withPackScopedStoragePrefix(buildConfig(readMode()), pack);
+      handle = configurePanel(currentConfig);
+      reapplyPersistedOverrides();
+      if (wasOpen) showDesignTokenPanel();
+    }, 0);
+  });
   window.__zdtpReadyClicks?.();
   const adapter = {
     onBeforeSwap(cb) {
@@ -52,6 +130,17 @@ function bootstrapDesignTokenPanel(configOrBuilder) {
   };
   setLifecycleAdapter(adapter);
 }
+let bootstrapped = false;
+function DesignTokenPanelBootstrap() {
+  if (!bootstrapped) {
+    bootstrapped = true;
+    bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);
+  }
+  return null;
+}
+DesignTokenPanelBootstrap.displayName = "DesignTokenPanelBootstrap";
 export {
-  bootstrapDesignTokenPanel
+  DesignTokenPanelBootstrap,
+  bootstrapDesignTokenPanel,
+  withPackScopedStoragePrefix
 };

package/dist/design-token-panel-config/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `@takazudo/zudo-doc/design-token-panel-config` — the PACKAGE-DEFAULT zdtp
+ * PanelConfig builder (#2658, epic Minimal Scaffold #2651, decision wave
+ * #2653 "Approach (a)").
+ *
+ * Ported from the showcase's `src/config/design-token-panel-config.ts` (441
+ * lines, ~90% mechanical derivation per the decision-wave audit) so
+ * `designTokenPanel: true` works with NO host config file: the Palette tab
+ * comes from `defaultColorSchemes`' shared `ramps`, the Color tab from
+ * `buildSemanticTierItems`, and Font/Spacing/Size from the manifest in
+ * `./manifest.js`. The hand-authored panel-identity constants
+ * (`storagePrefix`, `consoleNamespace`, `modalClassPrefix`, `schemaId`,
+ * `exportFilenameBase`) and the `FONT_ROLE_TO_SCALE` map are carried over
+ * verbatim — `storagePrefix: "zudo-doc-tweak"` in particular MUST NOT change
+ * (existing user-save carry-over guarantee, see `packages/zudo-doc/CLAUDE.md`
+ * and `src/CLAUDE.md`).
+ *
+ * A host that needs a fully custom panel (its own color schemes, its own
+ * token manifest) points `settings.designTokenPanelConfigModule` at a module
+ * exporting a named `buildDesignTokenPanelConfig` — see
+ * `../plugins/routes.ts` (`virtual:zudo-doc-design-token-panel-config`,
+ * mirrors the `chromeBindingsModule` contract). This module is what the
+ * routes plugin re-exports when NO override is configured.
+ *
+ * Unlike the showcase original, this builder does not resolve
+ * `settings.colorMode`/`settings.colorScheme` — the PACKAGE has no settings
+ * singleton to read (the preset's node-free eval-graph rule keeps this
+ * module out of the config eval graph too, so it must stay side-effect-free
+ * on import). It seeds the Color tab straight from `defaultColorSchemes`'
+ * "Default Light" / "Default Dark" entries for the requested `mode` — the
+ * exact pair `@takazudo/zudo-doc/theme.css` ships as the default scheme.
+ */
+import type { PanelConfig } from "@takazudo/zdtp";
+type PanelMode = "light" | "dark";
+/**
+ * Build the full PACKAGE-DEFAULT PanelConfig for a given color-scheme
+ * `mode`. Only the Color tab's semantic tier and `panelSettings.colorMode.
+ * defaultMode` vary by mode; the Palette/Font/Spacing/Size tabs are
+ * mode-independent. `@takazudo/zudo-doc/design-token-panel-bootstrap` calls
+ * this per mode on every `color-scheme-changed` toggle (destroy +
+ * reconfigure) — it is passed as the BUILDER, not a resolved config (#2610).
+ *
+ * `storagePrefix: "zudo-doc-tweak"` is the same value the showcase's own
+ * `design-token-panel-config.ts` has always used — keep it unchanged so a
+ * host migrating from an ejected config to this package default carries its
+ * existing user-saved tweaks over.
+ */
+export declare function buildDesignTokenPanelConfig(mode: PanelMode): PanelConfig;
+export {};

package/dist/design-token-panel-config/index.js

@@ -0,0 +1,211 @@
+import { SPACING_TOKENS, FONT_TOKENS, SIZE_TOKENS } from "./manifest.js";
+import { STATE_ROLES, buildSemanticTierItems } from "../color-scheme-utils.js";
+import { defaultColorSchemes } from "../color-schemes-defaults/index.js";
+const DEFAULT_SHIKI_THEME = "github-dark";
+function schemeNameForMode(mode) {
+  return mode === "dark" ? "Default Dark" : "Default Light";
+}
+function schemeForMode(mode) {
+  const scheme = defaultColorSchemes[schemeNameForMode(mode)];
+  if (!scheme) {
+    throw new Error(
+      `zudo-doc: defaultColorSchemes is missing "${schemeNameForMode(mode)}" \u2014 this is a package bug.`
+    );
+  }
+  return scheme;
+}
+function toTierItem(t) {
+  let kind;
+  if (t.control === "select") {
+    kind = { kind: "select", options: t.options ?? [] };
+  } else if (t.control === "text") {
+    kind = { kind: "text" };
+  } else {
+    kind = {
+      kind: "length",
+      step: t.step,
+      unit: t.unit
+    };
+  }
+  const item = {
+    id: t.id,
+    cssVar: t.cssVar,
+    label: t.label,
+    default: t.default,
+    type: kind
+  };
+  if (t.pill) item.pill = t.pill;
+  if (t.readonly) item.readonly = true;
+  return item;
+}
+function tierFromGroup(tokens, groupId, label) {
+  return {
+    id: groupId,
+    label,
+    items: tokens.filter((t) => t.group === groupId).map(toTierItem)
+  };
+}
+function buildRampTiers(mode) {
+  const { ramps } = schemeForMode(mode);
+  const baseTier = {
+    id: "base",
+    label: "Base",
+    items: ramps.base.map((color, i) => ({
+      id: `base-${i}`,
+      cssVar: `--palette-base-${i}`,
+      label: String(i),
+      default: color,
+      type: { kind: "color", format: "oklch" }
+    }))
+  };
+  const accentTier = {
+    id: "accent",
+    label: "Accent",
+    items: ramps.accent.map((color, i) => ({
+      id: `accent-${i}`,
+      cssVar: `--palette-accent-${i}`,
+      label: String(i),
+      default: color,
+      type: { kind: "color", format: "oklch" }
+    }))
+  };
+  const stateTier = {
+    id: "state",
+    label: "State",
+    items: STATE_ROLES.map((role) => ({
+      id: `state-${role}`,
+      cssVar: `--palette-state-${role}`,
+      label: role,
+      default: ramps.state[role],
+      type: { kind: "color", format: "oklch" }
+    }))
+  };
+  return [baseTier, accentTier, stateTier];
+}
+function buildPaletteTab(mode) {
+  return {
+    id: "palette",
+    label: "Palette",
+    tiers: buildRampTiers(mode)
+    // No colorExtras: a tab with multiple kind:'color' tiers MUST omit it so
+    // resolveColorClusterFromTab is not invoked and zdtp renders the ramps
+    // with its native curve editor (zdtp palette-tab contract).
+  };
+}
+function buildSemanticTier(mode) {
+  return {
+    id: "semantic",
+    label: "Semantic",
+    semantic: true,
+    referencesRamps: [
+      { tab: "palette", tier: "base" },
+      { tab: "palette", tier: "accent" },
+      { tab: "palette", tier: "state" }
+    ],
+    items: buildSemanticTierItems(schemeForMode(mode))
+  };
+}
+function buildColorExtras(mode) {
+  const lightScheme = schemeNameForMode("light");
+  const darkScheme = schemeNameForMode("dark");
+  return {
+    id: "zudo-doc",
+    label: "Zudo Doc",
+    baseRoles: {},
+    baseDefaults: {},
+    defaultShikiTheme: DEFAULT_SHIKI_THEME,
+    colorSchemes: {},
+    panelSettings: {
+      colorScheme: schemeNameForMode(mode),
+      colorMode: { defaultMode: mode, lightScheme, darkScheme }
+    }
+  };
+}
+function buildColorTab(mode) {
+  return {
+    id: "color",
+    label: "Color",
+    tiers: [buildSemanticTier(mode)],
+    colorExtras: buildColorExtras(mode)
+  };
+}
+const FONT_SCALE_TIER_ID = "font-scale";
+const FONT_ROLE_TO_SCALE = {
+  "text-micro": "text-scale-2xs",
+  "text-caption": "text-scale-xs",
+  "text-small": "text-scale-sm",
+  "text-body": "text-scale-md",
+  "text-title": "text-scale-lg",
+  "text-heading": "text-scale-xl",
+  "text-display": "text-scale-2xl"
+};
+function buildFontRoleTier() {
+  const base = tierFromGroup(FONT_TOKENS, "font-size", "Font size");
+  return {
+    ...base,
+    items: base.items.map((item) => {
+      const scaleId = FONT_ROLE_TO_SCALE[item.id];
+      return scaleId ? { ...item, default: scaleId } : item;
+    }),
+    referencesTier: FONT_SCALE_TIER_ID
+  };
+}
+function buildFontTab() {
+  return {
+    id: "font",
+    label: "Font",
+    tiers: [
+      tierFromGroup(FONT_TOKENS, FONT_SCALE_TIER_ID, "Scale"),
+      buildFontRoleTier(),
+      tierFromGroup(FONT_TOKENS, "line-height", "Line height"),
+      tierFromGroup(FONT_TOKENS, "font-weight", "Font weight"),
+      tierFromGroup(FONT_TOKENS, "font-family", "Font family")
+    ]
+  };
+}
+function buildSpacingTab() {
+  return {
+    id: "spacing",
+    label: "Spacing",
+    tiers: [
+      tierFromGroup(SPACING_TOKENS, "hsp", "Horizontal spacing"),
+      tierFromGroup(SPACING_TOKENS, "vsp", "Vertical spacing"),
+      tierFromGroup(SPACING_TOKENS, "icon", "Icons"),
+      tierFromGroup(SPACING_TOKENS, "layout", "Layout")
+    ]
+  };
+}
+function buildSizeTab() {
+  return {
+    id: "size",
+    label: "Size",
+    tiers: [
+      tierFromGroup(SIZE_TOKENS, "radius", "Radius"),
+      tierFromGroup(SIZE_TOKENS, "transition", "Transition")
+    ]
+  };
+}
+function buildDesignTokenPanelConfig(mode) {
+  return {
+    storagePrefix: "zudo-doc-tweak",
+    consoleNamespace: "zudoDoc",
+    modalClassPrefix: "zudo-doc-design-token-panel-modal",
+    // DISPLAY-ONLY in zdtp 0.4.6: the panel's export hard-codes
+    // `zudo-design-tokens/v2` and auto-upgrades to `.../v3` when object leaves
+    // ({ref}/{literal}/per-mode) are present — which the semantic tier's ramp
+    // refs always are, so real exports carry v3. `schemaId` does NOT gate
+    // import, and (verified against the installed zdtp 0.4.6 bundle) zdtp's
+    // Import/Export modals do not read this field at all — their hint/error
+    // text is hardcoded to zdtp's own internal `SCHEMA_V1`/`SCHEMA_V2`/
+    // `SCHEMA_V3` constants (#498/#505), which are unrelated to this field.
+    // It is thus a purely descriptive config value with no runtime effect;
+    // set to v3 (a literal, not one of those constants) to match what real
+    // exports carry.
+    schemaId: "zudo-design-tokens/v3",
+    exportFilenameBase: "zudo-doc-design-tokens",
+    tabs: [buildPaletteTab(mode), buildColorTab(mode), buildFontTab(), buildSpacingTab(), buildSizeTab()]
+  };
+}
+export {
+  buildDesignTokenPanelConfig
+};

package/dist/design-token-panel-config/manifest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Design-token manifest data arrays — the PACKAGE-DEFAULT source of truth for
+ * the spacing/font/size tabs of `buildDesignTokenPanelConfig` (#2658, epic
+ * Minimal Scaffold #2651).
+ *
+ * Ported verbatim from the showcase's `src/config/design-tokens-manifest.ts`
+ * (values mirror the defaults shipped by `@takazudo/zudo-doc/theme.css`,
+ * #2655) so `designTokenPanel: true` works with no host manifest file. A
+ * project that needs its own token set entirely ejects via
+ * `designTokenPanelConfigModule` (see `../plugins/routes.ts`), not by editing
+ * this file — this module stays the PACKAGE default.
+ *
+ * Type strategy: arrays are typed `readonly TokenDef[]`, matching the
+ * upstream zdtp `TokenDef` shape consumed by `../color-scheme-utils.js` and
+ * `./index.ts` (which partitions them into `TabConfig.tiers` by `group`).
+ */
+import type { TokenDef } from "@takazudo/zdtp";
+/**
+ * Spacing tokens — mirrors every `--spacing-*` declaration shipped by
+ * `@takazudo/zudo-doc/theme.css`, plus the `--zd-sidebar-w` layout token.
+ * Read-only rows surface tokens whose value can't be expressed on a
+ * single-axis slider (`clamp()`, structural `0`).
+ */
+export declare const SPACING_TOKENS: readonly TokenDef[];
+/**
+ * Font tokens — mirrors every font-related declaration shipped by
+ * `@takazudo/zudo-doc/theme.css`.
+ *
+ * Tier 2 semantic tokens (sizes, line-heights, weights, families) are exposed
+ * as primary tiers; Tier 1 abstract scale (`--text-scale-*`) lives in its own
+ * `font-scale` tier so designers who tweak the scale see the tokens that the
+ * semantic sizes resolve from.
+ */
+export declare const FONT_TOKENS: readonly TokenDef[];
+/**
+ * Size tokens — mirrors every non-breakpoint size-category custom property
+ * shipped by `@takazudo/zudo-doc/theme.css`. Breakpoints (`--breakpoint-*`)
+ * are intentionally omitted — live-changing them causes layout thrash
+ * mid-drag and adds no real tweak value.
+ *
+ * Radius defaults use `px` (matches a 0-100 slider), even though
+ * `theme.css` expresses them in `rem` — the browser accepts both.
+ * `--radius-full` carries a `pill` toggle: its design default (`9999px`) is
+ * an intentional sentinel a 0-100 slider can't reach.
+ */
+export declare const SIZE_TOKENS: readonly TokenDef[];