# DOC-1505: Widget Customization Variable Gap Analysis

Source list: 183 CSS custom properties supplied for the widget customization revamp.

Checked against the two live customization docs:

- **Multi-region widget** (Employments Brazil, Employment Records Mexico, Fiscal Mexico) → canonical source is `_partials/hosted-widget-branding-and-customization.md`, included via `{% partial %}` in the three product pages.
- **OFDA widget** (Brazil Open Finance / Regulated Aggregation) → `products/aggregation_brazil/ofda-widget-branding-and-customization.md` (fully inline, not a partial).


A third widget doc exists — `products/payments_brazil/payments-brazil-bio-pix-widget-customization.md` (Pix Biometria) — but it uses an entirely different variable namespace (`--nav-bar-stepper-color-active`, `--color-surface-base`, `--container-border-*`, etc.) not present in the supplied list, so it's excluded from the gap count below. Flag if Pix Biometria should also be in scope for DOC-1505.

## Headline numbers

|  | Count |
|  --- | --- |
| Total variables in supplied list | 183 |
| Documented in **both** Multi-region and OFDA | 72 |
| Documented in Multi-region **only** | 6 |
| Documented in OFDA **only** | 0 |
| **Missing from both docs** | 105 |


**57% of the supplied variable list (105/183) isn't documented anywhere.** The undocumented set is dominated by entire component categories that don't exist in the current docs at all: typography/fonts, links, page-level text tokens, dialogs, checkboxes, dropdowns, item lists, accordions, and the OFDA-specific consent/redirect screens.

## Gap 1 — Multi-region has 6 variables OFDA doesn't

The OFDA doc has no "Modify the widget credentials screen" section at all. These are documented for Multi-region only:

| CSS Variable |
|  --- |
| `--credentials-screen-institution-logo-border-radius` |
| `--credentials-screen-header-logo-reversed` |
| `--credentials-screen-help-link-align` |
| `--credentials-screen-help-link-font-size` |
| `--credentials-screen-counter-border-radius` |
| `--credentials-screen-counter-font-size` |


**Action needed:** confirm with engineering whether the OFDA widget actually supports credentials-screen theming. If yes, this section is missing from the OFDA doc. If no, no action — but worth a one-line note in the OFDA doc explaining the platform difference (mirrors the existing pattern where OFDA also lacks `--button-border-color-disabled` in its buttons table despite it appearing in the buttons code sample).

## Gap 2 — 105 variables missing from both docs

Grouped by apparent component, in the order they'd likely be added to both docs:

### Typography / fonts (new category — no existing section)

| Variable |
|  --- |
| `--font-family-primary` |
| `--font-family-regular-file-name` |
| `--font-family-semibold-file-name` |
| `--font-family-bold-file-name` |


### Links (new category)

| Variable |
|  --- |
| `--link-font-color` |
| `--link-font-color-dark` |
| `--link-text-decoration` |


### Page-level text tokens (new category — title/body outside specific components)

| Variable |
|  --- |
| `--text-title-color` |
| `--text-title-color-dark` |
| `--text-title-font-size` |
| `--text-title-line-height` |
| `--text-body-color` |
| `--text-body-color-dark` |
| `--text-body-font-size` |
| `--text-body-line-height` |


### Buttons (extends existing "Modify the widget buttons" section)

| Variable |
|  --- |
| `--text-button-font-color` |
| `--text-button-font-color-dark` |


### Banners (extends existing "Modify the widget banners" section)

| Variable |
|  --- |
| `--banner-icon-size` |
| `--banner-icon-name-error` |
| `--banner-icon-name-success` |
| `--banner-icon-name-info` |
| `--banner-icon-name-warning` |


### Input fields (extends existing "Modify the widget input fields" section — this is the single biggest gap in an existing section)

| Variable |
|  --- |
| `--input-text-font-size` |
| `--input-text-font-color` |
| `--input-text-font-color-dark` |
| `--input-text-border-color-error` |
| `--input-text-border-color-error-dark` |
| `--input-text-label-weight` |
| `--input-text-label-font-size` |
| `--input-text-assistive-color` |
| `--input-text-assistive-color-dark` |
| `--input-text-assistive-color-error` |
| `--input-text-assistive-color-error-dark` |
| `--input-text-assistive-font-weight` |
| `--input-text-icon-opacity` |
| `--input-text-icon-size` |
| `--input-text-icon-order` |
| `--input-text-password-visible-icon` |
| `--input-text-password-non-visible-icon` |


### Checkbox (new category)

| Variable |
|  --- |
| `--checkbox-border-color` |
| `--checkbox-border-color-dark` |
| `--checkbox-border-radius` |


### Dialog (new category)

| Variable |
|  --- |
| `--dialog-title-color` |
| `--dialog-title-color-dark` |
| `--dialog-body-color` |
| `--dialog-body-color-dark` |
| `--dialog-body-font-size` |
| `--dialog-body-line-height` |


### Tabs (extends existing "Modify Widget Tab Components" section — dark-mode variants missing)

| Variable |
|  --- |
| `--tab-text-color-dark` |
| `--tab-border-color-dark` |


Note: unlike every other themed component, the tabs section's own "Dark" code sample reuses the plain `--tab-text-color` / `--tab-border-color` keys instead of `-dark`-suffixed ones. That's inconsistent with the doc's own convention (stated explicitly: "append `-dark` to any of the CSS variables ... to apply a custom style specifically for dark mode") and with the rest of the page. Confirm with engineering whether tabs genuinely lack dark-mode-specific variables (in which case the code sample is correct and these two are out of scope) or whether the docs are just missing them (in which case the Dark code sample itself needs a fix, not just a new table row).

### Overlay / surface / divider / image / layout (new categories)

| Variable |
|  --- |
| `--overlay-background-color` |
| `--overlay-background-color-dark` |
| `--surface-color` |
| `--surface-color-dark` |
| `--divider-color` |
| `--divider-color-dark` |
| `--image-border-radius` |
| `--layout-side-padding` |


Note: `overlay_background_color` (lowercase, snake_case, no dashes) already exists in both docs but as a **branding JSON key** (`widget.branding.overlay_background_color`), not a CSS variable. `--overlay-background-color` / `-dark` are CSS-variable-namespaced siblings and are genuinely new/undocumented — worth double-checking with engineering that these aren't just the same knob exposed twice.

### Dropdown (new category)

| Variable |
|  --- |
| `--dropdown-border-radius` |
| `--dropdown-font-color` |
| `--dropdown-font-color-dark` |
| `--dropdown-label-display` |


### Item list (new category)

| Variable |
|  --- |
| `--item-list-hover-color` |
| `--item-list-hover-color-dark` |
| `--item-list-skeleton-color` |
| `--item-list-skeleton-color-dark` |
| `--item-list-icon-color` |
| `--item-list-icon-color-dark` |
| `--item-list-title-color` |
| `--item-list-title-color-dark` |
| `--item-list-body-color` |
| `--item-list-body-color-dark` |


### Accordion (new category)

| Variable |
|  --- |
| `--accordion-icon-color` |
| `--accordion-icon-color-dark` |
| `--accordion-title-color` |
| `--accordion-title-color-dark` |


### Credentials screen — extra info & title (extends the credentials-screen section, which itself is Multi-region-only today — see Gap 1)

| Variable |
|  --- |
| `--credentials-screen-extra-info-align` |
| `--credentials-screen-extra-info-font-weight` |
| `--credentials-screen-extra-info-font-size` |
| `--credentials-screen-extra-info-line-height` |
| `--credentials-screen-extra-info-color` |
| `--credentials-screen-extra-info-color-dark` |
| `--credentials-screen-title-align` |
| `--credentials-screen-title-font-weight` |
| `--credentials-screen-title-font-size` |
| `--credentials-screen-title-line-height` |
| `--credentials-screen-title-color` |
| `--credentials-screen-title-color-dark` |


### Consent details / consent summary (OFDA-only concepts — Open Finance consent flow has no CSS-variable documentation at all today)

| Variable |
|  --- |
| `--consent-details-identification-section-icon` |
| `--consent-details-expiration-section-icon` |
| `--consent-details-header-background-color` |
| `--consent-details-header-background-color-dark` |
| `--consent-summary-identification-section-icon` |
| `--consent-summary-expiration-section-icon` |
| `--consent-summary-purpose-section-icon` |
| `--consent-summary-shared-information-section-icon` |


**These are almost certainly OFDA-only** (consent screens are an Open Finance/Brazil-regulated concept — the multi-region widget has no consent step). Worth confirming scope with engineering before deciding whether these belong only in the OFDA doc.

### Fetching-consent screen (likely OFDA-only)

| Variable |
|  --- |
| `--fetching-consent-title-font-size` |
| `--fetching-consent-title-line-height` |
| `--fetching-consent-body-font-size` |
| `--fetching-consent-body-line-height` |


### Redirect screen (likely OFDA-only)

| Variable |
|  --- |
| `--redirect-title-font-size` |
| `--redirect-title-line-height` |
| `--redirect-body-font-size` |
| `--redirect-body-line-height` |
| `--redirect-openfinance-logo-visibility` |


## Fully documented (72 variables, no action needed)

Present with a table row (or documented dark-mode sibling) in **both** the Multi-region and OFDA docs today: the full primary-color, nav bar, buttons (minus the two text-button additions above), banners (minus icon-name/size), input fields (minus the additions above), and tabs (light-mode) sections. Full list available on request — omitted here since it needs no doc work.

## Source-of-truth caveat

`apis/BelvoOpenApiSpec.yaml` defines the `theme` array schema (`css_key` / `value`, both freeform `type: string`) for both the OFDA and multi-region token endpoints, but does **not** enumerate variable names as an enum — the `css_key` description only lists 3 illustrative examples (`--color-primary-base`, `--nav-bar-title-color`, `--nav-bar-icon-color`) in prose. The spec can't be used to validate the supplied 183-variable list against the product; that confirmation needs to come from engineering/design, not the API contract.

## Suggested next step

Before writing doc updates: confirm with engineering (a) which of the "likely OFDA-only" categories (consent details/summary, fetching-consent, redirect) are genuinely OFDA-exclusive vs. also available on multi-region, and (b) whether the Multi-region-only credentials-screen section (Gap 1) should be ported to OFDA or is a genuine platform limitation.