diff --git a/docs/reference/gtk/css-overview.xml b/docs/reference/gtk/css-overview.xml
index 0fe3891150..6afa20a6fe 100644
--- a/docs/reference/gtk/css-overview.xml
+++ b/docs/reference/gtk/css-overview.xml
@@ -552,11 +552,37 @@ checkbutton:indeterminate {
       GTK+ adds several additional ways to specify colors.
     </para>
 
-<literallayout><code>〈gtk color〉 = 〈color expression〉| 〈win32 color〉</code>
+<literallayout><code>〈gtk color〉 = 〈symbolic color〉 | 〈color expression〉| 〈win32 color〉</code>
 </literallayout>
 
     <para>
-      GTK+ allows to form color expressions, which can be nested and
+      The first is a reference to a color defined via a @define-color rule.
+      The syntax for @define-color rules is as follows:
+    </para>
+
+<literallayout><code>〈define color rule〉 = @define-color 〈name〉 〈color〉</code>
+</literallayout>
+
+    <para>
+      To refer to the color defined by a @define-color rule,
+      use the name from the rule, prefixed with @.
+    </para>
+
+<literallayout><code>〈symbolic color〉 = @〈name〉</code>
+</literallayout>
+
+    <example><title>An example for defining colors</title>
+      <programlisting><![CDATA[
+@define-color bg_color #f9a039;
+
+* {
+background-color: @bg_color;
+}
+]]></programlisting>
+    </example>
+
+    <para>
+      GTK+ also allows to form color expressions, which can be nested and
       provide a rich language to define colors which are derived from a
       set of base colors.
     </para>
diff --git a/docs/reference/gtk/css-properties.xml b/docs/reference/gtk/css-properties.xml
index 9ab0c4bb46..1f9a662a7d 100644
--- a/docs/reference/gtk/css-properties.xml
+++ b/docs/reference/gtk/css-properties.xml
@@ -480,7 +480,9 @@ We use <literallayout> for syntax productions, and each line is put in a <code>
       <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">