Themes documentation IJSDK-491 (#143)

* Initial theme * JSON theme construction and integration with sdk project. Added theme documentation. * Added images and review feedback * Added internal mode and internal actions documentation * More feedback * Removed stub internal menu entries. * Reduced use of images, clarified IntelliJ Platform, IDE. * OlyaB feedback and compress images * Moved json file to resources folder * 19.1 -> 2019.1 * Strong note about availability of Custom UI Themes * Removed reference to UiDefaultsHardcodedKeys.java * Added IJSDK-567 content + cautioning UI Control keys may be deprecated. * Better SVG icons, clarify macOS scroll bar name attributes. * Generalize IntelliJ references, soften description of High Contrast scheme file as reference. * Updated custom color editor scheme descriptions. * Corrected position of editor scheme declaration.
2025-07-30 18:27:49 +08:00 · 2019-03-14 02:43:03 -07:00 · 2019-03-14 02:43:03 -07:00 · a29e9b4e51
commit a29e9b4e51
parent 3f92bbf2d5
28 changed files with 898 additions and 1 deletions
--- a/.idea/modules.xml
+++ b/.idea/modules.xml
@ -21,6 +21,7 @@
      <module fileurl="file://$PROJECT_DIR$/code_samples/register_actions/register_actions.iml" filepath="$PROJECT_DIR$/code_samples/register_actions/register_actions.iml" group="code_samples" />
      <module fileurl="file://$PROJECT_DIR$/code_samples/run_configuration/run_configuration.iml" filepath="$PROJECT_DIR$/code_samples/run_configuration/run_configuration.iml" group="code_samples" />
      <module fileurl="file://$PROJECT_DIR$/code_samples/simple_language_plugin/simple_language_plugin.iml" filepath="$PROJECT_DIR$/code_samples/simple_language_plugin/simple_language_plugin.iml" group="code_samples" />
+      <module fileurl="file://$PROJECT_DIR$/code_samples/theme_basics/theme_basics.iml" filepath="$PROJECT_DIR$/code_samples/theme_basics/theme_basics.iml" group="code_samples" />
      <module fileurl="file://$PROJECT_DIR$/code_samples/tool_window/tool_window.iml" filepath="$PROJECT_DIR$/code_samples/tool_window/tool_window.iml" group="code_samples" />
      <module fileurl="file://$PROJECT_DIR$/code_samples/tree_structure_provider/tree_structure_provider.iml" filepath="$PROJECT_DIR$/code_samples/tree_structure_provider/tree_structure_provider.iml" group="code_samples" />
    </modules>
--- a/.idea/runConfigurations/theme_basics.xml
+++ b/.idea/runConfigurations/theme_basics.xml
@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="theme_basics" type="#org.jetbrains.idea.devkit.run.PluginConfigurationType" factoryName="Plugin">
+    <module name="theme_basics" />
+    <option name="VM_PARAMETERS" value="-Xmx512m -Xms256m -ea" />
+    <option name="PROGRAM_PARAMETERS" value="" />
+    <log_file path="$USER_HOME$/.IntelliJIdea15/system/plugins-sandbox/system/log/idea.log" checked="false" skipped="true" show_all="false" alias="IDEA LOG" />
+    <method />
+  </configuration>
+</component>
+
--- a/_SUMMARY.md
+++ b/_SUMMARY.md
@ -9,7 +9,6 @@
    * [Contributing](CONTRIBUTING.md)
    * [Code of Conduct](CODE_OF_CONDUCT.md)
 * [Getting Help](intro/getting_help.md)
-* [Recently Updated](recently_updated.md)

 ## Part I - Plugins
 * [Introduction](basics.md)
@ -38,6 +37,12 @@
    * [Plugin Dependencies](basics/plugin_structure/plugin_dependencies.md)
 * [IntelliJ Platform Artifacts Repositories](reference_guide/intellij_artifacts.md)
 * [Kotlin for Plugin Developers](tutorials/kotlin.md)
+* [Internal Actions Menu](reference_guide/internal_actions/internal_actions_intro.md)
+    * [Enabling Internal Mode](reference_guide/internal_actions/enabling_internal.md)
+    * [Internal Actions](reference_guide/internal_actions/interal_actions_menu.md)
+    * [UI Tools](reference_guide/internal_actions/internal_ui_sub.md)
+    * [UI Inspector](reference_guide/internal_actions/internal_uii.md)
+    * [Laf Defaults](reference_guide/internal_actions/internal_ui_lafd.md)
 * [IDE Development Instances](basics/ide_development_instance.md)
 * [Plugin Development FAQ](faq.md)

@ -60,6 +65,10 @@
    * [Miscellaneous Swing Components](user_interface_components/misc_swing_components.md)
    * [Icons and Images](reference_guide/work_with_icons_and_images.md)
    * [Color Scheme Management](reference_guide/color_scheme_management.md)
+* [UI Themes](reference_guide/ui_themes/themes_intro.md)
+    * [Creating UI Themes](reference_guide/ui_themes/themes.md)
+    * [Customizing a UI Theme](reference_guide/ui_themes/themes_customize.md)
+    * [Adding Schemes and Images](reference_guide/ui_themes/themes_extras.md)
 * [Actions](basics/action_system.md)
    * [Actions Tutorial](tutorials/action_system.md)
        * [1. Registering an Action](tutorials/action_system/working_with_custom_actions.md)
--- a/appendix/resources/useful_links.md
+++ b/appendix/resources/useful_links.md
@ -19,6 +19,7 @@ The following links represent useful resources for working with the _IntelliJ Pl
 * [Gradle Plugin for Grammar-Kit](https://github.com/hurricup/gradle-grammar-kit-plugin)
 * [Gradle IntelliJ Plugin](https://github.com/JetBrains/gradle-intellij-plugin)
 * [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier)
+* [Internal Actions Menu](/reference_guide/internal_actions/internal_actions_intro.md)

 ### Help
 * [Community SDK Forum](https://intellij-support.jetbrains.com/hc/en-us/community/topics/200366979-IntelliJ-IDEA-Open-API-and-Plugin-Development)
--- a/code_samples/theme_basics/resources/Lightning.xml
+++ b/code_samples/theme_basics/resources/Lightning.xml
@ -0,0 +1,197 @@
+<scheme name="Lightning" version="142" parent_scheme="Default">
+  <metaInfo>
+    <property name="created">2019-01-22T02:54:51</property>
+    <property name="ide">idea</property>
+    <property name="ideVersion">2019.1.0.0</property>
+    <property name="modified">2019-01-22T02:55:20</property>
+    <property name="originalScheme">Lightning</property>
+  </metaInfo>
+  <colors>
+    <option name="CARET_ROW_COLOR" value="e8e3cf" />
+  </colors>
+  <attributes>
+    <option name="BAD_CHARACTER">
+      <value>
+        <option name="FOREGROUND" value="ff0000" />
+      </value>
+    </option>
+    <option name="CONSTRUCTOR_CALL_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="b5" />
+      </value>
+    </option>
+    <option name="DEFAULT_ATTRIBUTE">
+      <value>
+        <option name="FOREGROUND" value="b2" />
+        <option name="FONT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="DEFAULT_CLASS_NAME">
+      <value>
+        <option name="FOREGROUND" value="27c7e" />
+      </value>
+    </option>
+    <option name="DEFAULT_CONSTANT">
+      <value>
+        <option name="FOREGROUND" value="d101d9" />
+        <option name="FONT_TYPE" value="2" />
+      </value>
+    </option>
+    <option name="DEFAULT_DOC_MARKUP">
+      <value>
+        <option name="BACKGROUND" value="e6eae8" />
+      </value>
+    </option>
+    <option name="DEFAULT_ENTITY">
+      <value>
+        <option name="FOREGROUND" value="b2" />
+        <option name="FONT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="DEFAULT_FUNCTION_CALL">
+      <value>
+        <option name="FOREGROUND" value="2686a" />
+      </value>
+    </option>
+    <option name="DEFAULT_FUNCTION_DECLARATION">
+      <value>
+        <option name="FOREGROUND" value="27c7e" />
+      </value>
+    </option>
+    <option name="DEFAULT_GLOBAL_VARIABLE">
+      <value>
+        <option name="FOREGROUND" value="3c90" />
+        <option name="FONT_TYPE" value="2" />
+      </value>
+    </option>
+    <option name="DEFAULT_INSTANCE_FIELD">
+      <value>
+        <option name="FOREGROUND" value="2686a" />
+        <option name="FONT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="DEFAULT_INSTANCE_METHOD">
+      <value>
+        <option name="FOREGROUND" value="2686a" />
+      </value>
+    </option>
+    <option name="DEFAULT_INTERFACE_NAME">
+      <value>
+        <option name="FOREGROUND" value="27c7e" />
+      </value>
+    </option>
+    <option name="DEFAULT_INVALID_STRING_ESCAPE">
+      <value>
+        <option name="FOREGROUND" value="ff0000" />
+      </value>
+    </option>
+    <option name="DEFAULT_KEYWORD">
+      <value>
+        <option name="FOREGROUND" value="3504a8" />
+        <option name="FONT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="DEFAULT_LOCAL_VARIABLE">
+      <value>
+        <option name="FOREGROUND" value="69ff" />
+      </value>
+    </option>
+    <option name="DEFAULT_METADATA">
+      <value>
+        <option name="FOREGROUND" value="a09d6b" />
+        <option name="BACKGROUND" value="ffffff" />
+      </value>
+    </option>
+    <option name="DEFAULT_NUMBER">
+      <value>
+        <option name="FOREGROUND" value="46d8" />
+      </value>
+    </option>
+    <option name="DEFAULT_PARAMETER">
+      <value>
+        <option name="FOREGROUND" value="6c0063" />
+      </value>
+    </option>
+    <option name="DEFAULT_STATIC_FIELD">
+      <value>
+        <option name="FOREGROUND" value="2686a" />
+        <option name="FONT_TYPE" value="3" />
+      </value>
+    </option>
+    <option name="DEFAULT_STATIC_METHOD">
+      <value>
+        <option name="FOREGROUND" value="2686a" />
+        <option name="FONT_TYPE" value="2" />
+        <option name="EFFECT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="DEFAULT_STRING">
+      <value>
+        <option name="FOREGROUND" value="1a114" />
+      </value>
+    </option>
+    <option name="IMPLICIT_ANONYMOUS_CLASS_PARAMETER_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="27d7f" />
+      </value>
+    </option>
+    <option name="INHERITED_METHOD_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="b5" />
+        <option name="EFFECT_COLOR" value="b5" />
+        <option name="EFFECT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="INSTANCE_FINAL_FIELD_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="8f0197" />
+        <option name="FONT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="METHOD_CALL_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="b5" />
+      </value>
+    </option>
+    <option name="METHOD_DECLARATION_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="b5" />
+        <option name="FONT_TYPE" value="1" />
+      </value>
+    </option>
+    <option name="NOT_USED_ELEMENT_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="808080" />
+        <option name="BACKGROUND" value="ffffff" />
+      </value>
+    </option>
+    <option name="STATIC_FINAL_FIELD_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="d101d9" />
+        <option name="FONT_TYPE" value="2" />
+      </value>
+    </option>
+    <option name="STATIC_FINAL_FIELD_IMPORTED_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="d101d9" />
+        <option name="FONT_TYPE" value="2" />
+      </value>
+    </option>
+    <option name="TODO_DEFAULT_ATTRIBUTES">
+      <value>
+        <option name="FOREGROUND" value="ba7480" />
+        <option name="FONT_TYPE" value="2" />
+      </value>
+    </option>
+    <option name="UNMATCHED_BRACE_ATTRIBUTES">
+      <value>
+        <option name="BACKGROUND" value="ff8a8a" />
+      </value>
+    </option>
+    <option name="XML_ATTRIBUTE_VALUE">
+      <value>
+        <option name="FOREGROUND" value="17913" />
+      </value>
+    </option>
+  </attributes>
+</scheme>
--- a/code_samples/theme_basics/resources/META-INF/plugin.xml
+++ b/code_samples/theme_basics/resources/META-INF/plugin.xml
@ -0,0 +1,29 @@
+<idea-plugin>
+  <id>com.jetbrains.sdk.theme_basics</id>
+  <name>SDK Theme Basics</name>
+  <version>0.1</version>
+  <vendor email="support-email@company.com" url="https://blog.jetbrains.com/platform/">JetBrains Plugin Platform SDK</vendor>
+
+  <description><![CDATA[
+      IntelliJ Platform SDK code sample to illustrate creating <em>UI Themes</em>.
+    ]]></description>
+
+  <change-notes><![CDATA[
+      <ul>
+      <li>0.1   Initial release. Basic theme functionality.</li>
+      </ul>
+    ]]></change-notes>
+
+  <!-- please see http://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/build_number_ranges.html for description -->
+  <idea-version since-build="191"/>
+
+  <extensions defaultExtensionNs="com.intellij">
+    <!-- Add your extensions here -->
+    <themeProvider id="eb9b7461-397b-4b98-a422-224fc0a74564" path="/theme_basics.theme.json"/>
+  </extensions>
+
+  <actions>
+    <!-- Add your actions here -->
+  </actions>
+
+</idea-plugin>
--- a/code_samples/theme_basics/resources/austria.png
+++ b/code_samples/theme_basics/resources/austria.png
--- a/code_samples/theme_basics/resources/factory.svg
+++ b/code_samples/theme_basics/resources/factory.svg
@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+  <path fill="#59A869" fill-rule="evenodd" d="M0.346570397,0 L1.86281588,0 L2.16606498,6.45126354 L7.19133574,3.72202166 L7.23465704,6.32129964 L12,3.76534296 L12,12.732852 L0,12.732852 L0.346570397,0 Z M1.29963899,9.01083032 L3.59566787,9.01083032 L3.59566787,10.1805054 L1.29963899,10.1805054 L1.29963899,9.01083032 Z M8.40433213,9.01083032 L10.700361,9.01083032 L10.700361,10.1805054 L8.40433213,10.1805054 L8.40433213,9.01083032 Z M4.85198556,9.01083032 L7.14801444,9.01083032 L7.14801444,10.1805054 L4.85198556,10.1805054 L4.85198556,9.01083032 Z" transform="translate(2 1)"/>
+</svg>
--- a/code_samples/theme_basics/resources/run.svg
+++ b/code_samples/theme_basics/resources/run.svg
@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+  <path fill="#59A869" fill-rule="evenodd" d="M1.05797872,7.87468085 L3.13244681,8.34904255 L4.08117021,7.06425532 C4.11101931,7.02424037 4.29776351,7.06272099 4.3093617,7.1112766 C4.3901628,7.44837667 4.54193462,7.76427124 4.75444834,8.03791729 C4.75910662,8.04391559 4.76379409,8.04989359 4.76851064,8.05585106 L5.08521277,8.45829787 C5.15936902,8.55269144 5.15104446,8.68766821 5.06585106,8.77223404 L4.04797872,9.79010638 C3.85154522,10.0164653 3.54622284,10.1159345 3.25414894,10.0487234 L0.663829787,9.45542553 C0.439790528,9.40408421 0.247868589,9.26048158 0.135396305,9.06003331 C0.022924021,8.85958505 0.000370469744,8.62094917 0.0732978723,8.40297872 C0.219108322,8.00182808 0.643111393,7.77434328 1.05797872,7.87468085 Z M10.01,3.11308511 C10.8190284,3.29552137 11.623138,2.78893234 11.8078723,1.98042553 C11.9442449,1.38608398 11.7087705,0.768161188 11.2114456,0.415305333 C10.7141206,0.0624494777 10.0531006,0.0443026533 9.53716561,0.369341724 C9.02123057,0.694380795 8.75220905,1.29845378 8.85576815,1.89938212 C8.95932724,2.50031046 9.41502781,2.97949074 10.01,3.11308511 L10.01,3.11308511 Z M5.33414894,1.53095745 C5.09800864,1.45373939 4.83851405,1.51514244 4.66202128,1.69 L2.92223404,3.40765957 C2.66219564,3.65727179 2.63751721,4.06476682 2.86553191,4.34393617 C2.98682858,4.48379607 3.16063317,4.5671736 3.34562944,4.57424853 C3.53062571,4.58132346 3.71029064,4.51146389 3.84191489,4.3812766 L5.30510638,2.93744681 L6.5,3.56117021 L5.27606383,5.43095745 C4.87628798,6.10690516 4.93458382,6.95934435 5.42265957,7.57457447 L7.18457447,9.81914894 L5.94680851,12.5035106 C5.78247162,12.8401666 5.8615181,13.2449975 6.14042553,13.4951064 C6.24394169,13.5824459 6.36747748,13.6427883 6.5,13.6707447 C6.53100631,13.6777372 6.56241301,13.6828177 6.59404255,13.6859574 C6.94280338,13.7231385 7.27650583,13.5340405 7.42382979,13.2157447 L8.86904255,10.0459574 C8.99745704,9.77483175 8.96384424,9.45470981 8.78191489,9.21617021 L7.66446809,7.11819149 L8.69893617,5.3106383 L9.22031915,6.37829787 C9.29974458,6.58837535 9.47961766,6.74433466 9.69882979,6.79319149 L9.76244681,6.80425532 L12.2130851,7.12234043 C12.3946311,7.1498745 12.5793783,7.09967145 12.7220213,6.98404255 C12.8654228,6.86856715 12.9545513,6.69882244 12.9681915,6.51521277 C12.9850198,6.15113242 12.7163684,5.83649566 12.3541489,5.79606383 L10.333617,5.53191489 L9.77351064,4.14893617 C9.64526878,3.83182905 9.42639558,3.55956042 9.14425532,3.36617021 C8.03467166,2.60468769 6.82012223,2.00882703 5.53882979,1.59734043 L5.33414894,1.53095745 Z" transform="translate(1 1)"/>
+</svg>
--- a/code_samples/theme_basics/resources/theme_basics.theme.json
+++ b/code_samples/theme_basics/resources/theme_basics.theme.json
@ -0,0 +1,54 @@
+{
+  "name": "theme_basics",
+  "dark": false,
+  "author": "IntelliJ Platform SDK",
+
+  "ui": {
+    "*": {
+      "background": "#FFFFFF",
+      "foreground": "#0C5800",
+      "selectionBackground": "#AED7E3",
+      "selectionForeground": "#032294",
+      "selectionInactiveBackground": "#BBE7F4",
+      "selectionBackgroundInactive": "#BBE7F4"
+    },
+
+    "Label.foreground": "#3959CC",
+    "Label.background": "#F6E9C9",
+
+    "Panel.background": "#E1E1E1",
+
+    "Window.border" : "4,4,4,4,E6E6E6"
+  },
+
+  "icons": {
+    "/actions/compile.svg": "/factory.svg",
+    "/actions/execute.svg": "/run.svg",
+
+    "ColorPalette": {
+      "Actions.Blue": "#5BC0DE",
+      "Actions.Red": "#D9534F",
+      "Actions.Yellow": "#FFEEAD",
+      "Actions.Grey": "#354E5A",
+
+      "Objects.Blue": "#5BC0DE",
+      "Objects.Red": "#D9534F",
+      "Objects.Yellow": "#FFEEAD",
+      "Objects.Purple": "#BA7FBA",
+      "Objects.Pink": "#FFC5E8",
+      "Objects.Grey": "#4694AE",
+      "Objects.BlackText": "#0C5800",
+
+      "#59A869": "#00C5C0FF"
+    }
+  },
+
+  "editorScheme": "/Lightning.xml",
+
+  "background": {
+    "image": "/austria.png",
+    "transparency": 10,
+    "fill": "scale",
+    "anchor": "center"
+  }
+}
--- a/code_samples/theme_basics/theme_basics.iml
+++ b/code_samples/theme_basics/theme_basics.iml
@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PLUGIN_MODULE" version="4">
+  <component name="DevKit.ModuleBuildProperties" url="file://$MODULE_DIR$/resources/META-INF/plugin.xml" />
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/resources" type="java-resource" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>
--- a/reference_guide/internal_actions/enabling_internal.md
+++ b/reference_guide/internal_actions/enabling_internal.md
@ -0,0 +1,21 @@
+---
+title: Enabling Internal Mode
+---
+
+There are useful tools, such as the Internal Actions menu, that are only visible if internal mode is enabled in IntelliJ IDEA.
+
+## Setting Internal Mode in the IDE Properties File
+There are multiple ways to enable internal mode, but the simplest is within IntelliJ IDEA:
+* Start IntelliJ IDEA.
+* From the main menu, select **Help | Edit Custom Properties**.
+This selection opens IntelliJ IDEA's `idea.properties` file.
+If it does not exist, IntelliJ IDEA will prompt to create one.
+* Add the line shown below to the `idea.properties` file:
+```
+idea.is.internal=true
+```
+* Save the `idea.properties` file and restart IntelliJ IDEA.
+
+The Internal Actions menu is available in **Tools \| Internal Actions**.
+
+
--- a/reference_guide/internal_actions/img/internal_lafd_win.png
+++ b/reference_guide/internal_actions/img/internal_lafd_win.png
--- a/reference_guide/internal_actions/img/internal_uii_icon_info.png
+++ b/reference_guide/internal_actions/img/internal_uii_icon_info.png
--- a/reference_guide/internal_actions/interal_actions_menu.md
+++ b/reference_guide/internal_actions/interal_actions_menu.md
@ -0,0 +1,11 @@
+---
+title: Internal Actions Menu
+---
+
+The Internal Actions menu provides JetBrains IDE plugin developers with a suite of tools to help develop, debug, and test their IntelliJ Platform project.
+
+If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [enable internal mode](enabling_internal.md)
+
+## The Tools Available on the Internal Actions Menu
+
+* [UI submenu](internal_ui_sub.md)
--- a/reference_guide/internal_actions/internal_actions_intro.md
+++ b/reference_guide/internal_actions/internal_actions_intro.md
@ -0,0 +1,11 @@
+---
+title: Internal Actions Menu
+---
+
+The Internal Actions menu provides JetBrains IDE plugin developers with a suite of tools to help develop, debug, and test their IntelliJ Platform project.
+
+Click on the following topics to learn more about the _Internal Actions_ menu.
+* [Enabling Internal Mode](enabling_internal.md) in IntelliJ IDEA.
+* [The Internal Actions Menu](interal_actions_menu.md)
+* [The UI Inspector](internal_uii.md)
+* [The LaF Defaults Tool](internal_ui_lafd.md)
--- a/reference_guide/internal_actions/internal_ui_lafd.md
+++ b/reference_guide/internal_actions/internal_ui_lafd.md
@ -0,0 +1,35 @@
+---
+title: Internal Actions - LaF Defaults
+---
+
+The _LaF Defaults_ window provides a key-value pair lookup for UI Controls.
+It also allows interactive prototyping of UI Control color changes. 
+
+If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [enable internal mode](enabling_internal.md)
+
+## Opening LaF Defaults
+The _LaF Defaults_ window is opened by selecting the menu item **Tools \| Internal Actions \| UI \| LaF Defaults**.
+
+The _LaF Defaults_ window has two columns representing key-value pairs for UI Controls: 
+* The _Name_ column contains the UI Control `key` for each IntelliJ Platform UI element available at runtime.
+* The _Value_ column contains the UI Control color `value` for each IntelliJ Platform UI element. 
+
+## Using the the LaF Panel
+
+### Finding UI Controls 
+The _LaF Defaults_ window is used interactively by entering a UI element type - e.g. `Panel` - in the _Filter_ text box at the top.
+_LaF Defaults_ shows the list of UI Control names matching the filter.
+Clicking on one of the names narrows the information to show only the key-value pair for that UI element: 
+
+![LaF Lookup](img/internal_lafd_win.png)
+
+### Prototyping the Color of UI Controls
+The color of UI Controls can be changed (in real time) by clicking in the _Value_ column next to a _Name_ (`key`) of interest.
+The _Choose Color_ window is displayed.
+Color changes can be specified as RGB, hexadecimal, or using the color picker.
+Pressing the _Choose_ button changes the UI Control color immediately.
+
+UI Control colors can be reset using the _Choose Color_ window, or by resetting the [UI Theme](https://www.jetbrains.com/help/idea/settings-appearance.html). 
+
+ 
+
--- a/reference_guide/internal_actions/internal_ui_sub.md
+++ b/reference_guide/internal_actions/internal_ui_sub.md
@ -0,0 +1,12 @@
+---
+title: Internal Actions - UI Submenu
+---
+
+The Internal Actions UI submenu provides IntelliJ Platform plugin developers with a suite of tools to help develop, debug, and test their IntelliJ Platform project UI.
+
+If the menu item **Tools \| Internal Actions \| UI** is not available in IntelliJ IDEA, then the first step is to [enable internal mode](enabling_internal.md)
+
+## The Tools Available on the UI Submenu
+
+* [UI Inspector](internal_uii.md)
+* [LaF Defaults](internal_ui_lafd.md)
--- a/reference_guide/internal_actions/internal_uii.md
+++ b/reference_guide/internal_actions/internal_uii.md
@ -0,0 +1,23 @@
+---
+title: Internal Actions - UI Inspector
+---
+
+The _UI Inspector_ is a tool to interrogate elements of the IntelliJ IDEA UI to get an internal description of each element.
+UI elements can be tested interactively by clicking on the element while the _UI Inspector_ is enabled.
+
+If the menu item **Tools \| Internal Actions \| UI \| UI Inspector** is not available in IntelliJ IDEA, then the first step is to [enable internal mode](enabling_internal.md)
+
+## Enabling the UI Inspector
+Before using the _UI Inspector_, it must be enabled by selecting the menu item **Tools \| Internal Actions \| UI \| UI Inspector**.
+The enabled state of the _UI Inspector_ is modal; it remains enabled until it is disabled by selecting the _UI Inspector_ menu item again. 
+
+When enabled, the _UI Inspector_ menu entry displays a check mark.
+
+## Using the UI Inspector
+While enabled, centering the cursor on a UI element and pressing _control-alt_ when _clicking_ the mouse reveals the internal description of the UI element.
+
+For example, to get information about the build (hammer) icon on the toolbar, put the cursor on the icon and press _control-alt_ while clicking the mouse.
+The _UI Inspector_ displays that the icon has the internal path `Allcons.Actions.Compile`:
+
+![Internal Icon Info](img/internal_uii_icon_info.png)
+
--- a/reference_guide/ui_themes/img/devkit_wiz_action.png
+++ b/reference_guide/ui_themes/img/devkit_wiz_action.png
--- a/reference_guide/ui_themes/img/devkit_wiz_dialog.png
+++ b/reference_guide/ui_themes/img/devkit_wiz_dialog.png
--- a/reference_guide/ui_themes/img/theme_colorpalette_popup.png
+++ b/reference_guide/ui_themes/img/theme_colorpalette_popup.png
--- a/reference_guide/ui_themes/img/theme_components.png
+++ b/reference_guide/ui_themes/img/theme_components.png
--- a/reference_guide/ui_themes/img/uit_control_complete.png
+++ b/reference_guide/ui_themes/img/uit_control_complete.png
--- a/reference_guide/ui_themes/themes.md
+++ b/reference_guide/ui_themes/themes.md
@ -0,0 +1,102 @@
+---
+title: Creating Custom UI Themes
+---
+
+Creating a custom UI Theme is a process of choosing a base IDE Theme (_Light_ or _Darcula_,) then changing aspects of the base Theme definition. 
+Custom UI Themes can:
+* substitute icons,
+* change the colors of icons and UI controls,
+* alter the borders and insets of UI controls,
+* provide custom editor schemes,
+* add background images.
+
+## The Structure of a UI Theme
+UI Themes are components within IntelliJ Platform plugins. 
+Theme plugins should be stand-alone plugins, and not combined with other plugin functionality. 
+This approach is the best user experience because it avoids an IDE restart when installing a UI Theme plugin.
+
+UI Themes have several components:
+* A required Theme description (JSON) file in the plugin project's `resources` folder. 
+* A required `themeProvider` declaration in the plugin's `plugin.xml` file, located in the plugin project's `META-INF` folder.
+* An optional Editor Scheme description (XML) file derived from an exported IDE editor scheme. 
+  This file is located in the plugin project's `resources` folder.
+* An optional background image file, located in the plugin project's `resources` folder.
+* Optional icon image files, located in the plugin project's `resources` folder.  
+
+![UI Theme Components](img/theme_components.png)
+
+## Custom UI Theme Workflow
+Creating a UI Theme follows this general sequence:
+* [Start with a Plugin Project](/basics/getting_started/creating_plugin_project.md)
+* [Add UI Theme components to the plugin](#creating-a-ui-theme-with-the-devkit-theme-wizard) by using the DevKit UI Theme Wizard.
+* [Customize the UI Theme](themes_customize.md) by adding data objects to the Theme description (JSON) file.
+* [Add an Editor Scheme or Background Image](themes_extras.md) to the plugin.
+* [Build and test](/basics/getting_started/running_and_debugging_a_plugin.md) the UI Theme plugin.
+* [Deploy the UI Theme plugin](/basics/getting_started/deploying_plugin.md)
+* [Publish the UI Theme plugin](/basics/getting_started/publishing_plugin.md) 
+
+
+## Creating Custom UI Themes
+
+A UI Theme is added to an IntelliJ Platform plugin using the DevKit UI Theme Wizard.
+
+### Creating a UI Theme with the DevKit Theme Wizard
+The DevKit Wizard is part of the DevKit plugin, which is bundled with IntelliJ IDEA. 
+This Wizard can be used for both DevKit-based and Gradle-based plugins.
+
+While a plugin project is open in IntelliJ IDEA, select the `resources` folder in the _Project_ tool window.
+From the main menu, select the _**New | Plugin DevKit | Theme**_ action. 
+
+![DevKit Wizard Action](img/devkit_wiz_action.png)
+
+<br>
+
+The Wizard then prompts for the name of the new Theme, and the basis for the Theme:
+
+![DevKit Dialog](img/devkit_wiz_dialog.png)
+
+The best practice is to name the new Theme the same as the name of the plugin. 
+The checkbox indicates the basis for the Theme. 
+Checking _Dark theme_ means basing the custom Theme on _Darcula_. 
+Leaving the box unchecked means basing the custom Theme on the default IntelliJ IDEA _Light_ Theme. 
+For the SDK code sample `theme_basics` the box is _unchecked_.
+
+Clicking the _OK_ button creates a default Theme description file named `[themeName].theme.json` in the plugin project's `resources` folder. 
+In this example, the file is named `theme_basics.theme.json`. 
+The content of the default file is a short set of key–value pairs:  
+```json
+{
+ "name": "theme_basics",
+ "dark": false,
+ "author": "",
+ "editorScheme": "/theme_basics.xml",
+ "ui": {
+ }
+}
+```
+
+The `value` of the `name` key matches the first portion of the Theme description `[themeName].theme.json` file name. 
+The `value` of `name` is displayed in the [Theme](https://www.jetbrains.com/help/idea/settings-appearance.html)  _Preferences_ dropdown when the UI Theme's plugin is installed in the IDE. 
+The value of the `author` key is by default empty.
+The `editorScheme` section will be addressed in [Adding a Custom Editor Scheme](themes_extras.md#adding-a-custom-editor-scheme) 
+The `ui` section will be addressed in [Customizing UI Control Colors](themes_customize.md#customizing-ui-controls). 
+
+The Wizard also creates a `themeProvider` declaration in the `<extensions>` section of the plugin's `plugin.xml` file. 
+This declaration binds the Theme description file to a theme provider extension `id`.
+```xml
+  <extensions defaultExtensionNs="com.intellij">
+    <themeProvider id="eb9b7461-397b-4b98-a422-224fc0a74564" path="/theme_basics.theme.json"/>
+  </extensions>
+```
+> **WARNING** Do not change the value of the `themeProvider` `id` attribute.
+
+At this point, the UI Theme `theme_basics` is a valid UI Theme. 
+Its plugin can be built and tested in IntelliJ Platform-based IDEs, giving the user the opportunity to select _theme_basics_ in the [Theme](https://www.jetbrains.com/help/idea/settings-appearance.html) _Preferences_ dropdown. 
+The custom Theme looks exactly like the IntelliJ IDEA default `Light` Theme, but it is a valid custom Theme.
+
+### Completing the Default UI Theme Description File
+The default UI Theme definition can be directly edited to add or change some of the values for the default keys, if desired:
+The following values can be changed directly in the Theme (`*.theme.json`) description file:
+* The value of the `dark` key can be changed to `true`, which would switch the basis of the Theme to _Darcula_ instead of _Light_.
+* The value of the `author` key, which defaults to an empty string, can be set to a `String` literal. 
+In the case of the `theme_basics` code sample, it is set to "IntelliJ Platform SDK".
--- a/reference_guide/ui_themes/themes_customize.md
+++ b/reference_guide/ui_themes/themes_customize.md
@ -0,0 +1,192 @@
+---
+title: Customizing UI Themes - Icons and UI Controls
+---
+A UI Theme is customized by adding information to the UI Theme description file that overrides the base (_Light_ or _Darcula_) UI Theme. 
+
+## Introduction to UI Theme Description File Syntax
+The syntax of a Theme description file follows the JSON open-standard file format of key-value pairs. 
+The minimum valid default file is the output of the [DevKit Theme Wizard](themes.md#creating-a-ui-theme-with-the-devkit-theme-wizard). 
+Adding key-value pairs customizes a Theme.
+
+UI Theme key-value pairs often use a color as the `value`.
+Colors are defined by six-digit RGB or eight-digit RGBA hexadecimal notation.
+
+### UI Theme Reference Implementations
+When learning new syntax, it is often useful to have some existing implementations for reference.
+For example, refer to the [Theme description file](upsource:///platform/platform-resources/src/themes/HighContrast.theme.json) for the IntelliJ IDEA _High Contrast_ Theme.
+
+## Customizing Icons
+UI themes can customize the color of default IntelliJ IDEA UI icons, or substitute custom icons for the default ones. 
+Customization is done by adding an `"icons": {}` section to the Theme description file.
+
+### Overriding the Global Color of Icons
+Default global icon colors are customized by adding key-value pairs to a `"ColorPalette": {}` section. 
+The `ColorPalette` must be inserted in the `icons` section.
+
+In the following example the `key` - the default red color (#DB5860) used for `Action` icons in the _Light_ Theme - is overridden to the `value` of a different color (#D61A26):
+```json
+{
+  "name": "Theme Basics",
+  "dark": false,
+  "author": "IntelliJ Platform SDK",
+  "editorScheme": "/theme_basics.xml",
+  "ui": {
+  },
+  "icons": {
+    "ColorPalette": {
+      "#DB5860": "#D61A26"
+    }
+  }
+}
+```  
+This color substitution is applied throughout the IDE UI.
+
+### Custom Icon Palette Colors
+Icon Palettes are predefined UI Theme color keys, each describing a single color in an `Actions` or `Objects` context. 
+
+#### Icon Colors in "Actions" and "Objects" Contexts
+IntelliJ IDEA has default icon colors defined for `Actions` and `Objects` contexts. 
+* `Actions` are Theme keys for icons that appear in the context of toolbars, and represent actions such as _Compile_, _Run_, or _Debug_. 
+* `Objects` are Theme keys for icons that appear in the contexts of lists and trees, and represent entities like files, symbols, or run and debug configurations.
+
+The [JetBrains Platform UI Guideline for Icons](https://jetbrains.github.io/ui/principles/icons/)
+defines the default hexadecimal RGB values of colors for `Actions` and `Objects` keys. 
+Note that this document refers to `Objects` keys as "Noun icons."
+
+#### Customizing "Actions" and "Objects" Icon Colors
+An icon Palette color is customized by adding an `Actions` or `Objects` `key` and custom color `value` to the `"ColorPalette": {}` section in a Theme description file.
+The list of available icon `Actions` and `Objects` keys are provided by the completion popup in the editor:
+
+<img src="img/theme_colorpalette_popup.png" alt="Color Palette Popup" width="600px"/>
+
+For example, the following key-value pair changes the color for  all blue-colored icons on toolbars to the color #5BC0DE:
+```json
+{
+  "icons": {
+    "ColorPalette": {
+      "Actions.Blue": "#5BC0DE"
+    }
+  }
+}
+```
+This more specific change to the `Actions.Blue` color overrides the default definition. 
+It will also, in the narrower context of blue `Actions` icons, supersede any global color overrides of the default blue icon color.
+
+### Custom Icons
+The default IntelliJ IDEA UI icons can be replaced by custom icons. 
+The file format for icons is SVG. 
+The [JetBrains Platform UI Guideline for Icons](https://jetbrains.github.io/ui/principles/icons/) has detailed specifications for icons. 
+
+An icon replacement is described within the `icon {}` section of a Theme description file. 
+Note that icon replacement key-value pairs appear outside of the `ColorPalette` section. 
+
+For icon substitutions, the `key` is the path to the default icon image.
+This path is derived from the `AllIcons.[Group].[IconName]` path in icon section reported by the [UI Inspector](/reference_guide/internal_actions/internal_uii.md).  
+
+For example, the _Build_ (hammer) icon in the toolbar has the path `Allcons.Actions.Compile` as reported by the UI Inspector. 
+Therefore the `key` for the _Build_ icon is `/actions/compile.svg`. 
+The `value` is the file name of the replacement icon, located in the `resources` folder of the UI Theme plugin project:
+```json
+{
+  "icons": {
+    "/actions/compile.svg": "/factory.svg"
+  }
+}
+```
+The color of a replaced icon takes precedence over any `ColorPalette` overrides.
+
+## Customizing UI Controls
+UI Themes can change the appearance of more general controls in the IntelliJ IDEA UI. 
+Examples of these controls are labels, buttons, checkboxes, trees, lists, and menus.
+
+### Custom UI Control Colors
+The custom color of a UI control is specified by adding a key-value pair to the `"ui": {}` section of a Theme description file.  
+
+A UI control `key` has the compound format `element.property`, where:
+* `element` is the type (label, checkbox, etc.,) of the UI control.
+* `property` is how the color is applied. Examples include `foreground`, `background`, and `errorForeground `.
+
+Note that some UI control keys have more than two parts, for example `Popup.Advertiser.foreground` or `ScrollBar.Mac.Transparent.thumbColor`.
+The full key must be used to customize that specific button control.
+However, for other purposes the first section can be considered the `element`, and the last section considered the `property`.
+
+Methods for finding UI control keys are in the [Finding Attribute Keys for UI Controls](#finding-attribute-keys-for-ui-controls) section. 
+
+#### Customizing All UI Control Colors with the Same Property
+All UI Controls that have the same `property` portion of their key can be set to the same color. 
+This customization is done using the wildcard `"*": {}` section in the Theme description file. 
+A key-value pair is inserted in this section, but only the `property` portion of the key is specified. 
+The `value` is the custom color. 
+
+The following example would change the default background color to #AED7E3 for all UI controls:
+```json
+{
+  "ui": {
+    "*": {
+      "background": "#AED7E3"
+     }
+  }
+}
+```
+Note that the wildcard `"*": {}` section must be within the `"ui": {}` section.
+
+
+#### Customizing the Color of Specific UI Control Types
+The color of a specific UI control types are changed by adding a key-value pair to the `"ui": {}` section of a Theme description file. 
+The `key` is the full `element.property` format and the `value` is the custom color.
+  
+The following example sets the background color for all labels to the color #F6E9C9
+```json
+{
+  "ui": {
+    "*": {
+      "background": "#AED7E3"
+     },
+    "Label.background": "#F6E9C9"
+  }
+}
+```
+The `Label.background` entry supersedes, in the narrower context of label backgrounds, any default color as well as any wildcard color assigned to backgrounds.
+
+### Customizing the Borders of UI Controls
+The color and geometry of borders used in UI controls can be customized by key-value pairs in a Theme description file. 
+The format of keys for borders is `element.property`, where:
+* `element` is the type of UI control containing a border, such as a window or a popup menu. 
+* `property` is the desired border appearance, for example:
+  * `border` is the border width (in pixels) specified as top, left, bottom, and right widths.
+  Border color is also (optionally) specified as hexadecimal RGB, e.g. "E6E6E6" with no "#" character.
+  * `borderInsets` is the inset distance (in pixels) from the edge of the `element` to the border. 
+  It is specified as top, left, bottom, and right insets.  
+
+Methods for identifying UI control keys are in the [Finding Attribute Keys for UI Controls](#finding-attribute-keys-for-ui-controls) section. 
+
+
+#### Customizing the Border Appearance of Specific UI Controls
+The appearance of borders for specific UI control types are customized by adding a key-value pair to the `"ui": {}` section of a Theme description file. 
+
+The following example sets a new border width and color for all windows:
+```json
+{
+  "ui": {
+    "Window.border" : "4, 4, 4, 4, E6E6E6"
+  }
+}
+```
+In this example the customized border supersedes the default definition and 
+any global color override.
+
+## Finding Attribute Keys for UI Controls
+There are hundreds of UI control `element.property` keys defined in the IntelliJ Platform UI. 
+Some keys and strategies for applying them can be gleaned from the [UI Theme reference implementations](#UI-Theme-Reference-Implementations). 
+For a general search, here some suggested methods for locating UI control keys.
+
+### Finding a UI Control Key Using Code Completion in the Editor
+The preferred method of finding UI control keys is to use the code completion feature in the IntelliJ IDEA editor. 
+Note that some keys presented by the code completion feature may be deprecated. 
+New entries in the `"ui": {}` section will invoke the code completion popup, as shown below:
+
+![UI Control Key Code Completion](img/uit_control_complete.png)
+
+### Finding a UI Control Key using Laf Defaults UI
+Using the [Laf Defaults](/reference_guide/internal_actions/internal_ui_lafd.md) inspector, enter the `element` portion of the key. 
+The Laf Defaults inspector will prompt with a list of UI Control keys and their default color.
--- a/reference_guide/ui_themes/themes_extras.md
+++ b/reference_guide/ui_themes/themes_extras.md
@ -0,0 +1,155 @@
+---
+title: UI Themes - Editor Schemes and Background Images
+---
+
+UI Themes can also provide custom color and font settings, as well as custom images for display in the IntelliJ IDEA application window.
+ 
+## Adding a Custom Editor Scheme
+Users of IntelliJ Platform-based IDEs, such as Intellij IDEA, can set preferences to configure the colors and fonts used in the Editor. 
+These custom color and font settings are called _Editor Color Schemes_.
+
+### Creating a Custom Editor Scheme Using Settings/Preferences
+Custom editor color schemes can be specified and exported using the IDE _Settings/Preferences_ dialog.
+Note that editor [Colors and Fonts](https://www.jetbrains.com/help/idea/configuring-colors-and-fonts.html), and [Colors for Version Control File Status](https://www.jetbrains.com/help/idea/file-status-highlights.html) are customized in different sections of _Settings/Preferences_.
+
+Use the following procedure to customize an editor color scheme for a UI Theme: 
+* Create the desired custom editor color scheme using the IDE preferences. 
+* Export the custom editor color scheme to the desired file name.
+  In this example, the file is exported to `Lightning.icls`
+* Once exported, change the file extension from `*.icls` to `*.xml`.
+  In this example, the result is `Lightning.xml`.
+* See [Customizing Editor Scroll Bar Colors](#customizing-editor-scroll-bar-colors) to change the colors of editor scroll bars. 
+
+### Incorporating the Editor Color Scheme in the Custom UI Theme
+The next step is to add the color scheme to the UI Theme plugin project:
+* Replace the default generated custom editor color scheme XML file (in this example `theme_basics.xml`) in the `resources` folder with the exported custom editor color scheme.
+  In this case, the action is to _replace_ `theme_basics.xml` with `Lightning.xml`.
+* In the UI Theme file (in this example `theme_basics.theme.json`,) replace the name of the generated editor scheme file (`theme_basics.xml`) with the new (`Lightning.xml`) file name.
+  The `key` is always "editorScheme".
+  The `value` is the name of the editor color scheme file.
+
+The example below adds an editor scheme named "Lightning" to the _Theme Basics_ custom UI Theme:
+```json
+{
+  "name": "Theme Basics",
+  "dark": false,
+  "author": "IntelliJ Platform SDK",
+  "editorScheme": "/Lightning.xml",
+  "ui": {
+  }
+}
+```
+
+### Editor Color Scheme XML Files
+When an editor color scheme is exported as a file, the color options appear as `name`-`value` attributes of `option` elements.
+The `name` is the aspect of the editor to be changed, and the `value` is the new color in six-digit RGB or eight-digit RGBA hexadecimal notation.
+For example, the snippet below sets the color of the line numbers displayed in the editor:
+```xml
+<colors>
+  <option name="LINE_NUMBERS_COLOR" value="999999" />
+</colors>
+```
+For additional examples of `name` and `value` attributes, review the editor color scheme XML file for the [High Contrast editor scheme](upsource:///platform/platform-resources/src/themes/highContrastScheme.xml).
+
+### Customizing Version Control File Status Colors
+As [described above](#creating-a-custom-editor-scheme-using-settingspreferences), colors corresponding to the VCS status of files can be customized and exported via the [IntelliJ IDEA Preferences/Settings](https://www.jetbrains.com/help/idea/file-status-highlights.html).
+No other procedure is necessary to customize these colors.
+In the exported color scheme file the `name` is the VCS file status, and the `value` is the new color corresponding to that status.
+For example, customized VCS colors for a subset of file statuses will appear in the editor scheme file as:
+```xml
+<colors>
+  <option name="FILESTATUS_ADDED" value="62cc47" />
+  <option name="FILESTATUS_COPIED" value="62cc47" />
+  <option name="FILESTATUS_DELETED" value="ed864a" />
+</colors>
+
+```
+For additional examples of `FILESTATUS` color `name` attributes, see the editor color scheme XML file for the [High Contrast editor scheme](upsource:///platform/platform-resources/src/themes/highContrastScheme.xml).
+
+### Customizing Editor Scroll Bar Colors
+Editor scroll bar colors should be coordinated with, and switch together with an editor color scheme.
+Please note that Custom UI Theme (`*.theme.json`) files also contain `ScrollBar.*` name attributes, but these are for scroll bars outside the context of the editor.
+
+>**Note** The Editor Scroll Bar colors are the only editor scheme settings that cannot be customized and exported through IDE preferences.
+
+Customizing the editor scroll bar colors requires manually changing an editor color scheme XML file.
+At this time there isn't code completion functionality for changing custom color editor scheme XML files, so the `name` attributes are described below.
+
+#### Editor Scroll Bar Attribute Name Format
+The typical format of a scroll bar `name` attribute is `ScrollBar.usage`, where `usage` describes where the color is to be applied.
+In some cases `usage` itself can be compound such as `ScrollBar.Mac.Transparent.thumbColor`. 
+In these compound cases, the last portion of the compound `usage` still describes where the color is to be applied.
+
+Note that the following example snippet uses an eight-digit hexadecimal color `value` to give `ScrollBar.Mac.thumbColor` transparency:
+```xml
+<color>
+<option name="ScrollBar.background" value="000000"/>
+<option name="ScrollBar.Mac.trackColor" value="000000"/>
+<option name="ScrollBar.Mac.thumbColor" value="FFFFFFBE"/>
+</color>
+```
+
+#### Editor Scroll Bar Attribute Names
+A list of scroll bar `name` attributes is in the [High Contrast editor scheme](upsource:///platform/platform-resources/src/themes/highContrastScheme.xml) file. 
+These name attributes cannot be accessed from anywhere in the IDE UI at this time, so they must be manually added to an editor color scheme XML file.
+
+The following list explains the `usage` format of the `name` attribute, i.e. where a custom scroll bar color is applied:
+* `*.trackColor` — The scroll bar thumb moves across this area.
+* `*.thumbColor` — The movable rectangle that corresponds to the visible content's size.
+* `*.thumbBorderColor` — The thumb border.
+* `*.hoverTrackColor` — Same `usage` as above but for hover.
+* `*.hoverThumbColor` — Same `usage` as above but for hover.
+* `*.hoverThumbBorderColor` — Same `usage` as above but for hover.
+
+The `name` attribute patterns are enumerated below. 
+
+**Platform Independent Name Attributes**
+
+`ScrollBar.background` sets the background color for the horizontal scroll bar. 
+This background color is visible only if the horizontal scroll bar's `*.trackColor` has transparency.
+
+**Windows/Linux Name Attributes** 
+
+The `name` attributes for Windows and Linux have the pattern `ScrollBar.Transparent.*`, where the wildcard portion corresponds to the `usage` definitions above.
+
+**macOS Name Attributes** 
+
+The `name` attribute pattern for the vertical scroll bar is `ScrollBar.Mac.*`.
+
+The `name` attribute pattern for the horizontal scroll bar depends on the macOS preferences _Show scroll bars_ setting:
+  * `ScrollBar.Mac.*` when the _Always_ setting is selected.
+  * `ScrollBar.Mac.Transparent.*` when the _When scrolling_ setting is selected.
+
+The wildcard portion of these patterns corresponds to the `usage` definitions above.
+
+
+## Adding a Custom Background Image
+The IDE supports setting an image as a background in the application window. 
+Users can do this manually in [Preferences](https://www.jetbrains.com/help/idea/setting-background-image.html).
+
+UI Themes support specifying a background image as a key-value pair in the `"background": {}` section of a Theme description file:
+* The `image` key uses the file name of the image as the value.
+The background image is placed in the UI Theme plugin project's resources folder. 
+* The `transparency` key uses a `value` of 1-100. 
+A `value` of 100 is opaque.
+* The `fill` key uses a value of `scale`, meaning to expand the image to fill the space as the window gets resized.
+* The `anchor` key uses a value of `center`, meaning to locate the center of the image in the center of the window. 
+
+
+The following example adds an image of the Austrian countryside to the _Theme Basics_
+Theme description file:
+```json
+{
+  "name": "Theme Basics",
+  "dark": false,
+  "author": "IntelliJ Platform SDK",
+  "ui": {
+  },
+  "background": {
+    "image": "/austria.png",
+    "transparency": 10,
+    "fill": "scale",
+    "anchor": "center"
+  }
+}
+```
--- a/reference_guide/ui_themes/themes_intro.md
+++ b/reference_guide/ui_themes/themes_intro.md
@ -0,0 +1,14 @@
+---
+title: Custom UI Themes
+---
+
+Beginning with the 2019.1 release, custom UI Themes are supported by IntelliJ IDEA.
+Custom UI Themes give designers control of the appearance of built-in IntelliJ IDEA UI elements. 
+[Creating a new UI element](/user_interface_components/user_interface_components.md) for a plugin is distinctly different than Custom UI Themes. 
+
+> **note** Custom UI Themes are available beginning in version **2019.1**.
+
+This section discusses creating and customizing UI Themes:
+* [Creating UI Themes](themes.md)
+* [Customizing UI Themes](themes_customize.md)
+* [Adding Editor Schemes and Background Images](themes_extras.md)