Theme System

​

How It Works

​

Token to CSS Variable Conversion

bg.editor       → --tempest-bg-editor
fg.default      → --tempest-fg-default
accent.blue     → --tempest-accent-blue
syntax.keyword  → --tempest-syntax-keyword

function tokenToCssVar(token: string): string {
  return "--tempest-" + token.replace(/\./g, "-");
}

​

Theme Structure

{
  "name": "Tempest Dark",
  "type": "dark",
  "colors": {
    "bg.base": "#000000",
    "fg.default": "#ededed",
    "accent.blue": "#62a6ff"
  }
}

​

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 Dark

​

Tempest Light

​

Color Token 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.*)

• accent.blue
• accent.pink
• accent.green
• accent.yellow
• accent.purple
• accent.cyan
• accent.red

​

Syntax Highlighting (syntax.*)

• 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.*)

• 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.*)

• 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.*)

• semantic.error: Error state
• semantic.warning: Warning state
• semantic.info: Info state
• semantic.success: Success state

​

Terminal Colors (terminal.*)

• 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

​

Using Themes in Components

.button {
  background: var(--tempest-bg-editor);
  color: var(--tempest-fg-default);
  border: 1px solid var(--tempest-border-default);
}

.button:hover {
  background: var(--tempest-bg-hover);
}

.accent {
  color: var(--tempest-accent-blue);
}

​

Theme Management

​

React Context API

import { useTheme } from "./themes/ThemeContext";

function MyComponent() {
  const { theme, themes, setTheme } = useTheme();
  
  return (
    <button onClick={() => setTheme(themes[0])}>
      Switch Theme
    </button>
  );
}

​

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

1. Checks if a theme is saved in localStorage
2. Validates the saved theme name (handles legacy “Origin” theme name migration)
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

​

Legacy Theme Names

• “Origin Dark” → “Tempest Dark”
• “Origin Light” → “Tempest Light”

​

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 localStorage

​

Creating Custom Themes

const { loadThemeFromJson } = useTheme();

const customTheme = JSON.stringify({
  name: "My Custom Theme",
  type: "dark",
  colors: {
    "bg.base": "#1a1a1a",
    "fg.default": "#ffffff",
    // ... other color tokens
  }
});

loadThemeFromJson(customTheme);