Branding a deployment

This page is for the operator who presents a deployment of archmax automation under another name: a customer’s, a department’s, a product’s. Everything is set in one place, the config’s branding section. There is no settings page for it, nothing is stored in the database, and no environment variable carries it, so the same image serves every brand.

What changes

Set	Where it shows
title	The browser tab, the tooltip and accessible name of the mark at the top of the icon rail, and the text of the sign-in screens (“Acme Automation cannot be reached right now”).
logoUrl, darkLogoUrl	The mark at the top of the icon rail, in place of the ax monogram, and the head of every sign-in screen. The dark logo is used in the dark theme.
colors	Every colour the interface chooses for itself: status tags, the success and failure marks, warnings, the borders on a session’s graph, the Sessions board’s bars, the pending-invitation dot, glyphs and the Chat page’s start backdrop.
appearancePalette	The tones of the seven colours authors give states and transitions in the editor, and of the colours that tell a session’s tags apart.

With a title or a logo set, the deployment still says where it comes from: the rail mark’s tooltip shows powered by archmax beneath the title, and so does every sign-in screen. Colours alone change no name.

Two things stay archmax’s whatever the section says: the boot screen (the ax monogram stepping through archmax’s colours while the page loads) and the favicon. Both are drawn before the application can read the config.

A worked example

branding:
  title: Acme Automation
  logoUrl: https://cdn.acme.example/automation-logo.svg
  darkLogoUrl: https://cdn.acme.example/automation-logo-dark.svg
  colors:
    brand: "#0b7285"
    success: "#2f9e44"
    error: "#c92a2a"
    executing: "#1971c2"
    attention: "#e8590c"
    waiting: "#868e96"
  appearancePalette:
    purple: "#6c5ce7"

Every field is optional, and anything left out keeps archmax’s. Quote every colour: YAML reads an unquoted # as the start of a comment. Restart the API after a change; the config is read once, when the process starts.

The logo

The mark sits in a small round control at the top of the rail, so a logo is drawn within about 32 × 20 pixels at its own aspect ratio, and within about 128 × 32 on the sign-in screens. A square mark or a short wordmark reads best; a long wordmark shrinks until it fits. Prefer SVG.

A logo is either of:

• An https: URL the browser can load. The page’s content security policy admits images from any https: address, so no change to the image is needed.

• The image inlined as a data: URL, so the deployment hosts nothing. Encode the file and prefix it with its type:

  printf 'data:image/svg+xml;base64,%s' "$(base64 < automation-logo.svg | tr -d '\n')"

  A large image makes a large config; keep an inlined logo to a few kilobytes.

Give a darkLogoUrl when the logo does not read on the dark theme’s near-black rail. Without one, the dark theme shows logoUrl too.

The colours

The six brand colours are named by what they mean, not by their hue, so each one recolours everything that means it at once: success turns a succeeded tag, the success tick, a state’s visited border and the finished bar together. The config reference lists what each one draws and archmax’s value.

• Tags print white text on a brand colour, so pick mid-tones rather than pale ones.
• Glyphs and text need no value of their own. A success tick or a warning triangle takes a shade derived from its colour at a lightness that reads in each theme.
• The appearance palette keeps its names. An author picks sage or purple in the editor, and workflow.yaml stores that name, so every published workflow keeps its colours. The palette sets what each name looks like on this deployment. A state card prints dark text on its colour, so keep these tones light to mid as well.

Checking the section

Branding never stops the platform from starting. A value it cannot use is left out, archmax’s own applies in its place, and the process prints one line naming the field, never its value:

[config] config (/app/config.yaml): branding.logoUrl is ignored: a logo is an https: or a data:image/ URL; the ax monogram applies
[config] config (/app/config.yaml): branding.colors.purple is ignored: "purple" is not one of the brand colours (brand, success, error, executing, attention, waiting)

Run pnpm config:env --check before a deployment to see the same lines; it exits non-zero when there are any. Once the API is running it also fetches each https: logo and logs a line for one that does not answer with an image:

[branding] branding.logoUrl could not be loaded: cdn.acme.example answered 404; the SPA shows the ax monogram instead

A browser that cannot load the logo shows the ax monogram in its place and logs a warning in its console, so a missing logo never leaves an empty corner.

Rolling back

A release older than branding does not know the section and refuses to start with it in the config. Remove branding before rolling back past the release that introduced it. Nothing else is stored, so nothing else needs undoing.