Theme Plugin

A theme plugin provides colors without running JavaScript. Recall validates the theme file and merges each theme with the built-in light or dark base, so you only need to override the semantic colors that make the theme distinct.

Create the manifest

Point the entry at a JSON file, use the theme runtime, and request registry.theme:

package.json

{
  "$schema": "https://recall.jrtilak.dev/schemas/plugin-config/v0.1/schema.json",
  "name": "@example/ocean-theme",
  "displayName": "Ocean Theme",
  "version": "1.0.0",
  "description": "A calm blue theme for Recall.",
  "author": "Example Developer <https://example.com>",
  "recall": {
    "manifestVersion": "0.1",
    "category": "theme",
    "tags": ["theme", "ocean"],
    "permissions": ["registry.theme"],
    "entry": {
      "runtime": "theme",
      "file": "src/theme.json"
    }
  }
}

Theme plugins do not export init or unload and do not need the runtime package.

Define the themes

Add the theme schema to src/theme.json. A single file can contain multiple named themes:

src/theme.json

{
  "$schema": "https://recall.jrtilak.dev/schemas/theme-config/v0.1/schema.json",
  "version": "0.1",
  "themeFor": "app",
  "themes": [
    {
      "id": "ocean-light",
      "name": "Ocean Light",
      "mode": "light",
      "theme": {
        "colors": {
          "primary": "#087EA4",
          "primaryForeground": "#FFFFFF",
          "background": "#F5FBFF",
          "foreground": "#102A43",
          "card": "#FFFFFF",
          "border": "#B8D8E8"
        }
      }
    },
    {
      "id": "ocean-dark",
      "name": "Ocean Dark",
      "mode": "dark",
      "theme": {
        "colors": {
          "primary": "#66C7F0",
          "primaryForeground": "#071820",
          "background": "#071820",
          "foreground": "#E8F7FC",
          "card": "#0D2633",
          "border": "#285369"
        }
      }
    }
  ]
}

Keep each id stable and unique. It must use lowercase letters, numbers, and hyphens. name is the label shown to users, and mode selects the base theme used for omitted colors.

Colors use #RRGGBB or #RRGGBBAA; the final two digits in the second form are alpha. Unknown color names are rejected. See the theme schema reference for the complete color-token list and limits.

Build the theme

Run Plugin Creator against the plugin directory:

bunx @jrtilak-recall/plugin-creator build ./ocean-theme --zip

The build validates both JSON files, copies the normalized theme to dist/theme.json, writes dist/manifest.json, and creates dist.zip when --zip is used. Fix validation errors in the source files and rebuild; the generated files should not be edited directly.