Themes

An extension can add additional themes that the user can set for the editor, the workspace window, or both. These themes are written as special CSS files that define the styling attributes to apply to widgets, content, and syntax highlighting.

Unlike in regular CSS files, theme files only support class-like selectors expressed as a series of identifiers separated by periods, such as identifier.function and tag.attribute.name. While these look like an element + class name selector typical to CSS, the identifiers in theme selectors are all classes, and even the order does not matter (although following convention is encouraged).

Themes are stored within a Themes folder at the root of the extension bundle, and should have a .css file extension.

The Syntax Inspector

To help when building a theme, you can use the Syntax Inspector to see which syntax highlighting selectors are active for specific regions of text.

The Meta Selector

The plain meta selector is used to describe attributes of the theme itself, such as its preferred appearance (light or dark), which affects certain heuristics in the theme engine.

The following attributes are supported for the plain meta selector:

• -theme-interface-style: the interface style of the theme (light or dark, with light being the default)
• -theme-vibrancy: whether sidebars and other elements use vibrancy (vibrant or none, with none being the default). Vibrancy should be used sparingly, and only for themes that shift closely to either a light or dark unsaturated theme.
• -theme-accent-color: whether certain UI elements should use the system accent color instead of theme-specified colors for active state, such as selected buttons (true or false, with false being the default)

Themes can style the window and base content using CSS selectors that begin with the meta identifier, targeting elements such as buttons and text fields.

Window Content

The following selectors can be used to style specific parts of the window chrome:

• meta.window: Used to set base attributes of the window

  • background-color: the background color of the window
  • border-color: the color for separators and borders in the window (such as split dividers)

• meta.titlebar: Used to set attributes of the window title bar

  • color: the text color of window toolbar items
  • background, background-color: the background color or CSS gradient used for the title bar
  • border-color: the color for the title bar’s bottom separator, and separators between toolbar items

• meta.titlebar.inactive: The attributes for an inactive window title bar

  • Supports the same attributes as the normal title bar selector
  • Inactive title bars should generally use a flat color for their appearance (not a gradient)

Buttons

Buttons are styled using the following CSS selectors:

• meta.button: The standard, un-highlighted state of a button
• meta.button.disabled: A button that is disabled
• meta.button.highlighted: A button that is being held down by the user
• meta.button.selected: For toggle buttons in the “on” state
• meta.button.highlighted.selected: For toggle buttons in the “on” state that are being held down by the user

For any of these selectors, adding the document identifier specifies that the appearance should be applied to buttons appearing in document tabs, such as meta.document.button.

The following CSS attributes are supported for buttons:

• color
• background, background-color
• border, border-color
• text-shadow

For backgrounds and borders, CSS gradients are supported. For all color-related attributes, the common CSS color types are supported: named, hex, rgb, rgba, hsl, hsla, hsb, and hsba.

Text Fields

Text fields are styled using the following CSS selectors:

• meta.textfield: The standard, inactive state of a text field
• meta.textfield.active: A text field with keyboard focus

For any of these selectors, adding the document identifier specifies that the appearance should be applied to text fields appearing in document tabs, such as meta.document.textfield.

The following CSS attributes are supported for text fields:

• background, background-color
• border, border-color

For backgrounds and borders, CSS gradients are supported. For all color-related attributes, the common CSS color types are supported: named, hex, rgb, rgba, hsl, hsla, hsb, and hsba.

Document Content

The following selectors can be used to style specific parts of the document (editor) content:

• meta.document: Used to set the base attributes of the text editor

  • background-color: the background color of the editor
  • border-color: the color for separators and borders in the editor (such as split dividers)

• meta.text: Used to set the base attributes of unstyled text in an editor

  • color: the text color
  • background-color: the background color of text line fragments

• meta.text.selected: Used to set the base attributes of selected text in an editor

  • color: the text color
  • background-color: the background color of text line fragments

• meta.cursor: Attributes of the document cursor:

  • background-color: the background color for the current-line highlight

• meta.indentguide: Attributes of indentation guides

  • border-color: the color of indentation guide borders

• meta.gutter: Attributes of the editor gutter

  • background-color: the background color
  • color: the text color of line numbers

• meta.gutter.selected: Attributes of the editor gutter for selected lines

  • background-color: the background color
  • color: the text color of line numbers

Styling Syntax Highlighting

Syntax highlight attributes are styling using standard CSS classes, where each element of a syntax highlighting scope can be used as a CSS class selector.

Each syntax highlighting selector supports the following CSS attributes:

• background-color
• color
• font-style: support for italic / oblique
• font-weight
• text-decoration: support for underline and strike-through
• text-shadow

For best practices, there is a standard set of CSS classes that are common across most syntaxes, and are most often used for themes that wish to target the widest set of languages available:

• keyword: reserved words in a language

  • keyword.construct: construct words, such as function, class, interface, type
  • keyword.condition: condition words, such as if, while, try, switch, case
  • keyword.modifier: modifier words, such as async, public, from, in, as
  • keyword.operator: operator words, such as and, or, not
  • keyword.self: type-referential words, such as self, this, super

• comment: single and multiline comments

• processing: processing directives, such as C preprocessor commands

• declaration: declarative elements, such as XML and HTML doctypes

• bracket: paired brackets for syntactic scope and separation

• operator: arithmetic and logical operators

• invalid: invalid text, such as improper syntax

• value: base class of all value types

  • value.boolean: boolean values
  • value.null: null values
  • value.number: numeric values
  • value.entity: entity values (such as HTML entities)
  • value.symbols: symbol values (such as Ruby symbols)

• string: base class of all string types

  • string.key: a string used as a key (such as in a key-value map)

• string-template: string templates

  • string-template.value: the expression within string templates

• regex: regular expression strings

  • regex.escaped: Escape sequences within regexes (using the backslash, such as \w+)

• cdata: CDATA blocks

• identifier: base class of all identifiers

  • identifier.type: base class for all types
    • identifier.type.class: classes
    • identifier.type.protocol: protocols
    • identifier.type.enum: enumerations
    • identifier.type.union: unions
    • identifier.type.struct: structs
  • identifier.global: globals
  • identifier.variable: variables that require highlighting, such as PHP $FOO
  • identifier.constant: constants
  • identifier.property: object properties
  • identifier.decorator: object decorators (such as for Python)
  • identifier.function: functions
  • identifier.method: methods
  • identifier.key: keys, such as in key-value pairs
  • identifier.argument: arguments to callables

• identifier.core: applyable to any of the above, indicates a “core” (built-in) symbol

• definition: definition of a symbol

  • definition.type
  • definition.class
  • definition.package
  • definition.protocol
  • definition.enum
  • definition.union
  • definition.struct
  • definition.property
  • definition.function
  • definition.method

• tag: base class of all markup tags (such as HTML and XML)

  • tag.framework: tags specific to a framework (such as CFML, ERB, or Django)
  • tag.attribute: tag attributes
    • tag.attribute.name: name of an attribute
    • tag.attribute.value: value of an attribute

• style: base class of all stylesheet symbols (such as CSS)

  • style.at: CSS-style processing directives using the @<directive> syntax
  • style.selector: stylesheet selectors
    • style.selector.element: an element selector (such as an HTML tag)
    • style.selector.identifier.id: ID selectors
    • style.selector.identifier.class: class selectors
    • style.selector.pseudoclass: CSS pseudoclasses
    • style.selector.pseudoelement: CSS pseudoelements
  • style.attribute: stylesheet attributes
    • style.attribute.name: name of an attribute
  • style.value: base class of stylesheet values
    • style.value.number: number values
    • style.value.color: color values
      • style.value.color.named: hexadecimal color values
      • style.value.color.hex: hexadecimal color values
    • style.value.keyword: value keywords

• markup: base class for non-tag markup elements (such as Markdown)

  • markup.heading: heading elements
  • markup.line: line elements, such as separators
  • markup.bold: bold or strong elements
  • markup.italic: italic or emphasis elements
  • markup.strikethrough: strike-through or deleted elements
  • markup.list: base class for markup lists
    • markup.list.item: list items
  • markup.code: preformatted code elements
  • markup.link: link elements

Styling Terminal Colors

Terminal views will automatically use the background and text color of the document styles (see above) when the terminal is set to theme itself based on an active theme.

In addition to this, the theme may specify values for the 16 standard ANSI colors. The following selectors may specify the color CSS property:

• terminal.black

• terminal.red

• terminal.green

• terminal.yellow

• terminal.blue

• terminal.magenta

• terminal.cyan

• terminal.white

• terminal.bright-black

• terminal.bright-red

• terminal.bright-green

• terminal.bright-yellow

• terminal.bright-blue

• terminal.bright-magenta

• terminal.bright-cyan

• terminal.bright-white