Widget Theming & Design Tokens

Customize widget appearance with design tokens — colors, fonts, border radius, and more — using the styles JSON attribute.

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

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

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.