Widget Theming & Design Tokens

All Synctera card widgets support runtime theming through the styles attribute. Pass a JSON string of design tokens to customize colors, typography, border radius, and more — no widget redeployment needed.

Quick Start

Set a few brand tokens to theme any widget:

<activate-card
  token="your-token"
  env="production"
  styles='{
    "primaryColor": "#7c3aed",
    "fontFamily": "Inter, sans-serif",
    "borderRadius": "12px"
  }'
></activate-card>

The styles attribute follows the same pattern as custom-labels — a JSON string on the HTML element.

How It Works

The widget parses the JSON, resolves tokens against built-in defaults, and applies them as CSS custom properties (--gizmo-*) at runtime. Tokens propagate through the widget’s Shadow DOM and are securely bridged into PCI-compliant iframes via URL parameters at creation time.

Interaction with `theme`

The theme attribute ("default" or "night-shift") sets a base preset. The styles attribute overrides individual tokens on top of it. If both are set, styles values take precedence per-token.

<!-- Night-shift base with a custom accent color -->
<set-pin
  token="your-token"
  env="production"
  theme="night-shift"
  styles='{"primaryColor": "#f59e0b"}'
></set-pin>

Token Reference

Tokens are organized into two tiers. Tier 1 (semantic tokens) are the primary styling API — setting 5–6 of these gives you a fully branded widget. Tier 2 (component overrides) provide fine-grained control over individual elements, defaulting to their Tier 1 counterparts when not set.

Tier 1 — Semantic Tokens

Token	Type	Description
`fontFamily`	string	Font family for all text
`primaryColor`	color	Submit button, focus rings, spinner, toggle accent
`primaryColorHover`	color	Submit button hover state
`textColor`	color	Labels, titles, body text
`textColorSecondary`	color	Placeholders, muted text
`backgroundColor`	color	Widget container background
`inputBackground`	color	Input field background
`inputBorderColor`	color	Input field border
`inputBorderRadius`	size	Input field corner radius
`borderRadius`	size	Buttons, messages, containers
`errorColor`	color	Error borders and error text
`successColor`	color	Success borders and success text

Tier 2 — Component Overrides

These are optional. When not set, they inherit from Tier 1 tokens.

Token	Defaults to	Targets
`buttonBackground`	`primaryColor`	Submit button background
`buttonTextColor`	`#ffffff`	Submit button text
`buttonBorderRadius`	`borderRadius`	Submit button corners
`clearButtonBackground`	`#ffffff`	Clear/cancel button background
`clearButtonTextColor`	`textColor`	Clear/cancel button text
`clearButtonBorderColor`	`inputBorderColor`	Clear/cancel button border
`inputTextColor`	`textColor`	Text typed into inputs
`inputFocusBorderColor`	`primaryColor`	Input focus ring
`inputFontSize`	`15px`	Input text size
`labelColor`	`textColor`	Field labels
`labelFontSize`	`14px`	Field label size
`titleColor`	`textColor`	Widget title
`titleFontSize`	`18px`	Widget title size
`errorBackground`	computed	Error message background
`successBackground`	computed	Success message background

Reveal Card Tokens

These apply only to the Reveal Card Widget.

Token	Targets
`cardBackground`	Card face background (supports CSS gradient strings)
`cardTextColor`	Card overlay text (PAN, name, expiry, CVV)
`cardBorderRadius`	Card corner radius

Examples

Brand Colors Only

The simplest approach — set your primary color and font:

<activate-card
  token="your-token"
  env="production"
  styles='{
    "primaryColor": "#7c3aed",
    "fontFamily": "Inter, sans-serif"
  }'
></activate-card>

<set-pin
  token="your-token"
  env="production"
  styles='{
    "primaryColor": "#7c3aed",
    "fontFamily": "Inter, sans-serif"
  }'
></set-pin>

<reveal-card
  token="your-token"
  env="production"
  styles='{
    "primaryColor": "#7c3aed",
    "fontFamily": "Inter, sans-serif"
  }'
></reveal-card>

<reveal-pin
  token="your-token"
  env="production"
  styles='{
    "primaryColor": "#7c3aed",
    "fontFamily": "Inter, sans-serif"
  }'
></reveal-pin>

Full Customization

Override both semantic tokens and component-level tokens:

<activate-card
  token="your-token"
  env="production"
  styles='{
    "primaryColor": "#7c3aed",
    "primaryColorHover": "#6d28d9",
    "fontFamily": "Inter, sans-serif",
    "textColor": "#1e293b",
    "backgroundColor": "#f8fafc",
    "inputBackground": "#ffffff",
    "inputBorderColor": "#e2e8f0",
    "inputBorderRadius": "12px",
    "borderRadius": "12px",
    "buttonBackground": "#7c3aed",
    "buttonTextColor": "#ffffff",
    "errorColor": "#dc2626",
    "successColor": "#16a34a"
  }'
></activate-card>

Reveal Card with Custom Card Face

<reveal-card
  token="your-token"
  env="production"
  card-side="front"
  emboss-name="Jane Doe"
  last-four="4242"
  card-network="visa"
  show-toggle
  styles='{
    "primaryColor": "#7c3aed",
    "cardBackground": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
    "cardTextColor": "#ffffff",
    "cardBorderRadius": "16px"
  }'
></reveal-card>

Dark Theme with Overrides

Start from the built-in night-shift preset, then override individual tokens:

<set-pin
  token="your-token"
  env="production"
  theme="night-shift"
  styles='{
    "primaryColor": "#f59e0b",
    "primaryColorHover": "#d97706",
    "buttonBackground": "#f59e0b"
  }'
></set-pin>

Built-in Theme Presets

`default`

Light background with blue accents. This is used when theme is not set or set to "default".

`night-shift`

Dark background with purple accents. Apply with theme="night-shift":

<activate-card
  token="your-token"
  env="production"
  theme="night-shift"
></activate-card>

Notes

Unknown token keys are ignored. If you pass a key that doesn’t match a known token, it’s silently dropped.
Invalid JSON falls back to defaults. A malformed styles string logs a console warning and applies no overrides.
Token values are CSS values. Colors accept any CSS color format (#hex, rgb(), hsl(), named colors). Sizes accept px, rem, em, etc. cardBackground supports gradient strings.
Tokens apply at widget initialization. To change tokens after mount, update the styles attribute and the widget will re-apply.

Overview

Products

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Validate a Value Proposition

Widget Theming & Design Tokens

Quick Start

How It Works

Interaction with `theme`

Token Reference

Tier 1 — Semantic Tokens

Tier 2 — Component Overrides

Reveal Card Tokens

Examples

Brand Colors Only

Full Customization

Reveal Card with Custom Card Face

Dark Theme with Overrides

Built-in Theme Presets

`default`

`night-shift`

Notes

​Quick Start

​How It Works

​Interaction with theme

​Token Reference

​Tier 1 — Semantic Tokens

​Tier 2 — Component Overrides

​Reveal Card Tokens

​Examples

​Brand Colors Only

​Full Customization

​Reveal Card with Custom Card Face

​Dark Theme with Overrides

​Built-in Theme Presets

​default

​night-shift

​Notes

Quick Start

How It Works

Interaction with `theme`

Token Reference

Tier 1 — Semantic Tokens

Tier 2 — Component Overrides

Reveal Card Tokens

Examples

Brand Colors Only

Full Customization

Reveal Card with Custom Card Face

Dark Theme with Overrides

Built-in Theme Presets

`default`

`night-shift`

Notes