Theme format reference

Top-level document

Field	Meaning
version	Required. Must be 2.
name	Required non-empty name, up to 160 characters.
$schema	Optional editor schema reference.
author, description	Optional metadata.
appearance	adaptive by default, or fixed light / dark.
common, light, dark	Color-theme values for shared and per-mode overrides.
resources	Local assets map and ordered stylesheets list.
vscode	Resolved VS Code data retained by the importer.
iconTheme	{ kind: 'file' or 'product', path: 'icons.json' } for an icon package.

An icon package cannot also define common, light, dark, resources or vscode. Keep icon and color themes as separate selections.

Each color surface (common, light, dark) supports the following sections.

tokens

A map of CSS custom-property names to string values. Names use -- followed by lower-case letters, digits and hyphens, starting with a letter.

Common tokens	Purpose
--color-background, --color-background-text	Main background and text.
--color-surface, --color-surface-text	Surface background and text.
--color-surface-variant, --color-surface-variant-text	Secondary surfaces and text.
--color-outline	Borders.
--color-primary, --color-primary-text	Accent and text on the accent.
--color-error, --color-warning, --color-info	Status colors.
--font-family, --font-family-mono, --font-size	Base typography.
--density, --border-width, --focus-width	Spacing scale and line widths.
--radius-control, --radius-tab, --radius-menu, --radius-modal	Corner radii.
--terminal-padding, --pane-spacing, --sidebar-min-width, --sidebar-max-width	Panel spacing and dimensions.

The token catalogue lists all 226 DeepMono tokens with Light and Dark values. Use existing semantic tokens before targeting application selectors.

--color-* tokens, editor colors, syntax colors and terminal colors accept hex RGB/RGBA (#abc, #abcd, #aabbcc, #aabbccdd), transparent, var(--token) and color-mix(in srgb, var(--token) 70%, transparent), with a percentage from 0 to 100. Expressions outside that subset belong in an optional stylesheet. A var() reference in a structured color cannot contain a fallback argument.

layout

Field	Values
tabs	inline, above, below
statusbar	top, bottom
settingsNavigation	left, right, top, bottom

These values affect presentation. They do not rewrite the saved workspace layout.

styles

A map of CSS selectors to declaration maps. Property names use CSS kebab-case, and values are strings:

{
  "common": {
    "styles": {
      ".workspace-info": {
        "padding": "20px",
        "border-radius": "var(--radius-control)"
      }
    }
  }
}

This is a document fragment. The runtime validates and serializes declarations through CSSOM. Selectors are not isolated from the rest of the application.

backgrounds

Supported areas are app, terminal, sidebar, titlebar, statusbar, settings and modal. Each area accepts:

Field	Value
image	Relative file path inside the package.
opacity	Number from 0 to 1. Applies to the background layer, not text.
blur	Number from 0 to 100.
size, position	CSS values such as cover and center.
repeat	no-repeat, repeat, repeat-x, repeat-y, space, round.
overlay, blendMode	CSS overlay color and blend mode.

editor

fontFamily is a string and fontSize ranges from 6 to 72. colors accepts background, foreground, gutterBackground, gutterForeground, activeLine, selection and cursor.

syntax supports exactly these names:

keyword, string, number, comment, type, function, variable, property,
operator, punctuation, heading, strong, emphasis, link, invalid

Each syntax entry accepts color, fontStyle (normal or italic), fontWeight (normal, bold, or 100 to 900 in steps of 100), and textDecoration (none or underline). These map to the editor’s fixed CodeMirror/Lezer categories.

terminal

Field	Value
preset	Name from the bundled xterm-theme palette library. Use Load terminal presets in the editor to inspect names.
fontFamily	Font family string.
fontSize	6 to 72.
lineHeight	1 to 3.
letterSpacing	-2 to 20.
fontWeight, fontWeightBold	normal, bold, or a number from 1 to 1000.
cursorStyle	bar, block, underline.
cursorInactiveStyle	outline, bar, block, underline, none.
cursorBlink, drawBoldTextInBrightColors	Boolean.
cursorWidth	1 to 10.
minimumContrastRatio	1 to 21.

colors accepts all of these keys:

background, foreground, cursor, cursorAccent,
selectionBackground, selectionForeground, selectionInactiveBackground,
black, red, green, yellow, blue, magenta, cyan, white,
brightBlack, brightRed, brightGreen, brightYellow,
brightBlue, brightMagenta, brightCyan, brightWhite,
searchMatchBackground, searchActiveMatchBackground,
searchMatchBorder, searchActiveMatchBorder

Explicit colors override a preset. User choices in Settings > Terminal override the theme’s terminal defaults. A color theme does not configure shell behavior or editor indentation.

plugins

A map from plugin owner IDs to maps of token names and string values. These tokens become namespaced CSS custom properties; they do not override core properties through this field. See resources and CSS for an example.

Resource fields and validation boundaries

resources belongs at the document root, not inside an appearance. assets maps lowercase aliases to package-relative files; stylesheets is an ordered array of unique .css paths. A color theme can omit either. See resources and CSS for full examples.

Value	Bound or rule
Document	UTF-8 JSONC, up to 256 KiB and 32 nesting levels
Name	Non-empty, up to 160 characters
Ordinary metadata strings	Non-empty, up to 2000 characters
CSS selector	Non-empty, up to 1000 characters; must parse as a style rule
Token, plugin token or CSS declaration value	Non-empty string, up to 4000 characters
Resource path	Up to 1024 characters; no absolute paths, empty segments, . or .. segments
Asset alias	Lowercase letter first, then lowercase letters, digits or hyphens
Plugin owner ID	Lowercase namespaced ID, such as example.workspace-info

Unknown structural fields are rejected. Numeric fields require finite JSON numbers and are range-checked; do not quote them. Omit optional fields rather than assigning null. Duplicate object keys are errors, including inside nested objects.

The JSON schema helps with completion and structure; preview also checks CSS support, preset names and resource loading. A valid JSON document can still fail those checks. Error messages include a filename, line and column where available.

vscode stores resolved source data: import include and external TextMate references through the importer first. Do not place unresolved paths in that field. Native appearance remains the mode selector.

Use the token catalogue for every built-in token, editor and terminal for recipes, and icon guides for the separate icon-document format.

Source: format and limits, CSS generation, version 2 schema.