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.
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 exactly two color stops, comma-separated from the line and from each other. Each stop is
<offset>% #RRGGBB <alpha>— again space-separated internally, withalphaa bare float (1,0.5), not a percentage.
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)"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 or page background | Borders and strokes |
A text, shape, button or rating layer's own fill (background_color, or color on text/button) | 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. 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 | ❌ unsupported_for_type |
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 solid colour converts but a gradient does not
Converting a gradient means collapsing it to its first colour, which would silently turn your artwork into a flat fill. Converting a solid colour only costs some accuracy, and the warning tells you it happened.
A malformed token (a bad CMYK component, a % in a CMYK token, a gradient with the wrong number of stops) is invalid_payload at import time, and the error message spells out the accepted forms.
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.