> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/docs/embedded-ui/styles-and-branding.md).

# Styles and Branding

Position Embedded UI's iframe with your CSS, and brand what appears inside it

Embedded UI's look has two layers. The `iframe` it adds to your page is yours to position and frame with CSS. What renders inside it (the wallet picker, the QR code, the Web Wallet) follows the branding set for your Tenant.

### Style the iframe 🖼️ <a href="#style-customization" id="style-customization"></a>

Embedded UI adds its `iframe` to the end of your page's `<body>`, inside a wrapper element, and ships no styles for either. Your CSS decides where it appears and how it's framed. Until you add some, it renders in the normal page flow, at the bottom of the page.

| Class                         | Applied to                                             | Use it for                                                                                             |
| ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `.embedded-wallet-ui`         | The wrapper, while your page stays usable              | Stacking order                                                                                         |
| `.embedded-wallet-ui-blocked` | The same wrapper, while a step needs your page blocked | A full-screen layer that stops clicks reaching your page. Give it a background to dim the page as well |
| `.embedded-wallet-ui-iframe`  | The `iframe` itself                                    | Position, shadow, corners and background                                                               |

Embedded UI swaps the wrapper between the first two classes as the Holder moves from step to step.

**Leave the size to Embedded UI.** It sizes the `iframe` to fit the current step with inline styles: full width up to the step's own maximum, and at most 90% of the window's height unless a step needs the full screen. A `width` or `height` in your CSS is overridden.

For example, to show Embedded UI as a centered dialog:

```css
.embedded-wallet-ui {
  z-index: 100;
}

.embedded-wallet-ui-blocked {
  position: fixed;
  inset: 0;
  z-index: 100;
  background: transparent; /* or rgba(0, 0, 0, 0.32) to dim your page */
}

.embedded-wallet-ui-iframe {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  z-index: 100;
  border-radius: 24px;
  background-color: #ffffff; /* match your branding: dark if isDark is true */
  box-shadow:
    0 0 48px 0 rgba(0, 0, 0, 0.07),
    0 16px 32px 0 rgba(0, 0, 0, 0.07),
    0 12px 24px 0 rgba(0, 0, 0, 0.07);
}
```

### Branding 🎨

Your branding (colors, fonts, light or dark) is applied to everything Embedded UI renders inside its `iframe`: the wallet picker, the QR code, `tx_code` entry, the presentation steps, and the Web Wallet and its notifications list. You set it once for your Tenant, and Embedded UI loads it for the `tenant` you pass to `initEmbeddedUi`. There is nothing to configure in your page.

The [web components](/docs/embedded-ui/embedding-web-wallet.md) are only partly branded. Their buttons, `wallet-view-vc-list-button` and the `wallet-notifications` bell, sit in your page and inherit its text color and font, so style them with their CSS classes. The notifications list the bell opens is the Web Wallet's own, so it follows your branding. Only the dropdown around it, `.wallet-notifications-dropdown`, is yours to style.

#### Set your branding ✏️

Set your branding in the Operator Portal, under **Settings › Branding**. Embedded UI picks up your changes the next time it opens.

#### Start with a few values

Most Tenants only need a handful of settings. Everything you leave unset comes from the EQUS light palette, or the dark one when `isDark` is `true`. Each setting is listed by the name it's stored under.

| Setting             | What it does                                                                                                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `primaryColor`      | Your brand color: the background of main action buttons, such as Save or Confirm, and other key elements. Its hover, pressed, disabled and translucent shades are derived from it unless you set them yourself |
| `isDark`            | `true` switches every color you haven't set to the dark palette. Default `false`                                                                                                                               |
| `secondaryColor`    | Secondary brand color for supporting elements                                                                                                                                                                  |
| `accentColor`       | Accent color for highlighted elements. It is also the default text color, so choose one that reads well on your background                                                                                     |
| `fontFamily`        | Main font, used for base text                                                                                                                                                                                  |
| `fontFamilyHeading` | Heading font. Defaults to `fontFamily`                                                                                                                                                                         |
| `fontFamilyLight`   | Font for light-weight text. Defaults to `fontFamily`                                                                                                                                                           |

The derived shades: hover and pressed are `primaryColor` darkened by 8% and 16%, the translucent shades are `primaryColor` at 8%, 16% and 20% opacity, and disabled is 38% opacity.

#### Formats

* **Colors**: hex, such as `#0B5FFF`, or `rgb()` / `rgba()`. Stick to these for every color: the shades are computed from `primaryColor`, and a value in another format, such as a color name or `hsl()`, stops your branding from applying at all.
* **Fonts**: [Google Fonts](https://fonts.google.com/) family names, such as `Inter`. Embedded UI loads `fontFamily` and `fontFamilyHeading` from Google Fonts. `fontFamilyLight` isn't loaded separately, so use a family you've already set in one of those two.

#### Fine-tune 🎛️

Every other color Embedded UI uses can be set too. Open a group to see what each setting colors.

<details>

<summary>Primary shades</summary>

| Setting               | What it colors                                                                  |
| --------------------- | ------------------------------------------------------------------------------- |
| `primaryColorHover`   | Main action buttons on hover                                                    |
| `primaryColorPressed` | Anything with a primary background, such as a button, when pressed              |
| `primaryOpacity08`    | Background of secondary buttons, such as Cancel                                 |
| `primaryOpacity16`    | Background of secondary buttons on hover                                        |
| `primaryOpacity20`    | Buttons in their active state                                                   |
| `primaryDisabled`     | Background of disabled controls, such as checkboxes, switches and radio buttons |

</details>

<details>

<summary>Text and icons</summary>

| Setting                        | What it colors                                                            |
| ------------------------------ | ------------------------------------------------------------------------- |
| `onSurfaceDarkHighEmphasis`    | Main text: titles, body text and input values                             |
| `onSurfaceDarkMediumEmphasis`  | Secondary text: helper text and field labels                              |
| `onSurfaceDarkDisabled`        | Disabled and footer text                                                  |
| `onSurfaceLightHighEmphasis`   | Text on dark or colored backgrounds, such as status badges (Open, Active) |
| `onSurfaceLightMediumEmphasis` | Secondary text on dark backgrounds                                        |
| `onSurfaceLightDisabled`       | Disabled text on dark backgrounds                                         |
| `textOnSurface`                | Text of secondary buttons, such as Cancel                                 |

</details>

<details>

<summary>Surfaces</summary>

| Setting                          | What it colors                                                       |
| -------------------------------- | -------------------------------------------------------------------- |
| `surfaceNull`                    | Panel background, and close buttons on hover                         |
| `cardBg`                         | Background of pop-ups and dialogs                                    |
| `cardStroke`                     | Border of pop-ups and dialogs                                        |
| `surface1` to `surface4`         | Layered backgrounds tinted from your primary color, from low to high |
| `surface5`                       | Background of input fields and header sections                       |
| `surfaceGrey1` to `surfaceGrey5` | Neutral gray surface tones                                           |

</details>

<details>

<summary>Outlines and unselected controls</summary>

| Setting             | What it colors                                                                 |
| ------------------- | ------------------------------------------------------------------------------ |
| `darkOpacity05`     | Background of unselected controls, such as an unchecked radio button or switch |
| `darkOpacity08`     | Unselected controls on hover, and the scrollbar                                |
| `darkOpacity12`     | Unselected controls when pressed                                               |
| `darkDivider`       | Dividers                                                                       |
| `darkOutlineMedium` | Text and icons of disabled buttons                                             |
| `darkOutlineHigh`   | High-emphasis outlines                                                         |

</details>

<details>

<summary>Overlays, links and widgets</summary>

| Setting                                  | What it colors                                      |
| ---------------------------------------- | --------------------------------------------------- |
| `shutterDark70`, `shutterDark30`         | Dark overlay behind modals, at 70% and 30% opacity  |
| `shutterLight32`, `shutterLight75`       | Light overlay behind modals, at 32% and 75% opacity |
| `linkColor`                              | Links                                               |
| `widgetColor`                            | Background of embedded widgets                      |
| `widgetColorHover`, `widgetColorPressed` | Embedded widgets on hover and when pressed          |

</details>

<details>

<summary>Error, warning and success states</summary>

| Setting                                                                   | What it colors                                   |
| ------------------------------------------------------------------------- | ------------------------------------------------ |
| `notificationColor`                                                       | Error states                                     |
| `notificationHover`, `notificationPressed`                                | Error elements on hover and when pressed         |
| `notificationOpacity08`, `notificationOpacity12`, `notificationOpacity16` | Tinted backgrounds for errors                    |
| `warningColor`                                                            | Warning states                                   |
| `warningOpacity07`, `warningOpacity12`, `warningOpacity16`                | Tinted backgrounds for warnings                  |
| `successColor`                                                            | Success icons and states, such as Active or Open |
| `successHover`, `successPressed`                                          | Success elements on hover and when pressed       |
| `successOpacity07`, `successOpacity12`, `successOpacity16`                | Tinted backgrounds for success                   |

</details>

#### Check what's set 🔍

`GET /api/v1/tenants/{slug}/branding` on the Integration API returns your current branding, and needs no credentials: it's what Embedded UI itself reads. Your slug is the **Organization ID** in the Operator Portal settings.

## Get Tenant Branding

> Retrieves the branding metadata configured for the given tenant

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Tenant Metadata","description":""}],"paths":{"/api/v1/tenants/{slug}/branding":{"get":{"description":"Retrieves the branding metadata configured for the given tenant","operationId":"TenantMetadataController_getBranding_api/v1","parameters":[{"name":"slug","required":true,"in":"path","description":"URL-friendly slug generated from the tenant name.","schema":{"type":"string"}}],"responses":{"200":{"description":"The branding metadata for the requested tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTenantBrandingResponse"}}}},"404":{"description":"The tenant was not found."}},"summary":"Get Tenant Branding","tags":["Tenant Metadata"]}}},"components":{"schemas":{"GetTenantBrandingResponse":{"type":"object","properties":{"data":{"description":"Tenant branding metadata","allOf":[{"$ref":"#/components/schemas/TenantBrandingMetadata"}]}},"required":["data"]},"TenantBrandingMetadata":{"type":"object","properties":{"primaryColor":{"type":"string","maxLength":64,"description":"Primary brand color used for CTAs and key UI elements."},"primaryColorHover":{"type":"string","maxLength":64,"description":"Primary brand color applied on hover state."},"primaryColorPressed":{"type":"string","maxLength":64,"description":"Primary brand color applied on pressed/active state."},"primaryOpacity08":{"type":"string","maxLength":64,"description":"Primary brand color at 8% opacity, used for subtle backgrounds."},"primaryOpacity16":{"type":"string","maxLength":64,"description":"Primary brand color at 16% opacity, used for subtle backgrounds."},"primaryOpacity20":{"type":"string","maxLength":64,"description":"Primary brand color at 20% opacity, used for subtle backgrounds."},"primaryDisabled":{"type":"string","maxLength":64,"description":"Primary brand color applied to disabled UI elements."},"darkOpacity05":{"type":"string","maxLength":64,"description":"Dark overlay color at 5% opacity."},"darkOpacity08":{"type":"string","maxLength":64,"description":"Dark overlay color at 8% opacity."},"darkOpacity12":{"type":"string","maxLength":64,"description":"Dark overlay color at 12% opacity."},"darkDivider":{"type":"string","maxLength":64,"description":"Dark color used for borders and dividers."},"darkOutlineMedium":{"type":"string","maxLength":64,"description":"Dark medium-emphasis color used for outlines."},"darkOutlineHigh":{"type":"string","maxLength":64,"description":"Dark high-emphasis color used for outlines."},"onSurfaceDarkHighEmphasis":{"type":"string","maxLength":64,"description":"Dark high-emphasis text/icon color rendered on light surfaces."},"onSurfaceDarkMediumEmphasis":{"type":"string","maxLength":64,"description":"Dark medium-emphasis text/icon color rendered on light surfaces."},"onSurfaceDarkDisabled":{"type":"string","maxLength":64,"description":"Dark disabled text/icon color rendered on light surfaces."},"onSurfaceLightHighEmphasis":{"type":"string","maxLength":64,"description":"Light high-emphasis text/icon color rendered on dark surfaces."},"onSurfaceLightMediumEmphasis":{"type":"string","maxLength":64,"description":"Light medium-emphasis text/icon color rendered on dark surfaces."},"onSurfaceLightDisabled":{"type":"string","maxLength":64,"description":"Light disabled text/icon color rendered on dark surfaces."},"textOnSurface":{"type":"string","maxLength":64,"description":"Default text color rendered on top of a surface background."},"surfaceNull":{"type":"string","maxLength":64,"description":"Base surface color with no elevation applied."},"cardBg":{"type":"string","maxLength":64,"description":"Background color used for card components."},"cardStroke":{"type":"string","maxLength":64,"description":"Border/stroke color used around card components."},"surface1":{"type":"string","maxLength":64,"description":"Elevation level 1 surface color."},"surface2":{"type":"string","maxLength":64,"description":"Elevation level 2 surface color."},"surface3":{"type":"string","maxLength":64,"description":"Elevation level 3 surface color."},"surface4":{"type":"string","maxLength":64,"description":"Elevation level 4 surface color."},"surface5":{"type":"string","maxLength":64,"description":"Elevation level 5 surface color."},"surfaceGrey1":{"type":"string","maxLength":64,"description":"Grey surface tone, level 1."},"surfaceGrey2":{"type":"string","maxLength":64,"description":"Grey surface tone, level 2."},"surfaceGrey3":{"type":"string","maxLength":64,"description":"Grey surface tone, level 3."},"surfaceGrey4":{"type":"string","maxLength":64,"description":"Grey surface tone, level 4."},"surfaceGrey5":{"type":"string","maxLength":64,"description":"Grey surface tone, level 5."},"shutterDark70":{"type":"string","maxLength":64,"description":"Dark modal/overlay shutter color at 70% opacity."},"shutterDark30":{"type":"string","maxLength":64,"description":"Dark modal/overlay shutter color at 30% opacity."},"shutterLight32":{"type":"string","maxLength":64,"description":"Light modal/overlay shutter color at 32% opacity."},"shutterLight75":{"type":"string","maxLength":64,"description":"Light modal/overlay shutter color at 75% opacity."},"linkColor":{"type":"string","maxLength":64,"description":"Color applied to hyperlinks."},"widgetColor":{"type":"string","maxLength":64,"description":"Base color used for embedded widget backgrounds."},"widgetColorHover":{"type":"string","maxLength":64,"description":"Embedded widget accent color applied on hover state."},"widgetColorPressed":{"type":"string","maxLength":64,"description":"Embedded widget accent color applied on pressed state."},"notificationColor":{"type":"string","maxLength":64,"description":"Base color used to indicate error states."},"notificationHover":{"type":"string","maxLength":64,"description":"Notification color applied on hover state."},"notificationPressed":{"type":"string","maxLength":64,"description":"Notification color applied on pressed state."},"notificationOpacity08":{"type":"string","maxLength":64,"description":"Notification color at 8% opacity, used for subtle backgrounds."},"notificationOpacity12":{"type":"string","maxLength":64,"description":"Notification color at 12% opacity, used for subtle backgrounds."},"notificationOpacity16":{"type":"string","maxLength":64,"description":"Notification color at 16% opacity, used for subtle backgrounds."},"warningColor":{"type":"string","maxLength":64,"description":"Base color used to indicate warning states."},"warningOpacity07":{"type":"string","maxLength":64,"description":"Warning color at 7% opacity, used for subtle backgrounds."},"warningOpacity12":{"type":"string","maxLength":64,"description":"Warning color at 12% opacity, used for subtle backgrounds."},"warningOpacity16":{"type":"string","maxLength":64,"description":"Warning color at 16% opacity, used for subtle backgrounds."},"successColor":{"type":"string","maxLength":64,"description":"Base color used to indicate success states."},"successHover":{"type":"string","maxLength":64,"description":"Success color applied on hover state."},"successPressed":{"type":"string","maxLength":64,"description":"Success color applied on pressed state."},"successOpacity07":{"type":"string","maxLength":64,"description":"Success color at 7% opacity, used for subtle backgrounds."},"successOpacity12":{"type":"string","maxLength":64,"description":"Success color at 12% opacity, used for subtle backgrounds."},"successOpacity16":{"type":"string","maxLength":64,"description":"Success color at 16% opacity, used for subtle backgrounds."},"secondaryColor":{"type":"string","maxLength":64,"description":"Secondary brand color used for supporting UI elements."},"accentColor":{"type":"string","maxLength":64,"description":"Accent color used to highlight key interactive elements."},"fontFamily":{"type":"string","maxLength":100,"description":"Primary font family used across the tenant's branded UI."},"fontFamilyLight":{"type":"string","maxLength":100,"description":"Light-weight variant of the font family, used for secondary text."},"fontFamilyHeading":{"type":"string","maxLength":100,"description":"Font family used for headings."},"isDark":{"type":"boolean","description":"Indicates whether the tenant's branding uses a dark theme."}}}}}}
```


---

# 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.toolkit.equs.ai/docs/embedded-ui/styles-and-branding.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.