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 five tabs: Styles, Layout, Backgrounds, Icons, and Zone Maps.

1. Styles Tab

CSS editor for theme styling. Every theme has two stylesheets, selected with the file toggle above the editor:

• Custom CSS (custom.css) — site-specific overrides, opened by default. It loads after the base stylesheet, so rules here win at equal specificity. This file is yours: GEM updates never modify it.
• Base CSS (style.css) — the theme's base stylesheet. For official themes (prodigy, ember, and carbon) the base is release-managed: GEM updates refresh it automatically, the editor shows it read-only, and the server rejects writes to it — put site overrides in Custom CSS instead. For user-created themes the base is fully editable.

Features:

• Syntax-highlighted CSS editor
• 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 or switching between Custom and Base
• Save button to apply changes

Upgrading from a single style.css

The first boot after updating runs a one-shot migration for official themes: site edits found in style.css are extracted into custom.css (rules identical to official release CSS stay in the base), and a verbatim backup of the pre-split stylesheet is kept in the theme as style.pre-migration.css. When edits can't be confidently separated, the entire previous stylesheet is carried into custom.css — it then overrides the base completely, so the rendered result is unchanged either way.

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. Layout Tab

Theme-wide Layout & Presentation defaults. These are stored on ui_theme.config and apply to every UI using this theme. Changes take effect on the next reload (or immediately in an open Preview window). Unlike Styles, they resolve from the theme row rather than a stylesheet — GEM re-queries the config on reload.

Control	Config key	Options	Effect
Navigation	nav_layout	Top bar (classic) / Left rail + tab bar	rail shows a left icon rail in landscape and a bottom tab bar in portrait. Overridable per-UI with the UI's nav_layout attribute — the per-UI value wins over the theme default.
Rectangle buttons	rect_style	Default / State dot	state_dot renders rect controls as list-tile cards with a coloured state dot.
Scene chips	scene_chips	checkbox	When enabled, light/shade scene shortcuts render as state-disc chips.

Click Save to write the options back to the theme. Only these keys are managed here — other config entries (background maps, etc.) are preserved.

Rail styling is theme-provided

GEM ships the rail/tab-bar geometry for every theme, but only the Ember theme (and copies of it) skins those surfaces. Selecting Left rail + tab bar on another theme renders the rail on a plain surface until you add rail styles to its CSS — the tab shows a warning in that case. See the theme contract for the variant-selection model.

3. 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.)

4. Icons Tab

Manage theme icon library:

Official theme icons and updates

For official themes (prodigy, ember, and carbon), the shipped icons, backgrounds, and maps are release-managed like the base stylesheet: when a GEM update changes one of these files, the update replaces it automatically at the next boot. An asset you have edited or replaced in the theme editor is recognized as a site customization and is never overwritten — it keeps winning over the shipped version until you delete it. Assets you add under your own names are untouched by updates.

Browse Material Icons:

• Click Browse Material Icons to search and import icons from Google Fonts without leaving the admin
• Type to search by name, category, or tag (e.g. light, lock, fan); results are ranked by relevance then popularity
• Pick a style: Outlined (default), Filled, Rounded, Sharp, or Two Tone
• Click icons to multi-select, then Import Selected
• Choose a Format: SVG (default — scalable, recolorable via CSS) or PNG; for PNG pick a Size (64–256px)
• Save as — the selected icons list shows an editable filename per icon (defaulting to the material name). Rename any of them before importing to match GEM's expected icon names (e.g. import the material lightbulb as lighting); leave blank to keep the material name. Names are normalized to lowercase [a-z0-9_]
• Each icon is fetched server-side and saved to the theme's /icons/ directory as <name>.svg or <name>.png (e.g. lightbulb.svg); PNGs are rasterized with a transparent background at the chosen size
• Requires the GEM server to have internet access; previews load from Google's CDN

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
• Hover an icon and click the pencil (rename) button to rename it in place — enter the new base name (normalized to lowercase [a-z0-9_], extension preserved). The rename moves both the asset row's path and the on-disk file while keeping the asset id, so anything referencing the icon by id is unaffected; UIs that reference it by filename must be repointed to the new name

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

Icons resolve theme-first across the UI (nav buttons, controls-grid tiles, room-picker glyphs): a file in the theme's /icons/ directory overrides GEM's built-in icon of the same name, and anything the theme doesn't ship falls back to the built-in set — so a theme only needs the icons it restyles. Common names to override:

Control Icons:

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

Action Icons:

• power, power_on, power_off, volume, volume_up, volume_down, 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

5. 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 (base style.css and custom.css)
   • All icons copied
   • All backgrounds copied
   • All maps copied
5. Edit as needed

A copy is an ordinary user theme even when the source is official — its base CSS becomes editable, and neither its CSS nor its icons/backgrounds/maps are refreshed by GEM updates. The style.pre-migration.css migration backup is not carried into copies.

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
  • custom.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 (official)
• Glassmorphic surfaces with translucency
• Cinematic background imagery
• Best for residential touchpanels and large displays

ember

• Brass-on-matte dark theme (official)
• Left icon rail navigation in landscape, bottom tab bar in portrait (nav_layout: rail — see the theme contract)
• Scene chips, matte chip surfaces, Instrument Sans typography, its own full icon set and background
• Best for dedicated wall panels and high-end residential installs

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

• Neutral near-black dark theme (official) — prodigy's layout with a graphite skin in place of the navy glass
• Metallic gradients on the top bar and media nav, dark media bar
• 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.

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, with one exception: the release-managed files of official themes — the base style.css, plus shipped icons, backgrounds, and maps you haven't edited — are refreshed from the release at boot. That's how theme fixes reach deployed sites. Assets a release no longer ships are removed the same way, again only when never site-edited. Site customizations are safe: an asset you've edited or replaced is detected and preserved, and CSS overrides live in custom.css.

This also covers newly shipped official themes: if a site's database predates one (e.g. Ember on an older install), its theme record is created at startup with the shipped default Layout & Presentation configuration, and its CSS, icons, and backgrounds are imported in the same boot — the theme simply appears in the pickers after updating. An existing theme record is never modified, so site edits to a theme's configuration 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

Related Documentation

• UIs - Assigning themes to UIs
• UI Pages - Using themes on pages
• UI Widgets - Widget styling
• Gallery - Background image sources