Theming

The SDK accepts an appearance configuration — a constrained set of variables like brand color and corner radius — so the hosted verification flow can read as part of your product rather than a third-party redirect.

Appearance values are validated against an allowlist before they ever reach the rendered flow, so a malformed or out-of-range value fails fast in your integration instead of silently rendering broken.

How appearance is applied

appearance rides the session mint, not the browser. You can pass it server-side (the appearance field of POST /v1/verification-sessions) or through the SDK’s create({ appearance }); either way PersonaBlocks validates it against a strict allowlist before it reaches the flow. Validation is all-or-nothing:

An unknown key, selector, or property → 400 invalid_appearance, and the response names the exact offending key (for example variables.colorBrand for an unknown variable, or theme for an unsupported preset).
An appearance object larger than 8192 bytes → 400 appearance_too_large.

There is no sanitize-and-continue path: one bad key rejects the whole object.

`theme`

theme selects a preset base that the rest of your appearance layers on top of. It must be one of 'light', 'dark', or 'minimal'.

`variables`

variables is a flat map of design tokens. Every key must be one of these 23 names — any other name is rejected.

Colors

Variable	Purpose
`colorPrimary`	Primary brand / accent color.
`colorBackground`	Surface background color.
`colorText`	Default body text color.
`colorTextSecondary`	Muted / secondary text color.
`colorDanger`	Error and destructive-state color.
`colorSuccess`	Success-state color.
`accessibleColorOnColorPrimary`	Foreground color used on top of `colorPrimary` (contrast pair).

Typography

Variable	Purpose
`fontFamily`	Font stack for the flow.
`fontSizeBase`	Base font size.
`fontWeightNormal`	Normal text weight.
`fontWeightBold`	Bold / emphasis weight.

Spacing and radius

Variable	Purpose
`spacingUnit`	Base spacing unit that layout scales from.
`borderRadius`	Global corner radius.
`buttonBorderRadius`	Corner radius for buttons specifically.

Components

Variable	Purpose
`focusBoxShadow`	Focus-ring box shadow.
`inputColorBorder`	Input border color at rest.
`inputFocusColorBorder`	Input border color on focus.
`colorBackgroundButtonPrimaryHover`	Primary button background on hover.
`colorBackgroundButtonPrimaryActive`	Primary button background while pressed.
`colorBackgroundSurfaceModal`	Modal / dialog surface background.

Camera

Variable	Purpose
`colorCameraOverlay`	Dimming overlay around the camera frame.
`colorCameraGuide`	Capture guide / outline color.

Logo

Variable	Purpose
`logoUrl`	Your logo. Must be an `https://` URL, 2048 characters or fewer.

`rules`

For finer control, rules maps a component selector to a set of camelCase CSS properties. Selectors are strictly limited to these 10 documented component classes:

.Button, .Button--primary, .Input, .Input--invalid, .Label, .Error, .Step, .ProgressBar, .CameraFrame, .Modal

A selector may carry one optional pseudo-class suffix — :hover, :focus, :focus-visible, :active, or :disabled (for example .Button--primary:hover). Chained pseudo-classes, descendant combinators, attribute selectors, and bare element/id/universal selectors are all rejected.

Property names come from the 62-property CSS allowlist — purely visual box, typography, and color properties, written in React camelCase (backgroundColor, not background-color). Common ones include color, backgroundColor, border, borderRadius, boxShadow, padding, margin, fontFamily, fontSize, fontWeight, textAlign, and opacity. Anything that could break layout or escape a component’s box — position, content, filter, zIndex, pointerEvents, and any url() value — is rejected.

A worked example

{
  "theme": "light",
  "variables": { "colorPrimary": "#0F4D92", "borderRadius": "8px", "fontFamily": "Inter, sans-serif" },
  "rules": { ".Button--primary:hover": { "backgroundColor": "#0a3364" } }
}

This sets a light base, overrides the brand color, corner radius, and font, and darkens the primary button on hover. Pass the same object to create({ appearance }) or to the session-mint API’s appearance field.