diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index 1062ad7f5..31d64ce7c 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -213,30 +213,27 @@ 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 friendlier to a YAML editor.
+<3> The leading `+#+` on a hex value is entirely optional. However, we recommend that you always use either quotes around the value or a leading `+#+` (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.
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