# spacemacs-theme: a dark and light Emacs palette with unusually deep org support

> spacemacs-theme is an Emacs color theme that grew out of Spacemacs and is now distributed through NonGNU ELPA and MELPA, where its distinguishing feature is a set of options that let you tune org headings, agenda heights, code blocks and comment contrast individually rather than accepting one fixed look.

**nashamri/spacemacs-theme** — Light and dark theme for spacemacs that supports GUI and terminal

- Repository: https://github.com/nashamri/spacemacs-theme
- Stars: 620 · Forks: 111
- Language: Emacs Lisp
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/nashamri-spacemacs-theme

## A theme that escaped Spacemacs and kept the Spacemacs options

The theme started life inside Spacemacs, and the README says so directly: Spacemacs theme is an Emacs color theme that started as a theme for Spacemacs. What shipped as part of a distribution configuration became a standalone package, and the interesting part is what it kept on the way out. The customisation list is long and specific, and it is not the generic list of face colours you would expect from a theme. It is a list of behaviours that Spacemacs users had been asking for: whether comments get a background, whether comments are italic, whether keywords are italic, and a series of org-specific toggles for agenda heights, heading bold, heading heights, heading highlighting and priority bold in the agenda view. The audience, then, is two overlapping groups. Spacemacs users who want the familiar palette in a plain Emacs config, and org mode users who find most themes treat their outline as a wall of uniform text.

## Installing through the package archives

The theme is published on NonGNU ELPA and on MELPA, and installation is the standard package-install path.

```
M-x package-install RET spacemacs-theme
```

Loading it then needs a little configuration, because the theme ships as a package with separate dark and light variants. The example in the README adds the package with use-package, deferring the load, and then loads the dark theme explicitly.

```
(use-package spacemacs-theme
  :ensure t
  :defer t)

(load-theme 'spacemacs-dark t)
```

The two arguments to load-theme are the theme symbol and a non-interactive flag, which is why the form ends with t. Because the theme is available from two archives, a user will have one of them configured and the package-install command will find it there, and because the package declares a :defer t, the load is deferred until the theme is actually required rather than at startup. The theme also has a Gitter channel linked from the README badges, and it is packaged for both archives under the same name, spacemacs-theme.

## Dark and light variants, and the 256 colour terminal question

The theme comes with dark and light variants, and the README makes a specific claim about terminals: it should work well with 256 colour terminals. That is the constraint that shaped the palette, since a colour theme that looks right in a GUI Emacs can fall apart in a terminal with a smaller palette, and 256 colour is the common floor for a modern terminal emulator. The two force options exist for the same reason. The theme can be told to use GUI or terminal colours regardless of what display-graphic-p reports, which matters when Emacs is running inside a terminal but your configuration was written for a graphical session. The README is explicit about the precedence: if both toggles are on, spacemacs-theme-force-terminal-colors takes precedence. The repository layout reflects the two variants, with separate spacemacs-dark-theme.el and spacemacs-light-theme.el files alongside the shared spacemacs-theme.el and a spacemacs-theme-pkg.el package descriptor.

## The org mode options are the reason to use this theme

The theme's own highlight list says it has good support for org mode, and the customisation options are where that shows. There is a toggle for varying org agenda heights, one for bold text in org headings, one for varying org heading heights, one for highlighting org headings, and one for bold priority items in the agenda view. That is five separate switches for org behaviour, and they are separate for a reason. A user with a dense agenda may want the priority bold off and the varying heights on, while a user writing prose in org files may want heading bold on and the heading highlight off. A theme that treats org as one face gives no such control. There is also a code block treatment, with the cblk role for code block colour, cblk-bg for its background, cblk-ln for the header line and cblk-ln-bg for that header line's background, which is a level of detail most themes do not reach.

## Comment contrast is a decision you have to make

Two of the options interact, and the README explains how. The spacemacs-theme-comment-bg option toggles a background colour for comment lines, and spacemacs-theme-comment-italic toggles italics for comments and also adds a lighter colour to them. The recommendation is to disable spacemacs-theme-comment-bg if you turn the italic option on, for better contrast. That is a sensible piece of advice that says more about the palette than the option list does. A comment colour light enough to be legible on the base background is not light enough to be legible on a background that is itself a different light shade, and the two together wash out. Turning italics on also lightens the comment colour, so the two options interact in the direction of reduced legibility rather than improved. If you are configuring this theme by eye, that pairing is the first thing to check.

## Overriding colours through a role list

Beyond the on and off toggles, the theme exposes a table of colour roles that you can override. The README explains the mechanism: the theme can be customized by overriding one of the theme local variables by setting a list in the spacemacs-theme-custom-colors variable. The role table then maps short names to jobs, and the naming is worth reading because it tells you how the palette is structured. There are four background shades in a row, bg1 through bg4, described as the background, a darker background used to highlight the current line, yet another darker shade, and the darkest of all. There are four heading levels, head1 through head4, each with a matching background role. Then come the semantic roles, base for normal text, base-dim for a dimmer version of it, comment, const, comp, err, func, cursor, border, act1 and act2 for the two active mode-line colours, and cblk with its three companions for code blocks. The base, base-dim and four background scale means you can shift a surface without redoing the whole palette.

## Where this theme does not fit

There are limits that come from the era. The theme assumes a Spacemacs-shaped Emacs, with the package loaded through use-package and deferred, and the option set is tuned around that world. On a recent Emacs with the built in theme system and the wider customisation that ships with it, some of these options have no direct equivalent, and the org-specific switches in particular assume the org version the theme was written against. The second limit is scope. It is a color theme and nothing more. It does not change key bindings, add layers, restructure the mode line, or provide the Spacemacs behaviour that many people actually want when they say they want a Spacemacs theme, which is a distribution with a different feel rather than a palette. The third is packaging. The theme is distributed through ELPA archives, and a theme that lives in a third party archive rather than in Emacs itself is one more dependency to keep resolvable, and the repository publishes no GitHub releases, so the last push, on 2026-09-06, is the closest thing to a version marker. The alternative worth naming is one of the themes bundled with Emacs itself, which removes the packaging dependency and the compatibility questions, at the cost of the Spacemacs palette and the org options that are the actual reason to pick this one.

## Conclusion

Adopt spacemacs-theme if you came from Spacemacs and want that look outside it, or if you use org mode heavily and want per element control over headings, agenda rows, code blocks and comment contrast. Do not adopt it if you are on a recent Emacs with a native theme system, since the theme is written for the Spacemacs era and its options assume that setup. Verify first that the theme loads in your Emacs version, that the package archives still carry it, and that the org variables behave as you expect with the org version you run.

## FAQ

### How do I install the spacemacs-theme Emacs theme?

It is published on NonGNU ELPA and MELPA, so you install it with M-x package-install RET spacemacs-theme. To load the dark variant, add the package with use-package and :defer t to your init file, then call load-theme with the spacemacs-dark symbol.

### What org mode options does spacemacs-theme offer?

Separate toggles for varying org agenda heights, bold text in org headings, varying org heading heights, highlighting of org headings, and bold priority items in the agenda view, plus a distinct code block treatment with its own colour, background and header line roles.

### How do I override individual colors in spacemacs-theme?

Set a list in the spacemacs-theme-custom-colors variable, overriding one of the theme local variables. The roles include base, base-dim, four background shades from bg1 to bg4, comment, const, comp, err, func, cursor, border, the two mode-line active colors, the four heading levels, and the code block roles.

### Does the spacemacs theme work in a terminal?

The README says the theme comes with dark and light variants and should work well with 256 colour terminals. There are also options to force GUI or terminal colours regardless of the value of display-graphic-p, and if both are enabled the terminal colours take precedence.

## Sources

- [Issues](https://github.com/nashamri/spacemacs-theme/issues)
- [License: GPL-3.0](https://github.com/nashamri/spacemacs-theme/blob/master/LICENSE)
- [nashamri/spacemacs-theme on GitHub](https://github.com/nashamri/spacemacs-theme)
- [README](https://github.com/nashamri/spacemacs-theme/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nashamri-spacemacs-theme