> ## Documentation Index
> Fetch the complete documentation index at: https://recircles.rekosk.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a user theme

> Build a reusable color palette in a single JSON file, install it from Settings, and share it with anyone who wants the same colors in their launcher.

A ReCircles theme can be as small as one color. This example turns the ring copper at the top and plum at the bottom. The search capsule picks up the same copper and plum from the ring. The text keeps its Amber colors.

**1. Save a palette**

Save this file as `copper-dusk.json`. The filename gives the theme its ID, `copper-dusk`. The optional `name` gives it a label in Settings.

```json copper-dusk.json theme={null}
{
  "name": "Copper Dusk",
  "ring": {
    "top": "#673b29",
    "mid": "#382029",
    "bottom": "#291a28",
    "rim_top": "#ffd1a1"
  },
  "accents": {
    "files": "#ffb087",
    "custom": "#efa8bf"
  }
}
```

**2. Install it from Settings**

Run `recircles --run settings`. Open **Colors → Theme → Add local theme...** and choose the file. ReCircles installs it under `themes/` in your configuration directory and applies the palette. Open the main ring to see the new gradient.

**3. Try another palette**

Return to **Colors → Theme** and choose **Amber (Default)**. You can switch back to **Copper Dusk** from the same list. To tune one shade directly, choose its field under **Colors** and use the RGB sliders or hex entry. The picker saves the edit to your launcher configuration.

## Install or update the file by hand

With the launcher closed, copy your theme into the configuration directory. On the next launch, select **Copper Dusk** in Settings.

```sh theme={null}
theme_dir="${XDG_CONFIG_HOME:-$HOME/.config}/recircles/themes"
mkdir -p "$theme_dir"
cp copper-dusk.json "$theme_dir/"
```

You can also select it by editing just the `colors` object in `recircles.json`. Keep your other top-level settings. Reopen ReCircles after saving.

```json theme={null}
{
  "colors": {
    "theme": "copper-dusk"
  }
}
```

## Share a theme

Send the JSON file as it is, or put several theme JSON files with distinct filenames in one ZIP. Import either format through **Add local theme...**. With a ZIP, ReCircles installs valid palettes and applies the first one it imports.

Use a distinct filename when you want a new theme. A local file with a built-in ID can replace the corresponding palette in the picker. The ID `custom` is reserved. For manual installation, use a visible filename ending in lowercase `.json`.

If a palette is missing from the list, check that it contains at least one recognized color group and that each color uses a three- or six-digit RGB value. [Palette fields and defaults](https://recircles.rekosk.dev/docs/themes/palette.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.