= Colors
:description: The theming language supports color values in hex, RGB, and CMYK formats.

The theme language supports color values in three formats:

[[hex]]Hex:: A string of 3 or 6 hexadecimal characters with an optional leading `#` and optional enclosing quotes.
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.

Here's a quick translation between how hex, RGB, and CMYK colors are expressed in an Asciidoctor PDF theme.

|===
|Hex |RGB |CMYK (decimal) |CMYK (%)

|#333333
|[51, 51, 51]
|[0, 0, 0, 0.92]
|[0, 0, 0, 92%]
|===

This page describes each color model and how to use it in your theme.

== 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 (`#`), 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 would normally be the case in YAML.
That same preprocessor will also coerce a primitive value to a string if `color` is the name of the last segment in the key (e.g., `font-color`).
This avoids the problem of 000 becoming 0 (and similar implicit conversions) when the theme file is parsed.

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:

[cols="8*m"]
|===
|#ff0000
|#FF0000
|'ff0000'
|'FF0000'
|#f00
|#F00
|'f00'
|'F00'
|===

Here's how a hex color value appears in the theme file:

[,yaml]
----
base:
  font-color: #FF0000
----

== RGB

An RGB array value must be three numbers ranging from 0 to 255.
The values must be separated by commas and be surrounded by square brackets.

NOTE: An RGB array is automatically converted to a hex string internally, so there's no difference between ff0000 and [255, 0, 0].

Here's how to specify the color red in RGB:

* [255, 0, 0]

Here's how an RGB color value appears in the theme file:

[,yaml]
----
base:
  font-color: [255, 0, 0]
----

== CMYK

A CMYK array value must be four numbers ranging from 0 and 1 or from 0% to 100%.
The values must be separated by commas and be surrounded by square brackets.

Unlike the RGB array, the CMYK array _is not_ converted to a hex string internally.
PDF has native support for CMYK colors, so you can preserve the original color values in the final PDF.

Here's how to specify the color red in CMYK:

* [0, 0.99, 1, 0]
* [0, 99%, 100%, 0]

Here's how a CMYK color value appears in the theme file:

[,yaml]
----
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:

[,yaml]
----
table:
  background-color: transparent
----

The `transparent` keyword can be used for the background or border color, but not the font color.
