Merge pull request #200 from JohnHake/IJSDK-662

IJSDK-662

_SUMMARY.md

@@ -38,7 +38,7 @@
     * [Plugin Extensions and Extension Points](basics/plugin_structure/plugin_extensions_and_extension_points.md)
     * [Plugin Actions](basics/plugin_structure/plugin_actions.md)
     * [Plugin Configuration File](basics/plugin_structure/plugin_configuration_file.md)
-    * [Plugin Icon](basics/plugin_structure/plugin_icon_file.md)
+    * [Plugin Logo (Icon)](basics/plugin_structure/plugin_icon_file.md)
     * [Plugin Dependencies](basics/plugin_structure/plugin_dependencies.md)
 * [IntelliJ Platform Artifacts Repositories](reference_guide/intellij_artifacts.md)
 * [Kotlin for Plugin Developers](tutorials/kotlin.md)

basics/plugin_structure/img/kotlin40.svg

@@ -1,13 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40">
-  <defs>
-    <linearGradient id="kotlin-a" x1="2.195%" x2="91.789%" y1="91.369%" y2="0%">
-      <stop offset="0%" stop-color="#8F67FF" stop-opacity=".987"/>
-      <stop offset="56.707%" stop-color="#F9A02F" stop-opacity=".993"/>
-      <stop offset="100%" stop-color="#F7861E"/>
-    </linearGradient>
-  </defs>
-  <g fill="none" fill-rule="evenodd">
-    <polygon fill="#0EAEFF" points="4 4 4 35.995 36.001 35.995 20.045 19.925 36.001 4"/>
-    <polygon fill="url(#kotlin-a)" points="20.064 4 4 20.893 4 35.995 20.041 19.925 35.995 4"/>
-  </g>
-</svg>

basics/plugin_structure/plugin_icon_file.md

@@ -1,42 +1,92 @@
 ---
-title: Plugin Icon
+title: Plugin Logo
 ---
 
-Beginning in version 2019.1, the IntelliJ Platform supports representing a plugin with an icon.
-A _Plugin Icon_ is intended to be a unique representation of a plugin's functionality, technology, or 
-company. 
+Beginning in version 2019.1, the IntelliJ Platform supports representing a plugin with a logo.
+A _Plugin Logo_ is intended to be a unique representation of a plugin's functionality, technology, or company.
+Previously this page referred to Plugin Logos as _Plugin Icons_. 
 
-Plugin Icons are shown in the Settings/Preferences [Plugin Manager](https://www.jetbrains.com/help/idea/managing-plugins.html) UI
-in JetBrains' products. Plugin Icons also appear in the [Plugins Repository](https://plugins.jetbrains.com/),
-and also in [MarketPlace](https://plugins.jetbrains.com/marketplace).
+**Note:** icons and images used within a plugin have different requirements. 
+See [Working with Icons and Images](/reference_guide/work_with_icons_and_images.md) for more information.
 
-**Note:** icons and images that are used within a plugin have different requirements. 
-See [Working with Icons and Images](/reference_guide/work_with_icons_and_images.md)
-for more information.
+* bullet list
+{:toc}
 
-### Plugin Icon File Format
-All Plugin Icon images must be provided in SVG format. 
-Plugin Icons will be displayed in 40px by 40px and 80px by 80px size. However, _only one
-size icon_ should be supplied because it will automatically
-scale.
+## Introduction
+Plugin Logos are shown in the [Plugins Repository](https://plugins.jetbrains.com/), and in [MarketPlace](https://plugins.jetbrains.com/marketplace). 
+They also appear in the Settings/Preferences [Plugin Manager](https://www.jetbrains.com/help/idea/managing-plugins.html) UI in IntelliJ Platform-based IDEs. 
+Whether online or in the product UI, a Plugin Logo helps users to identify a plugin more quickly in a list, as shown below:
 
-| Icon Size  | Example SVG Icon                            |
-| ------------- | -------------                            |
-| 40x40         | ![Kotlin Plugin Icon](img/kotlin40.svg)  |
+![Example Product Plugin Preferences Dialog](img/plugin_prefs.png){:width="800px"}
 
-### Plugin Icon File Naming Convention
-Plugin Icon files are named according to the following conventions:
-* `pluginIcon.svg` for use with the default (light) JetBrains IDE theme
-* `pluginIcon_dark.svg` for use with the Darcula JetBrains IDE theme
+## Plugin Logo Requirements
+For a Plugin Logo to be displayed correctly within an IntelliJ Platform-based IDE, it must:
+* Follow the best practices design guidelines,
+* Be in the correct file format,
+* Conform to file name conventions,
+* Be in the `META-INF` folder of the plugin distribution file.  
 
-### Adding Plugin Icons to a Plugin Project
-The Plugin Icon files must be in the `META-INF` folder of the plugin distribution file, 
-i.e. the `*.jar` or `*.zip` file you upload to the plugin repository and install into
-a JetBrains IDE.
+### Plugin Logo Size
+The Plugin Logo should be provided in one size: 40px by 40px. 
+A Plugin Logo is displayed in two sizes, and scales automatically in each context:
+* 40px by 40px in the plugins list in the Plugin Manager UI.
+* 80px by 80px in the plugin details screen in the Plugin Manager UI, on the plugin's page in the Plugins Repository, and on MarketPlace.
 
-To include Plugin Icons in your distribution file, place the Plugin Icon files 
-into a plugin project's `resources/META-INF` folder. Note this requirement
-is the same regardless of using DevKit or Gradle for developing a plugin. For example:
+Verify that Plugin Logo designs are effective in both sizes and all display contexts.
+
+### Plugin Logo Shape
+Plugin Logo designs should leave at least 2px transparent padding around the perimeter, as shown below:  
+
+![36px by 36px is the area where the visible part of the Logo should fit](img/icon_size.png){:width="225px"}
+
+Make sure Plugin Logos have the same visual weight as the logos in the examples below. 
+The more filled a Plugin Logo design is, the less actual space it needs. 
+See more examples of [visual weight compensation](https://jetbrains.design/intellij/principles/icons/#08) in the IntelliJ Platform UI Guidelines for Icons. 
+
+For basic shapes, use the following sizes. 
+Note the different areas of transparent padding used for each shape: 
+
+| ![Square 32px by 32px](img/square_logo.png){:width="225px"} | ![Circle 36px in Diameter](img/circle_logo.png){:width="225px"} |
+|:---:|:---:|
+| _Square logo 32px by 32px_ | _Circular logo 36px in Diameter_ |
+| ![Horizontal rectangle 36px by 26px](img/rectangle_horizontal.png){:width="225px"} | ![Vertical rectangle 26px by 36px](img/rectangle_vertical.png){:width="225px"} |
+| _Horizontal rectangular logo 36px by 26px_ | _Vertical rectangular logo 26px by 36px_ |
+
+<br>
+
+### Plugin Logo Colors
+If the plugin’s technology already has a logo, use its colors. 
+Check the license terms before using the logo. 
+If there is no existing logo, or its use is prohibited, create a custom logo based on the [Action Colors Palette](https://jetbrains.design/intellij/principles/icons/#action-icons) in the IntelliJ Platform UI Guidelines for Icons.
+
+| ![The YouTrack Plugin Logo uses the YouTrack product logo ](img/yt_logo.png){:height="200px" width="200px"} | ![The Keymap Plugin Logo uses a color from the Action Colors Palette](img/keymap_logo.png){:height="200px" width="200px"} |
+|:---:|:---:|
+| _The YouTrack Plugin Logo uses<br>the YouTrack product logo_ | _The Keymap Plugin Logo uses a color<br>from the Action Colors Palette_ |
+
+Ensure a Plugin Logo is visible on both light and dark backgrounds. 
+If one Plugin Logo design does not work on both light and dark backgrounds, then create separate light and dark versions of the Plugin Logo. 
+The examples below illustrate how a good Plugin Logo design may work well for a light background but not so well for a dark background. 
+Consequently, a separate Plugin Logo for dark backgrounds is needed. 
+
+| ![Plugin Logo on Light UI Theme](img/light_version.png){:width="225px"} | ![Light Plugin Logo on Dark UI Theme](img/dark_bad.png){:width="225px"} | ![Plugin Logo for Dark UI Theme](img/dark_good.png){:width="225px"} |
+|:---:|:---:|:---:|
+| _The light Plugin Logo design<br>works well on light UI Theme_ | _The light Plugin Logo design does<br>not work well on a dark UI Theme_ | _A separate, dark Plugin Logo design<br>works well on dark UI Theme_ |
+
+### Plugin Logo File Format
+All Plugin Logo images must be SVG format. 
+This vector image format is required because the Plugin Logo file must be small, and the image must scale without any loss of quality.
+
+### Plugin Logo File Naming Convention
+Name the Plugin Logo files according to the following conventions:
+* `pluginIcon.svg` is the default Plugin Logo. If a separate Logo file for dark UI Themes exists in the plugin, then this file is used solely for light UI Themes,
+* `pluginIcon_dark.svg` is an optional, alternative Plugin Logo for use solely with dark IDE UI Themes.
+    
+
+## Adding Plugin Logo Files to a Plugin Project
+The Plugin Logo files must be in the `META-INF` folder of the plugin distribution file, i.e. the `*.jar` or `*.zip` file you upload to the plugin repository and install into a JetBrains IDE.
+
+To include Plugin Logo files in your distribution file, place the Plugin Logo files into a plugin project's `resources/META-INF` folder. 
+Note that this requirement is the same regardless of using DevKit or Gradle for developing a plugin. For example:
  
-![Plugin Icons in META-INF folder](img/resource_directory_structure.png)
+![Plugin Logo Files in META-INF folder](img/resource_directory_structure.png)