git:20260710.b92d46b to git:20260711.8eb8e35

17 added, 1 removed. Audit A to A.

---

name: vellum-workspace-theme

description: Customize the app's visual theme — author design-token overrides (accent, background, surfaces, text, message-bubble colors) in the workspace ui/theme.json, validated by the assistant runtime and applied live to connected clients. Covers the token slots, the all-or-none override groups, the contrast floor, and reading back validation issues.

compatibility: "Designed for Vellum personal assistants"

metadata:

emoji: "🖌️"

vellum:

category: "content"

display-name: "Workspace Theme"

---

You are customizing the visual theme of the app you and your user share. The theme lives in one file — `$VELLUM_WORKSPACE_DIR/ui/theme.json` — which the assistant runtime validates and serves to every connected client. Valid changes apply **live**, layered on top of the built-in light/dark/velvet base theme: open windows re-color within a few seconds of the file being saved. No restart, no build step.

**All commands in this skill use the `bash` tool.** `$VELLUM_WORKSPACE_DIR` is available in the sandbox environment.

## Inspect current state

Always check what's there before changing it:

```bash

cat "$VELLUM_WORKSPACE_DIR/ui/theme.json" 2>/dev/null || echo "No theme yet — clients render the built-in theme"

```

## The file

A complete example (all eleven token slots — you rarely need all of them):

```json

{

"version": 1,

"tokens": {

"accent": "#e8a04c",

"background": "#1c1512",

"surface": "#2b2018",

"surfaceRaised": "#332619",

"border": "#43301f",

"text": "#f2e4d4",

"textMuted": "#a68d75",

"userBubbleBackground": "#26201a",

"userBubbleText": "#efe3d2",

"assistantBubbleBackground": "#33202a",

"assistantBubbleText": "#ffd7e4"

}

```

| Token | What it controls |

| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| `accent` | Primary buttons, highlights, active states. The button-label color is derived automatically so it stays readable on any accent. |

| `background` | The page background and base surfaces. |

| `surface` | Panels, popovers, and overlays. |

| `surfaceRaised` | Elevated cards. |

| `border` | Borders and dividers. |

| `text` | Main copy. |

| `textMuted` | Secondary labels and captions. |

| `userBubbleBackground` / `userBubbleText` | The user's chat message bubble. |

| `assistantBubbleBackground` / `assistantBubbleText` | Accepted and validated, but not yet rendered — assistant messages don't have a themeable container yet. Safe to set now; they light up when the surface ships. |

`"base": "light" | "dark" | "velvet" | "system"` is also accepted at the top level but reserved — clients don't switch the base theme from it yet. The tokens are a color layer over whichever base the user has chosen.

## The rules (why an edit gets rejected)

The runtime validates the whole file and rejects it atomically — one bad value turns theming **off** (clients revert to the built-in theme) until the file is fixed. The rules:

1. **Hex colors only** — 3- or 6-digit (`#f0a`, `#e8a04c`). No alpha channel, no named colors, no CSS functions, no `url()`.

2. **Only the keys above** — unknown top-level keys or token slots reject the file. There is no way to inject arbitrary CSS; that is deliberate.

3. **Override groups are all-or-none.** Tokens that render against each other must be set together, because your overrides layer over a base palette the runtime doesn't resolve:

- Core group: `background`, `surface`, `surfaceRaised`, `text`, `textMuted` — set any one, set all five.

- Each bubble pair: background and text together.

- `accent` and `border` are free agents — fine alone.

4. **Contrast floor** — text/surface pairs must clear **3:1** (WCAG relative luminance): `text` against `background`/`surface`/`surfaceRaised`, `textMuted` against all three, and each bubble's text against its background. The floor blocks illegible themes, not bold ones.

5. **A real file, at most 64KB** — symlinks and oversized files are rejected.

Practical consequence of rule 3: an "accent-only" theme is two lines, but the moment you touch `background` you are authoring a full palette. Design the five core colors together.

## Verify after every edit

The runtime tells you exactly what it accepted or why it refused. Fetch `GET /v1/workspace/theme` from the assistant runtime HTTP API (the same authenticated API used for other configuration reads):

```json

{

"theme": { "version": 1, "tokens": { "accent": "#e8a04c" } },

"source": "workspace",

"issues": []

}

```

- `source: "workspace"` — your theme is live.

- `source: "invalid"` — rejected; `issues` lists human-readable reasons (e.g. `"incomplete override group: setting tokens.background also requires tokens.text, …"` or `"tokens.text on tokens.background has contrast 1.02:1 — minimum is 3:1"`). Fix and re-check.

- `source: "none"` — no theme file exists.

- To see the result visually, take a browser screenshot of the app, or ask the user — the change is already on their screen.

+ ## Seeing your work

+ You do not need the user to screenshot the app for you. The desktop app can render a **staged view** of its own UI — fixed generic content, never real conversation data — with your current theme applied, capture it offscreen, and hand you the PNG:

+ ```bash

+ assistant ui snapshot --view sampler --out /tmp/theme-sampler.png

+ assistant ui snapshot --view chat --out /tmp/theme-chat.png

+ ```

+ Then view the image file. Two views:

+ - **`sampler`** — a dense style sheet: the text ramp, accent, buttons, a raised card, inputs, borders, and both chat bubbles in one frame. Use it while iterating — it answers "does the palette read".

+ - **`chat`** — a staged conversation with a composer. Use it to judge the finished feel — it answers "does it look like home".

+ The capture reflects `ui/theme.json` as it is on disk at that moment, so edit → snapshot → look → adjust is a tight private loop. If the theme file is invalid, the command prints the validation issues and the capture shows the built-in theme. The framing is fixed, so before/after snapshots align exactly.

+ This requires the desktop app to be running; if the command times out or reports no connected client, fall back to taking a browser screenshot of the app or asking the user — the change is already on their screen.

## Removing the theme

Delete the file (or write `{"version":1}` with no tokens) and clients revert to the built-in theme:

```bash

rm "$VELLUM_WORKSPACE_DIR/ui/theme.json"

```

## Etiquette

The theme applies to every open window your user has, within seconds, with a small "Theme updated" notice. For a small tweak that was just discussed, go ahead. For a dramatic repaint — or one the user didn't ask for — tell them what you're about to do, or stage the palette in conversation first. It's a shared space; redecorate like someone who lives there too.