> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/color-customization.md).

# Color Customization

Smart Capture colors are customized in two layers, and both apply at the same time on iOS. On Android, the same visual roles exist as color resources — there is no TypeScript color API for that platform.

{% hint style="warning" %}
In React Native:

* Android: declare colors with the same resource ID in `android/app/src/main/res/values/colors.xml`. `colorCustomization` on `CerttaSmartCaptureConfiguration` is ignored.
* iOS: pass hex strings in TypeScript — `colorConfiguration` on `configureSDK(...)` for shared roles, `colorCustomization` on `open(...)` for Smart Capture tokens.
  {% endhint %}

{% tabs %}
{% tab title="Android" %}

### Overview

Smart Capture's colors are declared as regular Android color resources. To restyle the flow, declare a color with the same name in your app's `res/values/colors.xml`. See Customization for how resource overriding works.

The palette has three groups:

1. **Shared roles**: the same names as iOS `CafColorConfiguration`.
2. **Smart Capture tokens**: the same names as iOS `CerttaSmartCaptureColorCustomization`.
3. **Other colors**: read directly by the SDK and not covered by a role or token.

### API

| Mechanism               | Where                                        | Description                                          |
| ----------------------- | -------------------------------------------- | ---------------------------------------------------- |
| Color resource override | `android/app/src/main/res/values/colors.xml` | Declare a `<color>` with the same `name` as the SDK. |

Override a role or token to change only that use.

```xml
<!-- android/app/src/main/res/values/colors.xml -->
<resources>
    <color name="certta_sc_primary_color">#0057D8</color>

    <!-- Every text on every screen except the Validation method screen (that one uses content_color) -->
    <color name="certta_sc_text_primary">#1A1F2E</color>
</resources>
```

Colors accept `#RGB`, `#ARGB`, `#RRGGBB`, `#AARRGGBB` (alpha first) or a reference such as `@color/my_brand_blue`.

### Adding your colors

1. Create or reuse `colors.xml` in the Android app module.
2. Add only the names you want to override. Omitted names keep the SDK baseline.
3. Rebuild the app. Your resources replace the SDK defaults automatically.

### Resolution order

For each color, Android resolves in this order:

1. Your app’s color with that resource ID.
2. The SDK’s own color for that ID.

Partial overrides are supported and recommended.

### Shared roles

Same names as the iOS `CafColorConfiguration` / RN `colorConfiguration`, so one palette can be shared between platforms — on Android as resources, on iOS as TypeScript.

| Resource ID                         | Default   | Used by                                                                                                                                                                      |
| ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `certta_sc_primary_color`           | `#00A54B` | Fill of an enabled primary button (through `certta_sc_primary_button_color_selector`                                                                                         |
| `certta_sc_secondary_color`         | `#150A5C` | "Take another picture" button on Preview (style `CerttaPreviewRetakeButton`)                                                                                                 |
| `certta_sc_content_color`           | `#353535` | Title and card texts on the Validation method screen. Every other screen uses `certta_sc_text_primary`                                                                       |
| `certta_sc_background_color`        | `#FFFFFF` | Screen background of Preview and Success, and the footer behind the buttons                                                                                                  |
| `certta_sc_medium_color`            | `#D1D1D1` | Fill of a disabled primary button (through `certta_sc_primary_button_color_selector`) and the dividers above the footer buttons on Instructions and Camera permission denied |
| `certta_sc_dialog_background_color` | `#FFFFFF` | Background of the bottom sheets: Camera help and the remove-file confirmation (through `certta_sc_bottom_sheet_background`)                                                  |
| `certta_sc_dialog_border_color`     | `#A8A8A8` | Border of the cards on the Validation method screen (through `certta_sc_validation_type_card_background`)                                                                    |

### Smart Capture tokens

Same names as the iOS `CerttaSmartCaptureColorCustomization` / RN `colorCustomization` (mapped to `certta_sc_*` snake\_case).

| Resource ID                          | Default     | Used by                                                                                                                                                                                                                           |
| ------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `certta_sc_primary_button_text`      | `#003D1C`   | Label of an enabled or pressed primary button (through `certta_sc_primary_button_text_color_selector`)                                                                                                                            |
| `certta_sc_accent`                   | `#150A5C`   | Text of the secondary buttons (Skip tips, Attach document in Camera help, Delete in the remove sheet) and of the dashed Attach document button on Upload. The borders of these buttons are fixed (`#150A5C`) and do not follow it |
| `certta_sc_text_primary`             | `#353535`   | Titles, descriptions, chips and file names on every screen except Validation method                                                                                                                                               |
| `certta_sc_text_secondary`           | `#585858`   | File labels and the empty-state title on Upload, the message on the remove sheet, the hint on Camera help, and the label of a disabled primary button                                                                             |
| `certta_sc_warning_foreground`       | `#493204`   | Text of the in-camera error banner and of the error banners on Upload                                                                                                                                                             |
| `certta_sc_warning_background`       | `#FEF6E7`   | Fill of the error banners (through `certta_sc_camera_error_background_drawable`)                                                                                                                                                  |
| `certta_sc_warning_border`           | `#795306`   | Border of the error banners (through `certta_sc_camera_error_background_drawable`)                                                                                                                                                |
| `certta_sc_warning_icon`             | `#DA950B`   | Color of the warning triangle in the error banners (through `certta_sc_alert_triangle_icon`)                                                                                                                                      |
| `certta_sc_success`                  | `#30B814`   | Tint of the progress spinner when a capture or upload is validated, just before the check icon appears                                                                                                                            |
| `certta_sc_camera_overlay`           | `#80FFFFFF` | Fill of the document mask drawn over the camera while auto capture detects a document                                                                                                                                             |
| `certta_sc_camera_chrome_background` | `#000000`   | Frozen-frame backdrop on Camera                                                                                                                                                                                                   |
| `certta_sc_camera_chrome_foreground` | `#FFFFFF`   | Text of the instruction pill on Camera and the outline of the document mask                                                                                                                                                       |

{% hint style="info" %}
`certta_sc_content_color` and `certta_sc_text_primary` have the same default, and so do `certta_sc_secondary_color` and `certta_sc_accent`. They are separate resources because they match two separate iOS properties. If you want one text color everywhere, override both
{% endhint %}

There is no `certta_sc_error` in the Android resource set for the upload-failure icon the way iOS exposes `error` — that tint is covered by drawables / other tokens. Prefer the table above.

### Other colors

Read directly by the SDK and not covered by a role or token.

| Resource ID             | Default     | Used by                                       |
| ----------------------- | ----------- | --------------------------------------------- |
| `certta_sc_color_scrim` | `#CC000000` | Backdrop of the file preview dialog on Upload |

### Colors that follow a role

A few drawables read their colors from the resources above, so a color override reaches them without replacing the drawable. The borders of the secondary and attach buttons are not on this list: they are fixed (`#150A5C`), like the other drawables below.

| Drawable                                     | Follows                                                                  |
| -------------------------------------------- | ------------------------------------------------------------------------ |
| `certta_sc_preview_retake_button_background` | Border: `certta_sc_secondary_color`                                      |
| `certta_sc_bottom_sheet_background`          | Fill: `certta_sc_dialog_background_color`                                |
| `certta_sc_validation_type_card_background`  | Border: `certta_sc_dialog_border_color`                                  |
| `certta_sc_camera_error_background_drawable` | Fill: `certta_sc_warning_background`; border: `certta_sc_warning_border` |
| `certta_sc_alert_triangle_icon`              | Fill: `certta_sc_warning_icon`                                           |

### Colors that are not resources

Some colors are literals inside drawable files, so `colors.xml` cannot change them. Override the drawable instead ([see Images](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/image-customization.md)).

* The white fill and the border (`#150A5C`) of `certta_sc_secondary_button_background` and `certta_sc_attach_button_background`, and the white fill of `certta_sc_preview_retake_button_background`.
* The fill of `certta_sc_instructions_hint_background` (`#D1D1D1`), `certta_sc_camera_hint_drawable` (`#1B1B1B`) and `certta_sc_bottom_sheet_drag_handle` (`#A8A8A8`), and the dots in `certta_sc_dot_selector`.
* The icons: `certta_sc_arrow_left`, `certta_sc_eye`, `certta_sc_trash`, `certta_sc_ic_help` and the close buttons (`#353535`); `certta_sc_validation_type_camera`, `certta_sc_validation_type_upload` and `certta_sc_close_icon` (`#150A5C`); the success and hint illustrations (greens such as `#30B814`); and the shutter button states.

{% hint style="warning" %}
If you give the screens a dark background (`certta_sc_background_color`), the icons above keep their dark colors and the white button fills stay white. Replace those drawables too, or keep the default light backgrounds.
{% endhint %}

### Button state-list selectors

Two buttons use a `color` selector (state list) instead of a single flat color, so pressed/enabled/disabled states can differ. Override the role or token they point to for a lighter touch, or override the whole selector file with the same name to change how a button reacts to state.

| Resource ID                                    | Description                               | Points to                                                                        |
| ---------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------- |
| `certta_sc_primary_button_color_selector`      | Primary button background color per state | Disabled: `certta_sc_medium_color`. Otherwise: `certta_sc_primary_color`         |
| `certta_sc_primary_button_text_color_selector` | Primary button text color per state       | Disabled: `certta_sc_text_secondary`. Otherwise: `certta_sc_primary_button_text` |

### Accessibility

Check contrast after overriding. In particular, `certta_sc_primary_button_text` against `certta_sc_primary_color`, and `certta_sc_warning_foreground` against `certta_sc_warning_background`. The defaults are compliant; a partial override can break the pairing.<br>
{% endtab %}

{% tab title="iOS" %}

### Overview

Smart Capture colors are customized in two layers, and both apply at the same time. In React Native both layers are TypeScript hex strings.

* **Shared roles:** `CafColorConfiguration` (`colorConfiguration` on `configureSDK`). Seven design-system roles shared with Face Liveness and Document Detector.
* **Smart Capture tokens:** `CerttaSmartCaptureColorCustomization` (`colorCustomization` on `open()`). Thirteen colors that exist only in the Smart Capture flow.

Every field on both layers is optional. A field you leave unset keeps the SDK baseline.

Call `configureSDK` before `open()`. Shared roles are applied on the active session.

### API

| Layer                | TypeScript                                                  | Where                               |
| -------------------- | ----------------------------------------------------------- | ----------------------------------- |
| Shared roles         | `colorConfiguration?: CafColorConfiguration`                | `useCerttaSdk().configureSDK(...)`  |
| Smart Capture tokens | `colorCustomization?: CerttaSmartCaptureColorCustomization` | `useCerttaSmartCapture().open(...)` |

Hex strings: `#RGB`, `#RRGGBB` or `#AARRGGBB` (alpha first). A string of any other length, or one that does not parse, silently renders as black.

```typescript
import {
  useCerttaSdk,
  useCerttaSmartCapture,
  CafEnvironment,
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const { configureSDK } = useCerttaSdk();
const { open } = useCerttaSmartCapture();

await configureSDK({
  mobileToken: '<MOBILE_TOKEN>',
  userId: '<USER_ID>',
  environment: CafEnvironment.PROD,
  securityEnabled: true,
  colorConfiguration: {
    primaryColor: '#1B5E20',
    secondaryColor: '#0D2818',
    contentColor: '#212121',
    backgroundColor: '#FFFFFF',
    mediumColor: '#E0E0E0',
    dialogBackgroundColor: '#FFFFFF',
    dialogBorderColor: '#BDBDBD',
  },
});

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [
    CerttaAcceptedDocumentType.IDENTITY_CARD,
    CerttaAcceptedDocumentType.DRIVER_LICENSE,
  ],
  colorCustomization: {
    primaryButtonText: '#FFFFFF',
    accent: '#1B5E20',
    textPrimary: '#212121',
    textSecondary: '#595959',
    error: '#B81C1C',
    warningBackground: '#FFF7E0',
    warningBorder: '#FAC230',
    warningIcon: '#CC9100',
    warningForeground: '#332600',
    success: '#1B5E20',
    cameraOverlay: '#73FFFFFF',
    cameraChromeBackground: '#000000',
    cameraChromeForeground: '#FFFFFF',
  },
};

await open(config);
```

### Adding your colors

1. Set shared roles on `configureSDK` when you want them to apply across Certta products.
2. Pass only the Smart Capture tokens you want to change on `open()`.
3. Omitted fields keep the SDK baseline.

#### Partial customization

```typescript
const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  colorCustomization: {
    accent: '#4F46E5',
    cameraOverlay: '#4DFFFFFF',
  },
};

await open(config);
```

### Resolution order

For each token:

1. The value you set on `colorCustomization` / `colorConfiguration`.
2. The Smart Capture baseline for that token/role (not a global design-system default).

Colors are applied when the flow starts and reset when it finishes. Each session replaces the previous session’s colors as a whole, rather than merging with them.

An empty hex string on a `CafColorConfiguration` role is treated as unset and falls back to the Smart Capture baseline.

### Shared roles

These seven roles come from `CafColorConfiguration` and are shared across CAF products. Smart Capture falls back to its own baseline for any role you leave unset.

| TS field                | Smart Capture default            | Where it appears                                |
| ----------------------- | -------------------------------- | ----------------------------------------------- |
| `primaryColor`          | `#00A54B`                        | Fill of the primary call-to-action buttons      |
| `secondaryColor`        | `#012D1F`                        | Secondary surfaces and supporting chrome        |
| `contentColor`          | `#323232` light / `#CDCDCD` dark | Body content that follows the system appearance |
| `backgroundColor`       | `#FCFCFC`                        | Screen background outside the camera            |
| `mediumColor`           | `#D1D1D1`                        | Dividers, separators and neutral outlines       |
| `dialogBackgroundColor` | `#FCFCFC`                        | Bottom sheets and the validation-method card    |
| `dialogBorderColor`     | `#A8A8A8`                        | Border of those sheets and cards                |

### Smart Capture tokens

All thirteen tokens are optional strings and default to unset. The Default column is the color Smart Capture uses when the token is omitted.

| TS field                 | Default              | Where it appears                                                                 |
| ------------------------ | -------------------- | -------------------------------------------------------------------------------- |
| `primaryButtonText`      | `#0B2905`            | Label of the primary CTA. The button fill comes from `primaryColor`              |
| `accent`                 | `#150A5C`            | Secondary and link actions, dashed attach border, validation-method icon tint    |
| `textPrimary`            | `#353535`            | Upload failure title/description, accepted-documents chip, filled slot file name |
| `textSecondary`          | `#585858`            | Camera help footer, empty-state title and file labels on Upload review           |
| `error`                  | `#E5114A`            | Tint of the large icon on the Upload failure screen                              |
| `warningBackground`      | `#FEF6E7`            | In-camera warning view and Upload review warning banner                          |
| `warningBorder`          | Amber                | Border of the Upload review warning banner                                       |
| `warningIcon`            | Dark amber           | Tint of the warning banner icon                                                  |
| `warningForeground`      | Black                | Text and button tint inside the in-camera warning, warning copy on Upload        |
| `success`                | Green                | Tint of the check icon on a filled upload slot                                   |
| `cameraOverlay`          | White at 50% opacity | Fill of the auto-capture mask. Stroke comes from `cameraChromeForeground`        |
| `cameraChromeBackground` | Black                | Camera background, instruction pill, shutter flash                               |
| `cameraChromeForeground` | White                | Instruction text, help button tint, auto-capture rectangle stroke                |

`warningBorder`, `warningIcon`, `success` and `cameraOverlay` have baselines defined in RGB rather than hex.

### What cannot be customized

Some elements are still fixed and are not reachable through either layer:

* The separator on the camera help sheet.
* The page control dots on the instructions carousel.
* The upload preview chrome and its PDF background.
* The empty-state description on Upload review.
* The preview and delete icon tints on an upload slot.

Fonts and spacing are not customizable. If you replace an image, custom single images are rendered as supplied and are not tinted by these color tokens — see Image Customization.

### Accessibility

Check contrast after overriding. In particular, `primaryButtonText` against the `primaryColor` fill, and `warningForeground` against `warningBackground`. The defaults are compliant; a partial override can silently break the pairing because the two values come from different layers.
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-sdk/react-native/document-smart-capture/color-customization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
