> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme System

> Built-in themes, theme structure, and how to customize colors in Fresh

## Built-in Themes

Fresh includes several carefully designed themes optimized for terminal use:

<Tabs>
  <Tab title="High Contrast">
    **High visibility theme with strong color contrast**

    Optimized for accessibility and readability in any lighting condition. Features bright text on dark backgrounds with vivid syntax highlighting.

    ```json theme={null}
    {"theme": "high-contrast"}
    ```
  </Tab>

  <Tab title="Dark">
    **Classic dark theme**

    Comfortable dark theme with muted colors. Easy on the eyes for extended coding sessions.

    ```json theme={null}
    {"theme": "dark"}
    ```
  </Tab>

  <Tab title="Light">
    **Bright theme for daylight use**

    Clean light theme with dark text on light backgrounds. Perfect for well-lit environments.

    ```json theme={null}
    {"theme": "light"}
    ```
  </Tab>

  <Tab title="Nord">
    **Arctic-inspired color palette**

    Based on the popular Nord color scheme. Cool blues and muted pastels create a calm coding environment.

    ```json theme={null}
    {"theme": "nord"}
    ```
  </Tab>

  <Tab title="Dracula">
    **Dark theme with vibrant accents**

    Inspired by the Dracula theme. Dark purple backgrounds with bright, saturated syntax colors.

    ```json theme={null}
    {"theme": "dracula"}
    ```
  </Tab>

  <Tab title="Nostalgia">
    **Retro terminal aesthetic**

    Classic terminal look with amber/green monochrome styling reminiscent of vintage CRT displays.

    ```json theme={null}
    {"theme": "nostalgia"}
    ```
  </Tab>

  <Tab title="Solarized Dark">
    **Precision colors for readability**

    Based on Solarized Dark by Ethan Schoonover. Scientifically designed color relationships.

    ```json theme={null}
    {"theme": "solarized-dark"}
    ```
  </Tab>
</Tabs>

## Changing Themes

### Via Configuration File

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

```json config.json theme={null}
{
  "theme": "dracula"
}
```

**Available theme names:**

* `"high-contrast"` (default)
* `"dark"`
* `"light"`
* `"nord"`
* `"dracula"`
* `"nostalgia"`
* `"solarized-dark"`

### Via Menu

1. Open **View** → **Select Theme...**
2. Choose from the list of available themes
3. Theme changes apply immediately

### Via Command Palette

1. Press `Ctrl+P`
2. Type `>select theme`
3. Select theme from the dropdown

## Theme Structure

Themes are JSON files located in `~/.config/fresh/themes/` or in the editor's built-in theme directory. Each theme defines colors for:

* **Editor**: Background, foreground, cursor, selection, line numbers
* **UI**: Tabs, menu bar, status bar, popups, scrollbars
* **Search**: Match highlighting
* **Diagnostics**: Errors, warnings, info, hints
* **Syntax**: Keywords, strings, comments, functions, types

### Theme File Example

<CodeGroup>
  ```json dark.json theme={null}
  {
    "name": "dark",
    "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],
      "whitespace_indicator_fg": [70, 70, 70]
    },
    "ui": {
      "tab_active_fg": "Yellow",
      "tab_active_bg": "Blue",
      "tab_inactive_fg": "White",
      "tab_inactive_bg": "DarkGray",
      "status_bar_fg": "White",
      "status_bar_bg": [30, 30, 30],
      "menu_bg": [60, 60, 65],
      "menu_fg": [220, 220, 220]
    },
    "syntax": {
      "keyword": [86, 156, 214],
      "string": [206, 145, 120],
      "comment": [106, 153, 85],
      "function": [220, 220, 170],
      "type": [78, 201, 176],
      "variable": [156, 220, 254],
      "constant": [79, 193, 255],
      "operator": [212, 212, 212]
    },
    "diagnostic": {
      "error_fg": "Red",
      "warning_fg": "Yellow",
      "info_fg": "Blue",
      "hint_fg": "Gray"
    },
    "search": {
      "match_bg": [100, 100, 20],
      "match_fg": [255, 255, 255]
    }
  }
  ```

  ```json nord.json theme={null}
  {
    "name": "nord",
    "editor": {
      "bg": [46, 52, 64],
      "fg": [216, 222, 233],
      "cursor": [136, 192, 208],
      "selection_bg": [67, 76, 94],
      "current_line_bg": [59, 66, 82],
      "line_number_fg": [76, 86, 106],
      "whitespace_indicator_fg": [67, 76, 94]
    },
    "syntax": {
      "keyword": [129, 161, 193],
      "string": [163, 190, 140],
      "comment": [76, 86, 106],
      "function": [136, 192, 208],
      "type": [143, 188, 187],
      "variable": [216, 222, 233],
      "constant": [180, 142, 173]
    }
  }
  ```
</CodeGroup>

## Color Format

Colors can be specified in two formats:

### RGB Array

```json theme={null}
"bg": [46, 52, 64]
```

RGB values from 0-255.

### Named Colors

```json theme={null}
"fg": "White"
```

**Available named colors:**

* `"Black"`, `"Red"`, `"Green"`, `"Yellow"`, `"Blue"`, `"Magenta"`, `"Cyan"`, `"White"`
* `"Gray"`, `"DarkGray"`, `"LightRed"`, `"LightGreen"`, `"LightYellow"`, `"LightBlue"`, `"LightMagenta"`, `"LightCyan"`
* `"Default"` (use terminal default)

## Creating a Custom Theme

<Steps>
  <Step title="Create theme file">
    Create `~/.config/fresh/themes/my-theme.json`:

    ```json my-theme.json theme={null}
    {
      "name": "my-theme",
      "editor": {
        "bg": [20, 20, 20],
        "fg": [220, 220, 220],
        "cursor": [255, 255, 255],
        "selection_bg": [60, 80, 120]
      },
      "syntax": {
        "keyword": [100, 150, 255],
        "string": [150, 200, 100],
        "comment": [100, 100, 100]
      }
    }
    ```
  </Step>

  <Step title="Activate theme">
    Set the theme in `config.json`:

    ```json theme={null}
    {"theme": "my-theme"}
    ```
  </Step>

  <Step title="Reload">
    Fresh automatically reloads when config changes. Your custom theme is now active.
  </Step>
</Steps>

## Theme Components

### Editor Colors

| Key                       | Description                               |
| ------------------------- | ----------------------------------------- |
| `bg`                      | Editor background                         |
| `fg`                      | Default text color                        |
| `cursor`                  | Cursor color                              |
| `inactive_cursor`         | Cursor color in inactive splits           |
| `selection_bg`            | Selected text background                  |
| `current_line_bg`         | Current line highlight background         |
| `line_number_fg`          | Line number color                         |
| `line_number_bg`          | Line number gutter background             |
| `whitespace_indicator_fg` | Whitespace character color (tabs, spaces) |
| `diff_add_bg`             | Added line background (diff view)         |
| `diff_remove_bg`          | Removed line background                   |
| `diff_modify_bg`          | Modified line background                  |

### UI Colors

| Key                                         | Description              |
| ------------------------------------------- | ------------------------ |
| `tab_active_fg` / `tab_active_bg`           | Active tab colors        |
| `tab_inactive_fg` / `tab_inactive_bg`       | Inactive tab colors      |
| `tab_separator_bg`                          | Tab separator background |
| `status_bar_fg` / `status_bar_bg`           | Status bar colors        |
| `menu_bg` / `menu_fg`                       | Menu colors              |
| `menu_highlight_bg` / `menu_highlight_fg`   | Menu selection colors    |
| `popup_bg` / `popup_text_fg`                | Popup/dialog colors      |
| `scrollbar_track_fg` / `scrollbar_thumb_fg` | Scrollbar colors         |
| `split_separator_fg`                        | Split pane separator     |

### Syntax Colors

| Key        | Description                              |
| ---------- | ---------------------------------------- |
| `keyword`  | Language keywords (if, for, while, etc.) |
| `string`   | String literals                          |
| `comment`  | Comments                                 |
| `function` | Function names                           |
| `type`     | Type names (classes, structs, etc.)      |
| `variable` | Variables                                |
| `constant` | Constants                                |
| `operator` | Operators (+, -, \*, etc.)               |

### Diagnostic Colors

| Key                         | Description             |
| --------------------------- | ----------------------- |
| `error_fg` / `error_bg`     | Error diagnostic colors |
| `warning_fg` / `warning_bg` | Warning colors          |
| `info_fg` / `info_bg`       | Info colors             |
| `hint_fg` / `hint_bg`       | Hint colors             |

### Search Colors

| Key                     | Description               |
| ----------------------- | ------------------------- |
| `match_bg` / `match_fg` | Search match highlighting |

## Terminal Background Transparency

To use your terminal's background (e.g., for transparency):

```json config.json theme={null}
{
  "editor": {
    "use_terminal_bg": true
  }
}
```

This makes Fresh inherit the terminal's background color instead of using the theme's `editor.bg`.

## Theme Inheritance

You can create themes that extend existing ones:

```json custom-dark.json theme={null}
{
  "name": "custom-dark",
  "inherits": "dark",
  "syntax": {
    "keyword": [255, 100, 100],
    "string": [100, 255, 100]
  }
}
```

<Note>
  Only the specified fields are overridden. All other colors inherit from the parent theme.
</Note>

## Installing Community Themes

Fresh supports installing themes from the plugin registry:

```bash theme={null}
fresh --install-plugin theme-name
```

Themes are installed to `~/.config/fresh/themes/`.

## Sharing Themes

To share your theme:

1. Create a theme JSON file
2. Publish to GitHub
3. Submit to the [Fresh plugins registry](https://github.com/sinelaw/fresh-plugins-registry)

## Example: Complete Theme

<AccordionGroup>
  <Accordion title="View complete dracula.json theme">
    ```json dracula.json theme={null}
    {
      "name": "dracula",
      "editor": {
        "bg": [40, 42, 54],
        "fg": [248, 248, 242],
        "cursor": [255, 121, 198],
        "selection_bg": [68, 71, 90],
        "current_line_bg": [50, 52, 66],
        "line_number_fg": [98, 114, 164],
        "line_number_bg": [40, 42, 54],
        "whitespace_indicator_fg": [68, 71, 90]
      },
      "ui": {
        "tab_active_fg": [248, 248, 242],
        "tab_active_bg": [189, 147, 249],
        "tab_inactive_fg": [248, 248, 242],
        "tab_inactive_bg": [68, 71, 90],
        "tab_separator_bg": [40, 42, 54],
        "status_bar_fg": [40, 42, 54],
        "status_bar_bg": [189, 147, 249],
        "menu_bg": [40, 42, 54],
        "menu_fg": [248, 248, 242],
        "menu_highlight_bg": [189, 147, 249],
        "menu_highlight_fg": [40, 42, 54],
        "popup_bg": [40, 42, 54],
        "popup_text_fg": [248, 248, 242],
        "scrollbar_track_fg": [68, 71, 90],
        "scrollbar_thumb_fg": [98, 114, 164]
      },
      "syntax": {
        "keyword": [255, 121, 198],
        "string": [241, 250, 140],
        "comment": [98, 114, 164],
        "function": [80, 250, 123],
        "type": [139, 233, 253],
        "variable": [248, 248, 242],
        "constant": [189, 147, 249],
        "operator": [255, 121, 198]
      },
      "diagnostic": {
        "error_fg": [255, 85, 85],
        "error_bg": [64, 42, 54],
        "warning_fg": [241, 250, 140],
        "warning_bg": [64, 60, 42],
        "info_fg": [139, 233, 253],
        "info_bg": [40, 56, 70],
        "hint_fg": [98, 114, 164],
        "hint_bg": [40, 42, 54]
      },
      "search": {
        "match_bg": [241, 250, 140],
        "match_fg": [40, 42, 54]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Settings Reference" icon="sliders" href="/configuration/settings">
    Explore all editor configuration options
  </Card>

  <Card title="Keyboard Configuration" icon="keyboard" href="/configuration/keyboard">
    Customize keybindings and keymaps
  </Card>
</CardGroup>