8. Live Token Editor

Live Token Editor

This demo sets :root variables directly in the browser and saves them locally. Perfect for testing colors, widths, and radius values live before writing them into your own theme.

Page Background --xpulse-bg Primary canvas and overall page atmosphere. Surface --xpulse-surface Cards, panels and menu bands. Text --xpulse-text Main readable text color. Accent --xpulse-accent Primary action color for active states and CTAs. Warning --xpulse-warning Warnings and pending states. Danger --xpulse-danger Errors and destructive states. Content Width --xpulse-content-width Maximum shell width for the main content area. Sidebar Width --xpulse-sidebar-width Width for TOC and sidebar patterns. Lead Size --xpulse-font-size-lead Reading size for lead paragraphs and intros. Button Radius --xpulse-button-radius Shape of buttons and nav button links.

:root {
  /* no live overrides */
}

The Live Token Editor is an interactive widget that lets you modify the active theme directly in the browser. It sets CSS custom properties on the :root element, persists overrides in localStorage, and shows the resulting CSS block ready to copy.

Usage

Include the widget via template method:

1 {% themeTokenEditor() %}

The method renders a complete <div data-xpulse-theme-editor> block. The JavaScript in theme.js detects the attribute automatically and hydrates the widget.

Editable Tokens

CSS Variable	Label	Format
`--xpulse-bg`	Page Background	Color
`--xpulse-surface`	Surface	Color
`--xpulse-text`	Text	Color
`--xpulse-accent`	Accent	Color
`--xpulse-warning`	Warning	Color
`--xpulse-danger`	Danger	Color
`--xpulse-content-width`	Content Width	Length (`px`, `rem`, …)
`--xpulse-sidebar-width`	Sidebar Width	Length
`--xpulse-font-size-lead`	Lead Size	Length
`--xpulse-button-radius`	Button Radius	Length

On load the widget reads the computed values of the active theme and pre-fills the inputs. Color tokens use <input type="color">, length tokens use <input type="text">.

Behaviour

Live preview: Every change takes effect on the entire page immediately.
Persistence: Overrides are stored under the key xpulse_theme_tokens in localStorage and restored on the next page load.
CSS preview: A <pre> block shows the current :root { … } block with all active overrides — ready to copy into your own theme.
Reset: The "Reset Live Overrides" button removes all overrides and restores the theme defaults.
Theme sync: If the user switches theme (e.g. Dark → Light) and there are no stored overrides, the widget automatically updates its inputs to the new theme's values.

Events

Event	Payload	When
`xpulse:theme:tokens:changed`	`{ token, value }`	Token value changed
`xpulse:theme:tokens:changed`	`{ reset: true }`	Reset triggered

1 document.addEventListener('xpulse:theme:tokens:changed', (e) => {
2     console.log(e.detail); // { token: '--xpulse-accent', value: '#ff0000' }
3 });

Programmatic Access

You can set a single token directly via the global xpulseTheme API:

1 xpulseTheme.applyToken('--xpulse-accent', '#e74c3c');

Workflow: Override → Theme

Recommended workflow for building a new theme:

Open the editor and adjust colors and lengths live.
Copy the :root { … } block from the preview.
Paste it into your own theme CSS (e.g. src/themes/my-theme.css).
Click Reset — the widget now shows the defaults again.

CSS Classes

Class	Element
`.xpulse-theme-editor`	Outer container (`[data-xpulse-theme-editor]`)
`.xpulse-theme-editor__intro`	Title and description
`.xpulse-theme-editor__grid`	Grid of input fields
`.xpulse-theme-editor__field`	Individual `<label>` field
`.xpulse-theme-editor__actions`	Reset button row
`.xpulse-theme-editor__preview`	`:root` CSS preview

1	document.addEventListener('xpulse:theme:tokens:changed', (e) => {
2	console.log(e.detail); // { token: '--xpulse-accent', value: '#ff0000' }
3	});