Design

A design is the white-label theme applied to your team's public passports — the pages a QR code resolves to. Colours, corner rounding, shadow depth, logo, fonts, the page's structural style, how each kind of value is drawn and how each part of the page is styled (the top bar, the masthead, the chapters, the cards, the tables, the figures, the charts, the spacing): everything a visitor sees that is yours rather than Synex's.

There is exactly one design per team, and it is addressed without an id. A key is pinned to one team and a team has one theme, so there is nothing for an id to disambiguate — /v1/design is the whole address. A composition can override any of it, but the logo, for the passports of one ontology.

The abilities are the whole gate

Neither design:read nor design:write is in a key's default ability set — grant them explicitly when you mint the key.

They are non-default for a reason worth stating plainly: a key minted to write passport values has no business restyling every public passport the team has ever released. One careless grant turns a data integration into something that can repaint the customer-facing surface of the whole product line.

There is deliberately no gate beyond the ability. In the Synex application a member edits branding if their role grants design:write — the default Editor role does — and a key is capped by what its owner may currently do, so asking more of the key here would make the API stricter than the surface it mirrors. A rule that only exists on one of two equivalent paths is not a security boundary, just a difference to work around.

The design model

Twenty-six settings beside the object discriminator: the five original ones (palette, rounding, shadow, logo, font), thirteen that shape the page's structure, colours, type and components (see Presets, colour modes and components), and the eight part-style blocks. Null means "not set", and a setting that is not set inherits (see Resolution order).

The eight part-style blocks are objects even when nothing is set: every leaf is there, null until set.

palette is an ordered scale, not a bag of settings

The array's position carries meaning: entry 0 is step 50, entry 5 is step 500 and entry 10 is step 950. The renderer reads entry 5 as the brand colour. It builds the page background from step 50 blended toward white, or, on a dark page, from step 950 blended toward black; the other steps give the text, the shades between and the chart colours. Reordering the entries restyles the passport even though every colour in it is unchanged, so treat the palette as a scale you author top to bottom rather than as a set of named options you can shuffle.

Each entry is {lightness, hex} — lightness on the familiar 50/100/200/…/900/950 scale, and hex as #RRGGBB. The Synex application writes 11 entries; at most 32 are accepted, and the renderer reads the first 11.

Send all 11 steps. A palette with fewer usable entries (a 50…900 scale, a single colour, an entry whose hex is null) is completed rather than ignored: each usable entry keeps its position, and the others are filled from the brand scale of the usable entry nearest step 500 (entry 5 itself when it is usable; between two equally near, the darker). Position decides the step, with one exception: a palette of a single entry that carries a lightness is the step it names, so {"lightness": 500, …} is the brand colour and the scale is built around it. A single entry without one is step 50, so the brand scale is built from that colour and the page takes a tint of it. A palette with no usable entry draws in a neutral slate.

rounding and shadow are levels, not measurements

Both are integers from 1 to 6, and both index the renderer's own class maps. rounding: 3 is not "3px" and shadow: 2 is not a blur radius — they select the third and second steps of scales the renderer defines. Move them a step at a time and look at the result; there is no unit to compute with.

The font catalogue

font is the body font; font_heading and font_figures take the same values. A font is one of 24 families, and the viewer loads them from Synex's own servers, never from a third party.

A PATCH matches a family without case and without regard to hyphens, underscores or spaces between words, and stores the catalogue's own spelling: montserrat and bebas-neue are stored as Montserrat and Bebas Neue. A family outside the list is 400 parameter_invalid ("Pick a font from the list.").

Older teams stored fonts free-form, and the Synex Design page used to store lower-case slugs, so a stored value is read the same way: one that matches the catalogue comes back in its canonical spelling, and one that does not comes back as null. A PATCH of any setting writes the design back in that normalised form, so it also clears a stored font that is outside the catalogue.

An unset design reads as null, not as a default

A team that has never set a theme gets palette: [], null for every other setting and the eight blocks as objects of nulls — the Unset response under Retrieve the design. Those nulls mean "not set", not "set to the default". The renderer's own fallbacks decide what an unthemed passport looks like, and reporting those fallbacks here would claim the team had picked something it never picked — which is exactly the claim that breaks the moment the renderer's defaults change.

If you are mirroring a design into your own system, carry the nulls through rather than substituting values for them.

logo is an id, not a link

GET /v1/design returns the logo's file id and stops there. To get the bytes, turn it into a link yourself with GET /v1/files/{file}/download.

A presigned URL is a bearer credential with a clock on it. Minting one on every read of the theme would hand you a signature you did not ask for, on every poll, that you could not cache for longer than its own short lifetime — and it would put a signing round-trip inside a call that is otherwise a single cheap read.

Presets, colour modes and components

The thirteen settings below describe a passport's structure, colours, type and components. Every one of them is nullable, and null means "inherit" (see Resolution order). The eight part-style blocks have a section of their own, Part styles.

Presets

A preset is a structural style: heading weight, corner shape and spacing live in the viewer's stylesheet and follow the preset. It also supplies a default for each setting you leave null; for labels that is caps on editorial and technical, and muted on standard and soft.

A preset sets no part-style leaf: every block leaf defaults to the value in the part-style tables, whichever preset is chosen. The exceptions are the masthead's image_side, image_corners and image_fit, whose defaults follow the hero layout (a null hero takes the preset's) and, for image_fit, the preset itself.

Presets never set colours; colours come from palette or colors. Choosing a preset in the Synex application also writes the preset's fonts, rounding and appearance into the design, so you can see and change each, and leaves the hero, the component styles and every part style alone. The API does not write any of them: PATCH {"preset": "technical"} changes preset and nothing else, and the settings you left null follow the preset when a passport is drawn.

Colour modes

In simple mode the viewer generates the six colour roles from palette, for the appearance, and holds them to its contrast rules: text on the background at 12:1 or better, muted text at 4.5:1 or better on the background, on surfaces and on framed cards. colors is ignored.

In advanced mode colors is used as given. A role left null is derived: the background and text from the palette, the muted, rule and surface colours from the text and background, and the accent from the palette's brand colour. So you can set only background and accent.

Components

components sets how each kind of value is drawn by default. A kind is a group of property types, and a style is one way of drawing it:

Short text and date values have one look and no kind. A figure left null is drawn as a large figure in a stat grid and as an inline value elsewhere. An image or file value with no link is not drawn as a broken image or a dead download.

A single placement can override its kind's default with its own display: see Compositions.

Component options

component_options sets how every value of a kind is displayed, the way a placement's display_options set it for one value: in the passport's sections and among the masthead's key figures. Only image has options. The masthead's product image is styled by the masthead block's image_ leaves instead.

aspect, fit and backdrop apply to the plain, captioned and framed styles; the file style ignores all three, and only corners reaches its thumbnail. A placement's display_options win, key by key: a placement that sets its own aspect keeps it and still takes the design's fit when it sets none. corners and backdrop come from the design alone, and width stays a placement option.

component_options reads back as null until an option is set, and then with every option, null for those not set:

{ "component_options": { "image": { "aspect": "4:3", "corners": "rounded" } } }

Resolution order

Each setting is resolved separately, for every passport, from the first of these that is not null:

1. the composition's design block,
2. the team's design, this resource,
3. the preset's default, where the preset is itself resolved composition first, then team, then standard,
4. the viewer's default (for font_heading and font_figures, the resolved body font).

components resolves per kind, component_options per option (with no preset step) and each part-style block per leaf (and per show part) in the same order, and a placement's own display and display_options sit above all of them. In simple mode the advanced settings skip steps 1 and 2 and resolve from the preset alone (see The mode).

Part styles

Eight objects restyle one part of the passport each: top_bar, masthead, chapters, sections, fields, figures, charts and rhythm. Every leaf is nullable and null inherits, leaf by leaf, in the resolution order. The Default column is what an unset leaf draws, which is the passport as it has always looked: nothing changes until you set a leaf. A show object holds one true or false per part and null to inherit; every part shows by default.

The mode

mode decides whether the advanced settings apply. In simple the passport resolves color_mode, colors, font_figures, labels, hero, frames, shadow, components, component_options and every part-style leaf from the preset alone and ignores what is stored; in advanced every layer applies. Switching never deletes a value, so going back to advanced brings the stored ones back.

Each design, the team's and each composition's, has its own mode: the mode it stores, or, when that is null, advanced if it stores an advanced setting. An advanced setting is any of those listed above but shadow and font_figures (every older save stores a shadow, and picking a preset writes the figures face). A composition's mode wins over the team's, and only a winning simple gates anything:

• A composition that sets frames, hero, components, a part style or another advanced setting is advanced unless it says mode: "simple", even over a team in simple, and its settings apply. Like a composition set to advanced, it also brings back the advanced values the team has stored.
• A composition with no advanced setting and no mode follows the team's mode.
• A design with no mode and no advanced setting gates nothing.

A PATCH that sets an advanced setting and no mode (left out or null) stores mode: "advanced", so what you set is what a reader sees. To store an advanced value while the team stays in simple, send mode: "simple" in the same body. The Synex Design page writes the mode it shows on every save: the one the person chose, else the one this section infers.

top_bar

masthead

chapters

sections

fields

Field lists and the table of a children card. A Field List set to the Timeline style ignores rows and dividers.

figures

Stat grids and key figures.

charts

rhythm

A block replaces wholesale

A block in a PATCH replaces the stored block: a leaf you leave out is unset afterwards. To change one leaf, send the leaves you want to keep with it. A block sent as null or {} clears it, and a block you leave out of the body is untouched.

curl -X PATCH https://api.synexcloud.com/v1/design \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chapters": {"header": "minimal"}}'

curl -X PATCH https://api.synexcloud.com/v1/design \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chapters": {"size": "l"}}'

After the second call chapters.size is l and chapters.header is null: the second body replaced the first. A show object that names one part reads back with the other parts null, and those parts show.

Retrieve the design

curl https://api.synexcloud.com/v1/design \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "design",
  "palette": [
    { "lightness": 50, "hex": "#F5F8FC" },
    { "lightness": 100, "hex": "#E7EEF8" },
    { "lightness": 200, "hex": "#C8D9F1" },
    { "lightness": 300, "hex": "#9CBCE6" },
    { "lightness": 400, "hex": "#6698DA" },
    { "lightness": 500, "hex": "#2F6FED" },
    { "lightness": 600, "hex": "#2459C4" },
    { "lightness": 700, "hex": "#1C459B" },
    { "lightness": 800, "hex": "#153472" },
    { "lightness": 900, "hex": "#0E2450" },
    { "lightness": 950, "hex": "#0A1836" }
  ],
  "rounding": 3,
  "shadow": 2,
  "logo": "file_00a1b2c3d4e5f607",
  "font": "Inter",
  "preset": "technical",
  "color_mode": "simple",
  "appearance": "dark",
  "colors": null,
  "font_heading": "DM Sans",
  "font_figures": "JetBrains Mono",
  "navigation": "chapters",
  "hero": "split",
  "frames": "framed",
  "components": {
    "image": "framed", "file": "row", "figure": null, "boolean": null,
    "tags": null, "long_text": null, "range": null
  },
  "mode": "advanced",
  "labels": "caps",
  "component_options": {
    "image": { "aspect": "4:3", "fit": null, "corners": "rounded", "backdrop": null }
  },
  "top_bar": {
    "layout": "solid", "logo_size": null,
    "show": { "logo": null, "qr": false, "language": null, "audience": null, "identity": null }
  },
  "masthead": {
    "title_size": null, "figures": "tiles",
    "image_side": null, "image_size": null, "image_frame": "inset", "image_corners": null,
    "image_fit": null, "image_focus": null, "image_backdrop": null,
    "show": { "logo": null, "ids": null, "status": null, "figures": null, "image": null, "explore": null }
  },
  "chapters": {
    "header": "numeral", "size": null, "index": null, "tabs": null,
    "show": { "number": null, "icon": false, "divider": null }
  },
  "sections": { "header": null, "size": null, "gallery_columns": "2", "show": { "description": null } },
  "fields": { "rows": null, "dividers": null, "density": null },
  "figures": { "look": null, "size": null, "unit": null, "corners": null },
  "charts": { "colors": null, "grid": null, "legend": null, "bars": null },
  "rhythm": { "spacing": null, "width": null }
}

{
  "object": "design",
  "palette": [],
  "rounding": null,
  "shadow": null,
  "logo": null,
  "font": null,
  "preset": null,
  "color_mode": null,
  "appearance": null,
  "colors": null,
  "font_heading": null,
  "font_figures": null,
  "navigation": null,
  "hero": null,
  "frames": null,
  "components": null,
  "mode": null,
  "labels": null,
  "component_options": null,
  "top_bar": {
    "layout": null, "logo_size": null,
    "show": { "logo": null, "qr": null, "language": null, "audience": null, "identity": null }
  },
  "masthead": {
    "title_size": null, "figures": null,
    "image_side": null, "image_size": null, "image_frame": null, "image_corners": null,
    "image_fit": null, "image_focus": null, "image_backdrop": null,
    "show": { "logo": null, "ids": null, "status": null, "figures": null, "image": null, "explore": null }
  },
  "chapters": {
    "header": null, "size": null, "index": null, "tabs": null,
    "show": { "number": null, "icon": null, "divider": null }
  },
  "sections": { "header": null, "size": null, "gallery_columns": null, "show": { "description": null } },
  "fields": { "rows": null, "dividers": null, "density": null },
  "figures": { "look": null, "size": null, "unit": null, "corners": null },
  "charts": { "colors": null, "grid": null, "legend": null, "bars": null },
  "rhythm": { "spacing": null, "width": null }
}

Update the design

curl -X PATCH https://api.synexcloud.com/v1/design \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "color_mode": "advanced",
    "colors": {"background": "#0b1220", "text": "#e6edf7", "accent": "#4f8cff"},
    "components": {"figure": "meter"},
    "charts": {"bars": "square"}
  }'

{
  "object": "design",
  "palette": [
    { "lightness": 50, "hex": "#F5F8FC" },
    { "lightness": 100, "hex": "#E7EEF8" },
    { "lightness": 200, "hex": "#C8D9F1" },
    { "lightness": 300, "hex": "#9CBCE6" },
    { "lightness": 400, "hex": "#6698DA" },
    { "lightness": 500, "hex": "#2F6FED" },
    { "lightness": 600, "hex": "#2459C4" },
    { "lightness": 700, "hex": "#1C459B" },
    { "lightness": 800, "hex": "#153472" },
    { "lightness": 900, "hex": "#0E2450" },
    { "lightness": 950, "hex": "#0A1836" }
  ],
  "rounding": 3,
  "shadow": 2,
  "logo": "file_00a1b2c3d4e5f607",
  "font": "Inter",
  "preset": "technical",
  "color_mode": "advanced",
  "appearance": "dark",
  "colors": {
    "background": "#0b1220", "text": "#e6edf7", "muted": null,
    "rule": null, "surface": null, "accent": "#4f8cff"
  },
  "font_heading": "DM Sans",
  "font_figures": "JetBrains Mono",
  "navigation": "chapters",
  "hero": "split",
  "frames": "framed",
  "components": {
    "image": null, "file": null, "figure": "meter", "boolean": null,
    "tags": null, "long_text": null, "range": null
  },
  "mode": "advanced",
  "labels": "caps",
  "component_options": {
    "image": { "aspect": "4:3", "fit": null, "corners": "rounded", "backdrop": null }
  },
  "top_bar": {
    "layout": "solid", "logo_size": null,
    "show": { "logo": null, "qr": false, "language": null, "audience": null, "identity": null }
  },
  "masthead": {
    "title_size": null, "figures": "tiles",
    "image_side": null, "image_size": null, "image_frame": "inset", "image_corners": null,
    "image_fit": null, "image_focus": null, "image_backdrop": null,
    "show": { "logo": null, "ids": null, "status": null, "figures": null, "image": null, "explore": null }
  },
  "chapters": {
    "header": "numeral", "size": null, "index": null, "tabs": null,
    "show": { "number": null, "icon": false, "divider": null }
  },
  "sections": { "header": null, "size": null, "gallery_columns": "2", "show": { "description": null } },
  "fields": { "rows": null, "dividers": null, "density": null },
  "figures": { "look": null, "size": null, "unit": null, "corners": null },
  "charts": { "colors": null, "grid": null, "legend": null, "bars": "square" },
  "rhythm": { "spacing": null, "width": null }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Pick one of: plain, captioned, framed, file.",
    "param": "components.image",
    "errors": {
      "components.image": ["Pick one of: plain, captioned, framed, file."]
    }
  }
}

That body named four settings, applied to the design from Retrieve the design. The other twenty-two kept whatever they held. colors lists all six roles, with muted, rule and surface null (derived when the passport is drawn). components and charts were replaced: image and file were set before and are null now, and bars is the only chart leaf left.

Events

A successful PATCH emits design.updated. Its payload is byte-identical to the response you just received, so a consumer on the change feed sees the same theme the caller does, with no follow-up read.

There is no design.created. The singleton always exists, so there is no moment of creation to report.