Skip to content

Commit 238daa2

Browse files
TyriarTyriar
committed
Update color theme guide
Part of #2197
1 parent 4c43c04 commit 238daa2

File tree

1 file changed

+79
-33
lines changed

1 file changed

+79
-33
lines changed

‎api/extension-guides/color-theme.md

Lines changed: 79 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -3,58 +3,104 @@
33

44
# Color Theme
55

6-
---
7-
**Writing Instructions**
6+
Colors visible in the VS Code user interface fall in two categories:
87

9-
This is one of the options mentioned in https://vscode-ext-docs.azurewebsites.net/api/extension-capabilities/theming.
8+
- Workbench colors used in views and editors, from the Activity Bar to the Status Bar. A complete list of all these colors can be found in the [theme color reference](/api/references/theme-color).
9+
- Syntax colors used for source code in the editor. The theming of these colors is different as syntax colorization is based on TextMate grammars and TextMate themes.
1010

11-
- Migrate content from https://code.visualstudio.com/docs/extensions/themes-snippets-colorizers#_adding-a-new-color-theme
12-
- Update https://github.com/Microsoft/vscode-extension-samples/tree/master/theme-sample so it includes a README and link back to this guide
13-
- You can also mention:
14-
- https://github.com/Tyriar/vscode-theme-generator
15-
- https://css-tricks.com/creating-a-vs-code-theme/
11+
This guide will cover the different ways in which you can create themes
1612

17-
---
13+
## Workbench colors
1814

19-
**Suggested Sections**
15+
The easiest way to create a new workbench color theme is to start with an existing color theme and customize it. First switch to the color theme that you want to modify, then open your [settings](/docs/getstarted/settings.md) and make changes to the `workbench.colorCustomizations` setting, changes are applied live to your VS Code instance. The following for example would change the color of the title bar:
2016

21-
## UI Colors
17+
```json
18+
{
19+
"workbench.colorCustomizations": {
20+
"titleBar.activeBackground": "#ff0000"
21+
}
22+
}
23+
```
2224

23-
- In this section, explain `colors`, link to https://vscode-ext-docs.azurewebsites.net/api/references/theme-color, explain the setting `workbench.colorCustomizations`
24-
- Give a recommended workflow, such as:
25-
- Start adjusting colors by tweaking `workbench.colorCustomizations`
26-
- Then copy the keys to `colors` in a theme extension
25+
A complete list of all themable colors can be found in the [color reference](/api/references/theme-color).
2726

28-
## Syntax Colors
27+
## Syntax colors
2928

30-
- In this section, explain `tokenColors`, link to the [Syntax Highlight Guide](https://vscode-ext-docs.azurewebsites.net/api/language-extensions/syntax-highlight-guide), explain scope inspector, explain `editor.tokenColorCustomization` setting
31-
- Give a recommended workflow, such as:
32-
- Start adjusting colors by tweaking `workbench.tokenColorCustomizations`
33-
- Then copy the keys to `tokenColors` in a theme extension
29+
For syntax highlighting colors, there are two approaches. You just simply reference an existing TextMate theme (`.tmTheme` file) from the community, or you can come up with your own theming rules. The easiest way is to start with an existing theme and customize it, much like in the workbench colors section above.
3430

35-
---
31+
First switch to the color theme to customize and use the `editor.tokenColorCustomizations` [settings](/docs/getstarted/settings.md). Changes are applied live to your VS Code instance and no refreshing or reloading is necessary. For example the following would chang eht ecolor of comments within the editor:
32+
33+
```json
34+
{
35+
"editor.tokenColorCustomizations": {
36+
"comments": "#FF0000"
37+
}
38+
}
39+
```
40+
41+
The setting supports a simple model with a set of common token types such as 'comments', 'strings' and 'numbers' available. If you want to color more than that, you need to use TextMate theme rules directly which are explained in detail in the [Syntax Highlighting Guide](/api/language-extensions/syntax-highlight-guide).
42+
43+
## Create a new Color Theme
3644

37-
**Some content for reusing**
45+
Once you have tweaked your theme colors using `workbench.colorCustomizations` and `editor.tokenColorCustomizations`, it's time to create the actual theme.
3846

39-
As you can see in the illustration, Color Theme defines two mappings, `colors` for UI Component colors and `tokenColors` for Text Token colors.
47+
1. Generate a theme file using the **Developer: Generate Color Theme from Current Settings** command from the **Command Palette**
48+
2. Use VS Code's [Yeoman](http://yeoman.io) extension generator, [yo code](/docs/extensions/yocode.md), to generate a new theme extension:
4049

41-
[Theme Color Reference](/api/references/theme-color) is a good starting point for customizing UI Component colors.
50+
```bash
51+
npm install -g yo generator-code
52+
yo code
53+
```
4254

43-
If you want to change the color of text in your editor, you need to know how the text is tokenized. VS Code provides a handy command `Developer: Inspect TM Scopes` that shows you the TextMate scopes of each syntax token in the editor.
55+
3. If you customized a theme as described above, select 'Start fresh'.
4456

45-
![tm-inspector](./images/color-theme/tm-inspector.png)
57+
![yo code theme](/docs/extensions/images/themes-snippets-colorizers/yocode-colortheme.png)
4658

47-
There are also two settings, `workbench.colorCustomizations` and `editor.tokenColorCustomizations` that correspond to the `color` and `tokenColors` color theme config. They provide a quick way for you to play with colors. For example, try adding this to your user settings:
59+
4. Copy the theme file generated from your settings to the new extension.
60+
61+
You can also use a existing TextMate theme by telling extension generator to import a TextMate theme file (.tmTheme) and package it for use in VS Code. Alternatively, if you have already downloaded the theme, replace the `tokenColors` section with a link to the `.tmTheme` file to use.
4862

4963
```json
5064
{
51-
"workbench.colorCustomizations": {
52-
"titleBar.activeBackground": "#ff0000"
65+
"type": "dark",
66+
"colors": {
67+
"editor.background": "#1e1e1e",
68+
"editor.foreground": "#d4d4d4",
69+
"editorIndentGuide.background": "#404040",
70+
"editorRuler.foreground": "#333333",
71+
"activityBarBadge.background": "#007acc",
72+
"sideBarTitle.foreground": "#bbbbbb"
5373
},
54-
"editor.tokenColorCustomizations": {
55-
"comments": "#FF0000"
56-
}
74+
"tokenColors": "./Diner.tmTheme"
5775
}
5876
```
5977

60-
![color-setting](./images/color-theme/color-setting.png)
78+
>**Tip:** Give your color definition file the `.color-theme.json` suffix and you will get hovers, code completion, color decorators and color pickers when editing.
79+
80+
>**Tip:** [ColorSublime](https://colorsublime.github.io) has hundreds of existing TextMate themes to choose from. Pick a theme you like and copy the Download link to use in the Yeoman generator or into your extension. It will be in a format like `"https://raw.githubusercontent.com/Colorsublime/Colorsublime-Themes/master/themes/(name).tmTheme"`
81+
82+
## Test a new Color Theme
83+
84+
To try out the new theme, copy the generated theme folder to a new folder under [your `.vscode/extensions` folder](/docs/extensions/yocode.md#your-extensions-folder) and restart VS Code.
85+
86+
Open the Color Theme picker theme with **File** > **Preferences** > **Color Theme** and you can see your theme in the drop-down list. Arrow up and down to see a live preview of your theme.
87+
88+
![select my theme](images/themes-snippets-colorizers/mytheme.png)
89+
90+
After making changes to any theme file, it is necessary to reload VS Code with `Reload Window`.
91+
92+
## Publishing a Theme to the Extension Marketplace
93+
94+
If you'd like to share your new theme with the community, you can publish it to the [Extension Marketplace](/docs/editor/extension-gallery.md). Use the [vsce publishing tool](/docs/extensions/publish-extension.md) to package your theme and publish it to the VS Code Marketplace.
95+
96+
> **Tip:** To make it easy for users to find your theme, include the word "theme" in the extension description and set the `Category` to `Theme` in your `package.json`.
97+
98+
We also have recommendations on how to make your extension look great on the VS Code Marketplace, see [Marketplace Presentation Tips](/docs/extensionAPI/extension-manifest.md#marketplace-presentation-tips).
99+
100+
## Adding a new Color Ids
101+
102+
Color ids can also be contributed by extensions through the [color contribution point](/docs/extensionAPI/extension-points.md#contributescolors). These colors also appear when using code complete in the `workbench.colorCustomizations` settings and the color theme definition file. Users can see what colors an extension defines in the [extension contributions](/docs/editor/extension-gallery.md#extensiondetails) tab.
103+
104+
## Further reading
105+
106+
- [CSS Tricks - Creating a VS Code theme](https://css-tricks.com/creating-a-vs-code-theme/)

0 commit comments

Comments
 (0)