diff --git a/docs/reference/gtk/css-properties.xml b/docs/reference/gtk/css-properties.xml
index f7cc570eb5..4c804a4b1f 100644
--- a/docs/reference/gtk/css-properties.xml
+++ b/docs/reference/gtk/css-properties.xml
@@ -430,12 +430,26 @@ We use <literallayout> for syntax productions, and each line is put in a <code>
 </literallayout>
 
       <para>
-        The icon properties are used by widgets that are rendering 'icons', such
-        as arrows, expanders, spinners, checks or radios. -gtk-icon-style and
-        -gtk-icon-theme are used when resolving images using the -gtk-icontheme
-        syntax. -gtk-icon-palette defines a color palette for recoloring symbolic
+        The -gtk-icon-source property is used by widgets that are rendering 'built-in'
+        icons, such as arrows, expanders, spinners, checks or radios.
+      </para>
+
+      <para>
+        The -gtk-icon-style property determines the preferred style for
+        application-provided icons.
+      </para>
+
+      <para>
+        The -gtk-icon-transform and -gtk-icon-shadow properties affect the rendering
+        of both built-in and application-provided icons.
+      </para>
+
+      <para>
+        -gtk-icon-palette defines a color palette for recoloring symbolic
         icons. The recognized names for colors in symbolic icons are error,
-        warning and success.
+        warning and success. The default palette maps these three names to
+        symbolic colors with the names @error_color, @warning_color and
+        @error_color.
       </para>
 
       <table pgwide="1">