Color Schemes

February 10, 2026 · View on GitHub

This repository contains custom themes for nucleus-shell, you can add these into your setup by putting the json files into ~/.config/nucleus-shell/colorschemes

I also added a guide below which explains how to add, create, and customize color schemes.

Installation

Running the command below will install all the colorschemes in ~/.config/nucleus-shell/colorschemes:

curl -fsSL https://raw.githubusercontent.com/xZepyx/nucleus-colorschemes/main/install.sh | bash

1. Location of Color Schemes

All color scheme files are stored in:

~/.config/nucleus-shell/colorschemes/

Each scheme is a separate .json file. The filename (without .json) is used as the theme name in the shell.

Important

Each theme should have a -dark or -light specifier after it so the shell can recognize which theme type is it. If not specified shell will not recognize it or theme selector might break.

Example:

catppuccin-lavender-light.json
everforest-dark.json
monochrome-dark.json

2. Adding a Predefined Scheme

  1. Download or copy a .json file into the colorschemes directory.
  2. Ensure the file has a unique name (lowercase preferred, no spaces).
  3. The shell will automatically detect the new scheme after restarting the settings panel.
  4. The new scheme will appear in Appearance>Preset Themes.

3. Creating a Custom Color Scheme

  1. Navigate to the color schemes folder:
cd ~/.config/nucleus-shell/colorschemes
  1. Create a new JSON file:
touch my-custom-theme-variant(dark/light).json
  1. Open the file in a text editor and define your colors. Example template:
{
  "_comment": "<Theme Name> – Variant",

  "background": "#color",
  "surface": "#color",
  "surface_dim": "#color",
  "surface_bright": "#color",

  "surface_container_lowest": "#color",
  "surface_container_low": "#color",
  "surface_container": "#color",
  "surface_container_high": "#color",
  "surface_container_highest": "#color",

  "on_background": "#color",
  "on_surface": "#color",
  "on_surface_variant": "#color",

  "primary": "#color",
  "primary_container": "#color",
  "on_primary": "#color",
  "on_primary_container": "#color",

  "secondary": "#color",
  "secondary_container": "#color",
  "on_secondary": "#color",
  "on_secondary_container": "#color",

  "tertiary": "#color",
  "tertiary_container": "#color",
  "on_tertiary": "#color",
  "on_tertiary_container": "#color",

  "error": "#color",
  "error_container": "#color",
  "on_error": "#color",
  "on_error_container": "#color",

  "outline": "#color",
  "outline_variant": "#color",

  "inverse_surface": "#color",
  "inverse_on_surface": "#color",
  "inverse_primary": "#color",

  "shadow": "#color",
  "scrim": "#color",
  "surface_tint": "#color",
  "source_color": "#color"
}
  1. Replace #color with your desired hex values.
  2. Save the file — the filename (without .json) becomes the theme name.
  3. Select your new theme from the Nucleus's Settings app
  4. Note that all of the values above are required to be filled. If not shell will fallback to black or white color which can look very weird.

Feel free to make PR and add more themes for Nucleus Shell!