create-zudo-sg 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to `create-zudo-sg` are documented in this file.
 
 The format is based on Keep a Changelog.
 
+## [0.1.4] - 2026-09-21
+
+Gives a fresh starter a working preview token panel, not just the button that
+opens one.
+
+### Added
+
+- Scaffold the wiring the preview token panel needs: a `_body-end-islands.tsx`
+  that mounts `PreviewTokenPanelBootstrap` on the injected `/components/*` and
+  `/tokens` routes, a `_chrome-bindings.tsx`, a generated
+  `src/styleguide/token-manifest.ts`, and a `src/config/preview-token-panel-tabs.ts`
+  the panel reads its tabs from.
+- Turn on `bundleZdtp` and a tabs-only `zdtpApplyProxy` in the starter's
+  `zfb.config.ts`, so the panel gets the real zdtp loader instead of the
+  throwing stub without opting into the dev-only Apply endpoint.
+
+### Changed
+
+- Update the starter engine range to `@takazudo/zudo-sg ^0.3.1`, whose header
+  token trigger opens the panel the scaffold now wires.
+- Document the new scaffold contents and the `routingFile` + `writeRoot` opt-in
+  for the panel's Apply step in the README.
+
+## [0.1.3] - 2026-09-21
+
+Stops fresh starters from requesting favicons they never shipped, and moves
+them onto the engine's new chrome token namespace.
+
+### Fixed
+
+- Set the starter's favicon to the self-contained inline icon instead of
+  advertising four `/favicon*` files the template does not create, which made a
+  clean build log four missing-asset errors on first load.
+- Verify after every packed build that each local head asset a generated page
+  links to actually exists, so a reintroduced missing icon or stylesheet fails
+  the release gate rather than the adopter's browser console.
+
+### Changed
+
+- Update the starter engine range to `@takazudo/zudo-sg ^0.3.0`, which reads its
+  chrome colors from the `--sg-*` namespace. The starter's own stylesheet now
+  sets those roles explicitly, so the catalog chrome renders correctly whatever
+  order a project imports its component theme in.
+
 ## [0.1.2] - 2026-09-20
 
 Gives fresh starter projects a styled homepage and usable default navigation.

package/README.md

@@ -49,11 +49,18 @@ overwrite an existing project.
 The template is a minimal host, not a copy of this repository's full site. It
 contains:
 
-- `zfb.config.ts` composing `zudoDoc()` and `withZudoSg()` with a root base.
+- `zfb.config.ts` composing `zudoDoc()` and `withZudoSg()` with a root base,
+  `bundleZdtp: true`, and `chromeBindingsModule: "./pages/lib/_chrome-bindings.tsx"`.
+- `zfb.config.ts` uses an inline `favicon: "auto"`; replace it with a path or `FaviconConfig` when adding real icons under `public/`.
 - `zudo-sg.config.mjs` with a local `ui/` components root, registry output,
-  preview stylesheet, category order, and token-manifest inputs.
-- `pages/index.tsx` and an optional `pages/lib/_zudo-sg-islands.ts` import
-  shim for the host page.
+  preview stylesheet, category order, token-manifest inputs, and a tabs-only
+  `zdtpApplyProxy: { tabsModule }` (see "The preview token panel, out of the
+  box" below).
+- `pages/index.tsx`, `pages/lib/_body-end-islands.tsx`, and
+  `pages/lib/_chrome-bindings.tsx`, plus an optional
+  `pages/lib/_zudo-sg-islands.ts` import shim, for the host page and for
+  mounting the preview token panel on the injected `/components/*` and
+  `/tokens` routes.
 - Three small Preact examples under `ui/`: Button, Card, and Counter, with
   co-located stories and a Button MDX document.
 - `src/styleguide/sg-registry.ts`, generated from the three example stories.
@@ -72,6 +79,37 @@ renames the package-safe `_gitignore` to `.gitignore`. The token manifest is
 generated after installation; it is intentionally not checked into the
 template seed.
 
+## The preview token panel, out of the box
+
+`withZudoSg()` injects a header button (the tokens icon, hidden outside the
+catalog routes) that opens the engine's preview token panel — the same panel
+a component detail page's workbench toolbar and the `/tokens` dashboards
+open. This is on by default (`headerTokenTrigger: true`); the scaffold does
+not need to wire it.
+
+What the scaffold does still wire, so the button opens a *working* panel
+instead of an inert one:
+
+- `zudo-sg.config.mjs`'s `zdtpApplyProxy: { tabsModule: "./src/config/preview-token-panel-tabs.ts" }`
+  gives the panel its manifest-derived tabs. Without a `tabsModule` the panel
+  has nothing to render.
+- `pages/lib/_chrome-bindings.tsx`, wired via `chromeBindingsModule`, mounts
+  `pages/lib/_body-end-islands.tsx` (which bootstraps the panel) on the
+  injected `/components/*` and `/tokens` routes too, not just the host-owned
+  `/`.
+
+This ships **tabs without the Apply write sandbox** — `zdtpApplyProxy` also
+accepts `routingFile` and `writeRoot`, together, as an opt-in next step: they
+let the panel's **Apply** button persist a tweak directly into your project's
+CSS source under a running `pnpm dev`, instead of round-tripping through
+`localStorage`/JSON export only. `routingFile` and `writeRoot` are optional
+together (a tabs-only config, as shipped, omits both); supplying one without
+the other is invalid. A fresh scaffold has no sensible default `writeRoot`,
+which is why this step is left for you to add once your CSS source layout is
+settled — see the root project's
+[Design Token Panel guide](https://github.com/Takazudo/zudo-sg/blob/main/src/content/docs/overview/token-panels.mdx)
+for the wiring shape.
+
 ## Styles
 
 zfb discovers `src/styles/global.css` automatically; no page import or config
@@ -100,6 +138,32 @@ host defines consumer-only color tokens before zudo-doc's theme, replace
 omits the color-token reset; tokens defined by both stylesheets still follow
 source order.
 
+### Three token worlds and engine overrides
+
+The generated host has three color-token worlds: zudo-doc's `--zd-*` roles for the
+documentation shell, zudo-sg's raw `--sg-*` roles for catalog chrome, and the host
+component library's own `@theme` color tokens (usually `--color-*`) for previewed
+components. Keep the engine and component-library roles separate.
+
+The engine defaults are plain `--sg-*` properties under `:where(:root)`, so zudo-doc's
+`theme.css` `--color-*` reset cannot erase them. Retheme engine chrome with an ordinary,
+unlayered override in any import position:
+
+```css
+:root {
+  --sg-border: oklch(0.72 0.02 65);
+}
+```
+
+If the host previously used bare `--color-border` to style engine chrome, migrate that
+declaration to `--sg-border` (and migrate each other chrome role to its corresponding
+`--sg-*` role). `--color-border` can still style the host's own components. The
+order-proof engine hook does not change the import-order contract for those host-owned
+`@theme` colors: import `theme.css` before them, or deliberately use
+`theme-no-reset.css` when their earlier declaration must be preserved. This is the
+zudo-doc namespace contract for host-owned color tokens; the engine's raw `--sg-*`
+namespace is separate.
+
 The preview document uses `src/styles/preview-entry.css` independently. Add
 your component package's styles and source scan there too when previews need
 them; its `@source` paths are relative to that stylesheet. Keep dashboard and
@@ -119,7 +183,10 @@ checks each optional package independently.
 The starter targets Preact + zfb hosts. Keep these dependencies in a host
 that adopts the engine:
 
-- `@takazudo/zdtp` is required by the injected `/tokens` route at build time.
+- `@takazudo/zdtp` is required by the injected `/tokens` route at build time,
+  and by the header trigger's preview token panel at runtime — `bundleZdtp: true`
+  in the generated `zfb.config.ts` keeps that panel on the real zdtp loader
+  instead of zudo-doc's throwing stub (zudolab/zudo-doc#4261). Do not drop it.
 - `diff` and `katex` are required by the published zudo-doc route dist that
   the host loads, even when the corresponding optional features are disabled.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-sg",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Create a new zudo-sg styleguide project",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/default/package.json

@@ -17,7 +17,7 @@
     "@takazudo/zfb-md-wasm": "2.20.0",
     "@takazudo/zfb-runtime": "2.20.0",
     "@takazudo/zudo-doc": "5.26.2",
-    "@takazudo/zudo-sg": "^0.2.2",
+    "@takazudo/zudo-sg": "^0.3.1",
     "diff": "^8.0.4",
     "katex": "^0.16.38",
     "preact": "^10.29.1",

package/templates/default/pages/index.tsx

@@ -4,6 +4,11 @@
 import type { JSX } from "preact";
 // Optional islands seed; see pages/lib/_zudo-sg-islands.ts.
 import "./lib/_zudo-sg-islands";
+// Statically imported (not just reached through `chromeBindingsModule`'s
+// virtual re-export) so zfb's island scanner is guaranteed to discover
+// PreviewTokenPanelBootstrap and register it under its SSR marker — mirrors
+// the sibling zudo-doc showcase's pages/index.tsx import of the same chain.
+import { BodyEndIslands } from "./lib/_body-end-islands";
 
 export const frontmatter = { title: "Styleguide starter" };
 
@@ -34,6 +39,7 @@ export default function IndexPage(): JSX.Element {
             </a>
           </nav>
         </main>
+        <BodyEndIslands />
       </body>
     </html>
   );

package/templates/default/pages/lib/_body-end-islands.tsx

@@ -0,0 +1,60 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host-side body-end islands helper.
+//
+// Mirrors the sibling zudo-doc showcase's pages/lib/_body-end-islands.tsx,
+// minus the doc-site islands this starter has no use for (AI chat, mermaid,
+// doc-history, client-router bootstrap): this starter mounts only the
+// engine's preview zdtp token panel bootstrap (`toggle-preview-token-panel`),
+// which the header trigger `withZudoSg` injects opens.
+//
+// pages/index.tsx imports this file directly (as well as reaching it through
+// `_chrome-bindings.tsx`'s `chromeBindingsModule` wiring), so zfb's island
+// scanner is guaranteed to walk page -> this helper -> the real
+// PreviewTokenPanelBootstrap component and register its constructor under the
+// SSR marker name. `chromeBindingsModule` then makes the injected
+// /components/* and /tokens routes render the same marker, so they hydrate
+// against that registered constructor too — not just this starter's
+// host-owned `/`.
+
+import type { VNode, JSX } from "preact";
+import { Island } from "@takazudo/zfb";
+import PreviewTokenPanelBootstrap from "@takazudo/zudo-sg/token-tweak/preview-token-panel-bootstrap";
+
+(PreviewTokenPanelBootstrap as { displayName?: string }).displayName = "PreviewTokenPanelBootstrap";
+
+function prehydrationPanelToggleScript(toggleEvent: string): string {
+  return `(${function capturePanelToggle(channel: string) {
+    const script = document.currentScript as (HTMLScriptElement & {
+      __zdtpPrehydrateListener?: EventListener;
+    }) | null;
+    if (!script || script.dataset.bound === "1") return;
+    script.dataset.bound = "1";
+    script.dataset.pending = "0";
+    const listener = () => {
+      script.dataset.pending = String(Number(script.dataset.pending ?? "0") + 1);
+    };
+    script.__zdtpPrehydrateListener = listener;
+    window.addEventListener(channel, listener);
+  }.toString()})(${JSON.stringify(toggleEvent)});`;
+}
+
+/**
+ * The body-end islands this starter mounts. Currently just the preview
+ * token panel bootstrap the header trigger opens.
+ */
+export function BodyEndIslands(): JSX.Element {
+  return (
+    <>
+      {/* Capture pre-hydration clicks; the bootstrap drains this once it loads. */}
+      <script
+        id="zdtp-preview-prehydrate"
+        dangerouslySetInnerHTML={{ __html: prehydrationPanelToggleScript("toggle-preview-token-panel") }}
+      />
+      {Island({
+        when: "load",
+        children: <PreviewTokenPanelBootstrap />,
+      }) as unknown as VNode}
+    </>
+  );
+}

package/templates/default/pages/lib/_chrome-bindings.tsx

@@ -0,0 +1,23 @@
+// Host-callables channel for the package-owned routes (#113 upstream;
+// mirrors the sibling zudo-doc showcase's pages/lib/_chrome-bindings.tsx).
+//
+// `settings.chromeBindingsModule` points the zudo-doc routes plugin at this
+// module; it re-exports `chromeBindings` into
+// `virtual:zudo-doc-chrome-bindings`, which the injected chrome shim spreads
+// into `createChrome(routeCtx, { ...chromeBindings })`. Every slot we omit
+// keeps its package default.
+//
+// We override only BodyEndIslands: the package default excludes the host
+// token-panel bootstrap, but this starter mounts the engine's preview zdtp
+// panel (`toggle-preview-token-panel`). Without this binding, a body-end
+// islands file imported only from pages/index.tsx would cover the host-owned
+// `/` and leave the injected /components/* and /tokens routes on the
+// package-default BodyEndIslands — i.e. the header trigger's panel would not
+// mount on the pages that need it.
+
+import type { ChromeHostBindings } from "@takazudo/zudo-doc/factory-context";
+import { BodyEndIslands } from "./_body-end-islands";
+
+export const chromeBindings: ChromeHostBindings = {
+  BodyEndIslands,
+};

package/templates/default/pnpm-workspace.yaml

@@ -12,4 +12,4 @@ minimumReleaseAgeExclude:
   - "@takazudo/zfb-win32-x64-msvc@2.20.0"
   - "@takazudo/zfb@2.20.0"
   - "@takazudo/zudo-doc@5.26.2"
-  - "@takazudo/zudo-sg@0.2.2"
+  - "@takazudo/zudo-sg@0.3.1"

package/templates/default/src/config/preview-token-panel-tabs.ts

@@ -0,0 +1,25 @@
+// Host data for the engine's preview token panel: the manifest-derived tab set
+// re-exported by `@takazudo/zudo-sg/plugins/zdtp-apply-proxy`'s
+// `virtual:zudo-sg-preview-token-panel` (`zdtpApplyProxy.tabsModule` option in
+// zudo-sg.config.mjs). Without a tabs module the panel bootstrap short-circuits
+// and the header trigger button opens nothing (see
+// preview-token-panel-bootstrap.tsx).
+import { buildUiTokenTabs } from "@takazudo/zudo-sg/token-dashboard";
+import type { UiDesignTokensManifest } from "@takazudo/zudo-sg/token-dashboard";
+import {
+  UI_PALETTE_COLORS,
+  UI_COLOR_TOKENS,
+  UI_SPACING_TOKENS,
+  UI_FONT_TOKENS,
+  UI_SIZE_TOKENS,
+} from "../styleguide/token-manifest.ts";
+
+const uiDesignTokensManifest: UiDesignTokensManifest = {
+  paletteColors: UI_PALETTE_COLORS,
+  colorTokens: UI_COLOR_TOKENS,
+  spacingTokens: UI_SPACING_TOKENS,
+  fontTokens: UI_FONT_TOKENS,
+  sizeTokens: UI_SIZE_TOKENS,
+};
+
+export const tabs = buildUiTokenTabs(uiDesignTokensManifest);

package/templates/default/src/styleguide/token-manifest.ts

@@ -0,0 +1,754 @@
+/**
+ * Design-token manifest for configured UI tokens.
+ *
+ * GENERATED — do not hand-edit. Run `zudo-sg gen-token-manifest` after changing
+ * either configured source file, then commit the regenerated output.
+ * `zudo-sg gen-token-manifest --check` fails on drift.
+ *
+ * Source of truth: `src/styles/ui-tokens.css`,
+ * parsed by the `zudo-sg gen-token-manifest` CLI command
+ * (@takazudo/zudo-sg's src/cli/token-manifest/ui-token-manifest.ts). Only
+ * `default` values are derived from the CSS; `group`/`step`/`unit`/
+ * `control`/`options`/`pill` are presentation metadata with no CSS
+ * equivalent and are configured in that module's SPECS tables.
+ *
+ * Covers: Color / Spacing / Font / Size tabs.
+ * Does NOT include any --zd-* doc-chrome tokens.
+ */
+import type { TokenDef } from "@takazudo/zdtp";
+
+// --- Font weight select options ---
+const FONT_WEIGHT_OPTIONS = [
+  "100", "200", "300", "400", "500", "600", "700", "800", "900",
+] as const;
+
+/**
+ * Tier-1 raw palette colors from `src/styles/ui-tokens.css` (the `:root`
+ * `--palette-{group}-{step-or-role}` block). This is the raw material beneath the
+ * semantic `--color-*` tokens in UI_COLOR_TOKENS below — same three-tier
+ * model the doc-chrome panel exposes via `--palette-*` ramps and `--zd-*`
+ * semantic roles.
+ *
+ * These are plain name/value descriptors (NOT `TokenDef`) because zdtp's
+ * `TokenDef.control` has no `"color"` option — the preview panel builds them
+ * into `{ kind: "color" }` TierItems inline, mirroring the doc panel's
+ * ramp tiers. Rendered as a "Palette" swatch tier in the preview
+ * panel's Color tab; editing a swatch pushes `--palette-*` to the preview
+ * iframes via the sink, cascading into every semantic token that references it.
+ *
+ * Coverage: 36 colors.
+ */
+export interface UiPaletteColor {
+  /** Palette key without the `--palette-` prefix, e.g. "neutral-2". */
+  name: string;
+  /** Raw oklch value, from `src/styles/ui-tokens.css`. */
+  value: string;
+}
+
+export const UI_PALETTE_COLORS: readonly UiPaletteColor[] = [
+  { name: "neutral-0", value: "#ffffff" },
+  { name: "neutral-1", value: "#e2e8f0" },
+  { name: "neutral-2", value: "#475569" },
+  { name: "neutral-3", value: "#0f172a" },
+  { name: "accent-0", value: "#dbeafe" },
+  { name: "accent-1", value: "#93c5fd" },
+  { name: "accent-2", value: "#2563eb" },
+  { name: "accent-3", value: "#1e40af" },
+  { name: "state-danger", value: "#dc2626" },
+  { name: "state-danger-dark", value: "#f87171" },
+  { name: "state-success", value: "#15803d" },
+  { name: "state-success-dark", value: "#4ade80" },
+  { name: "state-warning", value: "#a16207" },
+  { name: "state-warning-dark", value: "#facc15" },
+  { name: "state-info", value: "#0369a1" },
+  { name: "state-info-dark", value: "#38bdf8" },
+  { name: "line-vacuum-accent", value: "#2563eb" },
+  { name: "line-vacuum-accent-dark", value: "#93c5fd" },
+  { name: "line-vacuum-hover", value: "#1e40af" },
+  { name: "line-vacuum-hover-dark", value: "#dbeafe" },
+  { name: "line-process-accent", value: "#2563eb" },
+  { name: "line-process-accent-dark", value: "#93c5fd" },
+  { name: "line-process-hover", value: "#1e40af" },
+  { name: "line-process-hover-dark", value: "#dbeafe" },
+  { name: "line-laser-accent", value: "#2563eb" },
+  { name: "line-laser-accent-dark", value: "#93c5fd" },
+  { name: "line-laser-hover", value: "#1e40af" },
+  { name: "line-laser-hover-dark", value: "#dbeafe" },
+  { name: "line-meeting-accent", value: "#2563eb" },
+  { name: "line-meeting-accent-dark", value: "#93c5fd" },
+  { name: "line-meeting-hover", value: "#1e40af" },
+  { name: "line-meeting-hover-dark", value: "#dbeafe" },
+  { name: "line-beauty-accent", value: "#2563eb" },
+  { name: "line-beauty-accent-dark", value: "#93c5fd" },
+  { name: "line-beauty-hover", value: "#1e40af" },
+  { name: "line-beauty-hover-dark", value: "#dbeafe" },
+];
+
+/**
+ * Color tokens from `src/styles/ui-tokens.css`.
+ *
+ * All values use light-dark() for dual-scheme support. Defaults here are
+ * the full CSS declarations including both light and dark sides.
+ * Stored as read-only text rows because light-dark() expressions cannot
+ * be driven by a single-axis slider.
+ *
+ * Coverage: 21 tokens total.
+ */
+export const UI_COLOR_TOKENS: readonly TokenDef[] = [
+  {
+    id: "ui-color-bg",
+    cssVar: "--color-bg",
+    label: "color-bg",
+    group: "surface",
+    default: "#ffffff",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-surface",
+    cssVar: "--color-surface",
+    label: "color-surface",
+    group: "surface",
+    default: "light-dark(#ffffff, #0f172a)",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-surface-2",
+    cssVar: "--color-surface-2",
+    label: "color-surface-2",
+    group: "surface",
+    default: "light-dark(#e2e8f0, #475569)",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-border",
+    cssVar: "--color-border",
+    label: "color-border",
+    group: "surface",
+    default: "#475569",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  // Translucent frost scrim derived from --color-bg (SPA loading overlay).
+  {
+    id: "ui-color-loading-scrim",
+    cssVar: "--color-loading-scrim",
+    label: "color-loading-scrim",
+    group: "surface",
+    default: "#ffffff80",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-fg",
+    cssVar: "--color-fg",
+    label: "color-fg",
+    group: "text",
+    default: "#0f172a",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-muted",
+    cssVar: "--color-muted",
+    label: "color-muted",
+    group: "text",
+    default: "#475569",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-accent",
+    cssVar: "--color-accent",
+    label: "color-accent",
+    group: "accent",
+    default: "#2563eb",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-accent-hover",
+    cssVar: "--color-accent-hover",
+    label: "color-accent-hover",
+    group: "accent",
+    default: "#1e40af",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  // Foreground token for text/icons on filled accent/state surfaces (consumed via `text-on-accent`).
+  {
+    id: "ui-color-on-accent",
+    cssVar: "--color-on-accent",
+    label: "color-on-accent",
+    group: "accent",
+    default: "#ffffff",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-focus",
+    cssVar: "--color-focus",
+    label: "color-focus",
+    group: "accent",
+    default: "#2563eb",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-rail-bg",
+    cssVar: "--color-rail-bg",
+    label: "color-rail-bg",
+    group: "rail",
+    default: "#0f172a",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-rail-bg-strong",
+    cssVar: "--color-rail-bg-strong",
+    label: "color-rail-bg-strong",
+    group: "rail",
+    default: "#0f172a",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-rail-fg",
+    cssVar: "--color-rail-fg",
+    label: "color-rail-fg",
+    group: "rail",
+    default: "#ffffff",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-rail-muted",
+    cssVar: "--color-rail-muted",
+    label: "color-rail-muted",
+    group: "rail",
+    default: "#e2e8f0",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-rail-border",
+    cssVar: "--color-rail-border",
+    label: "color-rail-border",
+    group: "rail",
+    default: "#475569",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-rail-hover-bg",
+    cssVar: "--color-rail-hover-bg",
+    label: "color-rail-hover-bg",
+    group: "rail",
+    default: "#475569",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-success",
+    cssVar: "--color-success",
+    label: "color-success",
+    group: "state",
+    default: "#15803d",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-danger",
+    cssVar: "--color-danger",
+    label: "color-danger",
+    group: "state",
+    default: "#dc2626",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-warning",
+    cssVar: "--color-warning",
+    label: "color-warning",
+    group: "state",
+    default: "#a16207",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-color-info",
+    cssVar: "--color-info",
+    label: "color-info",
+    group: "state",
+    default: "#0369a1",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+];
+
+/**
+ * Spacing tokens from `src/styles/ui-tokens.css`.
+ *
+ * Coverage: 15 tokens total.
+ */
+export const UI_SPACING_TOKENS: readonly TokenDef[] = [
+  {
+    id: "ui-hsp-2xs",
+    cssVar: "--spacing-hsp-2xs",
+    label: "hsp-2xs",
+    group: "hsp",
+    default: "0.125rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-hsp-xs",
+    cssVar: "--spacing-hsp-xs",
+    label: "hsp-xs",
+    group: "hsp",
+    default: "0.25rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-hsp-sm",
+    cssVar: "--spacing-hsp-sm",
+    label: "hsp-sm",
+    group: "hsp",
+    default: "0.5rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-hsp-md",
+    cssVar: "--spacing-hsp-md",
+    label: "hsp-md",
+    group: "hsp",
+    default: "1rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-hsp-lg",
+    cssVar: "--spacing-hsp-lg",
+    label: "hsp-lg",
+    group: "hsp",
+    default: "1.5rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-hsp-xl",
+    cssVar: "--spacing-hsp-xl",
+    label: "hsp-xl",
+    group: "hsp",
+    default: "2rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-hsp-2xl",
+    cssVar: "--spacing-hsp-2xl",
+    label: "hsp-2xl",
+    group: "hsp",
+    default: "3rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-3xs",
+    cssVar: "--spacing-vsp-3xs",
+    label: "vsp-3xs",
+    group: "vsp",
+    default: "0.0625rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-2xs",
+    cssVar: "--spacing-vsp-2xs",
+    label: "vsp-2xs",
+    group: "vsp",
+    default: "0.125rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-xs",
+    cssVar: "--spacing-vsp-xs",
+    label: "vsp-xs",
+    group: "vsp",
+    default: "0.25rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-sm",
+    cssVar: "--spacing-vsp-sm",
+    label: "vsp-sm",
+    group: "vsp",
+    default: "0.5rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-md",
+    cssVar: "--spacing-vsp-md",
+    label: "vsp-md",
+    group: "vsp",
+    default: "1rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-lg",
+    cssVar: "--spacing-vsp-lg",
+    label: "vsp-lg",
+    group: "vsp",
+    default: "1.5rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-xl",
+    cssVar: "--spacing-vsp-xl",
+    label: "vsp-xl",
+    group: "vsp",
+    default: "2rem",
+    step: 0.025,
+    unit: "rem",
+  },
+  {
+    id: "ui-vsp-2xl",
+    cssVar: "--spacing-vsp-2xl",
+    label: "vsp-2xl",
+    group: "vsp",
+    default: "3rem",
+    step: 0.025,
+    unit: "rem",
+  },
+];
+
+/**
+ * Font tokens from `src/styles/ui-tokens.css`.
+ *
+ * Coverage: 22 tokens total.
+ */
+export const UI_FONT_TOKENS: readonly TokenDef[] = [
+  {
+    id: "ui-text-xs",
+    cssVar: "--text-xs",
+    label: "text-xs",
+    group: "font-size",
+    default: "0.75rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-text-sm",
+    cssVar: "--text-sm",
+    label: "text-sm",
+    group: "font-size",
+    default: "0.875rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-text-base",
+    cssVar: "--text-base",
+    label: "text-base",
+    group: "font-size",
+    default: "1rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-text-lg",
+    cssVar: "--text-lg",
+    label: "text-lg",
+    group: "font-size",
+    default: "1.125rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-text-xl",
+    cssVar: "--text-xl",
+    label: "text-xl",
+    group: "font-size",
+    default: "1.25rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-text-2xl",
+    cssVar: "--text-2xl",
+    label: "text-2xl",
+    group: "font-size",
+    default: "1.5rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-text-xs--line-height",
+    cssVar: "--text-xs--line-height",
+    label: "text-xs / lh",
+    group: "font-size-lh",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-text-sm--line-height",
+    cssVar: "--text-sm--line-height",
+    label: "text-sm / lh",
+    group: "font-size-lh",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-text-base--line-height",
+    cssVar: "--text-base--line-height",
+    label: "text-base / lh",
+    group: "font-size-lh",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-text-lg--line-height",
+    cssVar: "--text-lg--line-height",
+    label: "text-lg / lh",
+    group: "font-size-lh",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-text-xl--line-height",
+    cssVar: "--text-xl--line-height",
+    label: "text-xl / lh",
+    group: "font-size-lh",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-text-2xl--line-height",
+    cssVar: "--text-2xl--line-height",
+    label: "text-2xl / lh",
+    group: "font-size-lh",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-font-weight-normal",
+    cssVar: "--font-weight-normal",
+    label: "font-weight-normal",
+    group: "font-weight",
+    default: "400",
+    step: 1,
+    unit: "",
+    control: "select",
+    options: FONT_WEIGHT_OPTIONS,
+  },
+  {
+    id: "ui-font-weight-medium",
+    cssVar: "--font-weight-medium",
+    label: "font-weight-medium",
+    group: "font-weight",
+    default: "500",
+    step: 1,
+    unit: "",
+    control: "select",
+    options: FONT_WEIGHT_OPTIONS,
+  },
+  {
+    id: "ui-font-weight-semibold",
+    cssVar: "--font-weight-semibold",
+    label: "font-weight-semibold",
+    group: "font-weight",
+    default: "600",
+    step: 1,
+    unit: "",
+    control: "select",
+    options: FONT_WEIGHT_OPTIONS,
+  },
+  {
+    id: "ui-font-weight-bold",
+    cssVar: "--font-weight-bold",
+    label: "font-weight-bold",
+    group: "font-weight",
+    default: "700",
+    step: 1,
+    unit: "",
+    control: "select",
+    options: FONT_WEIGHT_OPTIONS,
+  },
+  {
+    id: "ui-leading-tight",
+    cssVar: "--leading-tight",
+    label: "leading-tight",
+    group: "line-height",
+    default: "1.25",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-leading-snug",
+    cssVar: "--leading-snug",
+    label: "leading-snug",
+    group: "line-height",
+    default: "1.375",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-leading-normal",
+    cssVar: "--leading-normal",
+    label: "leading-normal",
+    group: "line-height",
+    default: "1.5",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-leading-relaxed",
+    cssVar: "--leading-relaxed",
+    label: "leading-relaxed",
+    group: "line-height",
+    default: "1.625",
+    step: 0.05,
+    unit: "",
+  },
+  {
+    id: "ui-font-sans",
+    cssVar: "--font-sans",
+    label: "font-sans",
+    group: "font-family",
+    default: "sans-serif",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-font-mono",
+    cssVar: "--font-mono",
+    label: "font-mono",
+    group: "font-family",
+    default: "monospace",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+];
+
+/**
+ * Size tokens from `src/styles/ui-tokens.css`.
+ *
+ * Coverage: 8 tokens total.
+ * `--radius-full` carries a pill toggle (sentinel 9999px).
+ */
+export const UI_SIZE_TOKENS: readonly TokenDef[] = [
+  {
+    id: "ui-radius-DEFAULT",
+    cssVar: "--radius-DEFAULT",
+    label: "radius-DEFAULT",
+    group: "radius",
+    default: "0.25rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-radius-sm",
+    cssVar: "--radius-sm",
+    label: "radius-sm",
+    group: "radius",
+    default: "0.25rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-radius-md",
+    cssVar: "--radius-md",
+    label: "radius-md",
+    group: "radius",
+    default: "0.5rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-radius-lg",
+    cssVar: "--radius-lg",
+    label: "radius-lg",
+    group: "radius",
+    default: "1rem",
+    step: 0.05,
+    unit: "rem",
+  },
+  {
+    id: "ui-radius-full",
+    cssVar: "--radius-full",
+    label: "radius-full",
+    group: "radius",
+    default: "9999px",
+    step: 1,
+    unit: "px",
+    pill: { value: "9999px", customDefault: "16px" },
+  },
+  {
+    id: "ui-shadow-card",
+    cssVar: "--shadow-card",
+    label: "shadow-card",
+    group: "shadow",
+    default: "0 1px 2px #0000001a",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-shadow-raised",
+    cssVar: "--shadow-raised",
+    label: "shadow-raised",
+    group: "shadow",
+    default: "0 2px 4px #0000001a",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+  {
+    id: "ui-shadow-overlay",
+    cssVar: "--shadow-overlay",
+    label: "shadow-overlay",
+    group: "shadow",
+    default: "0 4px 8px #0000001a",
+    step: 1,
+    unit: "",
+    control: "text",
+  },
+];

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

@@ -21,6 +21,16 @@
 @import "@takazudo/zudo-sg/styles.css";
 @import "@takazudo/zudo-sg/safelist.css";
 
+/* The engine chrome owns raw --sg-* tokens and no longer needs the host's
+ * bare --color-* values. To theme chrome intentionally, add an unlayered
+ * override after these imports, for example:
+ *
+ * :root {
+ *   --sg-border: #94a3b8;
+ *   --sg-accent: #7c3aed;
+ * }
+ */
+
 /* zfb resolves these global-entry globs from the project root.
  * Add your component package's @source here; package chrome uses the safelists. */
 @source "pages/**/*.{tsx,ts,jsx,js}";

package/templates/default/src/styles/ui-tokens.css

@@ -1,6 +1,15 @@
 /* Self-contained input for the packed gen-token-manifest CLI. The current
- * generator requires this complete vocabulary; none comes from demo-ui or
- * the workspace. The Button/Card still use only the original five tokens. */
+ * generator requires this complete host vocabulary; none comes from demo-ui
+ * or the workspace. The engine chrome owns raw --sg-* tokens and no longer
+ * depends on these bare --color-* values. Keep the vocabulary for host
+ * components and the manifest; override chrome separately in global.css, e.g.:
+ *
+ * :root {
+ *   --sg-border: #94a3b8;
+ *   --sg-accent: #7c3aed;
+ * }
+ *
+ * The Button/Card still use only the original five tokens. */
 :root {
   --palette-neutral-0: #ffffff;
   --palette-neutral-1: #e2e8f0;

package/templates/default/zfb.config.ts

@@ -15,11 +15,23 @@ export default defineConfig(
       siteName: "Styleguide Starter",
       base: "/",
       port: 4397,
+      // The starter ships no public/ icons; replace "auto" with a path or FaviconConfig once real icons exist.
+      favicon: "auto",
       // No mermaid diagrams anywhere in this starter's one seed doc; turned
       // off rather than leaving the default on to keep the dependency set
       // minimal (see package.json).
       mermaid: false,
       strictContentBridge: true,
+      // Bundling follows `bundleZdtp ?? designTokenPanel`; this starter never
+      // sets `designTokenPanel`, so without this the zdtp loader resolves to
+      // zudo-doc's throwing stub and the engine's PREVIEW token panel (opened
+      // from the header trigger `withZudoSg` injects) rejects at runtime
+      // (zudolab/zudo-doc#4261).
+      bundleZdtp: true,
+      // Mounts the preview token panel bootstrap on every package-owned
+      // route (/components/*, /tokens), not just this starter's host-owned
+      // `/`. See pages/lib/_chrome-bindings.tsx.
+      chromeBindingsModule: "./pages/lib/_chrome-bindings.tsx",
     }),
     zudoSgConfig,
   ),

package/templates/default/zudo-sg.config.mjs

@@ -20,4 +20,11 @@ export default {
     cssFiles: ["./src/styles/ui-tokens.css", "./src/styles/ui-tokens.css"],
     manifestOut: "./src/styleguide/token-manifest.ts",
   },
+  // Tabs-only shape (routingFile/writeRoot omitted): the header trigger's
+  // preview token panel gets the manifest-derived tabs, but no dev-only Apply
+  // write sandbox — a fresh scaffold has no sensible default path for one.
+  // Wiring the Apply sandbox is an opt-in next step (#818).
+  zdtpApplyProxy: {
+    tabsModule: "./src/config/preview-token-panel-tabs.ts",
+  },
 };