Making a theme

A theme changes Finch’s colours, the roundness of its cards, the width of its focus ring, and a few pictures. Themes are data only: a folder with a theme.json file and some PNG or JPEG pictures. A theme can’t run code, change the layout or bring fonts.

Where themes go

Finch looks in two places when it starts, so restart it after adding a theme.

• Your own themes: the themes folder in Finch’s data folder (~/.local/share/finch/themes, or ~/.var/app/dev.quietfield.Finch/data/finch/themes in the Flatpak). Put each theme in a folder of its own, such as themes/my-theme/theme.json.
• Themes installed with Finch: the themes folder next to the finch program (/app/share/finch/themes in the Flatpak).

If a folder with the same name is in both places, yours is used. Pick a theme in Settings, then Appearance, then Theme; each one shows its name and author.

The theme.json file

Here is a small one to start from; copy it into a folder of your own, such as themes/my-theme/theme.json, and change the colours:

{
  "schema": 1,
  "name": "My theme",
  "author": "Me",
  "version": "1.0",
  "colors": {
    "bg": "#0e1712", "surface": "#142019", "panel": "#1c2b22",
    "text": "#eef5ef", "muted": "#9db3a3", "focus": "#ffffff",
    "scrim": "#0e1712cc", "hero_scrim_strong": "#0e1712ee", "hero_scrim_weak": "#0e171288",
    "pill_bg": "#000000cc", "cap": "#2a3a30"
  },
  "accent": "#7cc48a",
  "shape": { "card_radius": 2.0, "focus_ring": 0.4 }
}

These are the fields:

• schema: always 1, the format this Finch reads.
• name, author and version: words shown in Settings (only the name is required).
• colors: any of bg, surface, panel, text, muted, focus, scrim, hero_scrim_strong, hero_scrim_weak, pill_bg and cap. bg, surface, panel, text, muted and focus are solid colours written #rrggbb; scrim, hero_scrim_strong, hero_scrim_weak, pill_bg and cap may be #rrggbb or #rrggbbaa (see-through). Colours you leave out are the Night theme’s.
• accent: an optional #rrggbb colour, chosen as “Theme’s colour” under Accent colour until you pick another.
• shape: optional card_radius (from 0 to 4) and focus_ring (from 0.15 to 1), in Finch’s own units; Finch’s built-in themes use 1.6 and 0.35 (the Finch theme, 1.8 and 0.35).
• images: an optional logo, a hero picture shown behind the Home banner when a title has no backdrop, and profile_icons, a list of pictures a profile can use, each written {"id": "fern", "file": "icons/fern.png", "label": "Fern"}.

Picture names are files inside the theme’s folder, and each must be under 8 MB. The theme.json file must be under 64 KB. The file and its pictures must be plain files, not links to files somewhere else.

If a theme can’t be read

It is still listed in Settings, marked “(can’t be read)”, and Finch keeps drawing the Finch theme instead. The reason (a typo in the file, a missing picture) is in Finch’s log. If your text is hard to read on your background (under 4.5 to 1), or the grey text or the focus ring is (under 3 to 1), Finch says so in the log and uses the theme anyway. The player’s controls over a video keep their dark colours whatever the theme says.

To get back to Finch’s own theme without the menus, start Finch once with --setting theme=finch (in Steam, put it in the launch options for one launch, then take it out), or move the theme’s folder out of the themes folder.