Creating Custom Themes

OpenBox features a strict, token-driven CSS architecture. Every color, surface, font, and border is driven by standard CSS variables defined in :root.

/* OpenBox Custom Theme: Midnight Circuit */
:root {
  --bg: #070b14;
  --panel: #0e1524;
  --surface-card: #0e1524;
  --surface-deep: #070b14;
  --text: #e6f0ff;
  --focus: #3de0ff;
  --action: #2dff9a;
  --action-ink: #041510;
  --border-card: #1b283d;
  --border-control: #1b283d;
  --line: #1b283d;
}

Design System Tokens

When creating a custom theme, you only need to override :root variables. No component CSS rules are modified.

The table below is the minimal starter subset (matching the warm default look). The full contract is much larger — mood-match (--mood-*), constellation edge (--constellation-edge-*), mastery (--mastery-*), overlay-insight, gamepad, health, toast, and font tokens — and is documented on the Design system page. Start with these, then override more as needed.

Text and interactive colors should use the semantic ink tokens rather than raw palette entries: --ink-strong for primary headings, --on-active for text on an active tab or selection, --on-danger for text on a danger surface, --border-input for form borders, and --state-hover / --state-press for interaction states. A contrast matrix in the test suite checks every stock theme against a fixed list of foreground/background pairs — text and ink on their surfaces, the on-active and on-danger pairs, toasts, health colors, and the non-text boundary and focus ring — so authoring against those tokens is what keeps a theme legible in all six bundled palettes. The hover and press tokens are alpha overlays rather than foregrounds and are deliberately not part of the matrix. See Themes.

Installing a Custom Theme

1. Create a CSS file named theme-mytheme.css in your themes directory:

   mkdir -p ~/.local/share/openbox-game-launcher/themes/
   nano ~/.local/share/openbox-game-launcher/themes/theme-mytheme.css
   

2. Paste your :root definition:

   :root {
     --bg: #11100e;
     --panel: #1b1916;
     --surface-deep: #141311;
     --surface-card: #211e1a;
     --surface-field: #27231e;
     --text: #f4efe6;
     --muted: #aaa094;
     --focus: #f06000;
     --active: #f06000;
     --action: #e08a3c;
     --action-ink: #1c160d;
     --border-card: #534a3d;
     --border-control: #4b4338;
     --line: #3d3932;
   }
   

3. Open OpenBox, click Themes in the top bar, choose a scope (All platforms or one specific platform), pick your theme from Active theme, and click Apply. Alternatively, use Import CSS theme with the absolute path to your file.