Themes and branding

A scorecard’s look is two independent layers.

The theme sets its personality: typography, corner radius, shadow, texture and motion. The brand palette sets its colours. Choosing a theme does not lock a palette, and setting a palette does not change the typography — so pick the theme for your audience, then tune the colours to your brand.

The four themes

default

Neutral system sans, moderate radius, conventional card shadows. No opinion of its own.

Use it when the scorecard is embedded in an existing site and should not fight the surrounding design, or when your brand palette is doing all the work.

playground

Bubbly and candy-coloured. Nunito and Quicksand, generous radius, floating defocused emoji in the background, bouncy spring transitions.

Use it for consumer audiences, self-assessments meant to feel light, and anything likely to be shared socially. This is the default for a new scorecard.

Avoid it when the subject is serious — money, health, risk, redundancy. The bounce reads as flippant.

obsidian

Editorial and premium. Instrument Serif display over DM Sans body, glass-morphism cards, subtle grain, restrained motion.

Use it for executive and leadership diagnostics, consultancies, high-ticket B2B — anything where the reader is deciding whether you are worth their time.

Avoid it when your audience is technical and allergic to anything that looks like a brochure.

brutalist

Raw and high-contrast. Space Mono and JetBrains Mono, zero corner radius, hard offset black shadows, an acid-green accent, instant transitions with no easing.

Use it for developer tools, security and infrastructure audits, and agencies with a strong visual point of view — audiences who read monospace as a signal of substance.

Avoid it when your palette matters: this theme fixes its own card surfaces and accent, so brand colours move less here than elsewhere.

Choosing between them

Ask what the respondent is doing thirty seconds before they land on your scorecard, and thirty seconds after they finish. A CTO evaluating a consultancy and a marketer clicking a LinkedIn link want different rooms.

When you are torn between two, pick the quieter one. The questions carry the experience, not the chrome.

Your plan decides which are available

Themes are gated by plan. If you set one your plan does not include, the write is refused and the error names the ones you can use. An AI assistant asking scorecard_design_guide about themes is told which are available on your account, so it will not recommend one you cannot have.

The brand palette

Ten colours, each a hex value:

Key	Where it shows
primary	Buttons, progress, the accent that carries the flow
primaryForeground	Text and icons sitting on primary
accent	Sparing emphasis
background / backgroundDark	The page behind everything
surface / surfaceDark	Cards and raised panels
text / textDark	Body copy
muted	Secondary copy

The *Dark values are used in dark mode. Set them deliberately rather than inverting the light palette — inverting usually produces something muddy.

The one thing worth checking by eye: primaryForeground has to be legible on primary, and text on background, at normal body size. That is the most common thing wrong with a custom palette.

Setting it

In the admin, both live on the scorecard’s edit screen.

From an AI assistant, both go through update_scorecard_config:

{
  "slug": "leadership-check",
  "theme": "obsidian",
  "branding": {
    "colors": { "primary": "#2563eb", "primaryForeground": "#ffffff" }
  }
}

Ask for the previewUrl afterwards — every draft returns one, and it renders the real thing before anything is published. The choose_theme prompt walks through this conversation if your client supports MCP prompts.