.theme.json plus an optional
.icls editor scheme), it has no code: no WebAssembly, nothing to compile, no
capabilities.
openidea-plugin new my-theme --template theme, which copies
Harbor Night,
a complete dark theme that sets every themeable token.
The manifest
wasm and no [capabilities]. Paths are relative to the package directory
and may not leave it. The other manifest fields are on Manifest.
The theme file
tokensare the CSS variables ofsrc/styles/tokens.css, the IDE’s single source of colours. Components never use colour literals, so every surface, border, text colour, syntax colour and status colour can be themed. The reference lists them all.kindpicks the built-in base. While the theme is active the IDE runs on Islands Dark or Islands Light, and every token the theme leaves out keeps that base’s value. Icons use the light or dark set that matches the kind. A partial theme still looks consistent, but listing every token keeps it stable when the IDE’s own palette changes.- Token names are
--followed by lowercase letters, digits and-(at most 64 bytes). - Values are plain CSS values: hex (
#rgb,#rrggbb,#rrggbbaa),rgb(),hsl(),color-mix(),var(--other-token), or for the few non-colour tokens a keyword (italic,normal,none) or a shadow list.url(),image(),;, braces,<,>,\and line breaks are rejected. //and/* */comments are allowed, as in VS Code theme files.- Tokens that tokens.css derives from others (for example
--bg-editorisvar(--bg-island), and the coverage and flame graph colours are mixed from the status colours) follow automatically. You may still set them. - Metrics (
--fs-*,--h-*,--radius-*) and fonts (--font-ui,--font-mono) can be overridden too, but a theme normally leaves them alone so that compact mode and the user’s font settings keep working.
The editor colour scheme file
.icls file. The split only organises the files: a theme can
put everything in its theme file.
How a theme is applied
The selected theme is injected as one stylesheet on:root that outranks the built-in
theme blocks, and data-theme is switched to the theme’s kind. Three things still layer on
top of it:
- an Accent colour picked in Settings › Appearance & Behavior › Appearance (other than the default),
- an explicit scheme or attribute overrides in Settings › Editor › Color Scheme,
- the appearance options that change only metrics (compact mode).
--bg-stripe-tooltip, --fg-stripe-tooltip, --border-stripe-tooltip
and --shadow-stripe-tooltip. A theme that omits them inherits the corresponding base
tooltip tokens.
Install, apply and iterate
There is no build step: the package is the folder.1
Start from the template
Run
openidea-plugin new my-theme --template theme (or copy plugins/official/harbor-night) and rename id,
name and the theme files.2
Edit the colours
Keep
kind truthful (light for light backgrounds).3
Install
In Settings › Plugins, open the gear menu and choose Install Plugin from Disk… (also an action in Find
Action) and pick the package folder, or Install Plugin from Package File… and pick its
plugin.toml or a .zip
of the folder.4
Apply
In Settings › Plugins, select the plugin and press Apply next to the theme. Use Default Theme switches
back. Plugin themes are also listed under Theme in Settings › Appearance & Behavior › Appearance.
openidea-plugin link (it is read in
place), or put or symlink it in <project>/.openidea/plugins/<name>/ of a trusted project.
Then press Reload on the plugin, or run the Reload Plugins action, to pick up your
edits. If a file or value is invalid, Settings › Plugins shows the load error with the
file and line.
To share a theme, publish it like any plugin; see Packaging.
Importing IntelliJ themes
To use a theme you already have in a JetBrains IDE, open the gear menu in Settings › Plugins (a project must be open):- Import Theme from JetBrains IDE… lists the theme plugins installed in the JetBrains IDEs
(and Android Studio) on this computer, one row per plugin of each IDE, with the plugins of
the themes the IDEs use first. It reads the settings folder of each IDE’s newest version:
~/Library/Application Support/JetBrains(macOS),%APPDATA%\JetBrains(Windows),~/.config/JetBrainsand~/.local/share/JetBrains(Linux). - Import IntelliJ Theme from File… takes a theme plugin downloaded from the JetBrains
Marketplace (
.jar, or a.zipwith the plugin’slib/*.jar) or a.theme.json(itseditorSchemefile is read from the same folder).
intellij.<plugin id>, with each of its
themes and their editor schemes. It is installed through the usual install page, and the
theme in use doesn’t change: choose one of its themes under Theme in Settings ›
Appearance & Behavior › Appearance. Importing the plugin again replaces it. Both commands
are also actions (plugins.importInstalledIntellijTheme, plugins.importIntellijTheme).
Porting an IntelliJ theme for publishing
Only port themes whose licence allows redistribution, keep their licence file, and credit the original authors inauthors and description.
scripts/theme/import-intellij-theme.ts in the repository converts an IntelliJ
.theme.json, and optionally its .icls editor scheme, into a plugin folder you can edit
before publishing. It needs only Node 22.
colors
section and * wildcards, and takes kind from "dark" (or the .icls parent_scheme).
Tokens without an IntelliJ counterpart keep the built-in values for that kind. Themes that
ship only a .theme.json with an editorScheme path need that .icls passed as the second
argument; themes that ship no .icls keep the built-in syntax colours.
.theme.json to UI theme
The full table is
UI_KEYS in
src/features/plugins/intellijTheme.ts.
.icls to editor scheme
The full tables are
ICLS_COLORS and ICLS_ATTRIBUTES in the same file. An attribute
written as <value /> has no colours of its own and shows as plain text (TEXT’s
foreground), as in IntelliJ, not with the parent scheme’s colour.
Porting a VS Code theme
A VS Code theme (themes/*.json in the extension) has type (dark / light / hc),
colors (workbench) and tokenColors (TextMate scopes). Set kind from type, then map
by hand:
tokenColors to syntax tokens, by TextMate scope:
A
fontStyle: "italic" on comments maps to "--syn-comment-style": "italic".
Testing a theme
- Install it (or link it), apply it, and walk through: the Project tool window with a
selection, the editor with a few languages, Search Everywhere, a popup menu, a tooltip,
Settings, the terminal (
ls --color), a diff, and the VCS colours in the Commit tool window. - Text should keep at least WCAG AA contrast (4.5:1) on its surfaces. The built-in themes
are checked by
src/features/settings/__tests__/contrast.test.ts. - For changes to the repository’s own template:
pnpm vitest run scripts/themevalidates the template against tokens.css and keeps the token reference current, andcargo test -p ide-pluginloads the template through the plugin host.
Token reference
The values of the two base themes, generated fromsrc/styles/tokens.css (pnpm gen:theme-docs regenerates the copy in plugins/themes.md). Groups marked UI theme
conventionally go in the theme file, groups marked editor scheme in the scheme file.
256 themeable tokens: 125 in the UI theme file, 131 in the editor colour scheme file.