Theme Builder

The theme builder is the admin overlay tool for customizing the visual appearance of all Spotlight UI components -- tooltips, modals, spotlights, checklists, and tour steps. It provides color pickers, typography controls, spacing adjustments, and a live preview that updates in real time.

Theme Architecture

Themes are stored per tenant in the Spotlight.Themes.Definitions DynamoDB table:

Spotlight.Themes.Definitions
PK: tenant_id = "tenant_abc"
SK: theme_id  = "theme_default" | "theme_dark" | "theme_custom_1"

Each tenant can have multiple themes. One theme is marked as the default and is applied to all content unless a specific tour or content item overrides it.

Theme Structure

A theme is a JSON object containing design tokens organized by category:

{
  "theme_id": "theme_default",
  "name": "Brand Theme",
  "is_default": true,
  "tokens": {
    "colors": {
      "primary": "#4F46E5",
      "primary_hover": "#4338CA",
      "secondary": "#10B981",
      "background": "#FFFFFF",
      "surface": "#F9FAFB",
      "text_primary": "#111827",
      "text_secondary": "#6B7280",
      "border": "#E5E7EB",
      "overlay": "rgba(0, 0, 0, 0.5)",
      "error": "#EF4444",
      "success": "#10B981",
      "warning": "#F59E0B"
    },
    "typography": {
      "font_family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
      "title_size": "18px",
      "title_weight": "600",
      "title_line_height": "1.4",
      "body_size": "14px",
      "body_weight": "400",
      "body_line_height": "1.6",
      "caption_size": "12px",
      "caption_weight": "500"
    },
    "spacing": {
      "tooltip_padding": "16px 20px",
      "modal_padding": "24px",
      "step_counter_gap": "8px",
      "button_padding": "8px 16px",
      "border_radius": "8px",
      "border_radius_small": "4px",
      "shadow": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
      "shadow_large": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)"
    },
    "components": {
      "tooltip_max_width": "360px",
      "modal_max_width": "480px",
      "modal_backdrop_blur": "4px",
      "progress_bar_height": "4px",
      "arrow_size": "8px",
      "close_button_size": "24px",
      "spotlight_border_radius": "8px",
      "spotlight_padding": "8px",
      "checklist_width": "320px"
    },
    "animations": {
      "duration": "200ms",
      "easing": "cubic-bezier(0.4, 0, 0.2, 1)",
      "entrance": "fadeInUp",
      "exit": "fadeOutDown"
    }
  }
}

Visual Editor

The theme builder panel is organized into collapsible sections matching the token categories:

Colors

Each color token has a color picker with hex, RGB, and HSL input modes. The picker shows WCAG contrast ratio against the background color to ensure accessibility:

• AA pass (4.5:1 for normal text, 3:1 for large text) -- shown with a green check.
• AA fail -- shown with an orange warning.
• AAA pass (7:1) -- shown with a double green check.

Contrast checking

The theme builder automatically validates contrast ratios for text_primary against background and text_secondary against surface. Fix any contrast warnings before publishing.

Typography

• Font family -- dropdown with web-safe fonts plus a custom input for hosted fonts.
• Size controls -- numeric inputs with px/rem toggle for title, body, and caption sizes.
• Weight -- dropdown with standard font weights (300-800).
• Line height -- numeric input (unitless multiplier).

Spacing

• Padding -- visual box model editor for tooltip and modal padding.
• Border radius -- slider from 0px to 24px with preview.
• Shadow -- presets (none, subtle, medium, prominent) plus a custom CSS box-shadow input.

Component Dimensions

• Max widths -- constrain tooltip and modal widths.
• Arrow size -- control the size of tooltip arrows.
• Progress bar -- adjust height and color of the tour progress indicator.

Animations

• Duration -- slider from 0ms (instant) to 500ms.
• Easing -- dropdown with standard easing presets plus a cubic-bezier editor.
• Entrance/exit -- select from built-in animation presets: fadeIn, fadeInUp, fadeInDown, slideIn, scaleIn.

Live Preview

The theme builder includes a live preview panel that renders sample Spotlight components with the current token values. Changes are reflected immediately without saving:

+--------------------------------------------------+
|  Theme Builder                          [Preview] |
|                                                   |
|  Colors                                          |
|  +-----+  Primary: #4F46E5                       |
|  | [*] |  Background: #FFFFFF                    |
|  +-----+  Text: #111827                          |
|                                                   |
|  Preview Panel                                   |
|  +--------------------------------------------+  |
|  |  [Sample Tooltip]                          |  |
|  |  "Welcome to your dashboard"               |  |
|  |  This is how your tooltips will look.      |  |
|  |                           [Next ->]        |  |
|  +--------------------------------------------+  |
|                                                   |
|  +--------------------------------------------+  |
|  |  [Sample Checklist]                        |  |
|  |  [ ] Set up your profile                   |  |
|  |  [x] Connect your data source              |  |
|  |  [ ] Create your first dashboard           |  |
|  +--------------------------------------------+  |
+--------------------------------------------------+

The preview renders four component types:

• Tooltip with arrow
• Modal with backdrop
• Step progress indicator (1 of N)
• Checklist widget

Theme API

Themes are managed through the admin API:

# List all themes for the tenant
GET /v1/admin/themes

# Create a new theme
POST /v1/admin/themes

# Update a theme
PUT /v1/admin/themes/{theme_id}

# Delete a non-default theme
DELETE /v1/admin/themes/{theme_id}

# Set a theme as the tenant default
POST /v1/admin/themes/{theme_id}/set-default

Create a theme

curl -X POST https://api.example.com/v1/admin/themes \
  -H "X-API-Key: sk_live_..." \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dark Mode",
    "tokens": {
      "colors": {
        "primary": "#818CF8",
        "background": "#1F2937",
        "surface": "#374151",
        "text_primary": "#F9FAFB",
        "text_secondary": "#D1D5DB"
      }
    }
  }'

Only the tokens you provide are applied; any omitted tokens fall back to the platform defaults. This allows creating partial themes that override only specific values.

Audit Events

All theme mutations emit admin audit events:

Action	Event Type
Create theme	ThemeCreatedByAdmin
Update theme	ThemeUpdatedByAdmin
Delete theme	ThemeDeletedByAdmin
Set as default	ThemeSetDefaultByAdmin

Events include before/after snapshots of the theme tokens, enabling full change tracking and rollback analysis.

Theme Inheritance

Themes apply in the following order of precedence (highest wins):

1. Content-level theme override -- a specific tour or content item can reference a theme_id.
2. Tenant default theme -- the theme marked is_default: true.
3. Platform defaults -- built-in Spotlight defaults if no tenant theme exists.

Platform Defaults  <--  Tenant Default Theme  <--  Content Override

This allows admins to set a global brand theme while overriding individual tours for special use cases (e.g., a dark-themed onboarding tour for a code editor page).