ShellCanvas / docs

Appearance

Create and install themes ​

A theme is a small JSON file that sets the desktop's colours and a few sizes. There is no build step, no SDK and no code — which is also why installing one is safe.

Prerequisites ​

ShellCanvas, and a text editor. Themes need no connection and no permissions.

Steps ​

Install a theme ​

Open Desktop settings → Desktop:

  • Install theme file takes a .json or .shellcanvas-theme file of up to 32 KB from your computer.
  • Install from GitHub takes an owner/repository and a branch, tag or commit, and reads shellcanvas.theme.json from the repository root.

Either way ShellCanvas shows a review first, stating plainly that a theme contains colours and desktop styling only. No scripts, network resources or host access. Choose Install and apply.

Installed themes appear in the theme grid with Built in or the author's name, and whether they provide Light & dark, Light or Dark. Selecting one applies it immediately and keeps your wallpaper and size choices.

Write one ​

Start from Canvas Study, the complete example theme in the application repository under examples/themes/canvas-study. A theme declares an identifier, a name, and palettes for the variants it supports:

json
{
  "format": 1,
  "kind": "theme",
  "id": "studio.paper",
  "name": "Paper",
  "author": "Your name",
  "variants": {
    "light": {
      "palette": { "base": "#f6f7f9", "surface": "#ffffff", "text": "#12161c", "accent": "#2f6fe0" }
    },
    "dark": {
      "palette": { "base": "#101418", "surface": "#171c22", "text": "#eef2f7", "accent": "#6aa8ff" }
    }
  }
}

Alongside colours, a theme can set a few shapes and sizes, each clamped to a safe range: window corner radius (0–24), window header height (32–60), dock corner radius (0–28), background blur (0–40), toolbar height (36–64) and dock icon size (32–64). Values outside a range are rejected rather than applied.

Identifiers are dotted and lowercase, such as studio.paper, so your theme cannot collide with someone else's.

Publish it ​

Commit shellcanvas.theme.json to the root of a public repository. Anyone can then install it with Install from GitHub, and installing an updated version replaces the one they have.

Remove one ​

Select a theme you installed and choose Remove theme; Canvas becomes active again. Reset installed themes… clears the collection.

Expected result ​

The desktop repaints immediately — windows, menus, the dock, the terminal and the editor — and stays that way across restarts. Wallpaper, interface scale and dock size are your own settings and survive a theme change.

Limitations ​

  • Data only. No CSS, JavaScript, fonts, images or remote resources. A theme cannot change layout or behaviour, and cannot reach the network or a host.
  • 32 KB per theme file, and up to 24 installed at once.
  • One-variant themes are used for both modes. ShellCanvas says so rather than inventing the missing variant.
  • Per device. Themes install on the computer you are using; they are not synchronised.
  • Wallpaper photos are separate — your own image, stored locally, up to 20 MB and 80 megapixels.
  • Public repositories only for the GitHub route.

ShellCanvas documentation

© 2026 ShellCanvas