> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```html theme={"system"}
<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.

```html theme={"system"}
<!-- 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](/v2/docs/card-widgets-reveal).

| 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:

<CodeGroup>
  ```html Activate Card theme={"system"}
  <activate-card
    token="your-token"
    env="production"
    styles='{
      "primaryColor": "#7c3aed",
      "fontFamily": "Inter, sans-serif"
    }'
  ></activate-card>
  ```

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

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

  ```html Reveal PIN theme={"system"}
  <reveal-pin
    token="your-token"
    env="production"
    styles='{
      "primaryColor": "#7c3aed",
      "fontFamily": "Inter, sans-serif"
    }'
  ></reveal-pin>
  ```
</CodeGroup>

### Full Customization

Override both semantic tokens and component-level tokens:

```html theme={"system"}
<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

```html theme={"system"}
<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:

```html theme={"system"}
<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"`:

```html theme={"system"}
<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.