How to create your own template themes

This guide gives an introduction as to how you could go about creating your own themes using the existing template mechanism.

The guide assumes that you have gone through and have understood the How to theme dusk using templates guide.

First here are all the pre-processor macros that can be defined.

Foreground	Background	Border
NORM_FG_COLOR	NORM_BG_COLOR	NORM_BORDER_COLOR
TITLE_NORM_FG_COLOR	TITLE_NORM_BG_COLOR	TITLE_NORM_BORDER_COLOR
TITLE_SEL_FG_COLOR	TITLE_SEL_BG_COLOR	TITLE_SEL_BORDER_COLOR
SCRATCH_NORM_FG_COLOR	SCRATCH_NORM_BG_COLOR	SCRATCH_NORM_BORDER_COLOR
SCRATCH_SEL_FG_COLOR	SCRATCH_SEL_BG_COLOR	SCRATCH_SEL_BORDER_COLOR
HID_NORM_FG_COLOR	HID_NORM_BG_COLOR
HID_SEL_FG_COLOR	HID_SEL_BG_COLOR
URGENT_FG_COLOR	URGENT_BG_COLOR	URGENT_BORDER_COLOR
MARKED_FG_COLOR	MARKED_BG_COLOR	MARKED_BORDER_COLOR
WS_NORM_FG_COLOR	WS_NORM_BG_COLOR
WS_VIS_FG_COLOR	WS_VIS_BG_COLOR
WS_SEL_FG_COLOR	WS_SEL_BG_COLOR
WS_OCC_FG_COLOR	WS_OCC_BG_COLOR

These should map to the individual colours in the dusk configuration.

static char *colors[SchemeLast][4] = {
	/*                       fg         bg         border    */
	[SchemeNorm]         = { "#D9CFC5", "#492B2D", "#492B2D" },
	[SchemeTitleNorm]    = { "#D9CFC5", "#492B2D", "#643B3E" },
	[SchemeTitleSel]     = { "#D9CFC5", "#82363A", "#82363A" },
	[SchemeScratchNorm]  = { "#D9CFC5", "#492B2D", "#643B3E" },
	[SchemeScratchSel]   = { "#D9CFC5", "#82363A", "#82363A" },
	[SchemeHidNorm]      = { "#D9CFC5", "#492B2D", "#000000" },
	[SchemeHidSel]       = { "#D9CFC5", "#82363A", "#000000" },
	[SchemeUrg]          = { "#E0E0E0", "#A23419", "#A23419" },
	[SchemeMarked]       = { "#DDC470", "#724559", "#724559" },
	[SchemeWsNorm]       = { "#D9CFC5", "#492B2D", "#000000" },
	[SchemeWsVisible]    = { "#D9CFC5", "#82363A", "#000000" },
	[SchemeWsSel]        = { "#D9CFC5", "#82363A", "#000000" },
	[SchemeWsOcc]        = { "#D9CFC5", "#492B2D", "#000000" },
};

There are also these shorthand aliases for some of the macros.

Alias	Macro	Notes
BORDER	NORM_BORDER_COLOR	The bar border colour
TITLENORM	TITLE_NORM_BG_COLOR
TITLESEL	TITLE_SEL_BG_COLOR
SCRATCHNORM	SCRATCH_NORM_BG_COLOR
SCRATCHSEL	SCRATCH_SEL_BG_COLOR
HIDNORM	HID_NORM_BG_COLOR
HIDSEL	HID_SEL_BG_COLOR
WARNING	WARNING_BG_COLOR	Used by dmenu and slock
URGENT	URGENT_BG_COLOR
MARKED	MARKED_BG_COLOR
FLOATNORM	FLOAT_NORM_BG_COLOR
FLOATSEL	FLOAT_SEL_BG_COLOR
WSNORM	WS_NORM_BG_COLOR
WSOCC	WS_OCC_BG_COLOR
WSSEL	WS_SEL_BG_COLOR
WSVIS	WS_VIS_BG_COLOR

Additionally most themes also include COLOR0 through COLOR15 and CURSOR for terminals and other terminal applications that use global colours.

The templates use a cascading effect. This means that if you do not define a colour, then that colour may be derived from another colour.

There are four macros that are required for this cascading effect to work. These are the BASE_FOREGROUND, BASE_BACKGROUND, SELECTED_FOREGROUND and SELECTED_BACKGROUND.

Here is a rundown of which macros are derived from what.

Macro	Cascades to	Notes
BASE_FOREGROUND	NORM_FG_COLOR
-	TITLE_NORM_FG_COLOR
-	SCRATCH_NORM_FG_COLOR
-	HID_NORM_FG_COLOR
-	URGENT_FG_COLOR
-	WARNING_FG_COLOR	Only if WARNING is defined
-	MARKED_FG_COLOR
-	WS_NORM_FG_COLOR
-	WS_OCC_FG_COLOR
-	MARKED_BG_COLOR
SELECTED_FOREGROUND	SEL_FG_COLOR
-	TITLE_SEL_FG_COLOR
-	SCRATCH_SEL_FG_COLOR
-	HID_SEL_FG_COLOR
-	FLOAT_SEL_FG_COLOR	Only if FLOAT_NORM_BG_COLOR is defined
-	WS_VIS_FG_COLOR
-	WS_SEL_FG_COLOR
BASE_BACKGROUND	NORM_BG_COLOR
-	TITLE_NORM_BG_COLOR
-	HID_NORM_BG_COLOR
-	URGENT_BG_COLOR
-	MARKED_BG_COLOR
-	WS_NORM_BG_COLOR
-	BORDER
SELECTED_BACKGROUND	SEL_BG_COLOR
-	TITLE_SEL_BG_COLOR
-	HID_SEL_BG_COLOR
-	WS_SEL_BG_COLOR
NORM_BG_COLOR	NORM_BORDER_COLOR
TITLE_NORM_BG_COLOR	TITLE_NORM_BORDER_COLOR
-	SCRATCH_NORM_BG_COLOR
SCRATCH_NORM_BG_COLOR	SCRATCH_NORM_BORDER_COLOR
URGENT_BG_COLOR	URGENT_BORDER_COLOR
MARKED_BG_COLOR	MARKED_BORDER_COLOR
WS_NORM_BG_COLOR	WS_OCC_BG_COLOR
TITLE_SEL_BG_COLOR	TITLE_SEL_BORDER_COLOR
-	SCRATCH_SEL_BG_COLOR
SCRATCH_SEL_BG_COLOR	SCRATCH_SEL_BORDER_COLOR
WS_SEL_BG_COLOR	WS_VIS_BG_COLOR
FLOAT_NORM_BG_COLOR	FLOAT_NORM_BORDER_COLOR
FLOAT_SEL_BG_COLOR	FLOAT_SEL_BORDER_COLOR

As a practical example let's have a look at the dwm theme and the macros it defines.

#define BASE_FOREGROUND #bbbbbb
#define BASE_BACKGROUND #222222
#define SELECTED_FOREGROUND #eeeeee
#define SELECTED_BACKGROUND #005577
#define TITLE_NORM_BORDER_COLOR #444444
#define MARKED_FG_COLOR #222222
#define MARKED_BG_COLOR #bbbbbb
#define WARNING #99500C
#define URGENT_FG_COLOR #005577
#define URGENT_BG_COLOR #eeeeee

We see that the primary colours are set using the base and selected macros, with a few tweaks to make urgent and marked clients stand out.

So start with the four base macros and build your theme up from there.

---

Tip: using a tool like entr can be handy to see your changes being reflected as soon as you save your theme file.

ls favourite_theme.res | entr xrdb_reload.sh

---

Back to Guides.