Skip to main content
Themes control the entire look of Synti — surfaces, text, and the accent colors that flow through your labels, statuses, and icons. Rather than styling each screen, Synti defines a small set of semantic color tokens and resolves everything from them. Change a token and the whole app follows, in both light and dark mode.

​
Semantic tokens

Six tokens describe the meaning of a color, not its exact shade. That indirection is what lets a theme swap cleanly and what keeps system colors consistent across the app. When a label or status references accent or success, it’s pointing at these tokens — so re-theming recolors every entity that uses them at once.

​
Light and dark mode

A theme defines its base colors for light mode, then overrides only what needs to change in dark mode through a dark object. You never have to restate values that stay the same.
When your system is in dark mode, any color under dark replaces its base counterpart; everything else carries over. Synti follows your OS light/dark preference by default.

​
Color formats

Token values accept hex (#8b5cf6, or with alpha #8b5cf6cc), rgb() / rgba(), hsl(), oklch(), and CSS named colors.
oklch() holds up better than hex or RGB across light and dark backgrounds because lightness is an independent channel. The format is oklch(lightness chroma hue) — lightness 0–1, chroma 0–0.4, hue 0–360.

​
How themes are layered

Synti resolves a theme by precedence, from highest to lowest:
  1. Workspace theme — a theme set on a specific workspace.
  2. App default — your chosen default for the app.
  3. Override file — partial customizations in ~/.synti/theme.json.
  4. Preset theme — the bundled or installed base theme.
A workspace with no theme of its own inherits the app default. This is what lets each workspace look distinct while sharing sensible fallbacks.

​
Storage locations

Edits to theme.json apply live — Synti picks them up without a restart, which makes it easy to dial in a color.

​
Workspace themes

Open Settings → Appearance → Workspace Themes to give a workspace its own look, or leave it on the app default. This is handy for telling a “work” workspace apart from a “personal” one at a glance.

​
Override file

~/.synti/theme.json is a partial theme: every field is optional, and only the tokens you list override the active preset. It’s the least invasive way to nudge a single color — for example, changing just accent — without maintaining a full theme.

​
Preset themes

A preset is a complete theme package. Alongside its colors it carries metadata: name, description, author, license, source, supportedModes (which light/dark variants it provides), and shikiTheme for code-block syntax highlighting. Install one under ~/.synti/themes/ and select it as your app default or per workspace.

​
Scenic mode

Scenic mode turns the window into an immersive full-bleed background with translucent glass panels floating over it. Set "mode": "scenic" and give a backgroundImage (a local filename or a URL).
Scenic themes add extra surface tokens for the glass layers — paper, navigator, input, popover, and popoverSolid — so panels stay readable over the image. Synti runs scenic mode in dark mode to keep contrast against the backdrop.
Because scenic mode enforces dark surfaces, choose a backgroundImage with enough contrast that light text on glass panels stays legible.

Colors

Assign system tokens or custom colors to individual entities.

Icons

Theme-aware SVGs recolor to match your active tokens.