Theme Studio connects to your JekCMS installation via a read/write API token scoped exclusively to theme assets. Changes are transmitted over a WebSocket connection and previewed in an embedded iframe that refreshes without a full page reload. The median time from saving a CSS change to seeing it in the preview is 140ms on a same-region server; cross-region latency adds 60–80ms.

Server-Side Compilation — No Local Toolchain

Asset compilation runs server-side. There is no local Node.js, Vite, or webpack process required. CSS variables defined in the theme's variables.json file appear as form controls — colour pickers, sliders, dropdowns — in Theme Studio's sidebar. Changing a variable updates every component that references it in the preview simultaneously.

Clean Export, No Lock-In

Export generates a clean ZIP of the theme directory. The output is byte-for-byte identical to a manually built theme — no Theme Studio metadata, no dependencies on Theme Studio being installed. The exported theme can be distributed through the JekCMS theme marketplace or installed directly.

Licensing and Access

Theme Studio is included with all JekCMS Agency and Enterprise licenses. Standard license holders can access a read-only preview mode that allows reviewing how a theme will look on their installation before purchasing.

The variables.json Configuration File

Every Theme Studio-compatible theme includes a variables.json file in its root directory. This file declares every adjustable property — colours, font sizes, spacing values, breakpoints — along with metadata that determines how each variable appears in the sidebar UI. A colour variable renders as a colour picker; a numeric variable with min, max, and step fields renders as a slider; an enumerated variable renders as a dropdown.

{
 "colors": {
 "--primary": {
 "label": "Primary Color",
 "type": "color",
 "default": "#2563eb",
 "group": "Brand"
 },
 "--surface": {
 "label": "Surface Background",
 "type": "color",
 "default": "#ffffff",
 "group": "Surfaces"
 }
 },
 "typography": {
 "--font-size-base": {
 "label": "Base Font Size",
 "type": "range",
 "default": "16px",
 "min": 12,
 "max": 24,
 "step": 1,
 "unit": "px"
 }
 }
}

Variable Groups and Sections

Variables are organized into groups that appear as collapsible sections in the sidebar. The default groups — Brand, Surfaces, Typography, Spacing, Layout — provide a logical structure, but theme authors can define custom groups. Each group can contain up to 50 variables. Variables without a group assignment appear in an "Other" section at the bottom of the sidebar.

WebSocket Architecture

Theme Studio maintains a persistent WebSocket connection between the browser editor and the JekCMS server. When you modify a CSS variable, the change travels through three stages:

  • The browser sends a JSON patch message containing the variable name and new value
  • The server validates the value against the variable type constraints defined in variables.json
  • The server injects the updated variable into the theme's compiled CSS and broadcasts the result to all connected preview clients

This architecture means multiple designers can work on the same theme simultaneously. Each connected browser sees changes from all other editors in real time. Conflict resolution uses a last-write-wins strategy per variable — there is no merge or lock mechanism, which keeps the implementation simple and fast.

Template Editing and Component Library

Beyond CSS variables, Theme Studio provides a template editor for modifying PHP template files directly in the browser. Syntax highlighting, auto-completion for JekCMS helper functions, and inline error reporting are built in. The component library panel lists every partial available in the theme, with drag-and-drop support for inserting get_partial() calls into templates.

Live Error Detection

When you save a template file that contains a PHP syntax error, Theme Studio catches it before the file is written to disk. The server runs php -l (lint) on the submitted content and returns the error message in the editor UI. This prevents the common scenario of breaking a live site by saving a template with a typo. The preview iframe continues showing the last working version until the error is fixed.

Performance Impact on Production

Theme Studio adds zero overhead to production sites. The WebSocket server, the variable compilation layer, and the editor UI are only active when a Theme Studio session is running. No additional JavaScript or CSS is loaded on the public-facing site. The compiled theme output is identical whether it was built through Theme Studio or assembled manually — the same CSS file, the same PHP templates, the same directory structure.

Version Control and Revision History

Every change made through Theme Studio is tracked in a built-in revision history. Each save creates a timestamped snapshot of the modified files, stored in .theme-studio/revisions/ within the theme directory.

You can browse up to 50 recent revisions, preview any previous state in the iframe, and restore a specific revision with a single click. The revision system operates independently of git — it does not create commits or require a repository. However, for teams that use git, Theme Studio can optionally commit each save to the active branch with an auto-generated commit message describing which files changed and which variables were modified.

Revisions are lightweight: only the files that actually changed are stored in each snapshot, not a full copy of the theme. A typical 30-revision history for a theme with 40 files consumes less than 2 MB of disk space. When the revision limit is reached, the oldest snapshots are pruned automatically. This makes it practical to experiment freely with design changes without worrying about losing a previous state that looked better.