Developer
Log in

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) or rgba(r, g, b, a) with a from 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:

JSON
"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:

JSONstudio-light.json, a built-in theme
{
  "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:

JSONstudio-dark.json, a built-in theme
{
  "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:

Text
"color.accent": "#12" isn't a color

Token names Studio doesn't recognize are reported as warnings, so a typo like color.acent doesn't silently do nothing.

to open · ↑ ↓ to move · Esc to close