Quickstart

Configure the panel, declare a tiny cssVar manifest, and toggle it from the devtools console.

This page is the smallest end-to-end wiring of @takazudo/zudo-design-token-panel — just enough code to call configurePanel({...}), declare a five-token manifest, and pop the panel from your browser console. After this, the Configure Panel reference covers every field on PanelConfig in depth.

What you’ll wire up

The public surface of the package is a single configure-once init:

import { configurePanel, type PanelConfig } from '@takazudo/zudo-design-token-panel';

configurePanel({
  storagePrefix: 'myapp-design-token-panel',
  consoleNamespace: 'myapp',
  modalClassPrefix: 'myapp-design-token-panel-modal',
  schemaId: 'myapp-design-tokens/v1',
  exportFilenameBase: 'myapp-design-tokens',
  tokens: { spacing: [], typography: [], size: [], color: [] },
  colorCluster: myColorCluster,
});

Once configured, the package installs three async helpers on window.<consoleNamespace> — showDesignPanel(), hideDesignPanel(), toggleDesignPanel(). Calling any of them lazy-imports the panel module and mounts the UI.

Step 1 — Define a minimal PanelConfig

Create a file alongside your source to hold the config. Five identifiers (storage prefix, console namespace, modal class prefix, schema id, export filename) plus your token manifest and color cluster are all the package needs.

// src/lib/my-panel-config.ts
import type { PanelConfig } from '@takazudo/zudo-design-token-panel';

export const myPanelConfig: PanelConfig = {
  storagePrefix: 'myapp-design-token-panel',
  consoleNamespace: 'myapp',
  modalClassPrefix: 'myapp-design-token-panel-modal',
  schemaId: 'myapp-design-tokens/v1',
  exportFilenameBase: 'myapp-design-tokens',
  tokens: myTokens,
  colorCluster: myColorCluster,
};

Pick identifiers that are unambiguous to your app — typically your app slug. The storagePrefix value is the only knob that controls every persisted localStorage key, so renaming it later loses users’ saved tweaks.

Step 2 — A five-line cssVar manifest

The token manifest is a host-supplied list of editable CSS custom properties grouped per tab (spacing / typography / size / color). The four arrays are required even if some are empty. Here is the smallest manifest that renders something in each non-color tab:

// src/lib/my-tokens.ts
import type { TokenManifest } from '@takazudo/zudo-design-token-panel';

export const myTokens: TokenManifest = {
  spacing: [
    { id: 'sp-md',   cssVar: '--myapp-spacing-md',   label: 'Spacing M', group: 'hsp',  default: '1rem',    min: 0,    max: 4,   step: 0.0625, unit: 'rem' },
  ],
  typography: [
    { id: 'text-base', cssVar: '--myapp-text-base', label: 'Body Text', group: 'font-size', default: '1rem', min: 0.75, max: 1.5, step: 0.0625, unit: 'rem' },
  ],
  size: [
    { id: 'sz-radius', cssVar: '--myapp-radius',     label: 'Radius',    group: 'radius', default: '0.5rem', min: 0,    max: 2,   step: 0.0625, unit: 'rem' },
  ],
  color: [],
};

That’s five tokens (one per array, color-cluster-driven sites ship color: []). The cssVar field is what the panel writes to :root via setProperty(), so make sure your stylesheet reads from the same variable names.

Step 3 — Call configurePanel(...) and toggle the panel

For a non-Astro host (Vite + React, Next.js, custom Vite SPA), call configurePanel(...) once at app boot — typically from your entry module — then open the devtools console:

// src/main.ts (Vite + React) or app/layout.tsx (Next.js, with 'use client')
import { configurePanel } from '@takazudo/zudo-design-token-panel';
import '@takazudo/zudo-design-token-panel/styles';
import { myPanelConfig } from './lib/my-panel-config';

configurePanel(myPanelConfig);

Then, in the browser devtools console:

window.myapp.toggleDesignPanel();

The first call lazy-imports the panel module and mounts it. Subsequent calls share the memoised module promise.

For Astro, you don’t call configurePanel(...) directly — you drop the host component into your layout and the host adapter wires everything up:

---
// src/layouts/Layout.astro
import { DesignTokenPanelHost } from '@takazudo/zudo-design-token-panel/astro';
import '@takazudo/zudo-design-token-panel/styles';
import { myPanelConfig } from '../lib/my-panel-config';
---

<!doctype html>
<html lang="en">
  <body>
    <slot />
    <DesignTokenPanelHost config={myPanelConfig} />
  </body>
</html>

<script>
  void import('@takazudo/zudo-design-token-panel/astro/host-adapter');
</script>

The <DesignTokenPanelHost> component AND the host-adapter <script> block are a paired unit — both lines are required, always together. Skipping the script leaves the JSON config payload on the page with no JS to read it.

Verify the panel mounts

Open the page in a browser, drop into devtools, and run:

window.myapp.toggleDesignPanel();

You should see a Preact-rendered side panel mount. Drag a slider; the matching --myapp-* CSS variable updates on :root immediately. Reload the page — the override re-applies before first paint, no FOUT.

Next step

This page got you to “the panel renders, my CSS variables update.” For the full PanelConfig shape, color-cluster anatomy, and apply-pipeline wiring, continue to the Configure Panel reference. For framework-specific snippets, see Three Frameworks.