Root

See also

This is the generation-time override. The equivalent at import time is each format's background_color on Create Import.

The root element customises the background of your image.

Property	Description
background_color	3 filling modes: Monochrome, Linear gradient, or Cmyka (print only). Full token grammar: Colors & Gradients.

Monochrome color

Supported formats:

• 6 hex digits prefixed with #: #RRGGBB — e.g. #0000FF
• 8 hex digits prefixed with #: #RRGGBBAA — includes alpha — e.g. #0000FF80 (blue at 50% opacity)

Opacity reference:

Opacity (0–100)	Alpha hex
0	00
5	0D
10	1A
20	33
30	4D
40	66
50	80
60	99
70	B3
80	CC
90	E6
100	FF

No 3-digit hex

3-digit hex colors (e.g. #AAA) are not supported.

Linear gradient

Can be used as background_color (banner background, button) or color (text). On a printer / printer_multipage design only a shape or button background_color takes one — the banner background and text are solid there, and a gradient is refused with 400 invalid_payload. For the exact token grammar, see Colors & Gradients below.

Examples:

Value	Result
"background_color": "linear-gradient(0% 0% 100% 0%,0% #1a47ff 1,100% #b65151 1)"
"background_color": "linear-gradient(0% 0% 0% 100%,0% #1a47ff 1,100% #b65151 1)"
"background_color": "linear-gradient(0% 0% 100% 100%,0% #1a47ff 1,100% #b65151 1)"

Cmyk / Cmyka Color

Used for print designs only — see Colors & Gradients below for the full CMYK token grammar and how it relates to hex.

Colors & Gradients

Every color field across the API takes a string token. Which token forms are accepted depends on the design type and on the specific field.

Hex

For static / animated designs:

#RRGGBB or #RRGGBBAA (the 8-digit form appends alpha). Case-insensitive. Nothing else is accepted (a cmyk(...) token is the one exception — it is converted, see below):

Value	Result
#ffffff, #FFFFFF, #ffffff80	✅ Accepted
#fff, #fffa (3/4-digit shorthand)	✅ Accepted on Design Import — expanded to the full form before storage. Use the full 6/8-digit form for generation-time overrides.
ff0000 (no #)	❌ Rejected
#fffffff (7 digits)	❌ Rejected
rgb(255,0,0), red	❌ Rejected

Linear gradient

Linear gradients do exist on static and animated designs, but they use Abyssale's own grammar — not CSS. CSS gradient syntax will not match:

linear-gradient(<x>% <y>% <x1>% <y1>%,<offset>% #RRGGBB <alpha>,<offset>% #RRGGBB <alpha>[,…])

• The first group is the gradient line: start point <x>% <y>% then end point <x1>% <y1>%, all four space-separated.
• Then between 2 and 8 color stops, comma-separated from the line and from each other. Each stop is <offset>% #RRGGBB <alpha> — again space-separated internally, with alpha a bare float (1, 0.5), not a percentage.
• Each stop carries its own offset, so stops need not be evenly spaced. Order them by ascending offset.

A worked example — an opaque top-to-bottom teal → navy fill:

"background_color": "linear-gradient(0% 0% 0% 100%,0% #0a363a 1,100% #041b2d 1)"

And the same line with a highlight three quarters of the way down:

"background_color": "linear-gradient(0% 0% 0% 100%,0% #0a363a 1,75% #1d6f78 1,100% #041b2d 1)"

Only fill-type fields accept a gradient. The property table you came from says whether a specific field is one of them.

Accepts a gradient	Hex / CMYK only
A format background on static / animated	A page background, and a format background on printer
A shape or button layer's background_color	A text layer's background_color, and both colours of a rating
A shape or button background_color on printer (CMYK stops)	A page background, and text on printer
color on a text or button layer, on static / animated	Borders and strokes
	Shadows and text decoration
	Overlays and patterns

CMYK

For printer / printer_multipage designs — print designs store CMYK:

cmyk(C,M,Y,K)        cmyka(C,M,Y,K)        cmyka(C,M,Y,K,A)

Components are integers 0–100, with no % sign. Whitespace between components is accepted and normalised away — except inside a gradient, where a stop is written cmyk(C,M,Y,K) with no spaces. Tokens are case-insensitive. See Print Imports → Colors.

Which token on which design type

Token	static / animated	printer / printer_multipage
#RRGGBB / #RRGGBBAA	✅ Accepted	✅ Converted to cmyk(...) + color_converted warning
linear-gradient(...)	✅ On gradient-capable fields	✅ On shape and button background_color — hex stops converted per stop + color_converted warning
cmyk(...) / cmyka(...)	✅ Converted to hex + color_converted warning	✅ Stored as sent

A solid color in the "wrong" space is converted, not rejected. The warning names the path and both values; alpha survives in both directions (#RRGGBBAA ⇄ cmyka(C,M,Y,K,A)), and the hex the converter emits is uppercase.

Conversion is approximate

No ICC profile is involved, so a converted print color is a close approximation, not a colour-managed match. Author cmyk(...) yourself when the exact ink matters — it is then stored verbatim, with no conversion and no warning.

Why a gradient converts stop by stop

A gradient used to be refused on print outright, because converting one meant collapsing it to its first colour — silently turning your artwork into a flat fill. The pipeline now carries every stop through to an axial shading in the PDF, so a gradient converts the way a solid colour does: each stop individually, at the same approximate accuracy, with the warning telling you it happened.

What still cannot convert is alpha. A PDF shading has no alpha channel, so a semi-transparent stop has nowhere to go; flattening it onto white would ship a colour you never authored, so it is refused instead.

A malformed token (a bad CMYK component, a % in a CMYK token, a gradient with fewer than 2 or more than 8 color stops) is invalid_payload at import time, and the error message spells out the accepted forms.

Gradients on print designs

printer / printer_multipage designs accept a linear gradient on a shape or button background_color, with the same grammar and the same 2-to-8 stop range. Two rules differ:

• Stops are stored as cmyk(...). You may author them in hex: each stop is converted individually, with a color_converted warning naming the path — the same rule a solid colour follows. Author cmyk(...) yourself when the exact ink matters, and it is stored verbatim.
• Stops must be opaque. A PDF shading carries no alpha, so a semi-transparent stop is rejected rather than silently flattened. Send 1 as the alpha of every stop.

"background_color": "linear-gradient(0% 0% 0% 100%,0% cmyk(0,100,100,0) 1,50% cmyk(0,0,100,0) 1,100% cmyk(100,0,0,0) 1)"

Printer color defaults

On printer, defaults are CMYK too: text / shape / button / qrcode colors default to cmyk(0,0,0,100) (black) and button text to cmyk(0,0,0,0) (white). Rating layers get print-appropriate defaults from the backend — star_color → cmyk(0,20,65,0) and background_color → cmyk(0,0,0,8) — where static/animated keep #FFCD59 / #EAEAEA.

background_color is the only root property

The root element accepts nothing else — no hidden, no shadows, no image. A background image is a regular image layer behind the others.

Related

• Element Properties — the per-layer overrides
• Colors & Gradients — the full token grammar