# Themes

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`:

```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:

```bash
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:

**.loam/themes/Ink.json**

```json
{
  "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`.