Skip to main content
DeepSpace has a theming system that keeps your widget’s colors consistent with the platform’s UI elements (chat panel, pills, modals). It works automatically for most widgets, but you can take control if you need to.

​
How It Works

  1. You define color tokens in your styles.css using Tailwind v4’s @theme block
  2. DeepSpaceThemeProvider (set up in main.tsx) reads those tokens from the DOM
  3. It maps them to 50+ --theme-* CSS variables that style the platform’s overlay UI
  4. Your widget uses the Tailwind tokens directly; the platform UI uses the --theme-* variables
This means the chat panel, modals, and other DeepSpace chrome automatically match your widget’s color scheme. In most cases, you just define your colors in styles.css and everything works: 
@import "tailwindcss";

@theme {
  --color-background: #0a0f1a;
  --color-foreground: #f1f5f9;
  --color-card: #0f172a;
  --color-primary: #8b5cf6;
  --color-secondary: #1e293b;
  --color-accent: #22d3ee;
  --color-muted: #94a3b8;
  --color-border: #1e293b;
  --color-surface-elevated: #1a1f35;
  --color-surface-overlay: #252b45;
  --color-content: #e2e8f0;
}
The theme provider auto-detects these CSS variables and maps them:
Your CSS tokenMaps to
--color-surface-elevatedPanel/toolbar backgrounds
--color-surface-overlayButton/secondary backgrounds
--color-primaryAccent/interactive elements
--color-contentText color
--color-backgroundUsed for dark/light mode detection

​
Explicit Theme

If you need more control, pass a theme config directly to the provider: 
<DeepSpaceThemeProvider theme={{
  primaryColor: '#0f172a',
  secondaryColor: '#1e293b',
  accentColor: '#8b5cf6',
  textColor: '#f1f5f9',
  glassmorphism: true,
}}>
  <App />
</DeepSpaceThemeProvider>

​
Theme Config Options

PropertyRequiredDescription
primaryColorYesPanel/toolbar background
secondaryColorYesButton/secondary backgrounds
accentColorYesInteractive elements, highlights
textColorYesPrimary text color
panelColorNoOverride panel background
accentContrastColorNoText on accent (default: #ffffff)
borderColorNoDefaults to secondaryColor
backgroundColorNoPage background (for dark/light detection)
shadowColorNoDefault: #000000
highlightColorNoGlass effects (default: #ffffff)
glassmorphismNoEnable blur effects (default: true)

​
Generated Variables

The theme system generates variables across several namespaces: --theme-* — Core platform UI:
  • --theme-panel-bg, --theme-panel-border
  • --theme-button-bg, --theme-button-hover, --theme-button-active
  • --theme-text, --theme-text-secondary, --theme-text-tertiary
  • --theme-accent, --theme-accent-hover
  • --theme-shadow-primary, --theme-component-shadow
--chat-* — Chat panel:
  • --chat-panel-bg, --chat-button-bg, --chat-accent
  • --chat-panel-gradient
--ui-* — Modals and overlays:
  • --ui-bg-primary, --ui-bg-secondary
  • --ui-text-primary, --ui-accent
  • --ui-active-bg

​
Dark/Light Mode

The theme system automatically detects whether your widget is dark or light by calculating the luminance of backgroundColor. This affects:
  • Default shadow intensity
  • Glass effect highlight colors
  • UI overlay contrast
You don’t need to set a “mode” — it’s inferred from your colors.