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);