Create a theme

Learn how to create custom themes for Pointer. Customize colors, appearance, and the splash screen.

Quick start

Base Starter template (ZIP). Extract into themes/, rename folder to your theme id (e.g. my-theme).

Copy the base template — Use the Base template above, or copy themes/_base/ from the repo. Folder name = theme id (lowercase, hyphens). Folders starting with _ are not discovered.
Update manifest.json — Set id (must match folder name), name, and titleBar colors.
Customize theme.css — Edit CSS variables under [data-theme="my-theme"]. Only override what you need; the rest inherits from the dark theme.
Test in app — Restart Pointer and select your theme in Settings → Appearance.

Example themes: themes/dracula/ (custom colors), themes/_base/ (template with all variables).

Folder structure

themes/<theme-id>/
  manifest.json    # Required. Metadata, titleBar, icon, optional splash.
  theme.css        # Required. CSS variables under [data-theme="<id>"].
  splash.css       # Optional. Full control over splash screen.

`id` = folder name	Lowercase, digits, hyphens. `_`-prefix = ignored (e.g. `_base` is template only).
Discovery	App scans `themes/` for dirs with both `manifest.json` and `theme.css`. Valid themes appear in Settings → Appearance.
Built-in themes	`dark` and `light` are defined in `src/styles/global.css` and don't need folders.

manifest.json

The manifest defines metadata, title bar colors, icon selection, and optional splash screen colors.

Field	Required	Description
`id`	✓	Must match folder name. Used as `data-theme` value in CSS.
`name`	✓	Display label shown in Settings → Appearance dropdown.
`description`		Optional hint text shown when theme is selected.
`titleBar`	✓	Electron window title bar configuration: `color` – Background (must match `--menu-bar-bg`) `symbolColor` – Minimize/maximize/close button color `height` – Optional, default 35px `modalColor` – Optional. When omitted, computed adaptively from `color` (blended with black; same alpha as `--modal-overlay-bg`: dark 0.6, light 0.35). `modalSymbolColor` – Optional, modal button color
`icon`		`"dark"` \| `"light"` – selects `icon.ico` or `icon_light.ico`. Omit for dark.
`splash`		Optional splash screen colors: `bg` – Background (required) `accent` – Accent color (required) `fg` – Foreground text (optional) `muted` – Muted text (optional) If omitted, splash uses `titleBar` colors. For full control, use `splash.css` instead.

Minimal manifest example

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "A custom dark theme.",
  "titleBar": {
    "color": "#1e1e1e",
    "symbolColor": "#cccccc",
    "height": 35
  },
  "icon": "dark"
}

theme.css

Override CSS custom properties under [data-theme="<id>"]. Only specify variables you want to change; unspecified variables inherit from :root (dark theme).

[data-theme="my-theme"] {
  /* Editor / Sidebar */
  --editor-bg: #282a36;
  --editor-fg: #f8f8f2;
  --sidebar-bg: #282a36;
  --sidebar-fg: #f8f8f2;
  
  /* Accent & Borders */
  --accent: #bd93f9;
  --accent-hover: #a78bfa;
  --border: #44475a;
  
  /* Add only what you need to override */
}

Variable groups

Group	Key variables
Editor / Sidebar	`--editor-bg`, `--editor-fg`, `--sidebar-bg`, `--sidebar-fg`, `--activity-bar-bg`, `--tab-bg`, `--tab-active-bg`, `--menu-bar-bg`
Borders & Accent	`--border`, `--border-light`, `--accent`, `--accent-hover`, `--hover`
Input / Form	`--editor-bg` (form & dropdown search inputs), `--input-bg`, `--input-fg`, `--input-placeholder`
List states	`--list-hover`, `--list-active`, `--list-active-border`
Semantic	`--muted`, `--destructive`, `--success`, `--button-fg`, `--button-bg`
DataTable	`--dt-header-bg`, `--dt-row-even-bg`, `--dt-cell-border`
Tool Call / Chat	`--tc-label`, `--tc-card-bg`, `--tc-card-border`
Modal	`--modal-overlay-bg` (dark: 0.6, light: 0.35 alpha – must match `icon` for adaptive title bar), `--modal-bg`, `--modal-border`
Toast	`--toast-bg`, `--toast-shadow`
Diagram	`--diagram-bg`, `--diagram-node-bg`, `--diagram-edge`

See themes/_base/theme.css for the complete variable reference with descriptions.

Splash screen

The splash screen (loading screen) can be customized in two ways:

Option 1: manifest.splash (simple)

Add a splash object to your manifest. The app generates splash CSS from these colors:

{
  "splash": {
    "bg": "#282a36",
    "accent": "#bd93f9",
    "fg": "#f8f8f2",
    "muted": "#6272a4"
  }
}

bg and accent are required; fg and muted default to sensible values.

Option 2: splash.css (full control)

Create themes/<id>/splash.css for complete control. Define all splash variables:

[data-theme="my-theme"] {
  --splash-body-bg: #282a36;
  --splash-screen-bg: rgba(40, 42, 54, 0.95);
  --splash-accent: #bd93f9;
  --splash-code-kw: #bd93f9;
  --splash-title-gradient: linear-gradient(180deg, #f8f8f2 0%, #6272a4 100%);
  /* ... see themes/_base/splash.css for all variables */
}

See themes/_base/splash.css for the complete splash variable reference.

Examples

Dracula theme

The themes/dracula/ theme demonstrates a complete custom theme:

themes/dracula/
  manifest.json    # id: "dracula", titleBar colors, splash colors
  theme.css        # Overrides editor, sidebar, accent, borders, etc.

Key features:

Purple accent color (--accent: #bd93f9)
Dark background (--editor-bg: #282a36)
Custom borders and hover states
Splash screen colors defined in manifest

Base template

The themes/_base/ folder contains:

manifest.json – Template with all fields documented
theme.css – All available CSS variables with descriptions
splash.css – All splash variables with descriptions
README.md – Quick reference

Download theme-base.zip or copy _base from the repo to start a new theme.

Addon themes

Addons can ship themes under addons/<id>/themes/<slug>/ with the same structure:

addons/my-addon/themes/dark/
  manifest.json
  theme.css
  splash.css  # Optional

Addon themes are discovered only when the addon is enabled. Theme IDs are addonId/slug (e.g. discord/dark).

See the add-on development guide for details on creating addons.

Reference

What	Where
Theme folder	`themes/<id>/`
Manifest	`manifest.json` (id, name, titleBar, icon, splash)
Theme CSS	`theme.css` with `[data-theme="<id>"]` selector
Splash CSS	`splash.css` (optional) or `manifest.splash`
Template	`themes/_base/` (copy and rename)
Example	`themes/dracula/`
Built-in themes	`dark`, `light` (defined in `src/styles/global.css`)