8. Live Token Editor

Live Token Editor

Diese Demo setzt :root-Variablen direkt im Browser und speichert sie lokal. Ideal, um Farben, Breiten und Radius live zu prüfen, bevor du sie in dein eigenes Theme schreibst.

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 */
}

Der Live Token Editor ist ein interaktives Widget, das direkt im Browser das aktive Theme veränderbar macht. Er setzt CSS-Custom-Properties auf dem :root-Element, speichert die Overrides im localStorage und zeigt den resultierenden CSS-Block zum Kopieren an.

Verwendung

Das Widget wird per Template-Methode eingebunden:

1 {% themeTokenEditor() %}

Die Methode rendert einen fertigen <div data-xpulse-theme-editor>-Block. Das JavaScript in theme.js erkennt das Attribut automatisch und hydratisiert das Widget.

Bearbeitbare Tokens

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

Beim Öffnen liest das Widget die aktuell berechneten Werte des aktiven Themes und befüllt die Felder damit. Farbfelder nutzen <input type="color">, Längenfelder <input type="text">.

Verhalten

Live-Vorschau: Jede Änderung wirkt sofort auf die gesamte Seite.
Persistenz: Overrides werden unter dem Key xpulse_theme_tokens im localStorage gespeichert und beim nächsten Seitenaufruf wiederhergestellt.
CSS-Preview: Ein <pre>-Block zeigt den aktuellen :root { … }-Block mit allen aktiven Overrides — bereit zum Kopieren in das eigene Theme.
Reset: Der Button „Reset Live Overrides" entfernt alle Overrides und stellt die Theme-Defaults wieder her.
Theme-Sync: Wechselt der Nutzer das Theme (z. B. Dark → Light) und es gibt keine gespeicherten Overrides, aktualisiert das Widget seine Felder automatisch auf die Werte des neuen Themes.

Events

Event	Payload	Wann
`xpulse:theme:tokens:changed`	`{ token, value }`	Token-Wert geändert
`xpulse:theme:tokens:changed`	`{ reset: true }`	Reset ausgelöst

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

Programmatischer Zugriff

Über die globale xpulseTheme-API lässt sich ein einzelner Token direkt setzen:

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

Workflow: Override → Theme

Der empfohlene Workflow, um ein neues Theme zu entwickeln:

Editor öffnen, Farben und Längen live einstellen.
Den angezeigten :root { … }-Block aus dem Preview kopieren.
In ein eigenes Theme-CSS einfügen (z. B. src/themes/my-theme.css).
Reset klicken — das Widget zeigt jetzt wieder die Defaults.

CSS-Klassen des Widgets

Klasse	Element
`.xpulse-theme-editor`	Äußerer Container (`[data-xpulse-theme-editor]`)
`.xpulse-theme-editor__intro`	Titel und Beschreibung
`.xpulse-theme-editor__grid`	Grid der Eingabefelder
`.xpulse-theme-editor__field`	Einzelnes `<label>`-Feld
`.xpulse-theme-editor__actions`	Reset-Button-Zeile
`.xpulse-theme-editor__preview`	`:root`-CSS-Vorschau

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