visage-theme

Visage Theme System

Theme Designer Workflow

1. Open Tools/theme-designer.html in a browser (works via file://, no server needed)
2. Edit colors visually or describe what you want to Claude
3. Claude updates the <script id="theme-data"> JSON block in the HTML
4. Refresh browser to see changes instantly
5. When happy, export C++: python3 scripts/generate_theme.py Tools/themes/my-theme.json --mode both --output Source/Theme
6. Include Source/Theme.h and call initThemePalette(palette) at plugin startup

JSON Theme Schema

The theme JSON has these sections:

• colors — Standard Visage widget tokens (Button, Toggle, TextEditor, PopupMenu, ScrollBar)
• values — Visage value tokens (rounding, margins, sizes) as floats with min/max hints
• custom — Project-specific tokens (knobs, meters, waveform, panels, cards, accents, etc.)
• juce — JUCE LookAndFeel ColourId mappings keyed as "ClassName::colourIdName"
• meta — Theme name, version, base (for inheritance)
• overrides — Per-OverrideId Visage color overrides (advanced)

Color format: "value": "#RRGGBB" (web-standard hex) + "alpha": 0.0-1.0 (separate float). The codegen converts to Visage 0xAARRGGBB format automatically.

ARGB Color Format

Visage uses 0xAARRGGBB — alpha in the most-significant byte. This differs from CSS rgba.

0xFFFF0000  // Fully opaque red
0x800000FF  // 50% transparent blue
0x00000000  // Fully transparent

Conversion: alpha_byte = round(alpha_0_to_1 * 255), shifted left 24 bits.

C++ Codegen

# Visage header (VISAGE_THEME_COLOR / VISAGE_THEME_VALUE macros)
python3 scripts/generate_theme.py theme.json --output Source/Theme.h

# JUCE LookAndFeel class
python3 scripts/generate_theme.py theme.json --mode juce --output Source/ThemeLookAndFeel.h

# Both at once
python3 scripts/generate_theme.py theme.json --mode both --output Source/Theme

# Validate only
python3 scripts/generate_theme.py theme.json --validate-only

Palette API

visage::Palette palette;
palette.initWithDefaults();  // Load all registered token defaults

// Apply theme colors
palette.setColor(theme::KnobArc, visage::Color(0xFF00FFD4));

// Apply theme values
palette.setValue(theme::TextEditorRounding, 6.0f);

// Propagate to frame tree
rootFrame->setPalette(&palette);

OverrideId Scoping

For per-component theme regions (e.g., a dark header in a light app):

VISAGE_THEME_PALETTE_OVERRIDE(HeaderRegion);

// Set override colors
palette.setColor(HeaderRegion, theme::PanelBackground, visage::Color(0xFF1A1A2E));

// Apply to a frame subtree
headerFrame->setPaletteOverride(HeaderRegion, true);

JUCE LookAndFeel Integration

The codegen produces a LookAndFeel_V4 subclass with all ColourIds set:

#include "ThemeLookAndFeel.h"

// In editor constructor:
static DefaultDarkLookAndFeel themeLAF;
setLookAndFeel(&themeLAF);

Common Mistakes

• Using CSS #RRGGBBAA order — Visage is 0xAARRGGBB (alpha FIRST)
• Forgetting palette.initWithDefaults() before applying custom colors
• Not calling setPalette() after modifying the palette
• Editing the generated C++ header directly — always regenerate from JSON

Reference Files

File	Purpose
Tools/theme-designer.html	Visual preview + editing tool
Tools/themes/default.json	Default theme with all tokens
scripts/generate_theme.py	JSON to C++ codegen

See references/token-catalog.md for all known Visage tokens with defaults.