# `.fvtheme` — Foldervas Theme Format — v1

Shareable color themes as a single JSON file — write one by hand, import it
from Settings → Application, export yours to share.

- **Version:** 1 · **Status:** stable · **License:** CC BY 4.0
- HTML version: <https://foldervas.com/spec/theme/>
- Related: [`.foldervas` file format](https://foldervas.com/spec/foldervas.md) ·
  [`.fvlang` language packs](https://foldervas.com/spec/language/fvlang.md)

## 1. Shape

```json
{
  "format": "fvtheme",
  "version": 1,
  "name": "Nord",
  "base": "dark",
  "css": {
    "canvas-bg": "#2e3440",
    "grid-dot": "#3b4252",
    "surface": "#3b4252",
    "text": "#eceff4",
    "accent": "#88c0d0"
  },
  "canvas": {
    "canvasBg": "#2e3440",
    "canvasText": "#eceff4"
  }
}
```

- `name` — shown in the theme picker. Importing a theme with the same name
  replaces it.
- `base` — `"light"` or `"dark"`: everything you don't define inherits from
  that built-in theme (and sets scrollbars/native controls).
- `css` — UI colors: any subset of the variables in §2, *without* the `--`
  prefix. Unknown keys are ignored.
- `canvas` — optional overrides for the canvas renderer tokens (§3). If
  omitted, the common ones are derived from `css` automatically
  (`canvas-bg → canvasBg`, `text → canvasText`, etc.).
- Values are CSS colors (hex recommended; `rgba()` accepted where the
  built-ins use it, e.g. scrims and shadows).

## 2. CSS variables

Grouped by role; all optional:

| Group | Variables |
|---|---|
| Canvas | `canvas-bg`, `grid-dot` |
| Surfaces | `surface`, `surface-hover`, `surface-2`, `surface-sunken`, `surface-sunken-2` |
| Text | `text`, `text-strong`, `text-muted`, `text-faint`, `text-dim` |
| Borders | `border`, `border-strong`, `border-input` |
| Accent | `accent`, `accent-hover`, `accent-bg`, `accent-bg-hover`, `accent-tint`, `focus-ring`, `on-accent` |
| Semantic | `danger`, `danger-strong`, `danger-text`, `danger-hover`, `danger-bg`, `danger-bg-2`, `success-text`, `success-bg`, `warning`, `warning-text` |
| Content | `note-bg`, `folder`, `folder-inner`, `container-bg`, `drop`, `drop-bg` |
| Chrome | `scrim`, `tooltip-bg`, `tooltip-text`, `shadow-sm`, `shadow-md`, `shadow-lg`, `minimap-bg`, `fab-bg`, `keycap-bg`, `keycap-border` |

## 3. Canvas tokens

The infinite canvas is drawn outside the DOM, so it has its own token set:
`accent`, `selectionFill`, `controlBg`, `canvasBg`, `gridDot`, `cardBg`,
`containerBg`, `noteDefaultBg`, `imgPlaceholderBg`, `previewPlaceholderBg`,
`folderInner`, `canvasText`, `canvasTextMuted`, `minimapCard`,
`minimapLayout`, `minimapImage`.

> Design note: Foldervas keeps *content* (notes, cards) light in every
> built-in theme — dark themes restyle the desk, not the paper. Your theme is
> free to break that rule, but text on cards auto-contrasts against the card
> color, not the theme.

## 4. Importing and exporting

- **Import:** Settings → Application → theme picker → "Import theme…". The
  file is validated; unknown keys are dropped; the theme appears in the picker
  under "Custom".
- **Export:** "Export current theme…" writes a complete `.fvtheme` of whatever
  you're looking at — the easiest way to start is exporting a built-in and
  editing the JSON.
- Themes can also be assigned **per folder** and **per document** inside the
  app (see the `.foldervas` spec, §7–8).

---

Published under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).