> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/widget/customization.md).

# Customization

Customize the STON.fi Widget appearance with themes, CSS variables, and the visual constructor.

You can change the STON.fi Widget's appearance through CSS custom properties (CSS variables). Override the color palettes to change the overall theme, or set component variables to customize individual elements. You can also adjust spacing, borders, corner radius, and widths.

Use the [visual constructor](https://widget.ston.fi/constructor) to configure the appearance and preview your changes in the Theme tab. In the Export tab, copy the generated CSS and JavaScript configuration or a complete HTML example into your project.

Declare custom properties on the same container you pass to `widget.mount()`. Put these rules in your application's stylesheet.

## Color variables

The widget uses two 12-step palettes: `--accent-1` through `--accent-12` for accent colors, and `--grey-1` through `--grey-12` for neutral colors. Shared text, icon, and component colors reference these palettes through `var()`. Override any palette variable to change the colors that use it.

### Light and dark themes

The widget uses the light theme by default. Add the `dark` class to the container to use the dark theme:

```html
<div id="omniston-widget-container" class="dark"></div>
```

Use the container selector for shared overrides and add `.dark` for dark-theme values. This example changes the accent colors used by buttons and other elements:

```css
#omniston-widget-container {
  --accent-9: #7c3aed;
  --accent-11: #6d28d9;
}

#omniston-widget-container.dark {
  --accent-9: #8b5cf6;
  --accent-11: #c4b5fd;
}
```

You can switch themes at runtime by adding or removing the container's `dark` class.

### Palette defaults

Each palette has separate light and dark values. You can override the complete palette or individual shades:

| Variable      | Light default | Dark default |
| ------------- | ------------- | ------------ |
| `--accent-1`  | `#fbfdff`     | `#09111d`    |
| `--accent-2`  | `#f5f9ff`     | `#0e1827`    |
| `--accent-3`  | `#e9f3ff`     | `#0c264b`    |
| `--accent-4`  | `#daecff`     | `#093065`    |
| `--accent-5`  | `#c8e2ff`     | `#0e3b78`    |
| `--accent-6`  | `#b3d4ff`     | `#174789`    |
| `--accent-7`  | `#99c3ff`     | `#1f539d`    |
| `--accent-8`  | `#72aafc`     | `#2462b8`    |
| `--accent-9`  | `#0071f0`     | `#0071f0`    |
| `--accent-10` | `#0063e0`     | `#0063e0`    |
| `--accent-11` | `#006ae8`     | `#7eb8ff`    |
| `--accent-12` | `#073168`     | `#cfe3ff`    |
| `--grey-1`    | `#fcfcfc`     | `#111111`    |
| `--grey-2`    | `#f9f9f9`     | `#191919`    |
| `--grey-3`    | `#efefef`     | `#222222`    |
| `--grey-4`    | `#e8e8e8`     | `#2a2a2a`    |
| `--grey-5`    | `#e0e0e0`     | `#313131`    |
| `--grey-6`    | `#d8d8d8`     | `#3a3a3a`    |
| `--grey-7`    | `#cecece`     | `#484848`    |
| `--grey-8`    | `#bbbbbb`     | `#606060`    |
| `--grey-9`    | `#8d8d8d`     | `#6e6e6e`    |
| `--grey-10`   | `#838383`     | `#7b7b7b`    |
| `--grey-11`   | `#646464`     | `#b4b4b4`    |
| `--grey-12`   | `#202020`     | `#eeeeee`    |

### Shared colors

These variables control the widget background, borders, text, icons, and status colors. Override them to change a shared color without replacing the palette:

| Variable                   | Light default               | Dark default                |
| -------------------------- | --------------------------- | --------------------------- |
| `--background-color`       | `#f4f4f4`                   | `#0f0f0f`                   |
| `--background-hover-color` | `var(--grey-3)`             | `var(--grey-3)`             |
| `--border-color`           | `var(--grey-4)`             | `var(--grey-4)`             |
| `--text-primary-color`     | `var(--grey-12)`            | `var(--grey-12)`            |
| `--text-secondary-color`   | `var(--grey-9)`             | `var(--grey-9)`             |
| `--text-accent-color`      | `var(--accent-9)`           | `var(--accent-9)`           |
| `--icon-primary-color`     | `var(--text-primary-color)` | `var(--text-primary-color)` |
| `--icon-secondary-color`   | `var(--grey-8)`             | `var(--grey-8)`             |
| `--icon-accent-color`      | `var(--text-accent-color)`  | `var(--text-accent-color)`  |
| `--success-color`          | `#15a45f`                   | `#15a45f`                   |
| `--danger-color`           | `#e9354b`                   | `#e9354b`                   |
| `--warn-color`             | `#ff8409`                   | `#ff8409`                   |

## Component variables

Override a component variable to change that component independently of the shared colors. The tables list the current defaults, including references to palette and shared variables. Values without separate theme columns apply to both light and dark themes.

For example, customize primary buttons without changing the accent palette used elsewhere:

```css
#omniston-widget-container {
  --button-primary-background-color: #7c3aed;
  --button-primary-background-hover-color: #6d28d9;
  --button-primary-text-color: #ffffff;
  --button-primary-text-hover-color: #ffffff;
}
```

### Icon buttons

| Variable                               | Default                     |
| -------------------------------------- | --------------------------- |
| `--icon-button-text-color`             | `var(--icon-primary-color)` |
| `--icon-button-background-color`       | `var(--background-color)`   |
| `--icon-button-background-hover-color` | `var(--grey-2)`             |
| `--icon-button-border-width`           | `var(--border-width)`       |
| `--icon-button-border-radius`          | `var(--border-radius)`      |
| `--icon-button-border-color`           | `var(--border-color)`       |

### Switches

| Variable                                          | Light default          | Dark default           |
| ------------------------------------------------- | ---------------------- | ---------------------- |
| `--switch-track-border-width`                     | `var(--border-width)`  | `var(--border-width)`  |
| `--switch-track-border-radius`                    | `var(--border-radius)` | `var(--border-radius)` |
| `--switch-track-checked-border-color`             | `var(--accent-9)`      | `var(--accent-9)`      |
| `--switch-track-checked-background-color`         | `var(--accent-9)`      | `var(--accent-9)`      |
| `--switch-track-checked-background-hover-color`   | `var(--accent-11)`     | `var(--accent-11)`     |
| `--switch-track-unchecked-border-color`           | `var(--grey-4)`        | `var(--grey-4)`        |
| `--switch-track-unchecked-background-color`       | `var(--grey-3)`        | `var(--grey-5)`        |
| `--switch-track-unchecked-background-hover-color` | `var(--grey-5)`        | `var(--grey-8)`        |
| `--switch-thumb-background-color`                 | `var(--grey-1)`        | `var(--grey-12)`       |
| `--switch-thumb-border-width`                     | `var(--border-width)`  | `var(--border-width)`  |
| `--switch-thumb-border-radius`                    | `var(--border-radius)` | `var(--border-radius)` |
| `--switch-thumb-checked-border-color`             | `var(--accent-9)`      | `var(--accent-9)`      |
| `--switch-thumb-unchecked-border-color`           | `var(--grey-4)`        | `var(--grey-4)`        |

### Primary buttons

| Variable                                     | Light default          | Dark default           |
| -------------------------------------------- | ---------------------- | ---------------------- |
| `--button-primary-text-color`                | `var(--grey-1)`        | `var(--grey-12)`       |
| `--button-primary-text-hover-color`          | `var(--grey-1)`        | `var(--grey-12)`       |
| `--button-primary-text-disabled-color`       | `var(--grey-1)`        | `var(--grey-12)`       |
| `--button-primary-background-color`          | `var(--accent-9)`      | `var(--accent-9)`      |
| `--button-primary-background-hover-color`    | `var(--accent-11)`     | `var(--accent-11)`     |
| `--button-primary-background-disabled-color` | `var(--grey-7)`        | `var(--grey-7)`        |
| `--button-primary-border-radius`             | `var(--border-radius)` | `var(--border-radius)` |

### Secondary buttons

| Variable                                       | Light default             | Dark default              |
| ---------------------------------------------- | ------------------------- | ------------------------- |
| `--button-secondary-text-color`                | `var(--accent-9)`         | `var(--accent-9)`         |
| `--button-secondary-text-hover-color`          | `var(--accent-9)`         | `var(--accent-9)`         |
| `--button-secondary-text-disabled-color`       | `var(--grey-8)`           | `var(--grey-8)`           |
| `--button-secondary-background-color`          | `transparent`             | `transparent`             |
| `--button-secondary-background-hover-color`    | `var(--accent-3)`         | `var(--accent-3)`         |
| `--button-secondary-background-disabled-color` | `var(--background-color)` | `var(--background-color)` |
| `--button-secondary-border-width`              | `var(--border-width)`     | `var(--border-width)`     |
| `--button-secondary-border-radius`             | `var(--border-radius)`    | `var(--border-radius)`    |
| `--button-secondary-border-color`              | `var(--accent-6)`         | `var(--accent-8)`         |
| `--button-secondary-border-hover-color`        | `var(--accent-6)`         | `var(--accent-8)`         |
| `--button-secondary-border-disabled-color`     | `var(--grey-8)`           | `var(--grey-8)`           |

### Inputs

| Variable                          | Light default          | Dark default           |
| --------------------------------- | ---------------------- | ---------------------- |
| `--input-border-radius`           | `var(--border-radius)` | `var(--border-radius)` |
| `--input-border-color`            | `var(--grey-4)`        | `var(--grey-5)`        |
| `--input-background-color`        | `var(--grey-3)`        | `var(--grey-3)`        |
| `--input-placeholder-color`       | `var(--grey-8)`        | `var(--grey-8)`        |
| `--input-caret-color`             | `var(--accent-9)`      | `var(--accent-9)`      |
| `--input-active-background-color` | `var(--grey-1)`        | `var(--grey-1)`        |
| `--input-active-border-color`     | `var(--accent-9)`      | `var(--accent-9)`      |
| `--input-invalid-border-color`    | `var(--danger-color)`  | `var(--danger-color)`  |

Input border width uses the shared `--border-width` variable.

### Form sections

| Variable                  | Default                |
| ------------------------- | ---------------------- |
| `--form-background-color` | `var(--grey-2)`        |
| `--form-border-color`     | `var(--border-color)`  |
| `--form-border-width`     | `var(--border-width)`  |
| `--form-border-radius`    | `var(--border-radius)` |

### Dialogs and drawers

| Variable                            | Default                |
| ----------------------------------- | ---------------------- |
| `--dialog-background-color`         | `var(--grey-1)`        |
| `--dialog-border-color`             | `var(--border-color)`  |
| `--dialog-border-width`             | `var(--border-width)`  |
| `--dialog-border-radius`            | `var(--border-radius)` |
| `--dialog-overlay-background-color` | `rgba(0, 0, 0, 0.25)`  |

### Alerts

| Variable                   | Light default                                         | Dark default                                          |
| -------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| `--alert-text-color`       | `var(--accent-10)`                                    | `var(--grey-11)`                                      |
| `--alert-icon-color`       | `var(--accent-9)`                                     | `var(--accent-11)`                                    |
| `--alert-border-color`     | `var(--accent-6)`                                     | `var(--accent-6)`                                     |
| `--alert-border-width`     | `var(--border-width)`                                 | `var(--border-width)`                                 |
| `--alert-border-radius`    | `min(var(--border-radius), var(--max-border-radius))` | `min(var(--border-radius), var(--max-border-radius))` |
| `--alert-background-color` | `var(--accent-5)`                                     | `var(--accent-4)`                                     |

### Tooltips

| Variable                     | Default                                               |
| ---------------------------- | ----------------------------------------------------- |
| `--tooltip-background-color` | `var(--form-background-color)`                        |
| `--tooltip-border-color`     | `var(--border-color)`                                 |
| `--tooltip-border-width`     | `var(--border-width)`                                 |
| `--tooltip-border-radius`    | `min(var(--border-radius), var(--max-border-radius))` |
| `--tooltip-text-color`       | `var(--text-primary-color)`                           |

### Toggle groups

| Variable                                   | Light default                      | Dark default                       |
| ------------------------------------------ | ---------------------------------- | ---------------------------------- |
| `--toggle-group-border-width`              | `var(--border-width)`              | `var(--border-width)`              |
| `--toggle-group-border-radius`             | `var(--border-radius)`             | `var(--border-radius)`             |
| `--toggle-group-text-color`                | `var(--grey-12)`                   | `var(--grey-12)`                   |
| `--toggle-group-border-color`              | `var(--grey-4)`                    | `var(--border-color)`              |
| `--toggle-group-background-color`          | `transparent`                      | `transparent`                      |
| `--toggle-group-hover-text-color`          | `var(--accent-11)`                 | `var(--accent-12)`                 |
| `--toggle-group-hover-border-color`        | `var(--toggle-group-border-color)` | `var(--toggle-group-border-color)` |
| `--toggle-group-hover-background-color`    | `var(--grey-2)`                    | `var(--grey-2)`                    |
| `--toggle-group-selected-text-color`       | `var(--accent-10)`                 | `var(--grey-11)`                   |
| `--toggle-group-selected-border-color`     | `var(--accent-10)`                 | `var(--accent-10)`                 |
| `--toggle-group-selected-background-color` | `var(--accent-5)`                  | `var(--accent-4)`                  |

### Snackbars

| Variable                      | Default                        |
| ----------------------------- | ------------------------------ |
| `--snackbar-background-color` | `var(--form-background-color)` |
| `--snackbar-border-color`     | `var(--border-color)`          |
| `--snackbar-border-width`     | `var(--border-width)`          |
| `--snackbar-border-radius`    | `var(--border-radius)`         |

### Asset swap button

| Variable                               | Default                        |
| -------------------------------------- | ------------------------------ |
| `--swap-button-icon-color`             | `var(--icon-primary-color)`    |
| `--swap-button-background-color`       | `var(--background-color)`      |
| `--swap-button-border-color`           | `var(--border-color)`          |
| `--swap-button-border-width`           | `var(--border-width)`          |
| `--swap-button-border-radius`          | `var(--border-radius)`         |
| `--swap-button-hover-background-color` | `var(--form-background-color)` |

### Active order button

| Variable                                 | Default                |
| ---------------------------------------- | ---------------------- |
| `--active-order-button-background-color` | `var(--grey-4)`        |
| `--active-order-button-border-color`     | `var(--border-color)`  |
| `--active-order-button-border-width`     | `var(--border-width)`  |
| `--active-order-button-border-radius`    | `var(--border-radius)` |

### Loading skeletons

| Variable                         | Default                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------- |
| `--skeleton-background-gradient` | `linear-gradient(90deg, var(--grey-3) 0%, var(--grey-6) 50%, var(--grey-3) 100%)` |
| `--skeleton-border-radius`       | `var(--border-radius)`                                                            |

### Labels

| Variable                | Default                |
| ----------------------- | ---------------------- |
| `--label-border-radius` | `var(--border-radius)` |

## Layout and icons

Use these variables to adjust the widget's dimensions, spacing, and borders. Component border widths and radii reference the shared variables unless you override them individually.

| Variable              | Default               | Purpose                                                                                 |
| --------------------- | --------------------- | --------------------------------------------------------------------------------------- |
| `--widget-width`      | `600px`               | Maximum container width.                                                                |
| `--widget-padding`    | `24px`                | Container padding.                                                                      |
| `--spacing-base`      | `4px`                 | Base unit for the spacing scale.                                                        |
| `--border-width`      | `1px`                 | Shared border width.                                                                    |
| `--border-radius`     | `0px`                 | Shared corner radius.                                                                   |
| `--max-border-radius` | `16px`                | Corner-radius limit for alerts and tooltips.                                            |
| `--dialog-width`      | `440px`               | Desktop dialog width.                                                                   |
| `--snackbar-width`    | `var(--dialog-width)` | Snackbar width.                                                                         |
| `--breakpoint-md`     | `48rem`               | Breakpoint for switching between desktop dialogs and mobile drawers, read when mounted. |

The container has a minimum width of `340px`. This example sets its maximum width, padding, and corner radius:

```css
#omniston-widget-container {
  --widget-width: 440px;
  --widget-padding: 20px;
  --border-radius: 12px;
}
```

Set `data-icon-variant` on the container to choose `square` icons (the default) or `rounded` icons:

```html
<div id="omniston-widget-container" data-icon-variant="rounded"></div>
```


---

# 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.ston.fi/developer-section/widget/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.
