> For the complete documentation index, see [llms.txt](https://surf-2.gitbook.io/surfliquid-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surf-2.gitbook.io/surfliquid-docs/sdk-docs/customisation.md).

# Customisation

Surf SDK is built to match your product's visual identity. Customisation works at three levels: theme tokens, CSS class overrides, and layout modes.

***

### Theme Tokens

Pass a `theme` object to the widget to override design tokens:

```typescript
<SurfWidget
  theme={{
    colors: {
      primary: "#6366f1",         // buttons, active states, progress indicators
      primaryText: "#ffffff",     // text on primary-coloured surfaces
      background: "#f9fafb",      // widget background
      cardBackground: "#ffffff",  // card and modal backgrounds
      text: "#111827",            // primary body text
      textSecondary: "#6b7280",   // labels and descriptions
      apy: "#10b981",             // APY value highlight colour
      border: "#e5e7eb",          // dividers and outlines
      success: "#10b981",         // success state colour
    },
    borderRadius: "12px",
    fontFamily: "'Inter', sans-serif",
  }}
/>
```

Every colour, radius and font can be overridden to match your brand.

***

### CSS Class Overrides

Every UI element in the widget carries a scoped `.surf-*` class under the `[data-surf-widget]` root. You can target any element without modifying the widget source:

```css
[data-surf-widget] .surf-btn--primary {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
}
[data-surf-widget] .surf-card {
  box-shadow: 0 4px 24px rgba(0,0,0,0.08);
}
[data-surf-widget] .surf-stat-value--apy {
  font-size: 2rem;
}
```

**Available class groups:**

* `.surf-card` - card containers
* `.surf-btn` - buttons (with modifiers like `--primary`)
* `.surf-modal` - modal overlays
* `.surf-tabs` - tab navigation
* `.surf-step` - progress tracker steps
* `.surf-amount-box` - amount input area
* `.surf-stat-value` - statistic displays (with modifiers like `--apy`)
* `.surf-activity-item` - activity feed entries

All widget styles are scoped to `[data-surf-widget]`. There is zero risk of style conflicts with your existing application CSS.

***

### Layout Modes

Four integration patterns let you control how much of the widget UI you own:

| Mode                      | How to use                                                         | Best for                                             |
| ------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------- |
| **All-in-One**            | `<SurfWidget />`                                                   | Fastest integration. Drop in and done.               |
| **Provider + Context**    | `<SurfProvider>` + `useSurf()`                                     | Scatter widget elements across your own layout       |
| **Individual Components** | `VaultCard`, `DepositModal`, `WithdrawModal`, `VaultActivityModal` | Mix and match pre-built components into your design  |
| **Headless Hooks**        | `useVault`, `useDeposit`, `useWithdraw`, `useAgentMessages`        | Build a fully custom UI using your own design system |

For headless integration, see Hooks and Headless Mode.