[themes] let extensions contribute colors

[siegebell]

Feature request: provide an interface for the user to customize extension-specific colors/styles.

Specifically:

1. allow an extension to declare various color/styling tag contributions with default values for dark, light, high-contrast, or particular color themes; to look up the current color/style for a tag; and to receive a notification when its color settings change.
2. provide a way for the user to override or specify the colors for any color/style tag. For example:

• via settings.json
• via a color theme that specifies colors/styles for extension-specific tags. (Maybe allow the user to specify a backup theme for tags that the main theme does not specify.)
• provide a UI for the user to customize a color theme, and in particular, allow the user to override select color settings and to specify those that the color theme does not (e.g. extension-specific colors).

Use case: I'm working on an extension that makes heavy use of highlighting. (It is a theorem prover, where lines are highlighted green, blue, red, etc. to indicate what the theorem prover has accepted, rejected, or is still working on. There are ~10 highlights used). I want the colors for the highlights to be user-configurable.

The current solution: an extension can provide configuration settings for the user to specify colors. Problems with this approach:

• coarse grain: it is limited to light vs dark themes
• each extension has to reimplement this approach if they want user-specified colors
• users have to deal with each extension providing a potentially different configuration syntax for a color/style setting.

Colors should not be hard-coded by an extension. I believe that all extensions using DecorationRenderOptions or providing an HTML preview will benefit from a unified way for the user to specify colors.

[aeschli]

If I understand right what you suggest is that extensions can extend color themes and that there is API to access these colors.

Maybe related: User definable colors for a color theme: #11556

[siegebell]

@aeschli Pretty much. #11556 is related and will help the situation for users. Extending color themes isn't strictly necessary, but I cannot think of a better way.

It is good to discourage generic color themes from providing extension- and language-specific colors, but there needs to be a way for extensions that contribute their own styling to work with color themes and to have their colors be overridden by the user. Providing dark-vs-light styles (currently supported) is a good start for default colors, but it is not sufficient because getting a color to work with all dark or all light themes is still very difficult. And it should ultimately be up to the user because they may have specific needs: poor vision, color blindness, a bad monitor, poor lighting, conflicting extension colors, etc.

So to reiterate, this feature request addresses the extension's needs:

• to enable declaration of additional color tags that a theme or the user can override,
• to be able to query the colors assigned to those tags,
• and to receive a notification when they change.

Additional features that could make this work better:

• making it much easier for the user to override particular colors ([themes] make color themes user configurable #11556) and/or
• allowing an extension to contribute "color theme extensions", which adds default values for additional color tags to existing color themes.

[eriklieben]

Would love to see this feature!

Use case:

In the Aurelia extension we color all tags related to Aurelia purple, with a customized syntax file.

We now need to copy themes and keep them in sync with all the changes occurring in original themes. It 'broke' yesterday with the release of 1.9.0 and we quickly needed to sync them again, that would not be required anymore if we could provider fallback colors. We basicly add the following to existing themes:

"scope": [
        "compose.element.html.au", 
        "router-view.element.html.au",
        "databinding.attribute.html.au",
        "invoke.attribute.html.au",
        "ref.attribute.html.au",
        "repeat.attribute.html.au",
        "for.attribute.html.au",
        "view-model.attribute.html.au",
        "matcher.attribute.html.au",
        "model.attribute.html.au",
        "view.attribute.html.au",
        "controller.attribute.html.au",
        "bindable.attribute.html.au",
        "containerless.attribute.html.au",
        "compile-spy.attribute.html.au",
        "view-spy.attribute.html.au",
        "if.attribute.html.au",
        "route-href.attribute.html.au",
        "show.attribute.html.au",
        "ref.attribute.html.au",
        "replace-part.attribute.html.au",
        "replaceable.attribute.html.au",     
        "element.html.au", 
        "attribute.html.au"],
			"settings": {
				"foreground": "#ba68c8"
			}

(Used to be only "html.au" scope, but that doesn't work anymore in 1.9.0/ doesn't inherit anymore)

[aeschli]

I'll use #26974 as the request to give extensions the API to access the workbench colors. That's IMO the first and most important step.
I understand that you also would like to define your own colors, but IMO that's quite advanced and I think only few themes would start defining colors for these. So maybe better it better if extensions try to derive new colors from existing, well known colors.

[KnisterPeter]

I don't see how extensions (e.g. an extension who provides a custom document representation) could access the current theme colors.
I need to build a custom diff view for my extension and I would love to use the theme colors so it feels more natural to users.

How do I resolve theme colors to css colors so I could embed these inside of my html document?

[aeschli]

With the recently added APIs you can just reference existing colors. There's currently no access to the RGB values, nor a theme change event where you have to listen to.

Do you want to use colors in an HTML preview?

[KnisterPeter]

Yes, thats exactly what I need to do.
I would like to build a diff view for github pull-requests. And I would like to have it to be most natural to users.

[aeschli]

For August I added the 'colors' contribution point that lets extensions define new colors that then can be defined in themes and users settings.

        "colors": [{
            "id": "superstatus.error",
            "description": "Color or the error message in the status bar.",
            "defaults": {
                "dark": "#FF0000",
                "light": "errorForeground",
                "highContrast": "errorForeground"
            }
        }]

Defaults can be actual colors or a reference to an existing color.

[aeschli]

Future improvements can be to allow functions on colors, e.g. take an existing color and add transparency, make it darker/lighter...

There's also still the request to have APIs to access colors and theme change events.

My hope is to avoid such API and force that only color references are used. All APIs in the extension host should take color id ('ThemableColor').
The advantage of that is:

• all colors can be configured through themes and user settings
• theme changes are handled by the UI components that use the color, no extension code needed

Closing this issue. If the current APIs are not good enough for you, please continue to comment here or open a new issue for the missing features explaining your use cases.

[KnisterPeter]

Is there already a way to use the colors/theme in a preview view?

[jens1o]

@KnisterPeter Yes, there is. Just download the Insiders Version from https://code.visualstudio.com :)

[DanTup]

@aeschli Thanks for this!

About not having an event for when these change - if I create a decoration type and use the the name of that new colour in it and then the user changes the theme colour, will the decorations automatically update to the new colour? If so; the lack of an event doesn't bother me :-)

[aeschli]

@DanTup Yes, updating of decorations on theme change happens automatically.