Look and feel

Where themes live, how to choose or write one, and what happens when a theme file has an error.

A theme is one JSON file in your vault. It sets colours and fonts, and how headings, task boxes and tags are drawn. It travels with the vault, like your notes. There is no CSS: a theme sets tokens, and every view reads them. Use this page to pick a theme, write your own, or fix one that does not load.

Where themes live

Each theme is a file named <name>.json in .loam/themes/. The theme in use is named in .loam/config.json:

{ "theme": "Paper" }

• No theme key: the built-in Dither Green theme. Loam ships other built-in themes too, listed in Settings > Appearance. A file in .loam/themes/ with the same name wins over a built-in one.
• "system": the macOS look, drawn light unless appearance says otherwise.
• appearance: "light", "dark", or "auto" to follow macOS. Settings > Appearance writes it.
• accent: a colour as #RRGGBB, which replaces the theme’s accent. Settings > Appearance writes it too.
• The sidebar header shows .loam/icon.png (or .jpg, .webp, .heic) when that file exists. Otherwise it shows the Loam icon.

Install or choose a theme

1. Open Settings > Appearance. The theme gallery lists the system look, the files of .loam/themes/, the built-in themes and the community themes. Click one to use it. A community theme you have not installed yet is downloaded first. Reveal Themes Folder opens .loam/themes/.
2. To get Paper.json and Night.json as templates, run Install example themes from the command palette. From a terminal, with the app open on the vault, run:

loam app run themes.install-examples
loam app run themes.use name=Paper

Use name=system for the system look. These two commands run inside the app, so the app must be open on this vault. They are not in loam list: loam app list shows them.

Write a theme

Start from Paper.json, which themes.install-examples writes. Keep only the keys you need. Every key is optional, and what a theme leaves out keeps the system’s look. This theme sets three colours, a dark variant and a font:

{
  "name": "Ink",
  "appearance": "auto",
  "colors": {
    "accent": "#C2410C",
    "text": "#1F2937",
    "background": "#FBF7F0"
  },
  "dark": {
    "colors": { "text": "#EDE6DA", "background": "#1C1A17", "accent": "#F59E0B" }
  },
  "fonts": { "body": "New York", "mono": "SF Mono", "size": 16 }
}

• colors: accent, text, secondaryText, background, separator, codeBackground, link and marker, plus keys for headings, highlights, tags and task boxes.
• dark.colors: the same keys, used when the window is dark. With "appearance": "auto", give a dark block.
• fonts: body, mono, interface and size (9 to 40 points).
• editor: lineHeight and columnWidth.
• headings, tasks and tags: how headings, task boxes and tags are drawn.

Colours are #RRGGBB or #RRGGBBAA. Numbers outside their range are brought back into it. A font that is not installed falls back to the system font.

When a theme does not load

• Invalid JSON, a colour that is not #RRGGBB or #RRGGBBAA, or a value of the wrong kind, such as "size": "big": the app keeps the system look. Settings > Appearance names the wrong key.
• The app keeps running in every case.
• Loam reads themes again whenever something in the vault changes. Fix the file, and the open window applies it within a second.
• Keys the app does not know are ignored, so a file written for a newer version still loads.

Write a theme as an agent

1. Write .loam/themes/<Name>.json with only the keys you need, starting from Paper.json. Keep the text readable: at least 4.5:1 contrast between text and background.
2. Set "theme": "<Name>" in .loam/config.json, and keep its other keys. Or run loam app run themes.use name=<Name> with the app open.
3. Check the result. If nothing changes, read the error in Settings > Appearance, or the answer of themes.use.