# Customization for ID Capture v2

You can customize the appearance of the SDK by setting colors and fonts. This can be done in two ways: through a JSON configuration file or using code.

## Customization Through JSON

You can define appearance settings in a JSON file and load it during initialization:

> **Note:** If you are already using themes loaded from JSON, you should extend the existing JSON file with the new structure described here.

### Example JSON File

```json
{
  "displayMode": "system",
  "colorPalette": {
    "neutralLight": "#FFFFFF",
    "neutralDark": "#000000",
    "brand50": "#E5FFF0",
    "brand200": "#99FFC3",
    "brand300": "#66FFA6",
    "brand400": "#33FF88",
    "brand500": "#00FF6A",
    "brand600": "#00CC55",
    "brand900": "#213B27",
    "gray50": "#FCFDFC",
    "gray100": "#EBEFEC",
    "gray150": "#D9DAE1",
    "gray200": "#C6D2C8",
    "gray250": "#B5B8C5",
    "gray300": "#A3B8A8",
    "gray400": "#82879A",
    "gray500": "#607C66",
    "gray600": "#4D5264",
    "gray700": "#3A4B3E",
    "gray750": "#30333E",
    "gray800": "#263128",
    "gray900": "#141A15",
    "gray1000": "#000000",
    "brandSecondary50": "#F2FEE2",
    "brandSecondary500": "#82D10A",
    "negative50": "#FFF0F0",
    "negative400": "#FF5F5A",
    "negative500": "#E71111",
    "negative950": "#240100",
    "warning50": "#FFEBF7",
    "warning400": "#FF47B6",
    "warning500": "#FF0099",
    "warning950": "#520031",
    "positive50": "#E4F0FB",
    "positive500": "#18609F",
    "positive950": "#0C3050"
  },
  "typography": {
    "family": {
      "text": {
        "ios": {
          "regular": "Helvetica",
          "medium": "Helvetica-Medium",
          "bold": "Helvetica-Bold"
        },
        "android": {
          "regular": "some font"
        }
      },
      "display": {
        "ios": {
          "extraBold": "Helvetica-Black"
        },
        "android": {
          "extraBold": "some font"
        }
      }
    },
    "letterSpacing": {
      "none": 0,
      "medium": -0.5,
      "large": -1.0,
      "extraLarge": -1.5
    }
  }
}
```

### Loading the JSON File

```swift
if let path = Bundle.main.path(forResource: "AppearanceConfig", ofType: "json"),
   let jsonString = try? String(contentsOf: URL(fileURLWithPath: path)) {
    IncdTheme.loadJsonTheme(jsonString)
}
```

## Customization Through Code

Use the API in code to set colors and fonts programmatically:

### Setting Colors

```swift
IncdTheme.colorPalette = .init(
    neutral: UIColor.white,
    black: UIColor.black,
    brand50: UIColor.red,
    // ...
)
```

### Setting Fonts

```swift
IncdTheme.typography = .init(
    family: .init(
        text: .init(regular: "Helvetica", medium: "Helvetica-Medium", bold: "Helvetica-Bold"),
        display: .init(extraBold: "Helvetica-ExtraBold")
    ),
    letterSpacing: .init(
        none: 0,
        medium: -0.5,
        large: -1.0,
        extraLarge: -1.5
    )
)
```

### Setting Display Mode

```swift
IncdTheme.displayMode = .system // or .light, .dark
```

## About Colors

The color scheme is based on the palette, which consists of colors that can be overridden:

- `neutralLight`
- `neutralDark`
- `brand50`
- `brand200`
- `brand300`
- `brand400`
- `brand500`
- `brand600`
- `brand900`
- `gray0`
- `gray50`
- `gray100`
- `gray150`
- `gray200`
- `gray250`
- `gray300`
- `gray400`
- `gray500`
- `gray600`
- `gray700`
- `gray750`
- `gray800`
- `gray900`
- `gray1000`
- `brandSecondary50`
- `brandSecondary500`
- `negative50`
- `negative400`
- `negative500`
- `negative950`
- `warning50`
- `warning400`
- `warning500`
- `warning950`
- `positive50`
- `positive400`
- `positive500`
- `positive750`
- `positive950`

### Color Format

In the JSON configuration file, colors should be specified in hex with the format `#RRGGBB` or `#AARRGGBB`.

## About Fonts

The typography system is based on font families, which can include the following optional styles:

- `regular`
- `medium`
- `bold`
- `extraBold`

### Text Fonts

For `text`, the following styles are currently used:

- `regular`
- `medium`
- `bold`

### Display Fonts

For `display`, the following style is used:

- `extraBold`

By default, these styles can be set using the `Family` structure in the JSON configuration file or programmatically in the code.

## About Display Mode

The display mode controls whether the SDK uses light or dark UI appearance. It works in conjunction with your color palette to provide appropriate theming.

### Available Options:

- `.light` (default) - Forces light appearance regardless of system settings
- `.dark` \- Forces dark appearance regardless of system settings
- `.system` \- Automatically adapts to the device's system appearance setting

## About Components

The `components` section in the JSON configuration allows you to customize specific UI components beyond the base color palette and typography. Currently, component-level customization is available for buttons.

### Components JSON Structure

```json
"components": {
  "buttons": [
    {
      "style": "primary",
      "surface": {
        "default": ["#00FF6A", "#00CC55"],
        "pressed": "#00CC55",
        "disabled": ["#C6D2C8", "#3A4B3E"]
      },
      "text": {
        "default": ["#FFFFFF", "#141A15"],
        "disabled": "#607C66"
      }
    },
    {
      "style": "secondary",
      "surface": {
        "default": ["#EBEFEC", "#263128"],
        "pressed": "#C6D2C8",
        "disabled": ["#FCFDFC", "#141A15"]
      },
      "text": {
        "default": ["#000000", "#FFFFFF"],
        "disabled": "#A3B8A8"
      }
    }
  ]
}
```

### Button Styles

Each entry in the `buttons` array describes the appearance of a button style:

- `style`: The button style identifier. Supported values:
  - `"primary"`
  - `"secondary"`
- `surface`: Colors used for the button surface (background) in different control states:
  - `default`
  - `pressed` (optional)
  - `disabled` (optional)
- `text`: Colors used for the button title in different control states (same keys as `surface`).
- `border`: Border configuration for the button:
  - `color`: Optional state-based colors for the border, with the same structure as `surface`.
  - `width`: Border width in points.
  - `radius`: Corner radius in points.

For `surface`, `text`, and `border.color` state values, you can use either:
- A single color value (for example, `"#000000"`) that applies to both light and dark modes.
- An array of up to two color values (for example, `"#000000", "#E8E8E8"`), where:
  - The first value is used in light mode.
  - The second value (if present) is used in dark mode. If omitted, the light color is reused in dark mode.

If a particular state, color, or button style is not defined in `components`, the SDK falls back to the default appearance derived from the base `colorPalette` and `typography`.

## Logo

We support the ability for you to use your own logo image which is shown on some of the onboarding screens. To achieve this, name your image `incdOnboardingLogo` and place it in your app’s asset catalog (usually called `Assets.xcassets`). The image will resize to fit 35pt height.

To hide the logo shown on some screens please create a fully transparent image, name it `incdOnboardingLogo` and place it in your app’s asset catalog.

## UX Configuration

In addition to visual theming, you can customize the user experience behavior through UX configuration. This allows you to control the positioning of UI elements and interaction patterns.

### UX Configuration Through JSON

You can define UX settings in a JSON file and load it during initialization:

#### Example UX Configuration JSON

```json
{
  "closeButtonPosition": "topRight",
  "helpButtonPosition": "bottomRight",
  "realtimeFeedbackMessageUIFlavor": "minimal",
  "showFooter": true,
  "headerAlignment": "center"
}
```

#### Loading UX Configuration

```swift
if let path = Bundle.main.path(forResource: "IncdUXConfig", ofType: "json"),
   let jsonString = try? String(contentsOf: URL(fileURLWithPath: path)) {
    IncdUXConfig.loadUXConfig(jsonString)
}
```

### UX Configuration Options

#### Close Button Position

Controls where the `X` (close) button appears on screens:
- `"topRight"` (default) - Close button in the top-right corner
- `"topLeft"` \- Close button in the top-left corner

#### Help Button Position

Controls where the help button appears on ID Capture V2 screens:
- `"bottomRight"` (default) - Help button in the bottom-right corner
- `"topRight"` \- Help button in the top-right corner
- `"topLeft"` \- Help button in the top-left corner

#### Realtime Feedback Message UI Flavor

Controls the style of realtime feedback messages in ID Capture V2:
- `"standard"` (default) - Full feedback messages with detailed information
- `"minimal"` \- Simplified, minimal feedback messages

#### Show Footer

Controls whether the "Verified by Incode" footer is displayed:
- `true` (default) - Footer is visible
- `false` \- Footer is hidden

#### Header Alignment

Controls the alignment of header content on certain screens:
- `"center"` (default) - Header content is center-aligned
- `"start"` \- Header content is left-aligned
- `"end"` \- Header content is right-aligned

## Animation Theming

The SDK uses Lottie animations throughout its UI. These animations are automatically tinted to match your brand color (`brand500` in the color palette). This ensures animations visually integrate with the rest of your themed experience without any additional work.

The following elements are tinted with your `brand500` color:
- Tutorial illustrations (ID scan, passport scan, selfie)
- Document chooser icons (ID card, passport, digital ID)
- Realtime capture feedback icons (alignment, blur, glare, lighting)
- Loading spinners

If you change `brand500` — whether via JSON or code — all animations update automatically.

## Replace Lottie Animations

You can replace the default animations used by the SDK with your own. To do so, add a Lottie file (`.json` or `.lottie`) with the matching name to your app bundle.

### Tutorial animations

These animations are shown before capture begins. They are replaceable:
| Animation name | Shown before |
| --- | --- |
| `id_scan_tutorial` | Front side ID scan |
| `id_back_scan_tutorial` | Back side ID scan |
| `passport_scan_tutorial` | Passport scan |
| `tutorial_selfie_v2` | Selfie / face enrollment |

Place a file named `id_scan_tutorial.json` (or `.lottie`) in your app bundle to override the default. The same applies for the other names.

### Processing animation

| Animation name | Where it appears |
| --- | --- |
| `incode-processing-animation` | Generic processing / loading screens |

### Static icons

Document chooser icons (`chooserId2`, `chooserPass2`, `chooserDigitalId`) use Lottie internally but are **not replaceable with custom Lottie files**. To customize these icons, provide a static image asset (PNG, PDF, or SVG) with the same name in your app's asset catalog. The SDK will use your image instead of the animated icon.