Add N&N for improved disabled icons

news/4.36/platform.md

@@ -16,10 +16,37 @@
 ## Preferences
 -->
 
-<!--
 ---
 ## Themes and Styling
--->
+
+### Improved Disabled Icons Generation <!-- https://github.com/eclipse-platform/eclipse.platform.swt/pull/1936 -->
+Up to now, disabled versions of icons usually were and had to be provided as explicit, separate image files.
+In case no such icon was provided, an algorithm in SWT was used to generate a disabled icon. However, that
+algorithm was very limited and produced hardly usable results.
+
+The algorithm in SWT was now improved such that results are by default equal to the disabled version of the
+icons that have explicitly been provided for the Eclipse Platform bundles. The pre-generated disabled icons
+have been replaced with the usage of on-the-fly generated disabled versions of the icons via the SWT algorithm.
+This particularly includes the removal of `disabledIcon` in `plugin.xml` files and programmatically setting the
+`disabledImageDescriptor` for `Actions`.
+
+In addition, the algorithm for the calculation of disabled versions of icons became exchangeable. The
+algorithm can be changed via the system property `org.eclipse.swt.image.disablement` with the
+following options:
+- `grayed` (default): produces a gray-scaled version of the icon, which is aligned with the
+  existing, pre-generated disabled versions of icons for Eclipse bundles
+- `desaturated` (preview): produces a desaturated version of the icon, comparable to the
+  `grayed` version but still keeping some color in it; the configuration of this option may be
+  subject to change in future releases of Eclipse
+- `gtk`: produces an icon version that conforms with the default disablement algorithm of GTK
+
+The following screenshots demonstrate the different options.
+
+| Option | Example |
+| --- | --- |
+| `grayed` | ![Disablement option 'grayed'](images/disabled_icons_grayed.png) |
+| `desaturated` | ![Disablement option 'desaturated'](images/disabled_icons_desaturated.png) |
+| `gtk` | ![Disablement option 'gtk'](images/disabled_icons_gtk.png) |
 
 <!--
 ---