BetterCurseForge/docs/guide/themes.md

# Themes

BetterCurseForge can load custom themes and reload them live. A theme is a CSS file, optionally with a JSON manifest, and it appears in CurseForge's own theme settings.

---

## Picking a theme

Client themes are added to CurseForge's own **Settings -> Themes** page.

### Finding client themes
1. Open CurseForge.
2. Click the **Settings** gear icon in the bottom-left corner.
3. Choose **Themes** in the settings sidebar.
4. Scroll past the *Classic*, *Colorblind* and *Premium* categories to reach **Client Themes**:

![Settings Themes View](/logo.svg){width=48 style="display:block;margin:1rem auto;"}

### What the theme page does
- **Hover preview**: Hover over a theme card to preview it across the whole launcher. Move the cursor away to revert, or click to apply it.
- **One theme at a time**: Picking a client theme deselects any native skin, and the other way around.
- **Open Folder button**: Opens your themes folder in Explorer so you can drop in new stylesheets.
- **Refresh button**: Reloads your custom themes from disk, no restart needed.
- **Premium themes unlocked**: The official Premium themes (*Pixelforge*, *Lifeforge*, *Fantasyforge* and *Spookyforge*) are unlocked and free to use.

---

## Theme folder

Themes live in your user application data directory:

```text
%APPDATA%\CurseForge\BetterCurseForge\themes\
```

Full path:
```text
C:\Users\<YourUsername>\AppData\Roaming\CurseForge\BetterCurseForge\themes\
```

The **Open Folder** button in **Settings -> Themes** opens it for you.

---

## Theme layout

There are two ways to lay out a theme:

### 1. Single file (recommended)
Put a `.css` file in `themes/`, with an optional `.json` manifest next to it:

```text
themes/
├── purple-night.css
└── purple-night.json   (optional metadata & preview colors)
```

### 2. Folder
Make a folder inside `themes/` containing `theme.css` and `theme.json`:

```text
themes/
└── emerald-dark/
    ├── theme.json
    ├── theme.css
    └── background.webp  (optional custom assets)
```

---

## Manifest (`theme.json`)

The manifest holds the theme's metadata and the colors of the small preview card shown in **Settings -> Themes**:

```json
{
  "name": "Emerald Dark",
  "version": "1.0.0",
  "description": "Deep obsidian tones with vivid emerald green accents.",
  "author": "ModderDev",
  "primaryColor": "#10b981",
  "titleColor": "#064e3b",
  "bodyColor": "#022c22",
  "backgroundColor": "#051c14"
}
```

### Fields

| Field | Type | Description |
| :--- | :--- | :--- |
| `name` | `string` | Name shown on the theme card and in settings. |
| `version` | `string` | Semantic version (e.g. `1.0.0`). |
| `description` | `string` | Short description, shown as a tooltip when you hover the title. |
| `author` | `string` | Author name or handle. |
| `primaryColor` | `string` | Hex color of the square icon on the preview card. |
| `titleColor` | `string` | Hex color of the top bar on the preview card. |
| `bodyColor` | `string` | Hex color of the lower text bar on the preview card. |
| `backgroundColor`| `string` | Hex background color of the preview card. |

---

## CSS variables

CurseForge is styled with CSS custom properties. Overriding them lets you theme most of the app without touching individual class names.

### Brand & accents

| Variable | Description |
| :--- | :--- |
| `--surface-brand-brand` | Main brand accent: active tabs, primary buttons, indicators. |
| `--surface-brand-brand-hover` | Hover state for brand-colored elements. |
| `--color-primary` | Main accent color. |
| `--color-accent` | Secondary highlight color. |
| `--selected-item-border` | Border style for selected items and active inputs. |

### Surfaces & backgrounds

| Variable | Description |
| :--- | :--- |
| `--color-background` | Main app background (content views, modpack library). |
| `--surface-base` | Darkest background layer (scroll tracks, container bases). |
| `--surface-primary` | Raised surface (sidebars, sub-panels). |
| `--surface-secondary` | Second surface layer (navigation menus, dialog panels). |
| `--surface-tertiery` | Third surface layer (mod cards, list row containers). |
| `--surface-on-surface` | Faint translucent overlay for buttons (`rgba(...)`). |
| `--surface-on-surface-hover` | Translucent hover overlay for buttons. |

### Modpack & library cards

| Variable | Description |
| :--- | :--- |
| `--surface-card` | Base background of modpack and project cards. |
| `--surface-card-hover` | Background when hovering over a modpack card. |
| `--color-surface-card-active` | Active or clicked state of a card. |

### Typography & text

| Variable | Description |
| :--- | :--- |
| `--text-pure` | Pure white text (`#ffffff`). |
| `--text-primary` | Main readable text color. |
| `--color-text-title` | Headings, modpack titles, section names. |
| `--color-text-body` | Normal body and description text. |
| `--color-text-secondary` | Subtitles, authors, version numbers. |

### Title bar & navigation

| Variable | Description |
| :--- | :--- |
| `--title-bar-background` | Background color or gradient of the window title bar. |
| `--btn-window-action` | Icons on the minimize, maximize and close buttons. |
| `--color-scrollbar-thumb` | Scrollbar thumb color. |

---

## Example: Emerald Night

A full working theme. Save the stylesheet as `emerald-night.css` and the manifest as `emerald-night.json`:

::: code-group

```css [emerald-night.css]
/* ==========================================================================
   BetterCurseForge Theme: Emerald Night
   ========================================================================== */

:root,
.cf-app,
.base-skin,
.dark-skin,
.cf-classic {
  /* ── Accent & Brand ── */
  --surface-brand-brand: #10b981 !important;
  --surface-brand-brand-hover: #34d399 !important;
  --color-primary: #10b981 !important;
  --color-primary-hover: #34d399 !important;
  --color-primary-active: #059669 !important;
  --color-accent: #6ee7b7 !important;
  --selected-item-border: 2px solid #10b981 !important;

  /* ── Backgrounds & Surfaces ── */
  --color-background: #06140f !important;
  --surface-base: #030b08 !important;
  --surface-primary: #091c16 !important;
  --surface-secondary: #0d271f !important;
  --surface-tertiery: #13352b !important;
  --surface-tertiery-hover: #194639 !important;

  /* ── Modpack & Library Cards ── */
  --surface-card: #0d271f !important;
  --surface-card-hover: #14382d !important;

  /* ── Typography & Text ── */
  --text-pure: #ffffff !important;
  --text-primary: #f0fdf4 !important;
  --color-text-title: #ffffff !important;
  --color-text-body: #d1fae5 !important;
  --color-text-secondary: #6ee7b7 !important;

  /* ── Title Bar ── */
  --title-bar-background: #091c16 !important;
  --btn-window-action: #6ee7b7 !important;

  /* ── Scrollbars ── */
  --color-scrollbar-thumb: #13352b !important;
}

/* Primary Action Buttons */
.btn-primary:not(.btn-secondary),
button[class*="primary"]:not([class*="secondary"]) {
  background: #10b981 !important;
  color: #030b08 !important;
  font-weight: 600 !important;
}

.btn-primary:not(.btn-secondary):hover,
button[class*="primary"]:not([class*="secondary"]):hover {
  background: #34d399 !important;
}
```

```json [emerald-night.json]
{
  "name": "Emerald Night",
  "version": "1.0.0",
  "description": "Deep emerald dark theme for CurseForge Launcher.",
  "author": "BetterCurseForge",
  "primaryColor": "#10b981",
  "titleColor": "#0d271f",
  "bodyColor": "#06140f",
  "backgroundColor": "#091c16"
}
```

:::

---

## Inspecting elements

CurseForge is an Electron and React app, so you can inspect its UI with Chromium DevTools:

1. Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> in CurseForge to open DevTools.
2. Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> to turn on the element inspector.
3. Click a button, banner, header or list item to see its computed styles and classes in the **Elements** panel.
4. Try CSS changes in the **Styles** tab before adding them to your theme.
5. In **Settings -> Themes**, click **Refresh** to load your updated stylesheet.