Skip to main content

UI Themes

UI Themes control the visual appearance of GEM user interfaces. Each theme includes CSS styles, icons, background images, and optional zone maps for creating consistent, branded experiences across all UIs.

Overview​

The UI Themes page provides complete theme management:

  • CSS Editor: Customize styles and colors
  • Background Management: Upload and map background images
  • Icon Library: Manage icon sets
  • Zone Maps: Create interactive floor plans
  • Theme Assignment: Apply themes to specific UIs
  • Preview: Test themes before deployment

Theme Selector​

Top toolbar provides theme selection and management:

Theme Selector

  • Dropdown of all themes
  • Select to edit
  • Shows theme name

Actions:

  • Copy - Duplicate existing theme
  • New - Create blank theme
  • Export - Export theme files to filesystem

UI Selector

  • Choose UI to apply theme to
  • Shows current theme for each UI

Set Button

  • Apply selected theme to selected UI
  • Saves theme attribute for UI

Preview Button

  • Open theme in live preview window
  • Test in real environment

Theme Tabs​

Themes have four tabs for different asset types:

1. Styles Tab​

CSS editor for theme styling:

Features:

  • Syntax-highlighted CSS editor
  • Edit theme's style.css file
  • Auto-complete (basic)
  • Search and replace (Ctrl+F / Ctrl+H)
  • Code formatting (Ctrl+Shift+B)
  • Status bar showing cursor position (line, column)
  • Unsaved changes warning when navigating away
  • Save button to apply changes

CSS Variables:

Themes should define CSS variables for consistency:

:root {
    /* Colors */
    --primary-color: #277ad4;
    --secondary-color: #1e5ba8;
    --background-color: #ffffff;
    --surface-color: #f9f9f9;
    --text-primary: #1f2937;
    --text-secondary: #6b7280;
    --border-color: #e5e7eb;

    /* Spacing */
    --spacing-xs: 4px;
    --spacing-sm: 8px;
    --spacing-md: 16px;
    --spacing-lg: 24px;

    /* Typography */
    --font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
    --font-size-base: 16px;
    --font-size-lg: 18px;
    --font-size-xl: 24px;

    /* Layout */
    --border-radius: 8px;
    --shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

Component Styles:

Style GEM components:

/* Zone Cards */
.zone-card {
    background: var(--surface-color);
    border: 1px solid var(--border-color);
    border-radius: var(--border-radius);
    padding: var(--spacing-md);
}

.zone-card.on {
    background: var(--primary-color);
    color: white;
}

/* Buttons */
.btn-primary {
    background: var(--primary-color);
    color: white;
    padding: var(--spacing-sm) var(--spacing-md);
    border-radius: var(--border-radius);
}

/* Navigation */
.nav-control {
    font-size: var(--font-size-base);
    padding: var(--spacing-sm);
}

Saving:

  • Click Save button after editing
  • Changes apply immediately to preview window (if open)
  • UIs reload automatically (if configured)

2. Backgrounds Tab​

Manage background images for pages and routes:

Background Selector

  • Dropdown of uploaded background images
  • Preview changes background display

Route Selector

  • Dropdown of all routes/pages
  • Special route * = default background for all pages

Mapping Actions:

  • Set - Map selected background to selected route
  • Unset - Remove background mapping for route

Upload:

  • File input to select image files
  • Upload button to upload to theme

Preview:

  • Large preview area shows selected background
  • Scaled to fit display area

Background Mapping​

Assign different backgrounds to different pages:

Example Configuration:

Route: * (default)
Background: neutral_texture.png

Route: /controls/lighting
Background: lighting_ambient.jpg

Route: /av
Background: theater_room.jpg

Route: /dashboard
Background: dashboard_bg.png

Result: Each page shows its configured background, or default if not mapped.

Uploading Backgrounds​

  1. Click file input
  2. Select PNG or JPG file
  3. Click Upload
  4. Background added to theme
  5. Appears in background selector

Image Requirements:

  • Format: PNG or JPG
  • Recommended Size: 1920x1080 or higher for large displays
  • File Size: < 5MB for performance
  • Aspect Ratio: Match target screen (16:9, 4:3, etc.)

3. Icons Tab​

Manage theme icon library:

Upload Icons:

  • File input supports multiple files
  • Click Upload Icons to upload
  • Icons added to theme's /icons/ directory

Icon Grid:

  • Visual display of all icons
  • Checkbox for batch selection
  • Icon filename shown below each icon

Delete Selected:

  • Select icons with checkboxes
  • Click Delete Selected
  • Confirm deletion
  • Icons removed from theme

Icon Count:

  • Display shows total icon count
  • Helps track theme assets

Icon Requirements​

  • Format: PNG or SVG
  • Size: 64x64 to 128x128 pixels recommended
  • Style: Should match theme aesthetic (flat, skeuomorphic, etc.)
  • Naming: Descriptive lowercase names (e.g., power.png, volume.svg)
  • Transparency: Use transparent backgrounds for flexibility

Standard Icons​

Include these icons for full GEM compatibility:

Control Icons:

  • lighting, audio, video, shades, climate, security
  • camera, pool, irrigation, lock, gate

Action Icons:

  • power, power_on, power_off, volume, mute
  • up, down, left, right, select, back, home
  • play, pause, stop, next, previous

State Icons:

  • on, off, open, closed, locked, unlocked
  • online, offline, warning, error, success

Misc Icons:

  • settings, user, notification, calendar, weather

4. Zone Maps Tab​

Create interactive floor plans and zone maps:

The Zone Maps tab provides a visual interface for placing zones on floor plan images:

Left Sidebar - Controls​

Map Configuration:

  • Subsystem - Select subsystem (lighting, shades, etc.)
  • UI - Select a specific UI to scope the map to (optional)
  • Map - Select floor plan image
  • Delete Current Map - Remove map and all zone positions

Zone Management:

  • Zone Group - Select which zone group to add
  • Add Zones to Map - Place all group zones on map
  • Remove Selected Zones - Delete selected zones from map

Map Upload:

  • File input to select floor plan image
  • Upload Map Image - Upload to theme

Status:

  • Shows current map name
  • Shows count of zones on map

Right Side - Map Display​

Interactive floor plan editor:

Features:

  • Drag Zones: Click and drag zone icons to position
  • Multi-Select: Shift+click to select multiple zones
  • Delete: Select zones and use Remove button
  • Zoom: Zoom in/out on map (if implemented)
  • Live Updates: Changes save automatically

Using Zone Maps​

1. Upload Floor Plan

  1. Create or obtain floor plan image:

    • Photo of actual floor
    • Architectural drawing
    • Simplified room layout
    • Recommended: PNG with transparency

  2. Click file input in "Upload New Map" section

  3. Select floor plan image

  4. Click Upload Map Image

  5. Map added to theme

2. Select Map and Subsystem

  1. Select Subsystem (e.g., Lighting)
  2. Select Map (e.g., first_floor.png)
  3. Map displays in right panel
  4. Select UI if working with specific UI

3. Add Zones to Map

  1. Select Zone Group (e.g., "First Floor Lights")
  2. Click Add Zones to Map
  3. Confirm adding zones
  4. All zones from group added at center of map (x:50%, y:50%)

4. Position Zones

  1. Click and drag each zone icon to actual position
  2. Icons represent zone locations on floor plan
  3. Positions save automatically as you drag

5. Remove Zones (Optional)

  1. Click zones to select (shift-click for multiple)
  2. Click Remove Selected Zones
  3. Confirm removal
  4. Zone icons removed from map

Zone Map Display​

Map data is stored as zone attributes:

{
  "map": "first_floor.png",
  "x": 25.5,
  "y": 42.3
}

Attribute: map_coordinate on each zone

Components: ZoneMap component renders maps in UIs

Theme Assignment​

Assigning Theme to UI​

  1. Select theme from dropdown
  2. Select UI from UI selector
  3. Click Set button
  4. Theme attribute set for UI: theme = "theme_name"
  5. UI immediately uses new theme (on next load)

Global vs. UI-Specific Themes​

Global Theme:

  • Set on UI with ID 0
  • Default for all UIs
  • Fallback when UI has no theme

UI-Specific Themes:

  • Set on specific UI IDs
  • Overrides global theme
  • Allows per-location branding

Example:

Global (UI 0): professional_theme
Kitchen Panel (UI 2): bright_theme
Master Bedroom (UI 5): dark_theme

Result:
- Kitchen shows bright theme
- Master bedroom shows dark theme
- All other UIs show professional theme

Theme Preview​

Click Preview button to test theme:

Preview Window​

Opens new browser window with:

  • Selected UI loaded
  • Selected theme applied
  • Live, functional interface

Use Preview For:

  • Testing color changes
  • Verifying icon compatibility
  • Checking background images
  • Ensuring readability
  • Client demonstrations

After Preview:

  • Close preview window when done
  • Returns to theme editor

Creating a New Theme​

To create a theme from scratch:

  1. Click New button
  2. Enter theme name (e.g., custom_dark)
  3. Theme created with minimal starter CSS
  4. Edit CSS in Styles tab
  5. Upload icons, backgrounds, maps
  6. Assign to UI and test

Copying a Theme​

To create a variation of an existing theme:

  1. Select source theme
  2. Click Copy button
  3. Enter new theme name (e.g., carbon_blue)
  4. Complete theme duplicated:
    • All CSS copied
    • All icons copied
    • All backgrounds copied
    • All maps copied
  5. Edit as needed

Use Cases:

  • Client-specific branding
  • Seasonal variations
  • Dark/light mode versions
  • Testing major changes without affecting original

Exporting Themes​

Click Export to write theme to filesystem:

Result:

  • Theme files written to static/themes/{theme_name}/
  • Includes:
    • style.css
    • /icons/ directory
    • /backgrounds/ directory
    • /maps/ directory

Use Cases:

  • Version control
  • Backup before changes
  • Sharing themes
  • External editing

Built-In Themes​

GEM includes several professional themes:

prodigy​

  • Default modern theme
  • Glassmorphic surfaces with translucency
  • Cinematic background imagery
  • Best for residential touchpanels and large displays

appeal​

  • iOS-style dark theme
  • System materials, vibrancy, SF-style typography
  • Pill-and-card components with subtle shadows
  • Best for mobile clients and minimalist installations

carbon​

  • Modern dark theme
  • Blue accent colors
  • High contrast
  • Professional aesthetic

flat​

  • Solid panels and high-contrast typography
  • Minimal effects — fastest rendering on low-power displays

legacy​

  • Classic GEM look retained for upgrades
  • Useful when refreshing UI is out of scope

Customize: Copy built-in theme and modify rather than editing directly.

:::note Shipped assets are auto-imported Theme files shipped with a release (e.g. new icons under static/themes/{name}/icons/) are backfilled into the database the first time GEM boots on the new version — so they behave like any other tracked asset (carried across copies, included in exports, served from disk after the next theme export). Existing rows are never overwritten, so user customizations are preserved. :::

Theme Development​

CSS Architecture​

Recommended Structure:

/* 1. CSS Variables */
:root {
    --primary-color: ...;
}

/* 2. Base Styles */
body, html {
    font-family: ...;
}

/* 3. Layout */
.container, .grid {
    ...
}

/* 4. Components */
.zone-card, .btn, .nav {
    ...
}

/* 5. States */
.on, .off, .active {
    ...
}

/* 6. Responsive */
@media (max-width: 768px) {
    ...
}

Responsive Design​

Support multiple screen sizes:

/* Desktop */
.zone-grid {
    grid-template-columns: repeat(4, 1fr);
}

/* Tablet */
@media (max-width: 1024px) {
    .zone-grid {
        grid-template-columns: repeat(3, 1fr);
    }
}

/* Mobile */
@media (max-width: 768px) {
    .zone-grid {
        grid-template-columns: repeat(2, 1fr);
    }
}

Dark Mode Themes​

Considerations for dark themes:

:root {
    --background-color: #1a1a1a;
    --surface-color: #2a2a2a;
    --text-primary: #e5e5e5;
    --text-secondary: #a0a0a0;

    /* Reduce contrast for readability */
    --border-color: #444444;

    /* Muted accent colors */
    --primary-color: #4a90e2;
}

Dark Mode Best Practices:

  • Reduce pure white (#fff) to off-white (#e5e5e5)
  • Increase border subtlety
  • Use muted accent colors
  • Test readability extensively
  • Consider eye strain for long viewing

Zone Maps​

Interactive floor plans enhance user experience:

Map Creation Workflow​

1. Create/Obtain Floor Plan

Options:

  • Take photo of floor
  • Scan architectural drawing
  • Create in design software (Illustrator, Figma)
  • Use online floor plan tools

Tips:

  • Remove clutter from photos
  • Increase contrast for clarity
  • Simplify details (focus on room outlines)
  • Use consistent scale

2. Prepare Image

  • Format: PNG (supports transparency)
  • Size: 1920x1080 or proportional
  • Resolution: 72-150 DPI
  • File size: < 2MB

3. Upload to Theme

  1. Select theme
  2. Go to Zone Maps tab
  3. In "Upload New Map" section:
    • Click file input
    • Select floor plan image
    • Click Upload Map Image
  4. Map appears in map selector

4. Add Zones to Map

  1. Select Subsystem (e.g., Lighting)
  2. Select UI (if UI-specific)
  3. Select Map (uploaded floor plan)
  4. Select Zone Group
  5. Click Add Zones to Map
  6. Confirm adding zones
  7. All zones from group appear on map at center

5. Position Zones

  1. Click and drag each zone icon to its physical location
  2. Icons represent zone positions:
    • Light: Place at light fixture location
    • Shade: Place at window location
    • Thermostat: Place at thermostat location
  3. Positions save automatically

6. Deploy Map

Maps can be used in:

  • Custom widgets (ZoneMap component)
  • Dashboard pages
  • Wall panels with touch screens
  • Interactive UIs

Map Display Options​

Icon Styles:

  • Use theme icons for zone icons
  • Different icons per zone type
  • State-based icons (on/off, open/closed)

Interactivity:

  • Click zone icon to toggle/control
  • Drag to reposition (admin mode)
  • Hover for zone details
  • Color-coded by state

Overlays:

  • Zone names/labels
  • Current state (on/off, position, temperature)
  • Real-time updates via subscriptions

Multiple Maps​

Create multiple maps for complex buildings:

Example:

first_floor.png
second_floor.png
basement.png
exterior.png
garage.png

Assign zones to appropriate maps:

  • First floor zones → first_floor.png
  • Second floor zones → second_floor.png
  • Etc.

UIs can switch between maps using map selector widget.

Best Practices​

Theme Design​

  1. Consistency: Use CSS variables for all colors, spacing, fonts

  2. Contrast: Ensure sufficient contrast for readability

    • WCAG AA minimum: 4.5:1 for normal text
    • WCAG AAA preferred: 7:1 for normal text

  3. Touch Targets: Buttons and controls at least 44x44px

  4. Responsive: Test on multiple screen sizes

  5. Performance: Optimize CSS, avoid expensive selectors

  6. Fallbacks: Provide fallback fonts, colors

  7. Documentation: Comment complex CSS

Icon Design​

  1. Consistency: All icons should have similar style

  2. Size: Design at 128x128, export at multiple sizes

  3. Simplicity: Keep designs simple for small display sizes

  4. Transparency: Use transparent backgrounds

  5. Testing: Test icons on dark and light backgrounds

Background Images​

  1. Resolution: High enough for largest display

  2. File Size: Compress images for fast loading

  3. Relevance: Choose backgrounds that don't distract from content

  4. Contrast: Ensure content remains readable over background

  5. Variety: Different backgrounds for different page types

Zone Maps​

  1. Clarity: Ensure floor plans are clear and easy to understand

  2. Scale: Maintain consistent scale across multiple floor maps

  3. Orientation: Orient maps consistently (north up, entrance at bottom, etc.)

  4. Simplification: Remove unnecessary details from floor plans

  5. Labels: Consider adding room labels to floor plan image

  6. Updates: Update maps when physical layout changes

Advanced Topics​

Theme Versioning​

Maintain theme versions:

  1. Copy theme before major changes
  2. Name with version: carbon_v1, carbon_v2
  3. Test new version thoroughly
  4. Switch UIs to new version when ready
  5. Keep old version as fallback

Multi-Brand Themes​

For service providers managing multiple clients:

  1. Create base theme with common structure
  2. Copy for each client
  3. Customize colors, logos, backgrounds
  4. Assign client-specific themes to their UIs
  5. Maintain base theme for updates

Theme Inheritance​

While not directly supported, simulate with:

  1. Create base theme with core styles
  2. Copy for variations
  3. Only modify differences in copies
  4. Maintain consistent variable names

Dynamic Theming​

CSS can respond to attributes:

/* Controlled by attribute: ui.color_scheme */
.zone-card[data-scheme="warm"] {
    --primary-color: #ff6b35;
}

.zone-card[data-scheme="cool"] {
    --primary-color: #4a90e2;
}

Set via JavaScript in theme or widgets.

Animations and Transitions​

Enhance user experience:

.zone-card {
    transition: all 0.3s ease;
}

.zone-card:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

.zone-card.on {
    animation: pulse 0.5s ease;
}

@keyframes pulse {
    0%, 100% { transform: scale(1); }
    50% { transform: scale(1.05); }
}

Use Sparingly: Too much animation can be distracting.

Troubleshooting​

Theme Not Applying​

Check:

  1. Theme Assignment: UI has theme attribute set
  2. Browser Cache: Clear cache and hard reload (Ctrl+F5)
  3. CSS Errors: Check browser console for CSS errors
  4. File Path: Verify style.css exists in theme directory

Icons Not Displaying​

Check:

  1. Theme Assignment: UI using correct theme
  2. Icon Exists: Icon file exists in theme's /icons/ directory
  3. Icon Name: Reference matches filename (without extension)
  4. File Format: PNG or SVG
  5. Cache: Clear browser cache

Background Not Showing​

Check:

  1. Mapping: Background mapped to route in Backgrounds tab
  2. Route Match: Current page route matches mapping
  3. File Exists: Background file uploaded successfully
  4. Image Format: PNG or JPG
  5. File Size: Not too large (< 5MB)

Zone Map Not Loading​

Check:

  1. Map Uploaded: Map image exists in theme
  2. Zones Positioned: Zones have map_coordinate attributes
  3. Subsystem Match: Viewing correct subsystem
  4. Component: ZoneMap component included on page
  5. Console Errors: Check browser console for errors

CSS Changes Not Reflecting​

Try:

  1. Click Save button in Styles tab
  2. Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)
  3. Close and reopen preview window
  4. Verify no CSS syntax errors
  5. Check browser developer tools for applied styles