Paneflow ships two bundled themes today: a dark default (`One Dark`)
and a light alternative (`PaneFlow Light`). Themes drive every
terminal-surface colour - ANSI palette, cursor, selection, scrollback
highlights, search matches. The sidebar and title bar stay on
Paneflow's app chrome palette and are not theme-controlled.

  **TL;DR.** Set `"theme": "PaneFlow Light"` in `paneflow.json` to
  switch to the light theme. Save the file; the running window picks
  up the new colours within \~300 ms with no restart.

## How do I switch the active theme? [#how-do-i-switch-the-active-theme]

Set the `theme` key in `paneflow.json`:

```json
{
  "theme": "PaneFlow Light"
}
```

The value must match one of the bundled theme names exactly,
including capitalisation. Unknown names fall back to `One Dark` and
emit a log warning the next time the file is parsed.

The config file lives at:

| OS    | Path                                                   |
| ----- | ------------------------------------------------------ |
| Linux | `~/.config/paneflow/paneflow.json`                     |
| macOS | `~/Library/Application Support/paneflow/paneflow.json` |

## Which themes ship with Paneflow today? [#which-themes-ship-with-paneflow-today]

| Name               | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| `"One Dark"`       | Dark theme, default. Inspired by Atom's One Dark palette.             |
| `"PaneFlow Light"` | Light theme. Higher-contrast palette tuned for daylight workstations. |

Both themes ship with all 16 ANSI colour slots, foreground / background,
cursor, selection, and search-highlight colours pre-tuned to meet WCAG
AA contrast on standard prompts.

  Earlier project plans referenced six bundled themes. Reality at
  v0.2.x is two. Additional bundled themes (Solarized, Gruvbox, and a
  high-contrast variant) are on the roadmap; track [GitHub releases](https://github.com/ArthurDEV44/paneflow/releases)
  for the announcement.

## How does theme hot-reload work? [#how-does-theme-hot-reload-work]

When you save `paneflow.json`, Paneflow re-resolves the theme on the
fly - no restart, no window reload.

Two mechanisms drive the reload:

* **Event-driven (preferred).** A `notify` watcher installed on the
  config directory fires within milliseconds of a save. Events are
  debounced by 300 ms so editor save bursts (write -> fsync ->
  atomic-rename) only trigger one reload.
* **Polling fallback.** Filesystems that do not support inotify /
  FSEvents / ReadDirectoryChangesW (NFS shares, locked-down sandboxes,
  some WSL paths) fall back to a 500 ms `mtime` poll. The fallback
  only runs when the event watcher fails to start.

You will see the new palette take effect on the next render frame
after the watcher fires - typically within \~300 ms of the save.

  Hot-reload covers every theme-related field on `paneflow.json`,
  including the typography keys (`font_family`, `font_size`,
  `line_height`). The `window_decorations` key is the one config field
  that is read once at startup - changing it requires restarting
  Paneflow.

## How do I create a custom theme? [#how-do-i-create-a-custom-theme]

Custom user-supplied themes are on the roadmap for a post-v0.3.0
release. v0.2.x recognises only the bundled theme names listed
above; there is no `theme.json` or custom palette format yet.

If you want a specific palette in the meantime, the most direct path
is to open a [GitHub issue](https://github.com/ArthurDEV44/paneflow/issues)
with the palette you want. Bundled themes are tuned in
`src-app/src/theme/builtin.rs` and ship with each release - new
palettes get fast-tracked when they have a clear use case.

The schema-level placeholder for a future custom-theme key is
deliberately not yet defined, so adding one to `paneflow.json` today
has no effect - it is silently ignored by the lenient runtime per
the [configuration overview](/docs/configuration#how-does-paneflow-handle-unknown-keys).