Skip to main content
Tempest uses a JSON-based theme system that drives the application’s appearance through CSS custom properties (variables). Themes define color tokens that are converted to CSS variables and applied at runtime.

How It Works

Themes in Tempest follow a token-to-CSS-variable naming pattern. A theme file defines semantic color tokens like bg.editor or fg.default, which are automatically converted to CSS variables like --tempest-bg-editor and --tempest-fg-default.

Token to CSS Variable Conversion

The system converts dot-notation tokens to kebab-case CSS variables:
The conversion function is:

Theme Structure

Each theme is a JSON file with the following structure:

Required Fields

  • name: A human-readable theme name (e.g., “Tempest Dark”, “Tempest Light”)
  • type: Either “dark” or “light”, used for semantics and theming context
  • colors: An object where keys are color tokens and values are hex color values

Built-in Themes

Tempest includes two built-in themes:

Tempest Dark

Located at src/themes/tempest-dark/theme.json Dark theme optimized for low-light environments with high contrast and vibrant accent colors.

Tempest Light

Located at src/themes/tempest-light/theme.json Light theme designed for bright environments with muted accents and light backgrounds. Themes are auto-discovered at build time via import.meta.glob over src/themes/**/theme.json — adding a theme folder is all it takes. There is no theme registry array to edit.

Color Token Categories

Themes organize colors into semantic categories:

Background Colors (bg.*)

  • bg.base: Primary background color
  • bg.editor: Editor/content area background
  • bg.sidebar: Sidebar background
  • bg.panel: Panel background
  • bg.titlebar: Title bar background
  • bg.hover: Hover state background
  • bg.active: Active/selected state background
  • bg.input: Input field background
  • bg.selection: Text selection background
  • bg.selection-focused: Focused text selection background

Foreground Colors (fg.*)

  • fg.default: Default text color
  • fg.muted: Muted or secondary text
  • fg.subtle: Very subtle/disabled text

Border Colors (border.*)

  • border.default: Default border color
  • border.subtle: Subtle/secondary border color

Accent Colors (accent.*)

Seven accent colors for UI elements and highlights:
  • accent.blue
  • accent.pink
  • accent.green
  • accent.yellow
  • accent.purple
  • accent.cyan
  • accent.red

Syntax Highlighting (syntax.*)

Colors for code syntax highlighting:
  • syntax.comment: Comments
  • syntax.keyword: Keywords
  • syntax.string: Strings
  • syntax.function: Function names
  • syntax.variable: Variables
  • syntax.constant: Constants
  • syntax.type: Type annotations
  • syntax.operator: Operators
  • syntax.attribute: Attributes

Git Status (git.*)

Colors for git status indicators:
  • git.added: Added files
  • git.modified: Modified files
  • git.deleted: Deleted files
  • git.conflict: Merge conflicts
  • git.ignored: Ignored files
  • git.untracked: Untracked files

Island UI (island.*)

Colors for collapsible/expandable UI elements:
  • island.bg-closed: Background when closed
  • island.border-closed: Border when closed
  • island.bg-open: Background when open
  • island.border-open: Border when open

Tooltip Colors (tooltip.*)

  • tooltip.bg: Tooltip background
  • tooltip.fg: Tooltip text color

Semantic Colors (semantic.*)

Standard status/message colors:
  • semantic.error: Error state
  • semantic.warning: Warning state
  • semantic.info: Info state
  • semantic.success: Success state

Terminal Colors (terminal.*)

16-color terminal palette:
  • terminal.fg: Default foreground
  • terminal.selection: Selection background
  • terminal.black, terminal.red, terminal.green, terminal.yellow, terminal.blue, terminal.purple, terminal.cyan, terminal.white: Standard colors
  • terminal.brightBlack, terminal.brightRed, terminal.brightGreen, terminal.brightYellow, terminal.brightBlue, terminal.brightPurple, terminal.brightCyan, terminal.brightWhite: Bright variants

Additional Token Groups

The full built-in catalog is ~111 tokens per theme. In addition to the groups above, themes define:
  • badge (e.g., badge.green)
  • canvas (e.g., canvas.border)
  • group — group.purple, group.blue, group.green, group.red, group.orange, group.pink, group.cyan
  • ui.* — tab, shadow, overlay, and gutter tokens
  • diff.* — diff badge and branch colors
  • minimap.* — minimap overlay and border colors

Using Themes in Components

Components use CSS variables directly in stylesheets:

Theme Management

React Context API

The theme system uses React Context (ThemeProvider) to manage theme state and provide theme switching capabilities throughout the app.

Available Context Functions

  • theme: The currently active theme object
  • themes: Array of all built-in themes
  • setTheme(theme): Switch to a different theme
  • loadThemeFromJson(json): Load a custom theme from a JSON string

Persistence

The currently selected theme is persisted as RuntimeState.theme (a JSON row in the SQLite app_state table, keyed runtime). On app startup, the system:
  1. Checks if a theme name is saved in runtime state
  2. Validates the saved theme name against the discovered themes
  3. Falls back to system preference (dark or light mode)
  4. Falls back to the first available built-in theme if no match is found

Application Flow

  1. Initialization: main.tsx wraps the app with ThemeProvider
  2. Theme Resolution: On startup, resolveDefaultTheme() determines which theme to use
  3. CSS Application: applyTheme() sets all CSS variables on the document root and adds a data-theme attribute
  4. Component Rendering: React components access variables via var(--tempest-*)
  5. Theme Switching: Users can change themes via setTheme(), which updates state, applies CSS, and persists to runtime state

Creating Custom Themes

Custom themes can be loaded programmatically using loadThemeFromJson():
The theme object must include name and colors properties to be valid.