Theme System User Flows

This document describes the user flows for adding and customizing themes in Fresh.

Overview

Fresh has a robust theming system with 5 color categories:

• Editor Colors - background, cursor, selection, line highlighting
• UI Colors - tabs, menus, status bar, popups, scrollbars
• Search Colors - match highlighting
• Diagnostic Colors - errors, warnings, info, hints
• Syntax Colors - keywords, strings, comments, functions, etc.

User Flow 1: Quick Theme Selection

Goal: Switch between available themes

1. Press Ctrl+P to open command palette
2. Type "select theme" and press Enter
3. Browse/filter themes (current theme marked with "(current)")
4. Press Enter to apply - takes effect immediately
5. Theme preference saved to ~/.config/fresh/config.json

Files involved:

• src/app/input.rs:1932-1975 - start_select_theme_prompt()
• src/app/input.rs:1978-1995 - apply_theme()

User Flow 2: Interactive Theme Editor

Goal: Create or modify themes visually

Opening the Editor

1. Press Ctrl+P to open command palette
2. Type "edit theme" and press Enter
3. Theme Editor opens in current split

Optional: Add a keyboard shortcut

To open the theme editor with a single keystroke, add a custom keybinding in ~/.config/fresh/config.json:

{
  "keybindings": {
    "normal": [
      ["C-S-t", "open_theme_editor"]
    ]
  }
}

This binds Ctrl+Shift+T to open the theme editor. You can choose any key combination.

Creating a New Theme

1. Press o to open a theme (built-in or user) as starting point
2. Navigate with arrow keys to color fields
3. Press Enter or Space to edit a color
4. Input color as: #FF0000 (hex), [255,0,0] (RGB), or Red (named)
5. Press s to save (prompts for name if built-in) - theme is automatically applied

Key Bindings

All commands are also available via the command palette (Ctrl+P) when the theme editor is open.

Color Input Formats

• Hex: #FF8000 or #ff8000
• RGB array: [255, 128, 0] or 255,128,0
• Named colors: Red, Green, Blue, DarkGray, White, etc.
• Special: Default or Reset (uses terminal's native color for transparency)

Files involved:

• plugins/theme_editor.ts - Full interactive editor implementation

User Flow 3: Manual JSON File Creation

Goal: Create themes by writing JSON directly

Steps

1. Create file at ~/.config/fresh/themes/my-theme.json
2. Use the required JSON structure (see below)
3. Theme appears automatically in theme selector
4. Select via Ctrl+P → "select theme"

Theme JSON Structure

{
  "name": "my-theme",
  "editor": {
    "bg": [30, 30, 30],
    "fg": [212, 212, 212],
    "cursor": [255, 255, 255],
    "inactive_cursor": [100, 100, 100],
    "selection_bg": [38, 79, 120],
    "current_line_bg": [40, 40, 40],
    "line_number_fg": [100, 100, 100],
    "line_number_bg": [30, 30, 30],
    "diff_add_bg": [35, 60, 35],
    "diff_remove_bg": [70, 35, 35],
    "diff_modify_bg": [40, 38, 30]
  },
  "ui": {
    "tab_active_fg": [255, 255, 255],
    "tab_active_bg": [30, 30, 30],
    "tab_inactive_fg": [150, 150, 150],
    "tab_inactive_bg": [45, 45, 45],
    "tab_separator_bg": [30, 30, 30],
    "menu_bar_bg": [51, 51, 51],
    "menu_bar_fg": [255, 255, 255],
    "status_bar_bg": [0, 122, 204],
    "status_bar_fg": [255, 255, 255],
    "prompt_fg": [255, 255, 255],
    "prompt_bg": [60, 60, 60],
    "prompt_selection_fg": [255, 255, 255],
    "prompt_selection_bg": [0, 122, 204],
    "popup_border_fg": [100, 100, 100],
    "popup_bg": [45, 45, 45],
    "popup_selection_bg": [0, 122, 204],
    "popup_text_fg": [255, 255, 255],
    "suggestion_bg": [45, 45, 45],
    "suggestion_selected_bg": [0, 122, 204],
    "help_bg": [30, 30, 30],
    "help_fg": [255, 255, 255],
    "help_key_fg": [86, 156, 214],
    "help_separator_fg": [100, 100, 100],
    "help_indicator_fg": [255, 100, 100],
    "help_indicator_bg": [30, 30, 30],
    "split_separator_fg": [100, 100, 100]
  },
  "search": {
    "match_bg": [255, 215, 0],
    "match_fg": [0, 0, 0]
  },
  "diagnostic": {
    "error_fg": [255, 85, 85],
    "error_bg": [50, 30, 30],
    "warning_fg": [255, 200, 100],
    "warning_bg": [50, 45, 30],
    "info_fg": [100, 200, 255],
    "info_bg": [30, 40, 50],
    "hint_fg": [150, 150, 150],
    "hint_bg": [30, 30, 30]
  },
  "syntax": {
    "keyword": [197, 134, 192],
    "string": [206, 145, 120],
    "comment": [106, 153, 85],
    "function": [220, 220, 170],
    "type": [78, 201, 176],
    "variable": [156, 220, 254],
    "constant": [100, 150, 200],
    "operator": [212, 212, 212]
  }
}

User Flow 4: Override Built-in Theme

Goal: Customize a built-in theme without renaming

1. Copy a built-in theme from themes/ directory
2. Place it at ~/.config/fresh/themes/<same-name>.json
3. User themes take precedence over built-ins with same name

Example:

cp themes/dark.json ~/.config/fresh/themes/dark.json
# Edit ~/.config/fresh/themes/dark.json

User Flow 5: Set Default Theme via Config

Goal: Change default theme without UI

Edit ~/.config/fresh/config.json:

{
  "theme": "nord"
}

Default theme is high-contrast if not specified.

Built-in Themes

Theme Storage Locations

Key Files Reference