Theming

You can match the verification flow to your brand. There are two layers, and they compose:

1. Dashboard themes — configured per organization in the Zyphe dashboard and saved. A theme defines light and dark color sets, a shared border radius, an optional custom font, and a logo. Each flow either selects a theme or uses the organization default.
2. SDK overrides — colors and border radius passed when you build a verification session URL. These override the configured theme for that session only, without changing anything saved in the dashboard.

Use the dashboard for your standing brand, and SDK overrides when a single integration needs different colors (for example, embedding the flow inside a host app that already has its own palette).

Managing themes in the dashboard

Themes live in the dashboard under Settings → Themes. From the organization sidebar, open Settings, then select the Themes tab (you need the Manage organization permission to see it). This page lists your themes and lets you create, edit, delete, and set a default.

Sandbox and production are separate

Themes are scoped to the environment you are in: your sandbox themes and your production themes are two independent lists. Switching the dashboard between sandbox and production shows a different set of themes, and editing a theme in one environment never affects the other.

To avoid rebuilding a theme twice, design it in one environment and then copy it across. On any theme row, use the copy action — labelled Copy to production when you are in sandbox (and Copy to sandbox when you are in production). This duplicates the theme into the other environment as a new theme ({name} (copy)), which you can then rename or set as the default there.

Default theme and per-flow overrides

Every organization has one default theme, marked Default in the list. Any flow that hasn't been given a specific theme renders with the default. To change which theme is the default, open the theme's actions menu and choose Set as default.

To override the theme for a single flow:

1. Go to the Flows page and open the flow's Flow configuration dialog.
2. In the Theme dropdown, pick the theme this flow should use.
3. Save.

A flow keeps inheriting the organization default until you explicitly pick a theme here; once set, that flow always renders with the chosen theme (in the matching environment). Because theme selection is per environment, a flow resolves its theme from the sandbox or production theme list depending on where the session runs.

Theme tokens

A theme is built from a small set of tokens, each available for light and dark mode:

Token	What it controls
background	The page background behind the flow card
accent	The primary action color — buttons, icons, links, and highlights
card	The surface the flow card is drawn on

Plus mode-agnostic tokens:

Token	What it controls
borderRadius	Shared corner radius applied to cards, buttons, and inputs
font	A self-hosted custom font (.woff2) — dashboard only
logo	A per-mode logo shown in the flow header — dashboard only

Text colors are derived automatically for readability: the label color on an accent button and the text on a card are computed to contrast with their background, so you only set the surface colors.

The custom font and logo can only be set in the dashboard — they are not overridable through the SDK.

SDK overrides

Pass any of these on the opts object of constructVerificationSessionUrl (and initializeZypheFlow in the browser SDK). All are optional; anything you omit falls back to the flow's configured theme.

Option	Maps to	Description
backgroundColor	light background	Page background (light mode)
accentColor	light accent	Buttons, icons, highlights (light mode)
cardColor	light card	Card surface (light mode)
darkBackgroundColor	dark background	Page background (dark mode)
darkAccentColor	dark accent	Buttons, icons, highlights (dark mode)
darkCardColor	dark card	Card surface (dark mode)
borderRadius	borderRadius	Shared radius, e.g. "12px"

Colors accept any CSS color value; we recommend hex codes. The dark-mode values apply when the flow renders in dark mode.

Example

import { constructVerificationSessionUrl } from '@zyphe-sdk/node'

const url = constructVerificationSessionUrl({
  flowParams: {
    flowId: '...',
    email: 'user@example.com',
    isSandbox: false,
  },
  verificationSession: response.data, // from createVerificationSession
  opts: {
    apiKey: '<your-api-key>',
    environment: 'production',
    // Light mode
    backgroundColor: '#ffffff',
    accentColor: '#155dfb',
    cardColor: '#ffffff',
    // Dark mode
    darkBackgroundColor: '#16181d',
    darkAccentColor: '#4f8bff',
    darkCardColor: '#1f2229',
    // Shared
    borderRadius: '12px',
  },
})

Deprecated options

Earlier SDK versions exposed primaryColor and secondaryColor. They still work for backwards compatibility but are deprecated — prefer the named options above:

Deprecated	Use instead	Notes
primaryColor	backgroundColor	Historically controlled the background
secondaryColor	accentColor	Historically controlled the accent

If both a deprecated option and its replacement are provided, the named option wins.

Building the URL manually

If you are not using the SDK, append the equivalent query parameters to the flow URL yourself. Each SDK option maps to a zyphe-prefixed parameter:

SDK option	URL parameter
backgroundColor	zypheBackgroundColor
accentColor	zypheAccentColor
cardColor	zypheCardColor
darkBackgroundColor	zypheDarkBackgroundColor
darkAccentColor	zypheDarkAccentColor
darkCardColor	zypheDarkCardColor
borderRadius	zypheBorderRadius
primaryColor (deprecated)	zyphePrimaryColor
secondaryColor (deprecated)	zypheSecondaryColor

Color values must be URL-encoded (a # becomes %23).

Forcing light or dark mode

The color overrides above define what the light and dark palettes look like. A separate parameter controls which mode the flow renders in.

Append zypheTheme to the flow URL to force the color mode for that session:

Value	Effect
light	Always render the flow in light mode
dark	Always render the flow in dark mode
system	Follow the end user's operating-system / browser preference

For example, …&zypheTheme=dark pins the session to dark mode regardless of the user's system setting. When zypheTheme is omitted, the flow follows the system preference. This parameter is independent of the color overrides — you can combine it with them (for instance, force dark and supply your darkAccentColor).

Accessibility

The accent color is rendered as a solid element (button fills) on top of card, so it should stay visually distinct from the card surface — the dashboard theme editor warns when the contrast falls below the WCAG 1.4.11 non-text threshold (3:1). When supplying colors through the SDK, pick an accent that stands out against your card, and a card/background that the auto-derived text color can sit on comfortably.