Structure of the JSON format for themes

This topic explains the structure of the JSON theme file. This JSON file contains mappings between different UI elements and their assigned colors, as well as other theme settings.

Themes are defined in JSON files and contain four blocks:

meta: metadata, such as the theme's name and type.
colors: colors for UI elements, such as buttons, headers, and backgrounds.
textAttributes (optional): text attributes used for syntax highlighting in the editor.
palette (optional): named colors that can be used in the colors and textAttributes blocks.

Supported color formats

The following color formats are supported, each offering specific ways to define colors with varying degrees of opacity:

#rrggbb: this format represents colors using three pairs of hexadecimal digits, where each pair corresponds to the red, green, and blue components of the color. Each component can have a value ranging from 00 to FF, which corresponds to the intensity of that color component.
Example: #7f7f7f
- Red: 7f (127 in decimal, indicating a medium intensity of red).
- Green: 7f (127 in decimal, indicating a medium intensity of green).
- Blue: 7f (127 in decimal, indicating a medium intensity of blue).
This format does not include an alpha channel, meaning it is fully opaque.
#rrggbbaa: this format is an extension of the #rrggbb format, with an additional pair of hexadecimal digits to represent the alpha channel, which defines the opacity of the color.
Example: #7f7f7fff.
- Red: 7f (127 in decimal).
- Green: 7f (127 in decimal).
- Blue: 7f (127 in decimal).
- Alpha: ff (255 in decimal, indicating full opacity).
#RRGGBB: similar to #rrggbb, this format uses uppercase letters to denote the hexadecimal digits, which is purely stylistic and has no effect on the color itself.
Example: #7F7F7F.
#RRGGBBAA: similar to #rrggbbaa, this format uses uppercase letters to denote the hexadecimal digits, which is purely stylistic and has no effect on the color itself.
Example: #7F7F7FFF.

colors

Specifies colors for UI elements like buttons, headers, and backgrounds.

Fallback rules: if a theme does not have a color key, it falls back to the corresponding key in the default Light or Dark theme, as defined by the theme.kind key in meta.

Example:

{
    "colors": {
        "dragAndDrop.background": "#0273EB33",
        "editor.background": "White" // Named color from the 'palette' section is used instead of a hex code
    }
}
        

textAttributes

Defines text attributes used for syntax highlighting in the editor. This block is optional.

The following fallback rules are applied to this block:

If the textAttributes block is missing, the text attributes from the default Light or Dark theme are used (depending on the theme.kind key in meta).
If the textAttributes block is present, text attributes will not fall back to the parent theme. If an attribute is not found, it tries to fall back on another attribute in the same theme by dropping the last segment. If there is no fallback, the default text color is used.

Fallback example: "problem.warning.weak"-> "problem.warning"-> "problem"-> using default text color

Example:

{
    "attributeName": {
        "foregroundColor": "Gray 10", // Text color [String in #RRGGBBAA format or named color from the palette]
        "backgroundColor": "Gray 10", // Background color [String in #RRGGBBAA format or named color from the palette]
        "statusColor": "Gray 10", // Scrollbar mark color to the right of the text [String in #RRGGBBAA format or named color from the palette]
        "fontWeight": "BOLD", // Font weight, options: [NORMAL, BOLD, SEMI_BOLD]
        "fontStyle": "ITALIC", // Font style, options: [NORMAL, ITALIC]
        "textDecoration": {
            "color": "Gray 10", // Decoration color, overrides foregroundColor
            "style": "SOLID", // Decoration style, options: [SOLID, DOUBLE, DOTTED, DASHED, WAVY]
            "type": "UNDERLINE", // Decoration position relative to text, options: [OVERLINE, LINE_THROUGH, UNDERLINE]
            "thickness": 1.0 // Decoration thickness [Double]
        },
        "border": {
            "color": "Gray 10", // Border color [String in #RRGGBBAA format or named color from the palette], overrides foregroundColor
            "thickness": 1.0 // Border thickness [Double]
        }
    }
}

        

Example:

{
    "textAttributes": {
        "editor.selection": {
            "backgroundColor": "Gray 80"
        },
        "editor.selection.focused": {
            "backgroundColor": "#A3D1FF"
        },
        "editor.indentGuide": {
            "foregroundColor": "Gray 90",
            "textDecoration": {
                "style": "DASHED"
            }
        },
        "problem.error": {
            "textDecoration": {
                "color": "#E81237",
                "style": "SOLID",
                "type": "UNDERLINE",
                "thickness": 2.0
            }
        }
    }
}
        

palette

Defines named colors that can be used in the theme. This block is optional.

Example:

    "colors": {
        "button.positive.text.default": "TextDefault",
        "button.primary.background.default": "BackgroundDefault"
    },
    "palette": {
        "TextDefault": "#FFFFFF",
        "BackgroundDefault": "#000000"
    } 

Example

Here is an example of a simple theme that changes colors in the code editor:

{
    "meta": {
        "theme.name": "Quantum Harmony",
        "theme.kind": "Light"
    },
    "textAttributes": {
        "editor.selection": {
            "backgroundColor": "#98FB98"
        },
        "editor.selection.focused": {
            "backgroundColor": "#AFEEEE"
        },
        "editor.indentGuide": {
            "foregroundColor": "#CD5C5C",
            "textDecoration": {
                "style": "DASHED"
            }
        },
        "problem.error": {
            "textDecoration": {
                "color": "#8B0000",
                "style": "SOLID",
                "type": "UNDERLINE",
                "thickness": 2.0
            }
        }
    },
    "colors": {
        "tab.background.default": "#FFDEAD",
        "tab.background.hovered": "#F5DEB3",
        "tab.background.selected": "#E6E6FA",
        "tab.indicator": "IndicatorColor",

        "popup.tab.background.default": "#FFE4C4",
        "popup.tab.background.hovered": "#D8BFD8",
        "popup.tab.background.selected": "#E0FFFF",
        "popup.tab.indicator": "IndicatorColor",

        "editor.background": "#FAFAD2",
        "editor.caret.background": "#FF7F50",
        "editor.caret.border": "#8A2BE2",

        "tool.background": "#7FFFD4"
    },
    "palette": {
      "IndicatorColor": "#DA70D6"
    }
}
        

Last modified: 10 December 2024