Customizing the Studio

VoxelSite ships with the full source code for the Studio admin panel. You can modify the interface — styles, icons, JavaScript behavior — and rebuild the compiled assets.

This page is for developers who want to customize the Studio itself. If you only want to customize the websites VoxelSite generates, you don't need any of this — just use the Chat, Visual Editor, or Code Editor.

What's included

The Studio source files are in _studio/ui/:

_studio/ui/
├── src/                    # Source files you can edit
│   ├── studio.src.css      # Tailwind CSS source (design tokens, components)
│   ├── icons.js            # Inline SVG icon definitions
│   ├── entry.js            # Build entry point
│   └── ...                 # Additional modules as the codebase evolves
├── app.js                  # Main application logic
├── state.js                # State management
├── router.js               # Client-side routing
├── api.js                  # API client
├── theme.js                # Dark/light theme toggle
├── dist/                   # Compiled output (don't edit these directly)
│   ├── studio.css          # Compiled from src/studio.src.css
│   └── studio.js           # Bundled from all JS modules
├── package.json            # npm dependencies and build scripts
└── esbuild.config.js       # JavaScript bundler configuration

The dist/ files are what the browser loads. They are compiled from the source files using two tools:

• Tailwind CSS (@tailwindcss/cli) compiles src/studio.src.css → dist/studio.css
• esbuild bundles all JavaScript modules → dist/studio.js

Prerequisites

You need Node.js 18+ installed on your development machine.

Node.js is only needed on your development machine for building. Your web server does not need Node.js — the compiled files in dist/ are what gets served to the browser.

Setup

Navigate to your VoxelSite installation root and install the build dependencies:

npm install

This installs @tailwindcss/cli and esbuild locally.

Building

To compile both CSS and JavaScript:

npm run build

This runs two commands:

1. npm run build:css — Compiles Tailwind CSS
2. npm run build:js — Bundles JavaScript with esbuild

Development mode

For live rebuilding while you work:

npm run watch

This watches for changes to both CSS and JavaScript files and rebuilds automatically. Reload the Studio in your browser to see changes.

Common customizations

Changing colors or design tokens

Edit _studio/ui/src/studio.src.css. The design system uses CSS custom properties with a --vs- prefix:

--vs-accent: #f59e0b;          /* Primary accent color (amber) */
--vs-bg-base: #1a1a1a;         /* Base background */
--vs-text-primary: #e5e5e5;    /* Primary text color */

After editing, run npm run build:css (or npm run watch for auto-rebuild).

Adding or changing icons

Edit _studio/ui/src/icons.js. Each icon is an inline SVG string:

export const icons = {
  box: `<svg ...>...</svg>`,
  // Add your custom icons here
};

After editing, run npm run build:js.

Modifying JavaScript behavior

The Studio JavaScript is organized into focused modules:

• app.js — Core application shell, routing, chat, event binding
• src/views/editor.js — Monaco code editor, file tree, tab management, Inline AI
• src/views/settings.js — Settings page (identity, AI provider, email, system info)
• src/ui/modals.js — Confirm and prompt dialog utilities
• src/ui/toasts.js — Toast notification system
• src/helpers.js — Shared utilities (escapeHtml, getCodeLanguage)
• state.js, router.js, api.js, theme.js — Framework-level modules

After editing any .js file, run npm run build:js.

After updating VoxelSite

When you update VoxelSite to a new version, the source files in _studio/ui/ will be overwritten with the latest version. If you've made customizations:

1. Back up your modified files before updating
2. After updating, re-apply your changes to the new source files
3. Run npm run build to recompile

Tip: Keep a diff or patch file of your customizations to make re-applying them easier after updates.