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

# Theming

> Match the widget to your brand: the tokens Ripio can set on your account, the values they accept, and the fonts the widget ships.

The widget's look is driven by CSS custom properties (tokens). Your brand theme is a set of values for those tokens, stored on your account. Ripio loads it for you, and the widget applies it at runtime, with no rebuild and no per-partner deploy.

### How it works

Send your Ripio contact the values you want to change. Anything you leave out keeps its default. A minimal theme is small:

```json theme={null}
{
  "tokens": {
    "--ripio-color-primary": "#EC0000",
    "--ripio-btn-border-radius": "24px",
    "--ripio-font-family": "\"Ubuntu\""
  }
}
```

The widget receives the theme when it starts. It writes the tokens as custom properties on `:root`, and they inherit into its Shadow DOM.

<Note>
  Theming is an account-level setting. There's no query parameter or runtime API for it. You can also override tokens yourself at the document level; see [Overriding tokens from your page](#overriding-tokens-from-your-page).
</Note>

### Supported tokens

These are the tokens your account theme can set. Any other name is rejected when the theme is loaded, so a theme built on these keeps working as the widget's internals change.

**Brand**

| Token | Default | Controls |
| - | - | - |
| `--ripio-color-primary` | `#7839ee` | Brand color: primary buttons, links, focus, selection, charts |
| `--ripio-bg-brand-solid-hover` | primary, 15 % darker | Primary button hover |
| `--ripio-btn-text-color-primary` | `--ripio-color-base` | Text on primary buttons |
| `--ripio-color-primary-light` | primary at 7 % over the base color | Tinted brand backgrounds: tertiary buttons, selected options |

Setting `--ripio-color-primary` alone is enough for a coherent theme: the hover and the tinted backgrounds are derived from it. Set them explicitly only when your brand guide defines them.

**Surfaces and text**

| Token | Default | Controls |
| - | - | - |
| `--ripio-color-base` | `#ffffff` | Base surface color |
| `--ripio-bg-secondary` | gray 50 | Secondary surfaces: action tiles, segmented controls |
| `--ripio-border-primary` | gray 200 | Borders of cards, inputs and the widget's frame |
| `--ripio-text-primary` | `--ripio-color-text` | Main text |
| `--ripio-text-secondary` | gray 700 | Secondary text and inactive tabs |
| `--ripio-color-text` | gray 900 | Default text color |
| `--ripio-widget-bg-color` | `--ripio-color-base` | Widget container background |
| `--ripio-widget-border-color` | `--ripio-border-primary` | Widget container border |

**Status and neutrals**

| Token | Default | Controls |
| - | - | - |
| `--ripio-color-success` | success 600 | Success states |
| `--ripio-color-warning` | warning 600 | Warning states |
| `--ripio-color-error` | error 600 | Error states |
| `--ripio-color-info` | gray 200 | Neutral informational states |
| `--ripio-color-disabled` | gray 100 | Disabled backgrounds |
| `--ripio-color-neutral`, `--ripio-color-neutral-10/20/50/80/100/120` | gray scale | Neutral ramp used across surfaces and secondary text |

**Shapes and spacing**

| Token | Default | Controls |
| - | - | - |
| `--ripio-btn-border-radius` | fully rounded | Buttons |
| `--ripio-card-border-radius-base` | `12px` | Cards and lists (your assets, activity, market) |
| `--ripio-input-border-radius` | `8px` | Inputs and menu options |
| `--ripio-chip-border-radius` | fully rounded | Chips and badges |
| `--ripio-widget-border-radius` | `16px` | Widget container corners |
| `--ripio-widget-padding` | `24px` | Widget container padding |
| `--ripio-widget-gap` | `16px` | Spacing between the widget's sections |

**Typography**

| Token | Default | Controls |
| - | - | - |
| `--ripio-font-family` | `"Lato"` | Typeface for the whole widget |

### Accepted values

Each token accepts one kind of value. Anything else is rejected, including CSS functions, `url()`, `@import`, comments and anything that isn't a plain value.

| Kind | Accepted | Examples |
| - | - | - |
| Color | `#RGB`, `#RRGGBB`, `#RRGGBBAA`, `rgb(r, g, b)`, `rgba(r, g, b, a)` | `#EC0000`, `rgba(0, 0, 0, 0.5)` |
| Length (radius, padding, gap) | `0`, or a non-negative number in `px`, `rem` or `%` | `8px`, `999px`, `1.5rem` |
| Font | One of the [supported fonts](#fonts), as a quoted CSS string | `"Nunito Sans"` |

### Fonts

The widget ships and serves its own fonts, so you don't load anything and your page's CSP doesn't need a third-party font host. `--ripio-font-family` accepts one of:

| Font | Weights |
| - | - |
| `"Lato"` (default) | 400, 700 |
| `"Libre Franklin"` | 400, 700 |
| `"Ubuntu"` | 400, 700 |
| `"Nunito Sans"` | 400, 700 |
| `"Source Sans 3"` | 400, 700 |

The widget only downloads the family it's using. If your brand needs a typeface that isn't on the list, talk to your Ripio contact: fonts are added to the widget, never loaded from your side.

### Overriding tokens from your page

You can also set tokens yourself with CSS custom properties on your page's `:root`. The order of precedence is:

1. The widget's defaults.
2. Your page's `:root`, which overrides the defaults.
3. Your account theme, which overrides both.

```css theme={null}
:root {
  --ripio-color-primary: #034cf5;
  --ripio-widget-border-radius: 16px;
}
```

From your page you can reach the design system's other tokens as well: per-component tokens such as `--ripio-btn-*`, `--ripio-input-*`, `--ripio-card-*`, `--ripio-chip-*`, `--ripio-toast-*` and `--ripio-overlay-*`, and the radius, shadow and type scales. They belong to the design system and may be renamed as it evolves, so prefer the [supported tokens](#supported-tokens) where they're enough.

### What not to override

<Warning>
  The design-system primitives (`--violet-*`, `--gray-*`, `--error-*`, `--warning-*`, `--success-*`) and the transaction status-chip tokens `--st-*` are internal. They're the raw palette the semantic tokens are built from, they aren't part of the contract, and they can change without notice. Override the semantic layer instead.
</Warning>

<Warning>
  Theming only repaints the widget. It can't reposition, resize or hide anything inside it. The widget's own classes, such as `.btn-primary`, live inside its Shadow DOM and your page's selectors can't reach them: use the tokens.
</Warning>

### Before and after

<Frame>
  <img src="https://mintcdn.com/ripio-9dfd4837/Ntx12LxEM0pFyETw/crypto-as-a-service/widget/assets/widget-theme-default.png?fit=max&auto=format&n=Ntx12LxEM0pFyETw&q=85&s=873f6acc2cdfe0ce2214cc2d3c329501" alt="The widget with Ripio's default theme" width="951" height="954" data-path="crypto-as-a-service/widget/assets/widget-theme-default.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ripio-9dfd4837/Ntx12LxEM0pFyETw/crypto-as-a-service/widget/assets/widget-theme-partner.png?fit=max&auto=format&n=Ntx12LxEM0pFyETw&q=85&s=aab4555df08575fa41e5f5676359b49f" alt="The same widget with a partner's brand theme applied" width="951" height="1003" data-path="crypto-as-a-service/widget/assets/widget-theme-partner.png" />
</Frame>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.