Create a color theme

A color theme is a folder containing theme.jsonc. CSS and assets are optional. It does not need a JavaScript entry or a plugin manifest.

Create it in Settings

1. Open Settings > Themes > Colors > Create theme.
2. Select Edit JSON.
3. Replace the draft with the following document.
4. Use Preview to inspect it in that window, then Save theme.
5. Select Graphite Notes in the catalogue to apply it.

{
  "version": 2,
  "name": "Graphite Notes",
  "appearance": "adaptive",
  "common": {
    "tokens": {
      "--radius-control": "6px",
      "--terminal-padding": "12px"
    },
    "editor": {
      "syntax": {
        "comment": { "fontStyle": "italic" }
      }
    },
    "terminal": { "fontSize": 14 },
    "plugins": {
      "example.workspace-info": { "surface": "var(--color-surface)" }
    }
  },
  "light": {
    "editor": { "colors": { "background": "#fafafa" } }
  },
  "dark": {
    "editor": { "colors": { "background": "#101010" } }
  }
}

This theme keeps DeepMono’s interface palette, changes control corners and terminal padding, sets a 14 px terminal font, and makes editor comments italic. The editor background differs between light and dark mode. The plugin token gives the workspace-info example a theme-controlled surface.

The complete package is also in examples/graphite-notes. Select that folder with Import folder to install the same example.

Write only overrides

You do not need to copy the complete DeepMono theme. Omitted properties inherit the current mode’s baseline. Put shared values in common, light-mode values in light, and dark-mode values in dark.

Nested editor syntax properties, terminal colors, background properties and CSS declarations merge by property. For example, common.editor.syntax.comment.fontStyle survives when dark.editor.syntax.comment.color supplies only a color.

An adaptive theme responds to System, Light or Dark. For a theme with only one supported appearance, set appearance to light or dark.

JSONC rules

Comments and trailing commas are accepted. Quoted JSON property names are required. Duplicate keys, unknown fields and JSON5 syntax are rejected. The document limit is 256 KiB and 32 levels of JSON nesting.

Use the version 2 schema for editor assistance. Create theme writes a local schema beside the new document. Runtime validation also checks colors, paths, CSS and resources; schema validation alone does not guarantee that a theme will load.

Share a theme

Open the installed theme folder and copy the entire package, including referenced CSS and assets. The recipient uses Import folder. Keep all resource paths relative to the package so it works on another computer.

To distribute the theme inside a plugin, declare it in contributes.themes and include its folder in the plugin build’s assets. See plugin packaging.

Work in the visual editor

The controls and Edit JSON modify one JSONC draft. Edit variant chooses where an override is written: common, light or dark. It does not by itself force the application’s appearance. Theme appearance determines whether the whole theme is adaptive or fixed.

Search tokens with Search theme tokens, or enable Overrides only to focus on values declared in the current section. Emptying an override field removes that property and exposes the inherited value. Controls preserve comments in the raw document. If JSON is invalid, correct the indicated line before returning to controls.

Preview is a temporary local action. Cancel preview restores the selected theme without discarding your draft. Saving writes the draft; selecting applies it to the app. Saving an inactive theme does not automatically select it. Closing with unsaved edits asks whether to keep editing or discard changes.

In JSON mode, Find in JSON searches the draft, Undo and Redo navigate edit history, and Format JSON formats the document while preserving JSONC comments. Formatting does not save. The editor also uses your configured save, find, go-to-line and word-wrap shortcuts. Show controls returns to the visual form.

Understand property merging

The following is a fragment to place inside a complete document with version and name:

{
  "common": {
    "editor": { "syntax": { "comment": { "fontStyle": "italic", "color": "#707070" } } },
    "terminal": { "fontSize": 14, "colors": { "red": "#b33a3a" } }
  },
  "dark": {
    "editor": { "syntax": { "comment": { "color": "#a0a0a0" } } },
    "terminal": { "colors": { "blue": "#7ca7d8" } }
  }
}

In dark mode, the comment is #a0a0a0 and remains italic. The terminal keeps size 14, red #b33a3a and gains blue #7ca7d8. Light mode uses the common comment color and red; the omitted blue comes from the baseline. An empty object does not erase an inherited object. Delete the property at the level that declares it, or provide an explicit replacement such as fontStyle: "normal".

Create files outside the app

Create a folder with a UTF-8 theme.jsonc at its root and copy the complete Graphite Notes document above. Import that folder using Import folder, then select the imported entry. No Node.js, Rust, compilation or plugin approval is needed for a standalone local theme.

Keep the editable source folder under version control if useful. Import makes a copy: choose one editing workflow deliberately. Either edit the installed copy through Settings, or edit your source and import a new copy for review. Import is not a live link to your source folder.

Continue with editor and terminal recipes, the token catalogue and the release checklist.

Source: theme format and inheritance, theme creation and import.