Themes

Trove ships with seven built-in colour schemes (Warm, Neutral, Sepia, Dark, High contrast, Tokyo Night, Tokyo Oxblood). You can edit any of them, or write your own from scratch. Themes are plain text — a single .toml file per theme, sitting inside your Trove library.

Where themes live

Inside your Trove root, next to manuscripts/ and codexes/:

<your trove root>/
├── manuscripts/
├── codexes/
└── themes/
    ├── warm.toml
    ├── neutral.toml
    ├── sepia.toml
    ├── dark.toml
    ├── high-contrast.toml
    ├── tokyo-night.toml
    └── tokyo-oxblood.toml

The seven built-ins are copied here on first launch so you have something to crib from. They never get overwritten — if Trove later ships a refreshed version of dark.toml, you’ll find it as dark.updated.toml alongside yours, and a one-off notice will point you at it.

Switching themes

Settings → Display → Colour scheme. Every .toml file in themes/ shows up there, including ones you’ve written by hand. Pick one and Trove applies it immediately.

You can also edit the active theme while the app is open — save the file, and Trove reflects the change within half a second. No restart, no reload.

Writing your own

Create themes/midnight.toml:

[meta]
name = "Midnight"
author = "you"
scheme = "dark"          # light | dark — drives macOS / iOS color-scheme hint
extends = "dark"         # inherit everything else from the Dark built-in

[tokens]
"--hue-accent" = "280"
"--chroma-accent" = "0.16"
"--color-canvas" = "oklch(12% 0.01 260)"
"--color-panel" = "oklch(14% 0.01 260)"
"--color-surface" = "oklch(16% 0.01 260)"
"--color-foreground" = "oklch(94% 0.005 90)"
"--color-accent" = "oklch(56% var(--chroma-accent) var(--hue-accent))"
"--color-accent-tint" = "color-mix(in oklch, var(--color-accent) 12%, var(--color-canvas))"

Two sections. [meta] describes the theme; [tokens] overrides primitive hue/chroma knobs, colours, shadows, radii, spacing, or layout tokens. The extends key lets you change five values without copying all 100+ tokens from the built-in.

Drop the file into themes/, open the picker, pick Midnight. That’s it.

What you can put in a value

Trove validates every value before applying it. Allowed forms:

• OKLCH — oklch(50% 0.12 280) (lightness % · chroma · hue°). Recommended.
• Hex — #1a1b26, #1a1b26ff.
• rgb / rgba — rgba(60, 30, 24, 0.06).
• color-mix — color-mix(in oklch, var(--color-accent) 12%, var(--color-canvas)). References to other Trove tokens are allowed; references to anything else are rejected.
• Numbers — 280, 0.16, or 58% for primitive tokens such as --hue-accent, --chroma-accent, and --entity-lightness.
• Shadows — 0 6px 18px rgba(0, 0, 0, 0.4). Multiple layers separated by commas.

Rejected outright (these don’t belong in a colour value and Trove won’t load them):

• url(...), data: URIs
• javascript: or any other protocol
• expression(...), @import, any at-rule
• HTML / script tags
• References to var(--something) where --something isn’t a Trove token

If anything in your theme is invalid, Trove drops the offending value, keeps everything else, and falls back to Warm if the whole file fails. You’ll see a warning in Settings → Display.

Token reference

Trove exposes 100+ tokens. The full list lives in packages/ts/design-tokens/registry.generated.ts in the source — the most common ones:

Token	What it colours
--hue-accent, --chroma-accent	Primitive knobs for the accent role
--color-canvas	Main background — the page behind everything
--color-panel	Secondary background — panes, drawer interiors
--color-surface	Cards, popovers, modal interiors
--color-navigation	Left navigation rail
--color-foreground	Primary body text
--color-foreground-muted	Secondary text
--color-foreground-subtle	Tertiary / hint text
--color-border-subtle	Quiet separators
--color-border	Active separators (table cells, form fields)
--color-accent	Primary action, focus, and link accent
--color-accent-tint	Hover backgrounds, soft highlights
--color-focus	Keyboard focus ring
--color-danger, --color-warning, --color-success	Status colours (drafting / outlining / complete)

Group prefixes:

• --color-* — colours (always start with --color-).
• --hue-*, --chroma-*, --entity-* — primitive numeric controls.
• --shadow-* — drop shadows.
• --radius-* — corner radii.
• --space-* — spacing scale.
• --width-* — layout widths.

Anything else (fonts, type scale, motion) is reserved for the app and can’t be overridden in v1.

Across devices

If you sync a Trove library across machines (iCloud, Dropbox, or future Trove-native sync), themes travel with it. Edit dark.toml on your laptop, and your phone picks up the change next time it sees the library. Conflict rule when two devices edit the same theme at once: last write wins.

Opting out

Don’t want themed Trove? Stick to one of the built-ins and don’t touch themes/. The picker stays where it is, and nothing in your library changes.

You can also delete a custom theme by removing its .toml file. Built-ins regenerate on next launch if you delete one by mistake.

Tips

• Start by editing a built-in. Copy dark.toml to midnight.toml, tweak a few tokens, rename, you’re done.
• Use extends for variants. A “tokyo-night-quiet” that only changes the accent hue is six lines, not sixty.
• Stick to OKLCH for colour. It’s perceptually uniform, so adjusting lightness without distorting hue is straightforward.
• Test focus contrast. --color-focus needs to clear 3:1 against --color-canvas and --color-surface so the keyboard ring stays visible.