Colors & Gradients

This grammar applies to every color field across the API — both when authoring a design via Design Import and when overriding colors at generation time.

Token forms

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. The grammar is the same when you import a design and when you override a color at generation time.

Hex

#RRGGBB or #RRGGBBAA, or the CSS shorthand #RGB / #RGBA. The 8- and 4-digit forms carry alpha. Case-insensitive.

Value	Result
#ffffff, #FFFFFF, #ffffff80	✅ Accepted
#fff, #fffa	✅ Accepted. An import stores the full form (#ffffff, #ffffffaa).
ff0000 (no #)	❌ Rejected
#fffff, #fffffff (5 or 7 digits)	❌ Rejected
rgb(255,0,0), red	❌ Rejected

Linear gradient

Linear gradients use Abyssale's own grammar, not CSS. CSS gradient syntax will not match:

linear-gradient(<x>% <y>% <x1>% <y1>%,<offset>% <color> <opacity>,<offset>% <color> <opacity>[,…])

• The line comes first: start point <x>% <y>%, then end point <x1>% <y1>%, all four space-separated.
• Then 2 to 8 stops, comma-separated, with no space after a comma. Each stop is <offset>% <color> <opacity>, separated by single spaces.
• offset is 0% to 100%. Each stop carries its own offset, so stops need not be evenly spaced. Order them by ascending offset.
• color is #RRGGBB or #RGB, or cmyk(C,M,Y,K) written without spaces. Every stop uses the same notation: a hex stop next to a CMYK stop is rejected.
• opacity is a bare number from 0 to 1 (1, 0.5), not a percentage. It is the only transparency a stop has, so a stop color with alpha (#RRGGBBAA, #RGBA, cmyka(...)) is rejected.

Stop	Result
0% #FF0000 1, 50% #f00 0.5, 100% cmyk(0,100,100,0) 1	✅ Accepted
101% #FF0000 1	❌ Offset above 100%
0% #FF0000 2	❌ Opacity above 1
0% #FF000080 1, 0% #F00F 1	❌ Alpha in the stop color: use the opacity
0% cmyk(0, 100, 100, 0) 1	❌ Spaces inside a CMYK stop

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

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

• Each component is an integer from 0 to 100, alpha included. A % after a component is accepted (cmyk(0%,100%,90%,10%)), and so are leading zeros (cmyk(007,0,0,0)).
• Spaces around the components are accepted (cmyk( 0, 100, 90, 10 )), except in a gradient stop, which is written cmyk(C,M,Y,K) with no spaces.
• Case-insensitive, and a 5-component cmyk(...) is read as cmyka(...).
• An import stores the canonical spelling: cmyk(0%, 100%, 90%, 10%) is stored as cmyk(0,100,90,10), and cmyka(C,M,Y,K,100) as cmyk(C,M,Y,K).

Print designs (printer / printer_multipage) store CMYK. On static / animated a CMYK color is converted to hex. 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, with hex stops (cmyk(...) stops are unsupported_for_type at import)	✅ On shape and button background_color — hex stops converted per stop + color_converted warning
cmyk(...) / cmyka(...)	✅ Converted to hex + color_converted warning	✅ Stored, in the canonical spelling

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 is invalid_payload, both at import and at generation, and the error message spells out the accepted forms. Malformed means: a CMYK component above 100, a gradient with fewer than 2 or more than 8 stops, a stop offset above 100%, a stop opacity above 1, or a stop color with alpha.

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.