> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes

> How Synti's semantic color tokens, light and dark modes, and workspace theme overrides fit together.

Themes control the entire look of Synti — surfaces, text, and the accent colors that flow through your [labels](/labels/overview), [statuses](/statuses/overview), and [icons](/customisation/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](/customisation/colors) consistent across the app.

| Token         | Role                                               |
| ------------- | -------------------------------------------------- |
| `background`  | Page and surface backgrounds                       |
| `foreground`  | Primary text and icons                             |
| `accent`      | Brand color and primary emphasis                   |
| `info`        | Informational and review states (amber by default) |
| `success`     | Connected and success states (green by default)    |
| `destructive` | Errors and destructive actions (red by default)    |

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.

```json theme={null}
{
  "accent": "#8b5cf6",
  "background": "#ffffff",
  "foreground": "#111111",
  "dark": {
    "background": "#0b0b0f",
    "foreground": "#f5f5f5"
  }
}
```

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.

<Tip>
  `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`.
</Tip>

## 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

```text theme={null}
~/.synti/theme.json                              # partial global overrides
~/.synti/themes/{name}.json                      # installed preset themes
~/.synti/workspaces/{workspace-id}/config.json   # per-workspace theme
```

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).

```json theme={null}
{
  "mode": "scenic",
  "backgroundImage": "mountains.jpg"
}
```

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.

<Note>
  Because scenic mode enforces dark surfaces, choose a `backgroundImage` with enough contrast that light text on glass panels stays legible.
</Note>

<CardGroup cols={2}>
  <Card title="Colors" icon="palette" href="/customisation/colors">
    Assign system tokens or custom colors to individual entities.
  </Card>

  <Card title="Icons" icon="image" href="/customisation/icons">
    Theme-aware SVGs recolor to match your active tokens.
  </Card>
</CardGroup>