Theming
The theme file
A theme is one JSON file in the velum-theme/1 format. It names itself, says which theme it extends, and sets the tokens it changes.
Fields
| Field | Required | Meaning |
|---|---|---|
format |
yes | Always "velum-theme/1". |
id |
yes | Lowercase letters, digits and dashes. Must be unique. |
name |
no | Shown in Appearance. |
author |
no | Shown in Appearance. |
appearance |
no | "dark" or "light". It also sets color-scheme for web extensions. |
extends |
no | The id of the theme to inherit from. Chains go up to 8 deep. |
tokens |
yes | The values you set. See every token. |
Values
- Colors:
#RGB,#RRGGBB,#RRGGBBAA,rgb(r, g, b)orrgba(r, g, b, a)withafrom 0 to 1. - Numbers: plain JSON numbers, in pixels unless the token says otherwise.
- References:
"{color.accent}"uses another token's value. - References with transparency:
"{color.accent} @ 22%"(or@ 0.22) is that color at 22% of its opacity.
References are how a theme stays coherent when you change one color. Studio Dark's selection and focus ring follow its accent:
"color.selection": "{color.accent} @ 22%",
"color.focus": "{color.accent} @ 60%",
"color.preview.selection": "{color.accent}"So a theme that sets only color.accent gets a matching selection, focus ring and layer outline for free.
Inheritance
Everything a theme doesn't set comes from the theme it extends, and from that theme's parent, up to eight levels. Studio Light is a complete light theme that sets only what differs from Studio Dark:
{
"format": "velum-theme/1",
"id": "studio-light",
"name": "Studio Light",
"author": "Velum Studio",
"appearance": "light",
"extends": "studio-dark",
"followSystemAccent": true,
"tokens": {
"color.window": "#E8E8EB",
"color.surface": "#F3F3F5",
"color.surface.raised": "#FFFFFF",
"color.surface.sunken": "#E0E0E4",
"color.surface.overlay": "#FFFFFF",
"color.hover": "rgba(0, 0, 0, 0.045)",
"color.pressed": "rgba(0, 0, 0, 0.085)",
"color.border": "rgba(0, 0, 0, 0.09)",
"color.border.strong": "rgba(0, 0, 0, 0.17)",
"color.divider": "rgba(0, 0, 0, 0.07)",
"color.text": "#1D1D1F",
"color.text.secondary": "#5C5C64",
"color.text.tertiary": "#6E6E76",
"color.text.disabled": "#B6B6BC",
"color.selection": "{color.accent} @ 40%",
"color.accent": "#E9C58B",
"color.accent.hover": "#DFB97C",
"color.accent.pressed": "#D3AC6C",
"color.accent.text": "#1D1406",
"color.accent.strong": "#87621B",
"color.live": "#D02C24",
"color.success": "#24883D",
"color.danger": "#D0342B",
"color.danger.text": "#FFFFFF",
"color.focus": "{color.accent.strong} @ 85%",
"color.preview.backdrop": "#2A2A2D",
"color.preview.canvas-edge": "rgba(0, 0, 0, 0.30)",
"color.scrollbar": "rgba(0, 0, 0, 0.18)",
"color.scrollbar.hover": "rgba(0, 0, 0, 0.32)",
"color.tooltip": "#1D1D1F",
"color.tooltip.text": "#FFFFFF"
}
}A theme with no extends starts from nothing, so it has to set every token itself, as Studio Dark does:
{
"format": "velum-theme/1",
"id": "studio-dark",
"name": "Studio Dark",
"author": "Velum Studio",
"appearance": "dark",
"followSystemAccent": true,
"tokens": {
"color.window": "#0C0D0F",
"color.surface": "#121316",
"color.surface.raised": "#1A1B1F",
"color.surface.sunken": "#0A0A0C",
"color.surface.overlay": "#1E1F24",
"color.hover": "rgba(255, 255, 255, 0.045)",
"color.pressed": "rgba(255, 255, 255, 0.08)",
"color.selection": "{color.accent} @ 22%",
"color.border": "rgba(255, 255, 255, 0.07)",
"color.border.strong": "rgba(255, 255, 255, 0.13)",
"color.divider": "rgba(255, 255, 255, 0.06)",
"color.text": "#EDEDF0",
"color.text.secondary": "#A0A0A8",
"color.text.tertiary": "#82828B",
"color.text.disabled": "#4B4B52",
"color.accent": "#E9C58B",
"color.accent.hover": "#F1D19D",
"color.accent.pressed": "#DAB478",
"color.accent.text": "#1D1406",
"color.accent.strong": "{color.accent}",
"color.live": "#D42D25",
"color.live.text": "#FFFFFF",
"color.success": "#30D158",
"color.warning": "#FF7A00",
"color.warning.text": "#1D1406",
"color.danger": "#FF453A",
"color.danger.text": "#230C09",
"color.focus": "{color.accent.strong} @ 72%",
"color.preview.backdrop": "#08080A",
"color.preview.canvas-edge": "rgba(255, 255, 255, 0.10)",
"color.preview.selection": "{color.accent}",
"color.preview.handle": "#FFFFFF",
"color.preview.guide": "#FF3B8B",
"color.preview.grid": "rgba(255, 255, 255, 0.10)",
"color.scrollbar": "rgba(255, 255, 255, 0.14)",
"color.scrollbar.hover": "rgba(255, 255, 255, 0.26)",
"color.tooltip": "#2A2B30",
"color.tooltip.text": "#F2F2F5",
"font.family": "Inter",
"font.size.body": 13,
"font.size.small": 12,
"font.size.caption": 11,
"font.size.title": 15,
"font.weight.regular": 400,
"font.weight.medium": 500,
"font.weight.semibold": 600,
"radius.small": 4,
"radius.control": 6,
"radius.panel": 10,
"space.xs": 4,
"space.s": 8,
"space.m": 12,
"space.l": 16,
"metric.control-height": 28,
"metric.border": 1,
"metric.scrollbar": 8,
"metric.dock-titlebar": 30,
"metric.preview.min-width": 320,
"metric.preview.min-height": 180,
"metric.window.min-width": 0,
"metric.window.min-height": 0,
"icon.stroke": 1.75
}
}If something is wrong
A theme with an error is never applied. Studio keeps the current theme and shows the error in Appearance (and in the log), for example:
"color.accent": "#12" isn't a colorToken names Studio doesn't recognize are reported as warnings, so a typo like color.acent doesn't silently do nothing.

