diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index 1062ad7f5..76530d9c0 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -213,30 +213,29 @@ You can define arbitrary key names to make custom variables.
 This is one way to group reusable values at the top of your theme file.
 If you are going to do this, it's recommended that you organize the keys under a custom namespace, such as `brand`.
 
-For instance, here's how you can define your (very patriotic) brand colors:
+For instance, here's how you can define your brand colors:
 
 [source,yaml]
 ----
 brand:
-  red_color: #E0162B
-  white_color: #FFFFFF
-  blue_color: #0052A5
+  primary: #E0162B # <1>
+  secondary: '#FFFFFF' # <2>
+  alert: '0052A5' # <3>
 ----
+<1> To align with CSS, you may add a `+#+` in front of the hex color value.
+A YAML preprocessor is used to ensure the value is not treated as a comment as it would normally be the case in YAML.
+<2> You may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool.
+<3> The leading `+#+` on a hex value is entirely optional.
+However, we recommend that you always use either a leading `+#+` or surrounding quotes (or both) to prevent YAML from mangling the value.
 
 You can now use these custom variables later in the theme file:
 
 [source,yaml]
 ----
 base:
-  font_color: $brand_blue_color
+  font_color: $brand_primary
 ----
 
-IMPORTANT: You must include the suffix `_color` in the key name for colors.
-Using this convention allows the the theme loader to preprocess hex values that begin with `#` correctly.
-This preprocessing step is necessary since `#` is the comment character in YAML.
-The value would otherwise be erased.
-Only key names that end in the suffix `_color` receive this treatment.
-
 === Math expressions & functions
 
 The theme language supports basic math operations to support calculated values.
@@ -345,29 +344,37 @@ The order of elements in a measurement array is the same as it is in CSS:
 
 The theme language supports color values in three formats:
 
-Hex:: A string of 3 or 6 characters with an optional leading `#`.
-+
-The special value `transparent` indicates that a color should not be used.
+Hex:: A string of 3 or 6 characters with an optional leading `#`, optional surrounding quotes or both.
 RGB:: An array of numeric values ranging from 0 to 255.
 CMYK:: An array of numeric values ranging from 0 to 1 or from 0% to 100%.
+Transparent:: The special value `transparent` indicates that a color should not be used.
 
 ==== Hex
 
 The hex color value is likely most familiar to web developers.
-The value must be either 3 or 6 characters (case insensitive) with an optional leading hash (`#`).
+The value must be either 3 or 6 characters (case insensitive) with an optional leading hash (`#`), optional surrounding quotes or both.
+
+To align with CSS, you may add a `+#+` in front of the hex color value.
+A YAML preprocessor is used to ensure the value is not treated as a comment as it would normally be the case in YAML.
+
+You also may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool.
+In this case, the leading `+#+` on a hex value is entirely optional.
+
+Regardless, we recommend that you always use either a leading `+#+` or surrounding quotes (or both) to prevent YAML from mangling the value.
 
 The following are all equivalent values for the color red:
 
 [%autowidth,cols=4]
 |===
-|f00
 |#f00
-|ff0000
+|'f00'
 |#ff0000
-|F00
+|'ff0000'
+
 |#F00
-|FF0000
+|'F00'
 |#FF0000
+|'FF0000'
 |===
 
 Here's how a hex color value appears in the theme file:
@@ -378,14 +385,6 @@ base:
   font_color: #ff0000
 ----
 
-It's also possible to specify no color by assigning the special value `transparent` as shown here:
-
-[source,yaml]
-----
-base:
-  background_color: transparent
-----
-
 ==== RGB
 
 An RGB array value must be three numbers ranging from 0 to 255.
@@ -426,6 +425,16 @@ base:
   font_color: [0, 0.99, 1, 0]
 ----
 
+==== Transparent
+
+It's possible to specify no color by assigning the special value `transparent`, as shown here:
+
+[source,yaml]
+----
+base:
+  background_color: transparent
+----
+
 === Images
 
 An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax.
diff --git a/lib/asciidoctor-pdf/theme_loader.rb b/lib/asciidoctor-pdf/theme_loader.rb
index 091d94dab..a8cc0fcaf 100644
--- a/lib/asciidoctor-pdf/theme_loader.rb
+++ b/lib/asciidoctor-pdf/theme_loader.rb
@@ -13,7 +13,7 @@ class ThemeLoader
 
   VariableRx = /\$([a-z0-9_]+)/
   LoneVariableRx = /^\$([a-z0-9_]+)$/
-  HexColorValueRx = /[_-]color: (?<quote>"|'|)#?(?<value>[A-Za-z0-9]{3,6})\k<quote>$/
+  HexColorEntryRx = /^(?<k>[[:blank:]]*[[:graph:]]+): +(?<q>["']?)#?(?<v>\w{3,6})\k<q> *(?:#.*)?$/
   MeasurementValueRx = /(?<=^| |\()(\d+(?:\.\d+)?)(in|mm|cm|pt)(?=$| |\))/
   MultiplyDivideOpRx = /(-?\d+(?:\.\d+)?) *([*\/]) *(-?\d+(?:\.\d+)?)/
   AddSubtractOpRx = /(-?\d+(?:\.\d+)?) *([+\-]) *(-?\d+(?:\.\d+)?)/
@@ -74,7 +74,7 @@ def self.load_theme theme_name = nil, theme_path = nil, opts = {}
   end
 
   def self.load_file filename, theme_data = nil
-    raw_data = (::IO.read filename).each_line.map {|l| l.sub HexColorValueRx, '_color: \'\k<value>\'' }.join
+    raw_data = (::IO.read filename).each_line.map {|l| l.sub HexColorEntryRx, '\k<k>: \'\k<v>\'' }.join
     self.new.load((::SafeYAML.load raw_data), theme_data)
   end