Appearance & Theme Settings

Appearance settings control the visual look and feel of the InsightMaps Admin Console. Administrators can select from built-in theme presets, create a custom color scheme, and toggle between light and dark modes.

Overview

Appearance Capabilities:

• Theme presets: Six professionally designed color schemes
• Custom theme: Define your own primary and accent colors using HSL sliders
• Dark mode: Independent light, dark, or system-matching mode
• Live preview: See changes instantly before saving
• Quick access: Switch themes from the toolbar without opening settings
• Permission control: Only administrators can change themes for the organization
• Persistent: Theme saved to the server, dark mode preference saved locally

[insert image later]

---

Access Appearance Settings

There are two ways to change the console theme:

Quick Theme Switcher (Toolbar)

Location: Top toolbar → Theme button (palette icon)

How to Use:

1. Click the Theme button (palette icon) in the top toolbar
2. A dropdown menu appears showing all available presets
3. Click a preset to apply it immediately
4. The theme saves to the server automatically

Note: Only users with Admin or System Admin roles see the preset selection. Non-admin users see the current theme name and a message to contact an administrator.

[insert image later]

---

Full Theme Settings (Settings Page)

Location: Console Settings → Theme section

How to Use:

1. Navigate to Settings in the console
2. Find the Theme card
3. Browse presets or switch to Custom for full color control
4. Click Save to persist your changes

[insert image later]

---

Theme Presets

InsightMaps includes six built-in color schemes, each designed for a different visual style. Every preset provides a complete set of colors for the entire console interface including backgrounds, borders, text, charts, sidebar, and geometry type indicators.

Preset	Description	Primary Color	Accent Color
Slate Blue	Professional government theme (default)	Dark navy blue	Bright blue
Classic Neutral	Warm grays with forest green	Dark forest green	Olive green
Ocean Teal	Coastal blues and teals	Deep teal	Bright teal-green
Sunset	Warm amber and orange	Saddle brown	Warm orange
Mocha Mousse	2025 Color of the Year	Warm brown	Soft brown
Charcoal	Modern dark monochrome	Dark charcoal	Gray

[insert image later]

Selecting a Preset

How to Use:

1. Open the Theme settings (toolbar dropdown or settings page)
2. Each preset appears as a button with two color swatches (primary and accent)
3. Click a preset to select it
4. A checkmark appears on the active preset
5. The console updates immediately with a live preview
6. Click Save to persist the change (settings page) or the change saves automatically (toolbar dropdown)

Tip: Each preset includes both light and dark mode variants. Switching presets does not change your light/dark mode preference — these are independent settings.

---

Custom Theme

For organizations that want brand-specific colors, the Custom theme allows you to define your own primary and accent colors using HSL (Hue, Saturation, Lightness) sliders.

What Custom Colors Control

Color	Purpose	Affects
Primary	Main brand color	Buttons, links, selected items, sidebar highlights, focus rings
Accent	Secondary highlight color	Hover states, accent backgrounds, badge accents, ring/focus indicators

Creating a Custom Theme

How to Use:

1. Open Theme settings (settings page recommended for full control)
2. Click the Custom preset button
3. The custom color editor panel appears below the presets
4. Adjust the Primary hue slider (0–360) to set your primary brand color
5. Adjust the Accent hue slider (0–360) to set your accent color
6. A color swatch and color name (e.g., "Blue", "Teal", "Orange") display next to each slider
7. The console updates in real-time as you drag the sliders
8. Click Save when satisfied

[insert image later]

Hue Reference

The hue slider maps to the color wheel:

Hue Range	Color
0–14	Red
15–44	Orange
45–74	Yellow
75–149	Green
150–194	Teal
195–254	Blue
255–284	Purple
285–329	Pink
330–360	Red

Custom Color Validation

Custom colors are validated before application to ensure they are safe and display correctly:

• Hue values must be between 0 and 360
• Saturation and lightness values must be between 0 and 100
• Invalid values are rejected and the default theme is applied instead

---

Dark Mode

Dark mode is an independent setting from the theme preset. Any theme preset (including Custom) has both a light and dark variant.

Dark Mode Options

Mode	Behavior
Light	Always uses light colors
Dark	Always uses dark colors
System	Matches your operating system's preference (default)

Toggling Dark Mode

Location: Top toolbar → Dark mode button (sun/moon/monitor icon)

How to Use:

1. Click the dark mode toggle button in the toolbar
2. Each click cycles through the modes: Light → Dark → System → Light
3. The icon changes to indicate the current mode:
   • Sun icon: Light mode
   • Moon icon: Dark mode
   • Monitor icon: System mode
4. A tooltip shows the current mode name on hover
5. The change applies instantly and is saved to your browser

[insert image later]

How Dark Mode Preference Is Stored

• Dark mode preference is saved to your browser's local storage
• This means it is per device, per browser — not shared across devices
• The preference persists across sessions (even after closing the browser)
• If using System mode, the console automatically switches when your OS changes between light and dark

---

How Theme Settings Are Saved

Setting	Storage	Scope
Theme preset	Server (Settings API)	Shared across the organization
Custom colors	Server (Settings API)	Shared across the organization
Theme cache	Browser localStorage	Per device (for instant load before server response)
Dark mode	Browser localStorage	Per device, per browser

Key Points:

• Theme changes made by an administrator affect all users in the organization
• Dark mode is a personal preference — each user controls their own
• The theme is cached locally so the correct colors appear immediately on page load, before the server response arrives
• Clearing browser data (cache/localStorage) does not change the theme permanently — it reloads from the server on next visit

---

Permissions

The console has two roles: Admin and User. Admins may also have a System Admin flag for unrestricted access. Users in Demo Mode can view admin features (including theme settings) but cannot make changes.

Action	System Admin	Admin	User (Demo Mode)	User
View current theme	Yes	Yes	Yes	Yes
Change theme preset	Yes	Yes	No	No
Customize colors	Yes	Yes	No	No
Toggle dark mode	Yes	Yes	Yes	Yes

• Only users with the Admin role can change themes (the canEdit permission)
• Demo Mode users can view the theme settings page but controls are disabled
• The toolbar Theme dropdown shows a read-only display for non-admin users with a message to contact an administrator
• Dark mode is available to all users regardless of role

---

Troubleshooting

Theme not applying

You see: Selected a theme but the console still shows the old colors.

To fix: Refresh the page (Ctrl+F5). If the issue persists, check that you have Admin permissions. Verify your network connection — the theme is saved to the server and may fail silently on network errors.

Custom colors look wrong

You see: Custom theme colors appear different than expected or washed out.

To fix: Check that the hue values match your intended color using the hue reference table above. Note that saturation and lightness are automatically derived from the hue — the slider controls hue only. If colors appear very dark or light, try a different hue value.

Dark mode resets after clearing browser data

You see: Dark mode preference resets to "System" after clearing browser cache or cookies.

To fix: This is expected behavior — dark mode is stored in browser localStorage. Simply re-select your preferred mode. The theme preset itself is not affected (it reloads from the server).

Theme changes not visible to other users

You see: Changed the theme but other users still see the old theme.

To fix: Other users need to refresh their browser to pick up the new theme. The theme is fetched from the server with a short cache period (approximately 1 minute). Ask users to reload the page or wait a few minutes.

"Contact an admin" message in theme dropdown

You see: Theme dropdown shows current theme but no options to change it.

To fix: This means your account has Editor or Viewer permissions. Only Admin and System Admin users can change the organization theme. Contact your administrator to request a theme change.

---

Summary

Theme Presets: Six built-in color schemes (Slate Blue, Classic Neutral, Ocean Teal, Sunset, Mocha Mousse, Charcoal) with instant application and live preview.

Custom Theme: Define your own primary and accent colors with HSL hue sliders for brand-specific appearance.

Dark Mode: Independent light/dark/system toggle available to all users, persisted per device.

All appearance settings support live preview. Theme presets are shared across the organization (admin-controlled), while dark mode is a personal per-device preference.