Theming Overview

EpisBox ships with four built-in presets and a full token system for complete customization. Pass theme config to EPIS.init() — no CSS access to the iframe needed.

Preset themes

Start with a preset and override individual tokens on top:

Preset	Mode	Primary	Font	Radius
`'dark'`	Dark	`#4f46e5` (indigo)	Inter	12px
`'light'`	Light	`#4f46e5` (indigo)	Inter	12px
`'auraspace'`	Dark	`#3dd6c8` (mint)	Poppins	20px
`'minimal'`	Light	`#111111` (near-black)	system	6px

Applying a preset

EPIS.init({
  clientId: 'your-client-id',
  theme: { preset: 'dark' }
});

EPIS.init({
  clientId: 'your-client-id',
  theme: { preset: 'light' }
});

EPIS.init({
  clientId: 'your-client-id',
  theme: { preset: 'auraspace' }
});

EPIS.init({
  clientId: 'your-client-id',
  theme: { preset: 'minimal' }
});

Overriding tokens on top of a preset

Individual tokens always win over the preset base:

EPIS.init({
  clientId: 'your-client-id',
  theme: {
    preset:  'dark',        // base: dark indigo theme
    primary: '#E32E78',     // override: your brand pink
    font:    'Nunito',      // override: your brand font
    radius:  '16px',        // override: your corner radius
  }
});

Only the tokens you specify are overridden — everything else comes from the preset.

Building a custom theme from scratch

If none of the presets match, specify tokens directly. You only need to provide primary and mode — everything else can be derived:

EPIS.init({
  clientId: 'your-client-id',
  theme: {
    primary:    '#E32E78',
    secondary:  '#F1873C',
    background: '#0a0a0a',
    surface:    '#111111',
    text:       '#F2F2FA',
    font:       'Inter',
    radius:     '12px',
    mode:       'dark',
  }
});

Token derivation

When you omit optional tokens, the SDK derives them automatically:

Omitted token	Derived from
`secondary`	`primary` hue shifted +30° in HSL
`surface`	`background` lightened 8% (dark) or darkened 3% (light)
`surface2`	`surface` by the same step
`textMuted`	`text` at 60% opacity
`border`	white/black at 8% opacity
`userBubble`	`primary` at 15% opacity
`aiBubble`	white/black at 4% opacity
`radiusSmall`	~60% of `radius`

Don’t want to compute all this by hand? Skip to AI theming skill below — describe your brand, get a ready-to-paste config.

AI theming skill

The EpisBox repo ships an AI agent skill graph at skills/customize/ that does everything on this page for you — no manual color math, no contrast-ratio checking by hand. Point any AI coding agent (Claude Code, Cursor, etc.) at theme-agent.md in that directory and describe your brand — colors, font, how rounded your UI is. The agent will:

Ask clarifying questions if anything’s ambiguous (e.g. missing secondary color, non-standard font)
Derive every token you didn’t specify (secondary, surface, textMuted, border, bubble colors) using the same rules as the token derivation table above
Verify WCAG AA contrast ratios and flag anything that would fail
Output a ready-to-paste theme object for EPIS.init(), with a short explanation of each derived value

It’s strictly scoped to the theme object — it won’t touch your auth flow, API calls, or component code. See constraints.md in the skill directory for the exact boundary, and examples/auraspace.md for a full worked session.

Syncing theme changes after init

If your own app has a light/dark toggle (or any other theme change) that fires after EPIS.init(), use EPIS.updateTheme() to push it to every mounted instance — no unmount/remount, no flicker, no lost conversation:

function onAppThemeToggle(isDark) {
  EPIS.updateTheme({
    preset: 'auraspace',
    mode: isDark ? 'dark' : 'light',
  });
}

It accepts the same shape as config.theme, including preset — only the tokens you pass are changed, everything else from the current theme stays as-is. See the updateTheme() reference for full details.

System mode

Set mode: 'system' to automatically follow the user’s OS color scheme preference:

EPIS.init({
  clientId: 'your-client-id',
  theme: {
    primary: '#4f46e5',
    mode:    'system',  // switches between dark/light with OS setting
  }
});

In 'system' mode, EPIS uses the dark token defaults when the OS is in dark mode and the light token defaults when in light mode. Your primary, font, and radius values apply in both.

Get Started

Frameworks

SDK Reference

Theming

More

Theming Overview

Preset themes

Applying a preset

Overriding tokens on top of a preset

Building a custom theme from scratch

Token derivation

AI theming skill

Syncing theme changes after init

System mode

​Preset themes

​Applying a preset

​Overriding tokens on top of a preset

​Building a custom theme from scratch

​Token derivation

​AI theming skill

​Syncing theme changes after init

​System mode

Preset themes

Applying a preset

Overriding tokens on top of a preset

Building a custom theme from scratch

Token derivation

AI theming skill

Syncing theme changes after init

System mode