create-zudo-doc 2.5.1 → 3.0.0

package/README.md

@@ -31,7 +31,7 @@ pnpm create zudo-doc my-docs --yes
 # Fully specified, non-interactive
 pnpm create zudo-doc my-docs \
   --lang ja \
-  --scheme Dracula \
+  --scheme "Default Dark" \
   --no-i18n \
   --search \
   --pm pnpm \
@@ -109,11 +109,11 @@ pnpm create zudo-doc my-docs \
   --install \
   --yes
 
-# Light/dark color scheme with Catppuccin pairings
+# Light/dark color scheme with the Default pairing
 pnpm create zudo-doc my-docs \
   --color-scheme-mode light-dark \
-  --light-scheme "Catppuccin Latte" \
-  --dark-scheme "Catppuccin Mocha" \
+  --light-scheme "Default Light" \
+  --dark-scheme "Default Dark" \
   --default-mode dark \
   --yes
 
@@ -130,7 +130,7 @@ await createZudoDoc({
   projectName: "my-docs",
   defaultLang: "en",
   colorSchemeMode: "single",
-  singleScheme: "Dracula",
+  singleScheme: "Default Dark",
   features: ["search", "sidebarFilter", "tagGovernance"],
   packageManager: "pnpm",
   install: true,

package/dist/api.js

@@ -1,4 +1,5 @@
 import path from "path";
+import { SINGLE_SCHEMES } from "./constants.js";
 import { scaffold } from "./scaffold.js";
 import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
@@ -6,6 +7,21 @@ export async function createZudoDoc(options) {
     const nameError = validateProjectName(rest.projectName);
     if (nameError)
         throw new Error(`Invalid projectName: ${nameError}`);
+    // Validate scheme names like the CLI (cli.ts) and preset (preset.ts) paths do.
+    // Only `Default Light`/`Default Dark` exist post-catalog-drop (#2619); an
+    // unvalidated name here would be written verbatim into settings.ts and throw
+    // "Unknown color scheme" at the generated site's build — the exact failure
+    // this epic set out to eliminate. This is the last scaffolding entry point
+    // that lacked the guard.
+    for (const [label, value] of [
+        ["color scheme", rest.singleScheme],
+        ["light scheme", rest.lightScheme],
+        ["dark scheme", rest.darkScheme],
+    ]) {
+        if (value && !SINGLE_SCHEMES.includes(value)) {
+            throw new Error(`Unknown ${label} "${value}"`);
+        }
+    }
     const choices = { ...rest, defaultLang: rest.defaultLang ?? "en" };
     await scaffold(choices);
     const targetDir = path.resolve(process.cwd(), choices.projectName);

package/dist/cli.js

@@ -110,12 +110,7 @@ ${pc.bold("Examples:")}
   create-zudo-doc my-docs --yes
 
   ${pc.dim("# Fully specified")}
-  create-zudo-doc my-docs --lang ja --scheme Dracula --no-i18n --pm pnpm --install
-
-  ${pc.dim("# Light/dark mode with custom schemes")}
-  create-zudo-doc my-docs --color-scheme-mode light-dark \\
-    --light-scheme "GitHub Light" --dark-scheme "GitHub Dark" \\
-    --default-mode dark --yes
+  create-zudo-doc my-docs --lang ja --scheme "Default Dark" --no-i18n --pm pnpm --install
 `);
 }
 export function validateArgs(args) {

package/dist/constants.js

@@ -1,73 +1,12 @@
 export const LIGHT_DARK_PAIRINGS = [
     { light: "Default Light", dark: "Default Dark", label: "Default" },
-    { light: "GitHub Light", dark: "GitHub Dark", label: "GitHub" },
-    { light: "Catppuccin Latte", dark: "Catppuccin Mocha", label: "Catppuccin" },
-    { light: "Solarized Light", dark: "Solarized Dark", label: "Solarized" },
-    { light: "Rose Pine Dawn", dark: "Rose Pine", label: "Rosé Pine" },
-    { light: "Atom One Light", dark: "Atom One Dark", label: "Atom One" },
-    { light: "Everforest Light", dark: "Everforest Dark", label: "Everforest" },
-    { light: "Gruvbox Light", dark: "Gruvbox Dark", label: "Gruvbox" },
-    { light: "Ayu Light", dark: "Ayu Dark", label: "Ayu" },
-];
-// All available single schemes (dark ones most popular first)
-export const SINGLE_SCHEMES = [
-    "Default Dark",
-    "Dracula",
-    "Catppuccin Mocha",
-    "GitHub Dark",
-    "Nord",
-    "TokyoNight",
-    "Gruvbox Dark",
-    "Atom One Dark",
-    "Rose Pine",
-    "Solarized Dark",
-    "Material Ocean",
-    "Monokai Pro",
-    "Everforest Dark",
-    "Kanagawa Wave",
-    "Night Owl",
-    "Ayu Dark",
-    "VS Code Dark+",
-    "Doom One",
-    "Challenger Deep",
-    "Catppuccin Frappe",
-    "Catppuccin Macchiato",
-    "Gruvbox Dark Hard",
-    "Rose Pine Moon",
-    "GitHub Dark Dimmed",
-    "Ayu Mirage",
-    "Material Darker",
-    "Material Dark",
-    "Monokai Remastered",
-    "Monokai Vivid",
-    "Monokai Soda",
-    "Solarized Dark Higher Contrast",
-    "Gruvbox Material Dark",
-    "Kanagawa Dragon",
-    // Light schemes
-    "Default Light",
-    "GitHub Light",
-    "Catppuccin Latte",
-    "Solarized Light",
-    "Rose Pine Dawn",
-    "Atom One Light",
-    "Everforest Light",
-    "Gruvbox Light",
-    "Ayu Light",
 ];
+// All available single schemes (dark-first ordering — asserted by the host
+// sync test).
+export const SINGLE_SCHEMES = ["Default Dark", "Default Light"];
 // Light-only subset of SINGLE_SCHEMES. Used by the preset generator to populate
 // the "Light scheme" dropdown (dark schemes are derived as SINGLE_SCHEMES minus these).
-export const LIGHT_SCHEMES = [
-    "Default Light",
-    "GitHub Light",
-    "Catppuccin Latte",
-    "Solarized Light",
-    "Rose Pine Dawn",
-    "Atom One Light",
-    "Everforest Light",
-    "Gruvbox Light",
-    "Ayu Light",
-];
+export const LIGHT_SCHEMES = ["Default Light"];
 export const SUPPORTED_LANGS = [
     { value: "en", label: "English" },
     { value: "ja", label: "Japanese" },

package/dist/index.js

@@ -89,7 +89,7 @@ async function main() {
             prefilled.respectPrefersColorScheme ??= true;
         }
         else {
-            prefilled.singleScheme ??= "Dracula";
+            prefilled.singleScheme ??= "Default Dark";
         }
         prefilled.packageManager ??= "pnpm";
         prefilled.githubUrl ??= "";

package/dist/prompts.js

@@ -1,5 +1,5 @@
 import * as p from "@clack/prompts";
-import { LIGHT_DARK_PAIRINGS, SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS } from "./constants.js";
+import { SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS } from "./constants.js";
 import { validateProjectName } from "./utils.js";
 export async function runPrompts(prefilled = {}) {
     // 1. Project name
@@ -88,48 +88,9 @@ export async function runPrompts(prefilled = {}) {
             darkScheme = prefilled.darkScheme;
         }
         else {
-            const pairingChoice = await p.select({
-                message: "Choose a light/dark pairing:",
-                options: [
-                    ...LIGHT_DARK_PAIRINGS.map((pair) => ({
-                        value: pair.label,
-                        label: `${pair.light} + ${pair.dark}`,
-                        hint: pair.label,
-                    })),
-                    {
-                        value: "custom",
-                        label: "Pick individually",
-                        hint: "Choose light and dark schemes separately",
-                    },
-                ],
-            });
-            if (p.isCancel(pairingChoice))
-                process.exit(0);
-            if (pairingChoice === "custom") {
-                const lightSchemes = SINGLE_SCHEMES.filter((s) => ["Light", "Latte", "Dawn"].some((k) => s.includes(k)));
-                const darkSchemes = SINGLE_SCHEMES.filter((s) => !["Light", "Latte", "Dawn"].some((k) => s.includes(k)));
-                const light = await p.select({
-                    message: "Choose light scheme:",
-                    options: lightSchemes.map((s) => ({ value: s, label: s })),
-                });
-                if (p.isCancel(light))
-                    process.exit(0);
-                lightScheme = light;
-                const dark = await p.select({
-                    message: "Choose dark scheme:",
-                    options: darkSchemes.map((s) => ({ value: s, label: s })),
-                });
-                if (p.isCancel(dark))
-                    process.exit(0);
-                darkScheme = dark;
-            }
-            else {
-                const pairing = LIGHT_DARK_PAIRINGS.find((pair) => pair.label === pairingChoice);
-                if (pairing) {
-                    lightScheme = pairing.light;
-                    darkScheme = pairing.dark;
-                }
-            }
+            // Only the Default pairing exists — auto-assign, no prompt.
+            lightScheme = "Default Light";
+            darkScheme = "Default Dark";
         }
         // Default mode
         if (prefilled.defaultMode === undefined) {

package/dist/scaffold.d.ts

@@ -11,5 +11,5 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^2.5.1";
+export declare const ZUDO_DOC_PIN = "^3.0.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -18,7 +18,7 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^2.5.1";
+export const ZUDO_DOC_PIN = "^3.0.0";
 /**
  * Files in `templates/base/**` that must never be copied into a generated
  * project. Each entry is matched against the path relative to `templates/base/`
@@ -582,7 +582,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^2.5.1";
+        deps["@takazudo/zudo-doc-history-server"] = "^3.0.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).
@@ -593,7 +593,7 @@ function generatePackageJson(choices) {
     if (choices.features.includes("designTokenPanel")) {
         // @takazudo/zdtp requires preact >= 10.29.1 — see the preact floor comment
         // above (~line 382) for why the floor is set there and the coupling this creates.
-        deps["@takazudo/zdtp"] = "0.4.2";
+        deps["@takazudo/zdtp"] = "0.4.5";
     }
     if (choices.features.includes("tagGovernance")) {
         // gray-matter is already in `deps` unconditionally (base template uses it),

package/dist/settings-gen.js

@@ -35,15 +35,15 @@ export function generateSettingsFile(choices) {
     lines.push(``);
     lines.push(`export const settings = {`);
     if (choices.colorSchemeMode === "single") {
-        lines.push(`  colorScheme: ${JSON.stringify(choices.singleScheme ?? "Dracula")},`);
+        lines.push(`  colorScheme: ${JSON.stringify(choices.singleScheme ?? "Default Dark")},`);
         lines.push(`  colorMode: false as ColorModeConfig | false,`);
     }
     else {
-        lines.push(`  colorScheme: ${JSON.stringify(choices.darkScheme ?? "GitHub Dark")},`);
+        lines.push(`  colorScheme: ${JSON.stringify(choices.darkScheme ?? "Default Dark")},`);
         lines.push(`  colorMode: {`);
         lines.push(`    defaultMode: ${JSON.stringify(choices.defaultMode ?? "dark")},`);
-        lines.push(`    lightScheme: ${JSON.stringify(choices.lightScheme ?? "GitHub Light")},`);
-        lines.push(`    darkScheme: ${JSON.stringify(choices.darkScheme ?? "GitHub Dark")},`);
+        lines.push(`    lightScheme: ${JSON.stringify(choices.lightScheme ?? "Default Light")},`);
+        lines.push(`    darkScheme: ${JSON.stringify(choices.darkScheme ?? "Default Dark")},`);
         lines.push(`    respectPrefersColorScheme: ${choices.respectPrefersColorScheme ?? true},`);
         lines.push(`  } satisfies ColorModeConfig as ColorModeConfig | false,`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "2.5.1",
+  "version": "3.0.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/src/config/color-scheme-utils.ts

@@ -1,21 +1,30 @@
 /**
  * Project-side color-scheme helpers.
  *
- * The MECHANISM (palette→CSS injection logic) now lives in the package:
+ * The MECHANISM (ramp→CSS injection logic) now lives in the package:
  * `@takazudo/zudo-doc/color-scheme-utils`. This file re-exports those
  * mechanism symbols and adds project-specific thin wrappers that read from
- * this project's `colorSchemes` map and `settings`. The DATA (palette values,
+ * this project's `colorSchemes` map and `settings`. The DATA (ramp values,
  * scheme names) stays in `./color-schemes` and `./settings`.
  *
  * S9a package-first migration — zudolab/zudo-doc#2333.
+ * Ramp-native rewrite — zudolab/zudo-doc#2585/#2586.
  */
 
 export {
-  type ColorRef,
+  type OKLCH,
+  type StateRole,
+  type SemanticKey,
+  type RampRef,
+  type Ramps,
+  type ModeMap,
   type ColorScheme,
-  SEMANTIC_DEFAULTS,
+  type CssEmitScope,
+  STATE_ROLES,
+  SEMANTIC_KEYS,
+  SEMANTIC_RAMP_DEFAULTS,
   SEMANTIC_CSS_NAMES,
-  resolveColor,
+  resolveRampRef,
   resolveSemanticColors,
   schemeToCssPairs,
   generateCssCustomProperties as generateCssCustomPropertiesFromScheme,

package/templates/base/src/config/color-schemes.ts

@@ -1,136 +1,165 @@
-/** A color reference: palette index (number) or direct color value (string) */
-export type ColorRef = number | string;
+/**
+ * Ramp-native color schemes (Color Ramp Restructure — zudolab/zudo-doc#2584;
+ * minimize pass #2601 / #2602).
+ *
+ * A `ColorScheme` is `{ ramps, map }` (the MECHANISM types live in the package
+ * and are re-exported by `./color-scheme-utils`):
+ *   - `ramps` — the shared Tier-1 source of truth: a warm-neutral `base` ramp
+ *     (5 stops, index 0 = lightest), an `accent` ramp (3 stops), and 4 `state`
+ *     colors. Light and dark modes SHARE these values.
+ *   - `map` — the per-mode Tier-2 wiring: which ramp stop (or literal OKLCH)
+ *     each UI role points at.
+ *
+ * The palette was minimized from base=12 / accent=7 to **base=5 / accent=3**
+ * (#2602): the ramp-native engine is length-agnostic, so this is a DATA change.
+ * Semantic roles are aggressively merged onto shared stops to keep the number of
+ * distinct tones small — most notably `surface`, `codeBg`(light) and
+ * `chatAssistantBg` collapse onto `bg`, so header Version boxes and doc cards
+ * render as page-bg + border only (no gray fill). 5 stops leave no subtle
+ * near-white, so light-mode elevated fills are border-only by design.
+ *
+ * `ColorScheme` is re-exported here so the many sites that still
+ * `import { ColorScheme } from "./color-schemes"` (contrast tooling,
+ * zfb.config.ts, …) keep resolving until their own waves port them.
+ */
 
-export interface ColorScheme {
-  background: ColorRef;
-  foreground: ColorRef;
-  cursor: ColorRef;
-  selectionBg: ColorRef;
-  selectionFg: ColorRef;
-  palette: [
-    string, string, string, string, string, string, string, string,
-    string, string, string, string, string, string, string, string,
-  ];
-  /** Optional, vestigial. Carried only in the optional color-scheme config
-   *  envelope consumed by the design token panel tooling (falls back to
-   *  DEFAULT_SHIKI_THEME when omitted), but has no visible effect: that
-   *  tooling's Shiki integration is a no-op stub, and page code highlighting is
-   *  done by syntect (dual-theme, configured via `codeHighlight` in
-   *  zfb.config.ts), not Shiki. */
-  shikiTheme?: string;
-  /** Optional semantic overrides — when omitted, defaults are used:
-   *  surface=p0, muted=p8, accent=p5, accentHover=p14
-   *  codeBg=p10, codeFg=p11, success=p2, danger=p1, warning=p3, info=p4
-   *  Each field accepts a palette index (number) or a direct color value (string). */
-  semantic?: {
-    surface?: ColorRef;
-    muted?: ColorRef;
-    accent?: ColorRef;
-    accentHover?: ColorRef;
-    codeBg?: ColorRef;
-    codeFg?: ColorRef;
-    success?: ColorRef;
-    danger?: ColorRef;
-    warning?: ColorRef;
-    info?: ColorRef;
-    mermaidNodeBg?: ColorRef;
-    mermaidText?: ColorRef;
-    mermaidLine?: ColorRef;
-    mermaidLabelBg?: ColorRef;
-    mermaidNoteBg?: ColorRef;
-    chatUserBg?: ColorRef;
-    chatUserText?: ColorRef;
-    chatAssistantBg?: ColorRef;
-    chatAssistantText?: ColorRef;
-    /** UI chrome over user images — enlarge/close overlay buttons */
-    imageOverlayBg?: ColorRef;
-    imageOverlayFg?: ColorRef;
-    /** <mark> highlight for matched keywords in search results */
-    matchedKeywordBg?: ColorRef;
-    matchedKeywordFg?: ColorRef;
-  };
-}
+import type { ColorScheme, Ramps, ModeMap } from "./color-scheme-utils";
+
+export type { ColorScheme } from "./color-scheme-utils";
 
 /**
- * Standard palette index convention (all schemes should follow this):
- *
- * | Index | Role              | Description                              |
- * |-------|-------------------|------------------------------------------|
- * | p0    | Dark surface      | Deepest surface (code blocks, mermaid)   |
- * | p1    | Danger            | Red family — errors, destructive actions  |
- * | p2    | Success           | Green family — confirmations, tips        |
- * | p3    | Warning           | Yellow/amber — caution messages           |
- * | p4    | Info              | Blue family — informational highlights    |
- * | p5    | Accent            | Primary interactive color (links, CTA)    |
- * | p6    | Neutral           | Slate/cyan — borders, secondary elements  |
- * | p7    | Secondary neutral | Gray or muted accent                      |
- * | p8    | Muted             | Gray — borders, secondary text, comments  |
- * | p9    | Background        | Page background                           |
- * | p10   | Surface           | Elevated surface (panels, sidebars)       |
- * | p11   | Text primary      | Main body text                            |
- * | p12   | Accent variant    | Brighter or alternate accent              |
- * | p13   | Decorative        | Purple/lavender — non-semantic decoration  |
- * | p14   | Accent hover      | Hover state for interactive elements      |
- * | p15   | Text secondary    | Secondary text or muted foreground         |
+ * Shared Tier-1 ramps — identical across Default Light and Default Dark.
+ * Minimized to 5 base / 3 accent (#2602). The warm-neutral spine keeps hue 65;
+ * the accent stops are the three tuned orange stops carried over from the 7-stop
+ * ramp (old accent2/3/6, re-indexed). Index 0 = lightest.
  */
-export const colorSchemes: Record<string, ColorScheme> = {
-  "Default Light": {
-    background: 9,
-    foreground: 11,
-    cursor: 6,
-    selectionBg: 11,
-    selectionFg: 10,
-    palette: [
-      "oklch(0.309 0.000 0.00)" /* #303030 */, "oklch(0.453 0.172 27.68)" /* #a01515 */, "oklch(0.398 0.090 147.43)" /* #1f5429 */, "oklch(0.451 0.130 23.94)" /* #903030 */,  // p0-3: dark surface, danger, success, warning — darkened for WCAG AA (#2298)
-      "oklch(0.441 0.144 258.56)" /* #174fa0 */, "oklch(0.453 0.0997 61.17)" /* #7d470b */, "oklch(0.704 0.040 256.99)" /* #90a1b9 */, "oklch(0.472 0.089 71.81)" /* #7a5218 */,  // p4-7: info, accent, neutral, secondary — darkened for WCAG AA (#2298)
-      "oklch(0.528 0.000 0.00)" /* #6b6b6b */, "oklch(0.901 0.007 53.44)" /* #e2ddda */, "oklch(0.936 0.003 17.22)" /* #ece9e9 */, "oklch(0.309 0.000 0.00)" /* #303030 */,  // p8-11: muted, background, surface, text
-      "oklch(0.670 0.119 251.69)" /* #5b99dc */, "oklch(0.749 0.106 300.21)" /* #b89ee7 */, "oklch(0.650 0.027 257.67)" /* #8590a0 */, "oklch(0.417 0.0755 72.95)" /* #654516 */,  // p12-15: accent variant, decorative, hover, muted foreground
-    ],
-    semantic: {
-      surface: 10,
-      muted: "oklch(0.492 0.000 0.00)" /* upstream #6b6b6b (p8) → L-0.036 for AA (scheme-a11y #2489) */, // muted-vs-bg → 4.61:1
-      accent: 5,
-      accentHover: "oklch(0.492 0.027 257.67)" /* upstream #8590a0 (p14) → L-0.158, C-0.000 for AA (scheme-a11y #2489) */, // accent-hover-vs-bg → 4.61:1
-      codeBg: 10,
-      codeFg: 11,
-      success: 2,
-      danger: 1,
-      warning: 3,
-      info: 4,
-      mermaidNoteBg: "oklch(0.821 0.007 53.44)" /* derived bg-elevated from bg (p9) — default (p0) collided 1:1 with mermaidText/p11 (scheme-a11y #2489) */,
-      imageOverlayBg: 11,
-      imageOverlayFg: 10,
-      matchedKeywordBg: "oklch(0.959 0.109 102.63)" /* #fff59d */,
-      matchedKeywordFg: "oklch(0.000 0.000 0.00)" /* #000000 */,
-    },
+const ramps: Ramps = {
+  base: [
+    "oklch(.965 .004 65)", // 0 — lightest (light bg / dark fg)
+    "oklch(.705 .008 65)", // 1 — dark muted / light selection & mermaid fill
+    "oklch(.480 .008 65)", // 2 — light muted / dark selection & mermaid note
+    "oklch(.300 .006 65)", // 3 — dark codeBg / mermaid fill
+    "oklch(.185 .005 65)", // 4 — darkest (dark bg / light fg)
+  ],
+  accent: [
+    "oklch(.755 .130 64)", // 0 — dark hover (was accent2)
+    "oklch(.700 .158 62)", // 1 — dark accent (was accent3)
+    "oklch(.470 .120 56)", // 2 — light accent (was accent6)
+  ],
+  state: {
+    danger: "oklch(.640 .170 25)",
+    success: "oklch(.680 .145 145)",
+    warning: "oklch(.760 .135 82)",
+    info: "oklch(.680 .130 245)",
+  },
+};
+
+/**
+ * Default Dark — the authored reference scheme (epic #2584; minimized #2602).
+ * bg = darkest base stop, fg = lightest. Roles merged onto shared stops:
+ * `surface`, `chatAssistantBg`, `imageOverlayBg` all = `bg` (b4) so elevated
+ * panels are bg + border only. Per-mode AA-tuned literals: `danger`,
+ * `matchedKeyword*` (carried from #2593). Full WCAG matrix passes at
+ * threshold+0.1.
+ */
+const darkMap: ModeMap = {
+  bg: { base: 4 },
+  fg: { base: 0 },
+  selectionBg: { base: 2 },
+  selectionFg: { base: 0 },
+  semantic: {
+    // Merged onto bg (b4) — elevated panels read as page-bg + border, no gray fill.
+    surface: { base: 4 },
+    muted: { base: 1 },
+    accent: { accent: 1 },
+    accentHover: { accent: 0 },
+    codeBg: { base: 3 },
+    codeFg: { base: 0 },
+    success: { state: "success" },
+    // Per-mode AA-tuned literal — shared state.danger oklch(.640 .170 25) is too
+    // dark for the danger-admonition title on its 12%-tint dark bg. L .640→.655
+    // (H/C fixed) — admonition-danger at threshold+0.1; carried from #2593.
+    danger: "oklch(.655 .170 25)",
+    warning: { state: "warning" },
+    info: { state: "info" },
+    mermaidNodeBg: { base: 3 },
+    mermaidText: { base: 0 },
+    mermaidLine: { base: 1 },
+    mermaidLabelBg: { base: 3 },
+    mermaidNoteBg: { base: 2 },
+    chatUserBg: { accent: 1 },
+    chatUserText: { base: 4 },
+    // Merged onto bg (b4) — the chat assistant bubble reads as page-bg + border.
+    chatAssistantBg: { base: 4 },
+    chatAssistantText: { base: 0 },
+    imageOverlayBg: { base: 4 },
+    imageOverlayFg: { base: 0 },
+    // Search-result <mark> highlight: an amber (accent-hue) fill with dark text —
+    // the classic highlighter look, identical in both modes. Kept as literals so
+    // the amber fill is scheme-stable; matchedKeywordFg dark so text clears AA on
+    // the amber bg — matched-keyword at threshold+0.1; carried from #2593.
+    matchedKeywordBg: "oklch(.700 .158 62)",
+    matchedKeywordFg: "oklch(.300 .003 65)",
   },
-  "Default Dark": {
-    background: 9,
-    foreground: 15,
-    cursor: 6,
-    selectionBg: 10,
-    selectionFg: 11,
-    palette: [
-      "oklch(0.226 0.000 0.00)" /* #1c1c1c */, "oklch(0.656 0.143 16.99)" /* #da6871 */, "oklch(0.746 0.103 133.16)" /* #93bb77 */, "oklch(0.809 0.096 82.54)" /* #dfbb77 */,  // p0-3: dark surface, danger, success, warning
-      "oklch(0.714 0.120 245.01)" /* #5caae9 */, "oklch(0.677 0.160 318.34)" /* #c074d6 */, "oklch(0.704 0.040 256.99)" /* #90a1b9 */, "oklch(0.706 0.000 0.00)" /* #a0a0a0 */,  // p4-7: info, accent, neutral, secondary
-      "oklch(0.627 0.000 0.00)" /* #888888 */, "oklch(0.209 0.000 0.00)" /* #181818 */, "oklch(0.341 0.000 0.00)" /* #383838 */, "oklch(0.907 0.000 0.00)" /* #e0e0e0 */,   // p8-11: muted, background, surface, text
-      "oklch(0.733 0.099 61.25)" /* #d69a66 */, "oklch(0.677 0.160 318.34)" /* #c074d6 */, "oklch(0.801 0.057 256.82)" /* #a7c0e3 */, "oklch(0.783 0.000 0.00)" /* #b8b8b8 */,  // p12-15: accent variant, decorative, hover, text secondary
-    ],
-    semantic: {
-      surface: 0,
-      muted: "oklch(0.657 0.000 0.00)" /* upstream #888888 (p8) → L+0.030 for AA (scheme-a11y #2489) */, // muted-vs-{bg,codeBg,chatAssistantBg} → 4.62:1
-      accent: 12,
-      accentHover: 14,
-      codeBg: "oklch(0.281 0.000 0.00)" /* upstream #383838 (p10) → L-0.060 toward bg for muted-vs-codeBg AA (rendered-bg #2510) */,
-      codeFg: 11,
-      success: 2,
-      danger: "oklch(0.662 0.143 16.99)" /* upstream #da6871 → L+0.006 for AA (scheme-a11y #2489) */, // admonition-danger → 4.61:1
-      warning: 3,
-      info: 4,
-      imageOverlayBg: 0,
-      imageOverlayFg: 11,
-      matchedKeywordBg: "oklch(0.959 0.109 102.63)" /* #fff59d */,
-      matchedKeywordFg: "oklch(0.000 0.000 0.00)" /* #000000 */,
-    },
+};
+
+/**
+ * Default Light — the authored light-mode scheme (epic #2584; minimized #2602).
+ * Shares `ramps` with Default Dark; the `map` inverts (light bg = lightest base
+ * stop, dark fg = darkest). Roles merged onto shared stops: `surface`, `codeBg`,
+ * `chatAssistantBg` all = `bg` (b0) so elevated panels are bg + border only
+ * (the intended flat, few-tone look — 5 stops leave no subtle near-white fill).
+ * The accent/state colors — authored for a dark bg — need darker per-mode
+ * literals to clear AA on a near-white bg. Full WCAG matrix passes at
+ * threshold+0.1; ramps untouched so Default Dark is unaffected.
+ */
+const lightMap: ModeMap = {
+  bg: { base: 0 },
+  fg: { base: 4 },
+  selectionBg: { base: 1 },
+  selectionFg: { base: 4 },
+  semantic: {
+    // Merged onto bg (b0) — elevated panels read as page-bg + border, no gray fill.
+    surface: { base: 0 },
+    muted: { base: 2 },
+    accent: { accent: 2 },
+    // Light: per-mode literal — the accent ramp has no stop darker than accent2,
+    // so the link-hover state darkens further (hover-darkens-on-light
+    // convention). L .400, C fitted to the sRGB gamut edge at that L; carried
+    // from #2595. accent-hover-vs-bg clears threshold+0.1.
+    accentHover: "oklch(.400 .096 56)",
+    // Merged onto bg (b0) — inline/code-block fill reads as page-bg + border.
+    codeBg: { base: 0 },
+    codeFg: { base: 4 },
+    // Light: per-mode literals — the shared state colors are authored for a dark
+    // bg and are too light on the 12%-tint admonition backgrounds over a light
+    // page bg. Each darkened (H fixed; C at gamut max, clipped where noted) to
+    // clear its admonition pair at threshold+0.1; carried from #2595.
+    success: "oklch(.470 .140 145)",
+    danger: "oklch(.505 .170 25)",
+    warning: "oklch(.490 .100 82)", // C .135→.100 (gamut-clips at this L)
+    info: "oklch(.485 .122 245)",
+    mermaidNodeBg: { base: 1 },
+    mermaidText: { base: 4 },
+    mermaidLine: { base: 2 },
+    mermaidLabelBg: { base: 1 },
+    mermaidNoteBg: { base: 1 },
+    chatUserBg: { accent: 1 },
+    // Dark text on the amber user bubble (matches Default Dark).
+    chatUserText: { base: 4 },
+    // Merged onto bg (b0) — the chat assistant bubble reads as page-bg + border.
+    chatAssistantBg: { base: 0 },
+    chatAssistantText: { base: 4 },
+    imageOverlayBg: { base: 4 },
+    imageOverlayFg: { base: 0 },
+    // Search-result <mark>: amber highlighter fill with dark text — same look as
+    // Default Dark (an amber-on-white highlight reads identically in both modes).
+    matchedKeywordBg: "oklch(.700 .158 62)",
+    matchedKeywordFg: "oklch(.300 .003 65)",
   },
 };
+
+export const colorSchemes: Record<string, ColorScheme> = {
+  "Default Light": { ramps, map: lightMap },
+  "Default Dark": { ramps, map: darkMap },
+};

package/templates/base/src/styles/global.css

@@ -74,18 +74,10 @@
  * Tight token strategy: import preflight + utilities only (no default theme).
  * Only project-specific tokens are available.
  *
- * Raw palette: --zd-0 to --zd-15 + bg/fg/sel (injected by ColorSchemeProvider)
+ * Base roles: --zd-bg/--zd-fg/--zd-selection-bg/--zd-selection-fg + ramps
+ * (--palette-base-0..4 / --palette-accent-0..2 / --palette-state-*) +
+ * 23 --zd-{role} semantic tokens, all injected by ColorSchemeProvider.
  * Tailwind tokens: registered below via @theme
- *
- * Palette slots:
- *   0/8:  black / bright-black (surfaces, muted text, borders)
- *   1/9:  red / bright-red
- *   2/10: green / bright-green
- *   3/11: yellow / bright-yellow
- *   4/12: blue / bright-blue
- *   5/13: magenta / bright-magenta
- *   6/14: cyan / bright-cyan
- *   7/15: white / bright-white
  * ======================================== */
 
 @theme {
@@ -117,26 +109,8 @@
   /* ── Base ── */
   --color-bg: var(--zd-bg);
   --color-fg: var(--zd-fg);
-  --color-sel-bg: var(--zd-sel-bg);
-  --color-sel-fg: var(--zd-sel-fg);
-
-  /* ── Raw palette (p0–p15) ── */
-  --color-p0: var(--zd-0);
-  --color-p1: var(--zd-1);
-  --color-p2: var(--zd-2);
-  --color-p3: var(--zd-3);
-  --color-p4: var(--zd-4);
-  --color-p5: var(--zd-5);
-  --color-p6: var(--zd-6);
-  --color-p7: var(--zd-7);
-  --color-p8: var(--zd-8);
-  --color-p9: var(--zd-9);
-  --color-p10: var(--zd-10);
-  --color-p11: var(--zd-11);
-  --color-p12: var(--zd-12);
-  --color-p13: var(--zd-13);
-  --color-p14: var(--zd-14);
-  --color-p15: var(--zd-15);
+  --color-sel-bg: var(--zd-selection-bg);
+  --color-sel-fg: var(--zd-selection-fg);
 
   /* ── Semantic aliases ── */
   --color-surface: var(--zd-surface);

package/templates/features/designTokenPanel/files/src/config/design-token-panel-config.ts

@@ -1,17 +1,61 @@
 /**
  * zdtp (zudo-design-token-panel) PanelConfig for this project.
  *
- * This config object is the single source of truth passed to
- * `configurePanel(designTokenPanelConfig)` in the bootstrap module.
+ * Single source of truth passed to `bootstrapDesignTokenPanel(...)` in
+ * `src/lib/design-token-panel-bootstrap.ts`.
  *
- * Type notes:
- * - zdtp's `ColorScheme` requires a `shikiTheme: string` field that is not
- *   present in this project's local `ColorScheme` type or data (zdtp uses it
- *   only for the panel's client-side code-block preview). Rather than an unsafe
- *   `as unknown as Record<string, ZdtpColorScheme>` double-cast, every local
- *   scheme map is run through `toZdtpColorSchemes()` below, which supplies
- *   `DEFAULT_SHIKI_THEME` as the fallback so the result satisfies zdtp's
- *   required-field shape with an ordinary type-checked assignment.
+ * Ramp-native model (mirrors zudo-doc's Color Ramp Restructure —
+ * zudolab/zudo-doc#2584 / #2592; mode-scoped Color tab — #2606 / #2610)
+ * -------------------------------------------------------------------------
+ * The color model is ramp-native (`ColorScheme = { ramps, map }`, see
+ * `src/config/color-schemes.ts`). The panel surfaces it through two tabs:
+ *
+ *  - **Palette tab** (reserved id `palette`): three `kind:'color'` OKLCH tiers —
+ *    `base` (5 stops → `--palette-base-0..4`), `accent` (3 stops →
+ *    `--palette-accent-0..2`), and `state` (4 roles → `--palette-state-{role}`).
+ *    zdtp's native L/C/H curve editor renders these. Per zdtp's palette-tab
+ *    contract, a tab carrying MULTIPLE `kind:'color'` tiers MUST omit
+ *    `colorExtras` (otherwise `resolveColorClusterFromTab` cannot pick a single
+ *    palette tier). The ramps are shared across light/dark, so token defaults
+ *    are read from the active scheme's `ramps` and stay in sync with
+ *    `color-schemes.ts`. The cssVars match the `--palette-*` custom properties
+ *    the ColorSchemeProvider emits (`schemeToCssPairs`).
+ *
+ *  - **Color tab** (reserved id `color`): a single `semantic` tier holding the
+ *    4 base roles (`--zd-bg`/`--zd-fg`/`--zd-selection-{bg,fg}`) + 23 `--zd-*`
+ *    semantic roles, each rendered as a grouped ramp dropdown. The tier declares
+ *    `referencesRamps` pointing at the Palette tab's `base`/`accent`/`state`
+ *    tiers, so each row's `default` is the encoded `tierId:itemId` ramp
+ *    reference (`buildSemanticTierItems` / `rampRefToPanelDefault`), the picker
+ *    renders grouped `<optgroup>` dropdowns, and editing emits live
+ *    `var(--palette-*)`. The tier carries NO `referencesTier` — that resolves
+ *    intra-tab only; the cross-tab wiring is `referencesRamps` + `semantic:true`.
+ *
+ * Mode-scoped defaults
+ * --------------------
+ * The Color tab's semantic defaults are MODE-SCOPED: `buildDesignTokenPanelConfig(mode)`
+ * seeds the tier from the active mode's scheme (light map vs dark map). The
+ * bootstrap (`@takazudo/zudo-doc/design-token-panel-bootstrap`) destroys +
+ * reconfigures the panel on every `color-scheme-changed` toggle so its defaults
+ * follow the live light/dark mode.
+ *
+ * Caveat: a *saved* color OVERRIDE is still mode-AGNOSTIC here — but this is
+ * this project's config-shape choice, not a zdtp limitation. zdtp 0.4.5 ships
+ * per-scheme/per-mode keyed color persistence (v4 envelope,
+ * Takazudo/zudo-design-token-panel#500 / #509): the color slice is keyed by
+ * the cluster's resolved scheme identity (`panelSettings.colorScheme` /
+ * `colorMode`). This project's color cluster is scheme-less
+ * (`colorExtras.colorSchemes = {}`, no `colorMode`) and switches modes
+ * externally via the destroy+reconfigure dance above rather than zdtp's own
+ * `colorMode` field, so zdtp always resolves the same single (stub) scheme
+ * identity and an override repaints both modes until Reset. Only the
+ * DEFAULTS are mode-faithful. Do NOT work around this by reaching into zdtp's
+ * private storage keys.
+ *
+ * The color cluster is **scheme-less**: `colorExtras.colorSchemes = {}` (zdtp's
+ * documented scheme-less cluster shape) — the ramps ARE the editable source of
+ * truth, surfaced by the Palette tab, so a bundled scheme-preset registry no
+ * longer applies.
  */
 
 import type {
@@ -20,7 +64,6 @@ import type {
   TierConfig,
   TierItem,
   ColorClusterExtras,
-  ColorScheme as ZdtpColorScheme,
   TokenDef,
 } from "@takazudo/zdtp";
 import {
@@ -28,66 +71,23 @@ import {
   FONT_TOKENS,
   SIZE_TOKENS,
 } from "./design-tokens-manifest";
+import {
+  getActiveScheme,
+  STATE_ROLES,
+  type ColorScheme,
+} from "./color-scheme-utils";
+import { buildSemanticTierItems } from "@takazudo/zudo-doc/color-scheme-utils";
 import { colorSchemes } from "./color-schemes";
-import type { ColorScheme as LocalColorScheme } from "./color-schemes";
-import { SEMANTIC_DEFAULTS, SEMANTIC_CSS_NAMES } from "./color-scheme-utils";
 import { settings } from "./settings";
-import { DESIGN_TOKEN_SCHEMA } from "@takazudo/zudo-doc/theme";
 
 /**
- * Base-role fallback indices. Background defaults to palette index 0,
- * foreground to 15, cursor to 6, selection to 0/15.
- */
-const BASE_DEFAULTS = {
-  background: 0,
-  foreground: 15,
-  cursor: 6,
-  selectionBg: 0,
-  selectionFg: 15,
-} as const;
-
-/**
- * Fallback Shiki theme used when a color scheme's `shikiTheme` field is absent.
+ * Inert fallback for the still-REQUIRED `ColorClusterExtras.defaultShikiTheme`.
+ * zdtp's Shiki integration is a no-op stub, so this value has no visible
+ * effect if you highlight code some other way — but the field is typed
+ * `string`, so a value is required.
  */
 const DEFAULT_SHIKI_THEME = "github-dark";
 
-/**
- * Normalize this project's local `ColorScheme` records into zdtp's
- * `ColorScheme` shape. zdtp's type requires `shikiTheme: string`; the local
- * scheme type makes it optional. This helper fills `DEFAULT_SHIKI_THEME` only
- * when a scheme doesn't declare its own, so the result is assignable to
- * `Record<string, ZdtpColorScheme>` via an ordinary type-checked assignment —
- * replacing the previous `as unknown as` double-cast that bypassed every field
- * check. Tracked upstream at Takazudo/zudo-design-token-panel#342 (shikiTheme
- * should be optional in zdtp's `ColorScheme` type); drop this helper once that
- * lands.
- */
-function toZdtpColorSchemes(
-  schemes: Record<string, LocalColorScheme>,
-): Record<string, ZdtpColorScheme> {
-  const normalized: Record<string, ZdtpColorScheme> = {};
-  for (const [name, scheme] of Object.entries(schemes)) {
-    normalized[name] = {
-      ...scheme,
-      shikiTheme: scheme.shikiTheme ?? DEFAULT_SHIKI_THEME,
-    };
-  }
-  return normalized;
-}
-
-/**
- * Initial palette taken from the configured active scheme.
- */
-function getInitialPalette(): readonly string[] {
-  const scheme = colorSchemes[settings.colorScheme];
-  if (!scheme) {
-    throw new Error(
-      `Unknown color scheme: "${settings.colorScheme}". Available: ${Object.keys(colorSchemes).join(", ")}`,
-    );
-  }
-  return scheme.palette;
-}
-
 // ---------------------------------------------------------------------------
 // Helpers — partition flat manifest arrays into TabConfig.tiers by group.
 // ---------------------------------------------------------------------------
@@ -129,6 +129,9 @@ function toTierItem(t: TokenDef): TierItem {
 
 /**
  * Build a tier from the subset of `tokens` whose `group` matches `groupId`.
+ * The tier's items share the same kind by construction (all items in a
+ * group share the same slider/select/text shape in this project's manifest).
+ * zdtp's `assertValidTabs` validator requires this.
  */
 function tierFromGroup(
   tokens: readonly TokenDef[],
@@ -145,100 +148,203 @@ function tierFromGroup(
 }
 
 // ---------------------------------------------------------------------------
-// Color tab — palette and semantic tiers + colorExtras for cluster metadata.
+// Palette tab — three ramp tiers (base / accent / state), OKLCH curve editor.
 // ---------------------------------------------------------------------------
 
-const PALETTE_TIER_ID = "palette";
+/**
+ * Build the three ramp tiers from the active scheme's shared `ramps`. Light
+ * and dark schemes share the same Tier-1 ramps, so the active scheme's ramps
+ * are the single source of truth — read from here rather than hardcoding a
+ * second copy of the values.
+ */
+function buildRampTiers(): TierConfig[] {
+  const { ramps } = getActiveScheme();
 
-function buildPaletteTier(): TierConfig {
-  const initial = getInitialPalette();
-  const items: TierItem[] = [];
-  for (let i = 0; i < 16; i++) {
-    items.push({
-      id: `p${i}`,
-      cssVar: `--zd-${i}`,
-      label: `p${i}`,
-      default: initial[i] ?? "#808080",
-      type: { kind: "color" },
-    });
-  }
-  return {
-    id: PALETTE_TIER_ID,
-    label: "Palette",
-    items,
+  const baseTier: TierConfig = {
+    id: "base",
+    label: "Base",
+    items: ramps.base.map((color, i): TierItem => ({
+      id: `base-${i}`,
+      cssVar: `--palette-base-${i}`,
+      label: String(i),
+      default: color,
+      type: { kind: "color", format: "oklch" },
+    })),
+  };
+
+  const accentTier: TierConfig = {
+    id: "accent",
+    label: "Accent",
+    items: ramps.accent.map((color, i): TierItem => ({
+      id: `accent-${i}`,
+      cssVar: `--palette-accent-${i}`,
+      label: String(i),
+      default: color,
+      type: { kind: "color", format: "oklch" },
+    })),
+  };
+
+  const stateTier: TierConfig = {
+    id: "state",
+    label: "State",
+    items: STATE_ROLES.map((role): TierItem => ({
+      id: `state-${role}`,
+      cssVar: `--palette-state-${role}`,
+      label: role,
+      default: ramps.state[role],
+      type: { kind: "color", format: "oklch" },
+    })),
   };
+
+  return [baseTier, accentTier, stateTier];
 }
 
-function buildSemanticTier(): TierConfig {
-  const items: TierItem[] = [];
-  for (const [key, cssVar] of Object.entries(SEMANTIC_CSS_NAMES)) {
-    const idx = SEMANTIC_DEFAULTS[key];
-    if (idx === undefined) continue;
-    items.push({
-      id: key,
-      cssVar,
-      label: key,
-      default: `p${idx}`,
-      type: { kind: "color" },
-    });
-  }
+const PALETTE_TAB: TabConfig = {
+  id: "palette",
+  label: "Palette",
+  tiers: buildRampTiers(),
+  // 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).
+};
+
+// ---------------------------------------------------------------------------
+// Color tab — mode-scoped semantic tier (4 base roles + 23 --zd-* roles) as
+// grouped ramp dropdowns referencing the Palette tab.
+// ---------------------------------------------------------------------------
+
+type PanelMode = "light" | "dark";
+
+/**
+ * Resolve the `ColorScheme` whose `map` seeds the semantic tier for `mode`.
+ * With a light/dark pair configured, picks `colorMode.{light,dark}Scheme`; on
+ * the single-scheme path (`settings.colorMode === false`) there is no pair, so
+ * the active `settings.colorScheme` is used for both modes (no toggle wiring).
+ */
+function schemeForMode(mode: PanelMode): ColorScheme {
+  const cm = settings.colorMode;
+  if (!cm) return getActiveScheme();
+  const name = mode === "dark" ? cm.darkScheme : cm.lightScheme;
+  return colorSchemes[name] ?? getActiveScheme();
+}
+
+/**
+ * Semantic tier — 4 base roles + 23 `--zd-*` roles, each a grouped ramp
+ * dropdown. `referencesRamps` names the Palette tab's ramp tiers this tier's
+ * `{ref}` mappings resolve against (cross-tab, resolved at mount by
+ * `resolveColorClusterFromTab`); `semantic: true` marks it so zdtp never
+ * mistakes it for the palette tier. Items come from `buildSemanticTierItems`:
+ * every `default` is an encoded `tierId:itemId` ramp reference, so a scheme
+ * with no override round-trips to the exact ramp stop (no snapping to a
+ * resolved color). Seeded from `schemeForMode(mode)` — this is the only
+ * mode-varying tier.
+ */
+function buildSemanticTier(mode: PanelMode): TierConfig {
   return {
     id: "semantic",
     label: "Semantic",
-    items,
-    referencesTier: PALETTE_TIER_ID,
+    semantic: true,
+    referencesRamps: [
+      { tab: "palette", tier: "base" },
+      { tab: "palette", tier: "accent" },
+      { tab: "palette", tier: "state" },
+    ],
+    items: buildSemanticTierItems(schemeForMode(mode)),
   };
 }
 
-const COLOR_EXTRAS: ColorClusterExtras = {
-  // Customize these values to match your project name to avoid localStorage
-  // collisions when multiple zudo-doc projects run in the same browser.
-  id: "my-doc",
-  label: "My Doc",
-  baseRoles: {
-    background: "--zd-bg",
-    foreground: "--zd-fg",
-    cursor: "--zd-cursor",
-    selectionBg: "--zd-sel-bg",
-    selectionFg: "--zd-sel-fg",
-  },
-  baseDefaults: BASE_DEFAULTS,
-  defaultShikiTheme: DEFAULT_SHIKI_THEME,
-  // toZdtpColorSchemes fills the fallback only for schemes without their own
-  // shikiTheme, so this is a type-checked assignment rather than an unsafe cast.
-  colorSchemes: toZdtpColorSchemes(colorSchemes),
-  panelSettings: {
-    colorScheme: settings.colorScheme,
-    // colorMode: strip off respectPrefersColorScheme (not in zdtp's shape).
-    colorMode: settings.colorMode
-      ? {
-          defaultMode: settings.colorMode.defaultMode,
-          lightScheme: settings.colorMode.lightScheme,
-          darkScheme: settings.colorMode.darkScheme,
-        }
-      : false,
-  },
-};
+/**
+ * Color cluster extras. Scheme-less (`colorSchemes: {}`) with no base-role
+ * editors (`baseRoles`/`baseDefaults` empty) — the Palette tab owns the ramps
+ * and the semantic tier owns the roles.
+ *
+ * `panelSettings.colorMode` is an OBJECT (not `false`) with `defaultMode = mode`.
+ * On this scheme-less cluster its only live effect is `getClusterDefaultMode()`,
+ * which drives the per-mode literal collapse/preview side — pinning it to the
+ * ACTIVE mode keeps that side following the live toggle (a bare `false` would
+ * pin it to `light` and mis-collapse per-mode literals for a dark-mode user).
+ * `colorScheme`/`lightScheme`/`darkScheme` only need to be non-empty strings
+ * (the validator requires that even with `colorSchemes: {}`; the names are not
+ * checked against the empty registry).
+ */
+function buildColorExtras(mode: PanelMode): ColorClusterExtras {
+  const cm = settings.colorMode;
+  const lightScheme = cm ? cm.lightScheme : settings.colorScheme;
+  const darkScheme = cm ? cm.darkScheme : settings.colorScheme;
+  return {
+    // Customize id/label to match your project name to avoid localStorage
+    // collisions when multiple zudo-doc-based projects run in the same browser.
+    id: "my-doc",
+    label: "My Doc",
+    baseRoles: {},
+    baseDefaults: {},
+    defaultShikiTheme: DEFAULT_SHIKI_THEME,
+    colorSchemes: {},
+    panelSettings: {
+      colorScheme: settings.colorScheme,
+      colorMode: { defaultMode: mode, lightScheme, darkScheme },
+    },
+  };
+}
 
-const COLOR_TAB: TabConfig = {
-  id: "color",
-  label: "Color",
-  tiers: [buildPaletteTier(), buildSemanticTier()],
-  colorExtras: COLOR_EXTRAS,
-};
+function buildColorTab(mode: PanelMode): TabConfig {
+  return {
+    id: "color",
+    label: "Color",
+    tiers: [buildSemanticTier(mode)],
+    colorExtras: buildColorExtras(mode),
+  };
+}
 
 // ---------------------------------------------------------------------------
-// Font tab
+// Font tab — five tiers grouped by the manifest's `group` field.
 // ---------------------------------------------------------------------------
 
 const FONT_SCALE_TIER_ID = "font-scale";
 
+/**
+ * Tier 2 semantic role → Tier 1 abstract scale item id. Mirrors the `var(--…)`
+ * wiring in `global.css` (`--text-body: var(--text-scale-md)` etc.). The role
+ * tier is a *reference* tier: each item's stored value is the id of a
+ * `font-scale` item, exactly like the Color tab's semantic→palette tier. zdtp
+ * renders these as dropdowns and emits `var(--text-scale-*)`, so editing a
+ * scale step propagates to every role live.
+ */
+const FONT_ROLE_TO_SCALE: Readonly<Record<string, string>> = {
+  "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",
+};
+
+/**
+ * Build the semantic font-size tier as a reference tier pointing at the
+ * `font-scale` tier. Defaults are overridden to the referenced scale id (the
+ * manifest still records resolved rem values for serde / the flat-manifest
+ * generator template, so the override happens here rather than in the
+ * manifest to keep both consumers correct).
+ */
+function buildFontRoleTier(): TierConfig {
+  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,
+  };
+}
+
 const FONT_TAB: TabConfig = {
   id: "font",
   label: "Font",
   tiers: [
     tierFromGroup(FONT_TOKENS, FONT_SCALE_TIER_ID, "Scale"),
-    tierFromGroup(FONT_TOKENS, "font-size", "Font size"),
+    buildFontRoleTier(),
     tierFromGroup(FONT_TOKENS, "line-height", "Line height"),
     tierFromGroup(FONT_TOKENS, "font-weight", "Font weight"),
     tierFromGroup(FONT_TOKENS, "font-family", "Font family"),
@@ -246,7 +352,7 @@ const FONT_TAB: TabConfig = {
 };
 
 // ---------------------------------------------------------------------------
-// Spacing tab
+// Spacing tab — four tiers grouped by the manifest's `group` field.
 // ---------------------------------------------------------------------------
 
 const SPACING_TAB: TabConfig = {
@@ -261,7 +367,7 @@ const SPACING_TAB: TabConfig = {
 };
 
 // ---------------------------------------------------------------------------
-// Size tab
+// Size tab — two tiers grouped by the manifest's `group` field.
 // ---------------------------------------------------------------------------
 
 const SIZE_TAB: TabConfig = {
@@ -273,16 +379,57 @@ const SIZE_TAB: TabConfig = {
   ],
 };
 
-export const designTokenPanelConfig: PanelConfig = {
-  // Customize these values to match your project name to avoid localStorage
-  // collisions when multiple zudo-doc projects run in the same browser.
-  storagePrefix: "my-doc-tweak",
-  consoleNamespace: "myDoc",
-  modalClassPrefix: "my-doc-design-token-panel-modal",
-  // Must match DESIGN_TOKEN_SCHEMA in @takazudo/zudo-doc/theme so that
-  // exported JSON files remain importable across panel versions.
-  schemaId: DESIGN_TOKEN_SCHEMA,
-  exportFilenameBase: "my-doc-design-tokens",
-  tabs: [COLOR_TAB, FONT_TAB, SPACING_TAB, SIZE_TAB],
-  colorPresets: {},
-};
+/**
+ * Detect the initial color-scheme mode for the first `configurePanel` call. In
+ * the browser, read `<html data-theme>` (set pre-paint by the
+ * ColorSchemeProvider bootstrap); otherwise fall back to
+ * `settings.colorMode.defaultMode` (or `light` on the single-scheme path).
+ * SSR-safe: guards `document`.
+ */
+function detectInitialMode(): PanelMode {
+  if (typeof document !== "undefined") {
+    const attr = document.documentElement.getAttribute("data-theme");
+    if (attr === "light" || attr === "dark") return attr;
+  }
+  const cm = settings.colorMode;
+  return cm ? cm.defaultMode : "light";
+}
+
+/**
+ * Build the full 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. The bootstrap calls
+ * this per mode on every `color-scheme-changed` toggle (destroy + reconfigure).
+ */
+export function buildDesignTokenPanelConfig(mode: PanelMode): PanelConfig {
+  return {
+    // Customize these values to match your project name to avoid localStorage
+    // collisions when multiple zudo-doc-based projects run in the same browser.
+    storagePrefix: "my-doc-tweak",
+    consoleNamespace: "myDoc",
+    modalClassPrefix: "my-doc-design-token-panel-modal",
+    // DISPLAY-ONLY in zdtp 0.4.5: 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; it only labels the Import-modal hint. zdtp DOES export its own
+    // `SCHEMA_V1`/`SCHEMA_V2`/`SCHEMA_V3` constants (#498/#505), but those are
+    // zdtp's fixed internal schema strings, unrelated to this field. Set to v3
+    // (a literal, not one of those constants) so the hint matches what exports
+    // actually carry.
+    schemaId: "zudo-design-tokens/v3",
+    exportFilenameBase: "my-doc-design-tokens",
+    tabs: [PALETTE_TAB, buildColorTab(mode), FONT_TAB, SPACING_TAB, SIZE_TAB],
+  };
+}
+
+/**
+ * Back-compat / initial-call export: the config for the mode detected at module
+ * load. Pass the `buildDesignTokenPanelConfig` BUILDER (not this plain object)
+ * to the bootstrap for live mode-scoped rebuilds on light/dark toggle — see
+ * `src/lib/design-token-panel-bootstrap.ts`. This plain-config export remains
+ * for callers that only need a static config.
+ */
+export const designTokenPanelConfig: PanelConfig = buildDesignTokenPanelConfig(
+  detectInitialMode(),
+);

package/templates/features/designTokenPanel/files/src/lib/design-token-panel-bootstrap.ts

@@ -5,9 +5,16 @@
  * settings.designTokenPanel is truthy. The dynamic import is gated there so
  * this module is only bundled when the feature is enabled.
  *
- * The wiring MECHANISM (configurePanel + setLifecycleAdapter) now lives in the
- * package at `@takazudo/zudo-doc/design-token-panel-bootstrap`. This file
- * passes the project's PanelConfig DATA to that mechanism.
+ * The wiring MECHANISM (configurePanel + setLifecycleAdapter + the mode-scoped
+ * reconfigure) lives in the package at
+ * `@takazudo/zudo-doc/design-token-panel-bootstrap`. This file passes the
+ * project's PanelConfig DATA to that mechanism.
+ *
+ * We pass the `buildDesignTokenPanelConfig` BUILDER (not the plain
+ * `designTokenPanelConfig` object) so the bootstrap rebuilds the panel per
+ * light/dark mode on every `color-scheme-changed` toggle — keeping the Color
+ * tab's semantic defaults mode-faithful. A plain-config caller also works (see
+ * `bootstrapDesignTokenPanel`'s JSDoc) but gets no toggle listener.
  *
  * S9a package-first migration — zudolab/zudo-doc#2333.
  *
@@ -18,6 +25,6 @@
  */
 
 import { bootstrapDesignTokenPanel } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
-import { designTokenPanelConfig } from "@/config/design-token-panel-config";
+import { buildDesignTokenPanelConfig } from "@/config/design-token-panel-config";
 
-bootstrapDesignTokenPanel(designTokenPanelConfig);
+bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);