Web Form 2.0 Public Documentation
Web Form 2.0 Public Documentation
Breadcrumbs

Switching from 2.0 to 2.1

This guide explains how to move an existing profile from the legacy aspect styling (UI 2.0) to the new theme styling so your users get the redesigned 2.1 UI.

Why switch

The theme model gives you what aspect can't:

  • The redesigned 2.1 UI (theme.base = DEFAULT_V2_1).

  • Dark mode (theme.palette.dark + functionality.colorMode).

  • Per-variant typography and component-level styling (buttons, inputs, links, icons, shape, shadows).

🟨 Beta. theme and DEFAULT_V2_1 are currently beta.

The catch: you recreate the profile

aspect and theme are mutually exclusive in a profile and there is no in-place conversion. You do not edit a profile to switch - you create a new theme-based profile and point your web forms at it.

Steps

  1. Read your current aspect profile (GET /api/profiles/{id}) and note its colors, font, and base theme.

  2. Create a new profile (POST /api/profiles) with a theme section, theme.base = DEFAULT_V2_1, mapping each aspect value to its theme equivalent (table below). Carry over brand and functionality as-is.

  3. Test by creating a web form with the new profileId.

  4. Cut over - pass the new profileId when creating web forms, or mark the new profile as default.

  5. Delete the old profile once nothing references it.

Field mapping (aspect → theme)

⚠ Verify against the authoritative table on the source page before publishing.

aspect

theme

colorScheme.brand

palette.light.primary.main (+ text.primary)

colorScheme.secondary

palette.light.primary.light

colorScheme.text.primary

palette.light.primary.dark (+ text.disabled)

colorScheme.text.secondary

palette.light.text.secondary

text.fontFamily

typography.fontFamily.body

theme (base enum)

theme.base

What 2.1 adds vs ignores

  • Adds: dark palette, full typography scale, component styling, plus the 2.1-only functionality flags (cancelButton, messageForm, featuredBankGroups, finapiFooterBranding).

  • Ignores/leaves behind: anything aspect-only that has no theme equivalent - list these explicitly from the source table so customers know what won't carry over.