Theming

The SDK ships a light and a dark theme and follows the visitor’s OS preference by default. Everything visible — buttons, comment pins, panels, backgrounds, badges, the placement cursor — is driven by CSS custom properties, so you can restyle the whole surface without forking any CSS.

There are two ways to do it. They compose, and you can use either or both.

Option 1 — CSS custom properties

Set any --markup-* property anywhere in your page. Values inherit into the SDK’s UI and into the comment pins the SDK anchors into your DOM.

:root {
    --markup-primary-color: #7c3aed;
    --markup-radius: 10px;
}

That single brand property themes the toolbar’s primary button, comment pins, and the placement cursor together, because they all resolve through it.

Set these on :root or html. Both trees the SDK renders into see them from there: the Shadow UI also picks them up from any ancestor of its container, but comment pins and the placement cursor live in your own DOM and resolve at :root, so a property set lower down — on body, or on a wrapper — reaches the toolbar and leaves the pins on their defaults. (If you also pass the theme option, see Precedence: a token set there is overridden from #markup-sdk-root rather than from html.)

These are the same six white-label properties the MarkUp web app honours (--markup-primary-color, --markup-primary-hover, --markup-primary-active, --markup-selected-pin-color, --markup-text-on-fill-color, --markup-text-on-selected-pin-color). If you already white-label MarkUp, your SDK embed picks up the same configuration.

Option 2 — the theme option

Pass a theme object to render(). This is the recommended path: values are validated, and text colours are contrast-corrected automatically.

import {MarkUpSDK} from "@ceros-dev/markup-sdk/ui";
 
const markup = MarkUpSDK.init({publicKey: "<YOUR_PUBLIC_KEY>", markupId: "<YOUR_MARKUP_ID>"});
 
markup.render({
    theme: {
        mode: "auto",
        tokens: {
            primary: "#7c3aed",
            radius: "10px",
            pinBackground: "#7c3aed"
        },
        dark: {
            primary: "#a78bfa"
        }
    }
});

The string shorthand still works and is equivalent to passing only mode:

markup.render({theme: "dark"});

Matching your app’s user colours

Avatar colours are chosen per user, so they cannot be custom properties. By default the SDK hashes the user’s id into avatarPalette. If your app already assigns each user a colour — from your own hash, or from a setting they picked — supply it with avatarColor and the SDK will use yours instead:

import type {AvatarColorResolver} from "@ceros-dev/markup-sdk/ui";
 
const avatarColor: AvatarColorResolver = ({email}) => (email ? (mySettings[email]?.color ?? myHash(email)) : undefined);
 
markup.render({theme: {avatarColor}});

The function is handed the whole user — {id, name, email} — so you can match on whichever of those your own colours are held by. Reach for email when a MarkUp user id means nothing on your side, which is the usual case: it is often the only identifier your app and MarkUp share.

This applies everywhere the SDK draws a user: comment pins, the thread panel, the popover, the toolbar presence stack and the mention menu — so a user is never shown in two different colours at once.

Points worth knowing:

• id, name and email are always strings, but any of them may be empty. id is "" for a user whose record has not loaded, and email for a guest or wherever MarkUp holds no address — so check before you key on one. The SDK’s own fallback hash uses the first of the three that is present, in that order. All three empty means there is no author to colour, and your function is not called at all — an authorless pin shows the frame colour instead.

• The address is passed through as MarkUp holds it, only trimmed. Case is not folded, since the SDK cannot know whether your own keys are. Normalise on your side if you index by a lower-cased address.

• Return nothing for users you have no colour for. undefined, null and "" all fall back to the palette hash, so you can adopt this partially.

• It must be synchronous, and it should be pure. It is called while rendering. Resolve async settings before render()/setTheme() and have the function read from what you already hold. Do not call setTheme() from inside it.

• Results are cached per user until the next setTheme(), so your function is not guaranteed to run again for a user it has already coloured. Re-passing the theme is how you publish a colour that has since changed — existing pins are recoloured in place. Keep the theme object around and pass the same one, because setTheme replaces rather than merges: calling setTheme({avatarColor}) on its own would silently drop every token override you set at render().

  const theme = {mode: "auto", tokens: {pinBackground: "#7c3aed"}, avatarColor};
   
  markup.render({theme});
  // ...later, once a user picks a new colour in your app:
  markup.setTheme(theme);

• Initials are made readable for you. The SDK derives a contrasting text colour — white or dark ink, whichever reads — for whichever fill an avatar ends up with, yours included.

• An invalid colour is ignored with a console warning, and that user falls back to the palette. So is a return value that is not a string. A function that throws is reported once and treated as no opinion.

• Screenshots and notification emails are not covered. Those pins are redrawn server-side and do not include an avatar, so they show the workspace pin colour regardless of what this returns.

One initial instead of two

An avatar without a picture falls back to the first and last initial of the user’s name — "Jane Doe" becomes "JD". Set avatarInitials to "one" for just the first letter, which reads better at pin size and matches apps that show a single letter elsewhere:

markup.render({theme: {avatarInitials: "one"}});

Points worth knowing:

• It applies to initials you supply as well as the ones the SDK derives. Pass initials="AB" to the Avatar component in a one-letter embed and it renders "A", so the setting holds everywhere rather than only where the SDK picked the letters.
• A user with no name still shows a placeholder — "?" in the panel, and nothing on a pin, where a lone "?" over the page would read as broken rather than as an unknown author.
• Avatars with a picture are unaffected, since they show no letters either way.
• An unrecognised value is ignored with a console warning and the default is kept. 1 and "single" are the easy mistakes, and treating either as “not two” would empty every avatar in the embed.

Changing the theme at runtime

setTheme() accepts the same shorthand and object forms. It replaces the active theme rather than merging into it, so pass the whole theme each time — that way removing a token is possible.

markup.setTheme({mode: "dark", tokens: {primary: "#a78bfa"}});
markup.setTheme("light");

Automatic contrast

Set a fill without its matching foreground and the SDK derives a readable one for you, using the WCAG relative-luminance formula to choose between white and its dark ink.

// Pale brand colour: white label text would be unreadable, so dark ink is used instead.
markup.render({theme: {tokens: {primary: "#f5f5c0"}}});

Set primaryForeground explicitly to opt out. If neither white nor dark ink can reach WCAG AA (4.5:1) against your fill, the SDK logs a warning — at that point only a different fill can fix it.

Every fill token with a text-on-top counterpart is paired this way: primary, destructive, success, warning, pinBackground, pinSelectedBackground, and pinResolvedBackground.

Which option should I use?

Prefer the theme option. CSS has no way to reject a bad value, and a bad value does not fall back to the default — a property that is defined but invalid drops the declaration to its initial value, which for a background is transparent. One typo in a stylesheet can make a button invisible. The theme option validates every value up front and ignores (with a warning) anything the browser would reject.

Validation is per token: primary must be a colour, radius a length, shadowMd a shadow, fontFamily a font stack, and so on. A rejected value leaves that token at its default and warns on the console — the rest of the theme still applies. An unrecognised mode warns and falls back to auto.

If you pass theme values through from configuration you do not control — a tenant’s branding record, say — this validation is also what stops them injecting arbitrary CSS into your page.

Use CSS when you want zero build-time coupling, or when your brand colours already live in your own stylesheet.

Precedence

Highest to lowest:

1. Your CSS on the SDK root — #markup-sdk-root { --markup-primary: … }
2. The theme option
3. Your ordinary CSS on :root or html (or, for the Shadow UI only, any ancestor of its container)
4. The SDK defaults

The SDK renders into two trees, and that shapes rung 1. The parts that live in your DOM — comment pins, the placement cursor, the element highlighter — resolve their tokens from :root, so ordinary !important on html/:root reaches them. The Shadow UI (toolbar, panels, popovers) resolves from the #markup-sdk-root element, and the theme option declares its values there. A declared value beats an inherited one regardless of importance, so for a token you set via theme, html { … !important } will change your pins but not the toolbar.

Targeting #markup-sdk-root overrides both consistently, and it does not need !important — ordinary CSS on that element already outranks the theme option:

#markup-sdk-root {
    --markup-primary: #7c3aed;
}

Use !important there only if something else in your page is also targeting that element.

Dark mode

mode: "auto" follows prefers-color-scheme. Overrides you supply apply on top of whichever mode is active, so a custom primary stays yours in both. Use the light and dark keys when you want different values per mode.

markup.render({
    theme: {
        mode: "auto",
        tokens: {radius: "10px"}, // both modes
        light: {primary: "#4c1d95"}, // light only
        dark: {primary: "#c4b5fd"} // dark only
    }
});

Token reference

theme.tokens keys are the camelCase form of each CSS property name — --markup-pin-background becomes pinBackground. Tokens with no dark value use the light value in both modes.

Where a property lists aliases, any of them works; the first is canonical.

Brand

Surfaces & text

Status

Borders

Thread priority

Pins & cursor

Avatar pins

These apply only when you opt into the avatar pin variant:

markup.render({pinVariant: "avatar"});

In that variant a pin is a teardrop framing the thread author’s avatar, anchored by its point rather than its centre. The avatar’s own fill is picked per user in JavaScript (theme.avatarPalette / theme.avatarColor), so it is not a token, and its initials are coloured automatically for contrast against whichever fill they land on.

There are no avatar-specific token keys. The variant is themed through the same keys as the numbered pin — pinBackground recolours whichever pin you render. Only the defaults differ, since the two are different shapes:

In the avatar variant pinSelectedBackground is the accent: the ring around a selected pin and the fill of the draft pin that marks the spot while a comment is written — not only a background. The numbered variant’s draft pin takes pinBackground, the same fill as its numbered discs. cursorInk is what the placement cursor is outlined and cross-hatched in.

One caveat: the legacy white-label aliases (--markup-primary-color and friends) set the numbered variant’s pin and cursor colours only. They exist for compatibility with the MarkUp web app’s brand-filled pin, and applying a brand fill to the avatar variant would flatten the teardrop-and-ring construction it depends on. Use pinBackground to theme the avatar variant.

pinRadius is the per-corner shorthand that makes the teardrop; the 0 corner is the one that sits on the anchor point. Set it to 50% for a plain circular avatar pin.

pinForeground colours the numbered pin’s number and, in both variants, the priority-badge glyph. It does not colour avatar initials: those are derived for contrast against each user’s own fill — white or dark ink, whichever reads — because a single fixed colour cannot stay legible across a palette of fills. The same is true of avatars in the panel, popover, toolbar and mention menu, so there is no token for them.

pinRing applies to the numbered variant only. The avatar variant’s selection ring takes pinSelectedBackground, and its frame pinBackground — a circular ring cannot be made concentric with a teardrop, so the variant draws its own.

pinBackground is the one avatar default that changes with the mode: the teardrop carries the page’s own surface colour — #fcfcfd in light, #222425 in dark — so the frame keeps holding the avatar apart from whatever is behind it. The variant’s other defaults do not change between modes; the design specifies a single pin that reads on either. Set any of them per mode through theme.light / theme.dark.

pinBackground colours both the teardrop and the ring the avatar carries inside it, which is what makes them read as one band. The variant’s states are:

pinResolvedBackground colours the resolved state of both variants.

Keyboard focus draws the same ring as selection. On Safari below 15.4, which does not support :focus-visible, the focus ring is absent but every other state is unaffected.

The variant also brings its own placement cursor — a light bubble outlined in ink rather than the numbered variant’s brand-filled disc. Both read cursorFill and cursorInk; only the defaults differ.

Pin priority badges

Typography

Spacing

Radius

Elevation

Focus

Motion

Layering

Sizing

Limits

• The placement cursor is an SVG data: URI, and a data URI cannot read CSS custom properties. The SDK resolves --markup-cursor-fill in JavaScript and regenerates the cursor whenever the theme changes — on setTheme(), and on an OS light/dark flip under mode: "auto" — so both channels work. A mid-session change made by editing a stylesheet from devtools will not repaint it until setTheme() runs.
• Size tokens take absolute lengths only. Percentages are rejected by the theme object (32px, 2rem and calc() over absolute lengths are all fine). The pins and the comment composer are positioned by the SDK in JavaScript against a zero-sized wrapper, so a percentage has nothing meaningful to resolve against: --markup-pin-size: 50% rendered a 4px sliver of a pin. Setting one through raw CSS is not validated and will do exactly that.
• Avatar colours and initials are decided per user in JavaScript rather than CSS, so there is no custom property for either. Use theme.avatarPalette to change the set of colours, theme.avatarColor to decide each one — see Matching your app’s user colours — and theme.avatarInitials to show one letter instead of two.
• Modern colour syntax (oklch(), color(), color-mix()) is not usable: the SDK supports Chrome 90+, Firefox 88+, Safari 14+, and those predate it. Use hex, rgb(), or hsl().