Visual Theme Configuration

This document explains how to customize the visual appearance of your InsightEmbed widget to match your website's design and branding.

Theme Overview

The InsightEmbed widget is designed to be highly customizable, allowing you to create a seamless integration with your website's existing design. You can modify colors, typography, spacing, and other visual elements to create a consistent user experience.

Configuration Methods

You can customize the widget's appearance through:

1. Management Portal: Use the visual theme editor in the Management Portal
2. API: Set theme properties programmatically via the Widget Configuration API
3. Initialization Options: Pass theme settings when initializing the widget

Color Scheme

Primary Colors

Property	Description	Default
primaryColor	Main accent color used for buttons and interactive elements	#3E63DD
primaryHoverColor	Color for hover states of primary elements	#364FC7
secondaryColor	Secondary accent color	#4B5563

Text Colors

Property	Description	Default
textColor	Main text color	#1F2937
textSecondaryColor	Secondary text color for less emphasis	#6B7280
linkColor	Color for text links	#3E63DD

Background Colors

Property	Description	Default
backgroundColor	Main widget background color	#FFFFFF
backgroundSecondaryColor	Secondary background for panels and cards	#F3F4F6
borderColor	Color for borders and dividers	#E5E7EB

Typography

Font Family

Property	Description	Default
fontFamily	Primary font family	'Inter', system-ui, sans-serif
headingFontFamily	Font family for headings (if different)	inherit

Font Sizes

Property	Description	Default
baseFontSize	Base font size in pixels	16
headingScale	Scale factor for headings	1.2

Border Radius

Property	Description	Default
borderRadius	Border radius for widget corners in pixels	8
buttonBorderRadius	Border radius for buttons in pixels	6

Shadows

Property	Description	Default
shadowColor	Color for shadows	rgba(0, 0, 0, 0.1)
shadowIntensity	Shadow intensity (0-1)	0.2

Example Configuration

Using the Management Portal

Navigate to Widget Settings > Visual Theme in the Management Portal to access the visual theme editor.

Using JavaScript Initialization

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  theme: {
    primaryColor: '#0F766E',
    backgroundColor: '#F8FAFC',
    textColor: '#334155',
    borderRadius: 12,
    fontFamily: '"Poppins", sans-serif',
    baseFontSize: 15
  }
});

Using the API

curl -X PATCH https://api.insightembed.com/v1/widget/configuration \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": {
      "primaryColor": "#0F766E",
      "backgroundColor": "#F8FAFC",
      "textColor": "#334155",
      "borderRadius": 12,
      "fontFamily": "\"Poppins\", sans-serif",
      "baseFontSize": 15
    }
  }'

Dark Mode Support

The widget can automatically adapt to your website's dark mode settings or be configured with a separate dark theme.

Auto Dark Mode Detection

By default, the widget detects if your website is using dark mode via the prefers-color-scheme media query or common CSS variables.

Custom Dark Theme

You can specify a separate dark theme configuration:

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  theme: {
    // Light theme settings
    primaryColor: '#0F766E',
    backgroundColor: '#F8FAFC',
    textColor: '#334155',
    
    // Dark theme settings
    dark: {
      primaryColor: '#14B8A6',
      backgroundColor: '#1E293B',
      textColor: '#E2E8F0',
      borderColor: '#475569'
    }
  }
});

Custom CSS

For advanced customization, you can provide custom CSS that will be injected into the widget's shadow DOM:

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  theme: {
    customCSS: `
      .insight-embed-button {
        text-transform: uppercase;
        letter-spacing: 0.05em;
      }
      
      .insight-embed-result {
        padding: 1.5rem;
      }
    `
  }
});

Best Practices

1. Match Your Brand: Align the widget's colors and typography with your website's brand guidelines

2. Contrast Ratio: Ensure sufficient contrast between text and background colors for accessibility

3. Responsive Considerations: Test your theme on different screen sizes

4. Dark Mode: Provide dark mode alternatives for better user experience

5. Minimal Customization: Start with minimal changes to the default theme and adjust as needed

Theme Presets

The Management Portal offers several theme presets that you can use as starting points:

• Default: Clean, professional appearance with blue accents
• Minimal: Subtle, unobtrusive design with minimal styling
• Bold: High-contrast design with strong colors
• Elegant: Refined design with subtle shadows and animations

You can select a preset and then customize it further to match your specific requirements.