Notes for aspiring Emacs theme developers
In Emacs a “theme” is a set of configurations that can be enabled or disabled as a block. Each of those controls a construct of the rendering engine known as a “face”. Faces store the properties that are associated with each element on display. These properties encompass background and/or foreground colours as well as typographic attributes, such as the font weight or slant.
Finding faces
Themes are programs written in Emacs Lisp (Elisp), whose intended role
is to control faces. We can learn about all the faces that are loaded
in the current session with M-x list-faces-display. The command will
produce a buffer with the symbol (i.e. unique name) of the face and a
preview of how it looks.
You can always consult the help page of a given symbol with C-h o
(M-x describe-symbol). Place the point over a face’s symbol, type
C-h o to have the thing at point as the default option. Select that
(such as with M-n) to get a description of what it is supposed to do.
If we do this over the cursor face, we get the following:
Basic face for the cursor color under X. Currently, only the ‘:background’ attribute is meaningful; all other attributes are ignored. The cursor foreground color is taken from the background color of the underlying text.
Note: Other faces cannot inherit from the cursor face.
As with all *Help* buffers, the ones for individual faces contain a
link to the library that defines them. We are informed, for instance,
that the cursor is defined in faces.el. So we can always visit the
source code from there whenever we need to understand more about the
item of our inquiry.
Note that list-faces-display will only cover the libraries that are
currently loaded, but not necessarily the faces that your active theme
defines. If you have installed some package that you have not used yet,
then any faces it may be defining will not be immediately available in
the *Faces* buffer. To actually include those in the list, you need
to either use their package or explicitly load the relevant file with
M-x load-library. You can always regenerate the *Faces* buffer by
typing g while inside of it.
Configuring an individual face
Before we proceed to write a fully fledged theme, let us first examine
how to control faces one by one. The function dedicated to that task is
set-face-attribute. Read its documentation string with C-h f
followed by its symbol. This is important because it provides
valuable information about the properties that a face may be associated
with. You will need it when configuring your own theme.
Assuming you read the documentation of set-face-attribute, let us
consider this example:
(set-face-attribute 'cursor nil :background "red")
We have learnt that the cursor only recognises a :background
property and will ignore any other. What we do here is instruct it to
use the generic red colour.
To confirm that this works, place the point to the right of the closing
parenthesis and type C-x C-e (which calls eval-last-sexp). Your
cursor show now be coloured red. If you were to put this in your
initialisation file, or any other library that gets loaded when you open
Emacs, your cursor would always get the colour you specified (unless
something else overrides it later on, but you get the point).
A good use-case for this is to define your font families for the three
main constructs of default, variable-pitch, and fixed-pitch.
This is the gist of what is included in the manual of the Modus themes on the topic of font configurations for Org (and others)
;; my custom build of Iosevka
;; https://gitlab.com/protesilaos/iosevka-comfy
(set-face-attribute 'default nil :font "Iosevka Comfy-15")
(set-face-attribute 'variable-pitch nil :family "Source Sans Pro" :height 1.0)
(set-face-attribute 'fixed-pitch nil :family "Iosevka Comfy" :height 1.0)
Depending on what you want to do, you can use Elisp to further control
things. Here we can be a bit more succinct by using dolist (remember
that C-h f, C-h v, or just C-h o are among your most valuable
tools in your Emacs journey).
(dolist (face '(default fixed-pitch))
(set-face-attribute face nil :family "Iosevka Comfy"))
Using colours
We can find the names of all generic colours with list-colors-display.
Notice how earlier we specified the :background of the cursor face
to a "red" value. Alternatively, one could use a hexadecimal RGB
code, such as "#ff0000" for pure red. I prefer the latter because it
is more precise and flexible.
How you specify colours is ultimately up to you. Picking the right values is not an easy task. It is a field of endeavour that stands at the intersection or art and science, as I explained in my essay about the design of the Modus themes.
Deconstructing an Emacs face
While set-face-attribute is perfectly fine for a few items, it becomes
inefficient at scale. This is why Emacs provides the
custom-theme-set-faces function. Before we start using that, we must
first understand what the specifications of a face are.
Consider this excerpt from M-x find-library RET faces (here “RET”
means to type the command, then confirm your choice with the
Return/Enter key, and follow it up with the “faces” library).
(defface tab-bar
'((((class color) (min-colors 88))
:inherit variable-pitch
:background "grey85"
:foreground "black")
(((class mono))
:background "grey")
(t
:inverse-video t))
"Tab bar face."
:version "27.1"
:group 'basic-faces)
We can read all about these specs with C-h o defface. Again, read the
docs to save yourself from trouble and frustration. While you start
making a habit of that, let me simplify this defface for you (extra
space for didactic purposes):
(defface tab-bar
'(
(
((class color) (min-colors 88))
:inherit variable-pitch
:background "grey85"
:foreground "black")
(
((class mono))
:background "grey")
(t
:inverse-video t)
)
"Tab bar face.")
Here we have the general structure of an expression that evaluates
multiple conditions. It looks like cond:
(cond
((FIRST TEST)
FIRST RESULT)
((SECOND TEST)
SECOND RESULT)
(t ; if none of the above
FALLBACK RESULT))
With these in mind, we can read each test more easily. Focus on this:
(
((class color) (min-colors 88))
:inherit variable-pitch
:background "grey85"
:foreground "black")
It checks whether the display terminal can support a minimum of 88
colours. If you are using Emacs with a graphical toolkit, this is most
likely the case. If the condition is satisfied, this face will use
grey85 for its background and black for its foreground. Whereas in
more limited display terminals, it uses something simpler:
(
((class mono))
:background "grey")
Same principle for the fallback condition, which merely inverts the colours with the assumption that those are some variant of black and white for the foreground/background:
(t
:inverse-video t)
While you could define all your faces to adapt to every possible display
terminal out there, I find that what one typically needs is to optimise
for ((class color) (min-colors 89)).
With these in mind, we can start writing our first theme.
Skeleton of a custom theme
As noted in the previous section, Emacs offers custom-theme-set-faces
for the express purpose of streamlining the process of controlling faces
in bulk. As always, read the documentation of that function to learn
more about the finer points.
Here we will be working with a minimal, yet perfectly usable base.
Every theme must be placed in a file whose name follows the pattern of
SYMBOL-theme.el. We declare the symbol of our theme with the
following:
(deftheme prot-base
"The basis for a custom theme.")
The above means that the file name must be prot-base-theme.el (we have
some more code at the end of the file, but we take things one step at a
time).
Now we want to configure a set of faces that are optimised for the
display spec of ((class color) (min-colors 89)). Instead of writing
this expression each time, we will dynamically bind it to a variable,
using let.
(let ((class '((class color) (min-colors 89)))
...other variables)
...body)
Since we are defining local variables, it is a good idea to also write
our colours here, so that we economise on typing, but also to avoid
discrepencies. Each colour is defined as (name value).
(let ((class '((class color) (min-colors 89)))
(main-bg "#ffffff") (main-fg "#000000")
(red "#a00000") (green "#005000") (blue "#000077"))
...body)
Everything is in place to start defining face attributes. The body of
our dynamically bound variables contains custom-theme-set-faces,
followed by the name of the deftheme we declared and then each face’s
symbol, display spec and attributes:
(deftheme prot-base
"The basis for a custom theme.")
(let ((class '((class color) (min-colors 89)))
(main-bg "#ffffff") (main-fg "#000000")
(red "#a00000") (green "#005000") (blue "#000077"))
(custom-theme-set-faces
'prot-base
`(default ((,class :background ,main-bg :foreground ,main-fg)))
`(cursor ((,class :background ,red)))
`(font-lock-builtin-face ((,class :foreground ,blue)))
`(font-lock-string-face ((,class :foreground ,green)))))
(provide-theme 'prot-base)
(provide 'prot-base-theme)
This is a valid theme. To actually use it, you must write it to a file,
which in this case is prot-base-theme.el. This file must be in a
directory read by Emacs. Say you put it in ~/.emacs.d/themes/. To
inform Emacs about it, evaluate this:
(add-to-list 'custom-theme-load-path "~/.emacs.d/themes/")
With the theme written at ~/.emacs.d/themes/prot-base-theme.el, you
can now M-x load-theme RET prot-base. And there you have it!
Note though that you may also need to M-x disable-theme and specify
the one currently in use to make sure you do not get mixed results
(unless you want to overlay one theme on top of another, but I will let
you run such experiments).
Remember to rely on list-faces-display to find all the symbols you
wish to cover. Furthermore, you can always identify the properties of
the character at point with M-x describe-char (or type it directly
with C-u C-x =). If it uses a face, you will see it mentioned in the
resulting *Help* buffer.
To understand the syntax for backquotes and commas, type M-: and then
insert (info "(elisp) Backquote"). This will take you to the relevant
node in the Emacs Lisp Reference Manual.
More tools for theme developers
These are excerpts from my dotemacs. They are meant to further assist you in the task of developing a custom theme. Check the doc string of each variable and adapt things to your liking.
Rainbow mode for colour previews
While experience may help estimate with decent accuracy a hexadecimal
RGB colour, it is always better to have a live preview available. Once
the following package is loaded, you can get it with M-x rainbow-mode.
(use-package rainbow-mode
:ensure
:diminish
:commands rainbow-mode
:config
(setq rainbow-ansi-colors nil)
(setq rainbow-x-colors nil))
Use a linter front-end to improve your code
You can either rely on the built-in flymake or the third party
flycheck. Both work great with Elisp files. You activate them with
flymake-mode or flycheck-mode respectively.
(use-package flymake
:commands flymake-mode
:config
(setq flymake-fringe-indicator-position 'left-fringe)
(setq flymake-suppress-zero-counters t)
(setq flymake-start-on-flymake-mode t)
(setq flymake-no-changes-timeout nil)
(setq flymake-start-on-save-buffer t)
(setq flymake-proc-compilation-prevents-syntax-check t)
(setq flymake-wrap-around nil))
(use-package flycheck
:ensure
:commands flycheck-mode
:config
(setq flycheck-check-syntax-automatically
'(save mode-enabled))
:hook (flycheck-error-list-mode-hook . visual-line-mode))
If you go with Flycheck, you may also want a modeline indicator, unless you use a custom modeline that already defines one:
(use-package flycheck-indicator
:ensure
:after flycheck
:config
(setq flycheck-indicator-icon-error (string-to-char "!"))
(setq flycheck-indicator-icon-info (string-to-char "·"))
(setq flycheck-indicator-icon-warning (string-to-char "*"))
(setq flycheck-indicator-status-icons
'((not-checked "%")
(no-checker "-")
(running "&")
(errored "!")
(finished "=")
(interrupted "#")
(suspicious "?")))
:hook (flycheck-mode-hook . flycheck-indicator-mode))
And here is how to ensure that you are following best practices for packaging Elisp libraries (you only need one of the two, depending on the front-end you choose):
(use-package flycheck-package
:ensure
:after flycheck
:config
(flycheck-package-setup))
(use-package package-lint-flymake
:ensure
:after flymake
:config
(package-lint-flymake-setup))
Remember that Emacs themes are Elisp programs
It should be clear by now that a theme can rely on advanced programming
techniques to do its work. Here we used let. While you can always go
with something simple, you retain the option to define more elaborate
criteria that, say, come into effect once a certain variable is enabled.
My Modus themes, which were recently added to upstream Emacs, contain lots of Elisp logic, making them highly customisable. Study their source code if you want. It can help you learn more about defining and then evaluating customisation options.
Use the information in this document to write your own theme or to just gain insight into how the theme of your choice is designed.
Good luck!