Themes¶

chatwire ships with 23 built-in color schemes and a theme package system for importing or building your own. Themes control colors, spacing, bubble shapes, typography, and custom CSS.

Terminology¶

Scheme — a color palette (Dracula, Rose Pine Moon, GitHub Dark, etc.)
Style — a structural layout (default, compact, wide)
Theme package — a JSON file that bundles a scheme, style, and optional custom CSS into one importable unit

These are distinct: you can mix any scheme with any style. Changing the scheme doesn't affect spacing; changing the style doesn't affect colors.

Changing the scheme¶

Settings → Themes → Color scheme

A dropdown with all 23 built-in schemes plus any imported theme packages. A sun/moon toggle appears to switch between light and dark variants when the scheme has both.

Changes apply immediately — no page reload.

Built-in schemes include: Dracula, Catppuccin (Mocha / Latte / Frappe / Macchiato), GitHub Dark / Light, Nord, Tokyo Night, One Dark, Solarized, Gruvbox, Rose Pine (Moon / Dawn / Main, via plugin), and more.

Changing the style¶

Settings → Themes → Style

Default — standard message spacing, sidebar width, and border radius
Compact — tighter spacing, smaller font size, narrower sidebar
Wide — wider sidebar, more padding

Accent color¶

Settings → Themes → Accent color

An optional hex color override for the primary action color (buttons, highlights, focus rings). Overrides the scheme's built-in accent. Leave blank to use the scheme default.

Custom CSS¶

Settings → Themes → Custom CSS

An arbitrary CSS string injected into the page. Use it for anything the variable system doesn't cover.

/* Example: italic timestamps */
.message-timestamp { font-style: italic; }

/* Example: hide the connection banner */
.connection-banner { display: none; }

Custom CSS is sanitized before injection: - @import rules are stripped (no external stylesheets) - url() with http:// or https:// URLs are replaced with url(about:blank) (prevents tracking pixels) - Everything else is preserved

Theme packages¶

A theme package is a JSON file that bundles colors, structure, decorations, and custom CSS in one importable unit.

Importing a package¶

Place the .json file in ~/.chatwire/themes/
Open Settings → Themes → Theme Packages
Select the package from the dropdown
The package activates immediately

Package format (brief)¶

{
  "name": "my-dark-theme",
  "author": "Your Name",
  "version": "1.0.0",
  "colors": {
    "background": "#0d1117",
    "foreground": "#c9d1d9",
    "msg-me": "#1f6feb",
    "msg-me-text": "#ffffff"
  },
  "structure": {
    "radius-bubble": "4px",
    "font-size-message": "0.9rem"
  },
  "decorations": {
    "avatar-shape": "8px"
  },
  "custom_css": ".message-timestamp { opacity: 0.6; }"
}

All fields except name are optional. A colors-only package is valid. See Theme format for the complete variable reference.

Exporting a package¶

Settings → Themes → Export — downloads a .json file capturing your current scheme, style, and custom CSS overrides.

Rose Pine theme (plugin)¶

The Rose Pine theme (Moon / Dawn / Main schemes) is distributed as a plugin:

pipx inject chatwire chatwire-theme-rosepine
launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

After installing, the Rose Pine schemes appear in the color scheme dropdown.

Theme packages are self-contained JSON files — share them by sending the file. Recipients drop it in ~/.chatwire/themes/ and it appears in the picker without any restart.

Priority order¶

When multiple theme layers are active, later layers win:

Base CSS (chatwire defaults)
Built-in scheme CSS variables
Theme package variables (drop ~/.chatwire/themes/)
Individual accent color override (Settings → Accent color)
Custom CSS (Settings → Custom CSS)

Individual settings always override theme package settings. This means you can import a package for its color scheme but override specific colors in Settings without editing the package file.