Design Token Panels
How to use the two live token-tweaking panels — the doc-chrome panel and the preview panel.
The styleguide ships two independent design-token panels. Each one edits a different layer and persists its own settings separately. Understanding which panel does what is key to using them effectively.
Quick orientation
| Doc-chrome panel | Preview panel | |
|---|---|---|
| Header control | Design Tokens icon (sliders glyph) — shown on every docs page | Preview tokens icon (stacked-frames glyph) — shown on styleguide/component pages; also a "Preview tokens →" button on the / toolbar |
| What it edits | The documentation site's own UI | The @zudo-sg/ui component tokens inside preview iframes |
| Where applied | Host <html> :root | Preview iframes only |
| localStorage prefix | sg-doc-tweak | sg-preview-tweak |
| Console namespace | window.sgDoc | window.sgPreview |
| Toggle event | toggle-sg-doc-tweak | toggle-preview-token-panel |
The header carries the two panels as a matched pair of icons in its right region: the Design Tokens icon is available site-wide (every docs page), while the Preview tokens icon appears only on the styleguide/component pages where preview iframes exist. So styleguide pages show two token icons and regular docs pages show one.
Doc-chrome panel (Design Tokens)
Click the Design Tokens icon in the header (the sliders glyph, on every page) to open this panel.
The doc-chrome panel edits the --zd-* CSS custom properties that control the documentation site's own look — background color, text color, spacing scale, sidebar width, and so on. Every change is written as inline CSS variables onto the host <html> element (:root), so the effect is visible immediately across the entire page.
Use this panel when you want to adjust or export the documentation site's design tokens.
Note
Changes in this panel affect only the docs chrome — they do not reach the component previews in the iframes.
Preview panel (Preview tokens)
Click the Preview tokens icon in the header (the stacked-frames glyph, on styleguide/component pages) or the "Preview tokens →" button on the / toolbar to open this panel.
The preview panel edits the @zudo-sg/ui design tokens — --color-*, --spacing-*, --font-*, --radius-*, --shadow-*. Instead of writing to the host :root, every change is sent directly into each registered preview iframe's :root via zudo-doc's theme bridge.
Its Palette tab exposes the raw Tier-1 colors as grouped base, accent, state, and line (business-line accents) swatches. The semantic Color tab keeps the unchanged --color-* names that point at those palette entries.
Why iframes only? In src/ the @zudo-sg/ui target tokens are aliased onto the doc chrome. Writing them to the host :root would corrupt the documentation site's appearance, so the panel deliberately routes all writes into the iframes and leaves the host untouched.
Late-mounted iframes are handled automatically: the registry replays the currently-active overrides into any iframe that loads after the panel has already applied changes. You will see the same token state regardless of which component page you navigate to.
Note
Changes in this panel affect only the component previews in the iframes — the documentation chrome is left untouched.
Apply — persist a tweak to CSS source
Both panel footers also have an Apply button, next to Export / Reset / Load from JSON. Unlike the other three actions (which are entirely localStorage/JSON round-trips), Apply POSTs the current tweak diff to a dev-only endpoint that rewrites the value directly into the project's CSS source — the change survives a hard reload with localStorage cleared, and shows up as an ordinary git diff.
This works today for every tab in the preview panel — Color, Palette, Spacing, Font, and Size — and only when running under pnpm dev (zfb dev). The doc-chrome panel has no apply endpoint at all. See the caveat below for what's still out of scope.
Apply routes every preview-panel tab now; a few internal prefixes still 400
The apply endpoint routes eight prefixes — palette, color, spacing, text, font, leading, radius, shadow — covering every tab the preview panel exposes: Color and Palette write into packages/; Spacing, Font, and Size (radius + shadow) write into packages/. Apply sends every currently-tweaked token across every tab in one request, and two prefix pairs land in the same file (palette + color; spacing/text/font/leading/radius/shadow) — plugins/'s same-file coalescing shim splits that single request into one sequential apply call per prefix so both same-file edits survive instead of the second write clobbering the first.
The failure window is narrowed, not eliminated: any CSS var whose prefix isn't in the routing map — e.g. --breakpoint-*, --default-transition-* (Tailwind plumbing, deliberately left out of every tab) — still fails the whole request with "Unsupported cssVar prefix" (400) if it ever reaches the endpoint. None of the tokens the preview panel currently exposes fall into that category, so hitting this 400 through normal panel use shouldn't happen today — but a future token family added to a tab without a matching routing entry would trip it again.
How it's wired, for anyone extending this: plugins/ registers a same-origin zfb dev devMiddleware handler (no separate process, no port, no CORS) at /, backed by @takazudo/'s createApplyHandler. The prefix → file routing map lives in zdtp-panel-routing.json at the repo root, and the endpoint/routing values are injected into src/ via a virtual:zdtp-apply-config module that resolves to undefined outside of zfb dev — a production build never sees the endpoint path or the routing map.
Broader apply routing shipped in Takazudo/zudo-sg#130 — palette, color, spacing, text, font, leading, radius, and shadow are all apply-writable now.
Shared panel actions
Both panels expose three utility actions in their footer:
Export — downloads a JSON blob of the current overrides for this panel. You can copy it and share it, or archive it as a token snapshot.
Reset — clears all overrides for that panel only. The doc-chrome Reset reverts the docs site to stylesheet defaults; the preview Reset reverts the iframes to their own stylesheet defaults. Neither Reset touches the other panel.
Load from JSON — paste an exported blob into the dialog to restore a saved token set. The dialog shows a "Loaded." status message on success and stays open so you can verify before closing.
Tip
Use Export / Load from JSON to hand off a token snapshot to a teammate or to record a design exploration.