Custom Themes

MeshMonitor supports creating custom color themes to personalize your monitoring experience. This feature allows you to:

• Create custom themes with 26 color variables
• Clone and modify existing themes
• Import and export themes as JSON
• Validate accessibility compliance (WCAG 2.1)
• Share themes across your organization

Overview

Custom themes are system-wide, meaning any theme created by an admin is available to all users. The theming system uses CSS custom properties (variables) to apply colors throughout the application.

Built-in Themes

MeshMonitor comes with 15 built-in themes:

• Catppuccin: Mocha, Macchiato, Frappe, Latte
• Nord: Nord Dark
• Dracula: Dracula
• Solarized: Solarized Dark, Solarized Light
• Gruvbox: Gruvbox Dark, Gruvbox Light
• High Contrast: High Contrast Dark, High Contrast Light
• Accessibility: Protanopia, Deuteranopia, Tritanopia

Permissions

Admin Users

• Create new custom themes
• Edit custom themes
• Delete custom themes
• Clone any theme (built-in or custom)

Regular Users

• View and apply any theme
• Clone any theme to create their own (if they have write permission)
• Cannot modify or delete themes

Creating a Custom Theme

Method 1: Visual Editor

1. Navigate to Settings → Custom Themes

2. Click Create New Theme

3. Enter a theme name (e.g., "Ocean Blue")

4. Use the visual editor to adjust colors:

   • Base Colors: Background and surface colors
   • Text Colors: Text and secondary text
   • Overlay Colors: UI element overlays and borders
   • Surface Colors: Card and panel backgrounds
   • Accent Colors: Primary accent colors
   • Semantic Colors: Warning, error, and decorative colors

5. View the Accessibility Check panel for WCAG compliance

6. Click Create Theme to save

Method 2: JSON Editor

1. Click the JSON Editor tab
2. Paste or edit JSON with all 26 color variables:

{
  "base": "#1e1e2e",
  "mantle": "#181825",
  "crust": "#11111b",
  "text": "#cdd6f4",
  "subtext1": "#bac2de",
  "subtext0": "#a6adc8",
  "overlay2": "#9399b2",
  "overlay1": "#7f849c",
  "overlay0": "#6c7086",
  "surface2": "#585b70",
  "surface1": "#45475a",
  "surface0": "#313244",
  "lavender": "#b4befe",
  "blue": "#89b4fa",
  "sapphire": "#74c7ec",
  "sky": "#89dceb",
  "teal": "#94e2d5",
  "green": "#a6e3a1",
  "yellow": "#f9e2af",
  "peach": "#fab387",
  "maroon": "#eba0ac",
  "red": "#f38ba8",
  "mauve": "#cba6f7",
  "pink": "#f5c2e7",
  "flamingo": "#f2cdcd",
  "rosewater": "#f5e0dc"
}

3. Click Create Theme

How colors reach the interface

New in 4.14.1

You author the 26 palette colors above and nothing else — that has not changed, and existing custom themes need no edits. What changed is how the app reads them.

MeshMonitor resolves every color through a role, and each role points at one of your palette colors:

Role	Palette color	Used for
--color-success	green	Success states, healthy status
--color-error	red	Errors, failures
--color-warning	yellow	Warnings, degraded status
--color-caution	peach	A step below a warning
--color-info	sky	Informational notices
--color-danger	maroon	Destructive actions
--color-accent	blue	Primary accent, links, focus
--color-accent-hover	sapphire	Hover shade of the accent
--color-accent-alt	mauve	Secondary accent
--color-accent-muted	lavender	Tertiary accent
--color-bg / --color-bg-raised / --color-bg-sunken	base / mantle / crust	Page and panel backgrounds
--color-surface / -hover / -active	surface0 / surface1 / surface2	Cards, rows, controls
--color-text / -muted / -subtle / -disabled / -faint	text / subtext1 / subtext0 / overlay1 / overlay0	Text, by descending emphasis
--color-border / -strong / -subtle	surface1 / surface2 / overlay0	Dividers and outlines
--color-surface-inactive	overlay0	Scrollbar thumbs, inactive dots, empty progress tracks

What this means for you: change what red means in your theme and every error surface follows, because they all ask for "the error color" rather than "the red one". Most roles map to the palette name you would expect, so the effect is usually what you already assumed was happening.

Migration in progress

Parts of the interface still read palette colors directly and will not pick up a role remap until they are converted. Component stylesheets are done; the global stylesheets in src/styles and inline component styles are not. Conversion is tracked as follow-up work to issue #4567. If a specific surface ignores a color change, that is why — please report it on that issue with a screenshot so it can be prioritized.

Cloning Themes

To create a variation of an existing theme:

1. Find the theme you want to clone
2. Click the Clone button (📋)
3. Edit the colors as desired
4. Give it a new name
5. Click Create Theme

Tip: Cloning the currently active theme is a great way to start customizing!

Importing and Exporting Themes

Export a Theme

1. Open the theme editor
2. Click Export
3. Save the .json file

Import a Theme

1. Click Create New Theme
2. Click Import
3. Select a .json theme file
4. Review and adjust as needed
5. Click Create Theme

Theme File Format

{
  "name": "Ocean Blue",
  "slug": "custom-ocean-blue",
  "definition": {
    "base": "#0a1929",
    "text": "#e3f2fd",
    ...
  }
}

Color Variables Reference

Base Colors

• base: Main background color
• mantle: Secondary background color
• crust: Tertiary background color

Text Colors

• text: Primary text color
• subtext1: Secondary text color
• subtext0: Tertiary text color

Overlay Colors

• overlay2: Strong overlays
• overlay1: Medium overlays
• overlay0: Light overlays

Surface Colors

• surface2: Raised surfaces
• surface1: Normal surfaces
• surface0: Recessed surfaces

Accent Colors

• lavender: Accent color
• blue: Primary interactive elements
• sapphire: Info elements
• sky: Highlight elements
• teal: Success elements
• green: Positive feedback

Semantic Colors

• yellow: Warning elements
• peach: Caution elements
• maroon: Important elements
• red: Error elements
• mauve: Special elements
• pink: Decorative elements
• flamingo: Decorative elements
• rosewater: Decorative elements

Chart & Data Colors

Added in 4.14.1 (#4605, #4611)

Charts draw from two dedicated scales, separate from the role/accent tokens above, so data colors stay meaningful and distinct in every theme.

• Categorical scale — chart1…chart8 (CSS --chart-1…--chart-8): eight hues for unordered series (e.g. per-node or per-channel lines) that only need to be tellable apart. They do not have to match the accent palette.
• Sequential scale — --seq-1…--seq-5: a five-step magnitude ramp for ordered/quantitative data (heatmaps, distance distributions), from low to high.

Accessibility Validation

The theme editor includes real-time accessibility checking based on WCAG 2.1 guidelines:

Compliance Levels

WCAG AA (Minimum Standard)

• Normal text: 4.5:1 contrast ratio
• Large text: 3:1 contrast ratio

WCAG AAA (Enhanced Standard)

• Normal text: 7:1 contrast ratio
• Large text: 4.5:1 contrast ratio

Accessibility Report

When creating or editing a theme, the editor shows:

• Critical Issues: Must be fixed for usability
• Warnings: Recommended improvements
• Recommendations: Best practices

Example Report:

✓ Theme meets WCAG AA standards
⚠ Text on surface background passes AA (4.8:1) but not AAA (7:1 required)
ℹ Consider adjusting color values for AAA compliance

Theme Slug Format

Custom theme slugs must:

• Start with custom-
• Contain only lowercase letters, numbers, and hyphens
• Be between 8 and 50 characters

Valid: custom-ocean-blue, custom-dark-mode-2024Invalid: oceanblue, Custom-Theme, my_theme

Best Practices

1. Start with a Similar Theme

Clone a theme that's close to your vision and modify it.

2. Test Contrast Ratios

Ensure text is readable on all backgrounds:

• Light text on dark backgrounds
• Dark text on light backgrounds
• Sufficient contrast for UI elements

3. Consider Color Blindness

Use the built-in accessibility themes as reference:

• Protanopia (red-green)
• Deuteranopia (red-green)
• Tritanopia (blue-yellow)

4. Test in Different Lighting

View your theme in:

• Bright office lighting
• Dim lighting
• Night mode/dark environments

5. Get Feedback

Share theme exports with your team and gather feedback.

6. Document Your Themes

Export themes with descriptive names and keep a library.

Troubleshooting

Theme Not Applying

Problem: Selected a custom theme but colors haven't changed.

Solutions:

1. Refresh the page (hard refresh: Ctrl+Shift+R / Cmd+Shift+R)
2. Check browser console for errors
3. Verify the theme definition is valid JSON
4. Try switching to a built-in theme, then back to custom

Low Contrast Warning

Problem: Accessibility checker reports low contrast.

Solutions:

1. Increase the difference between text and background colors
2. Use the Visual Editor to see real-time changes
3. Refer to WCAG color contrast calculator tools
4. Test with the provided color suggestions

Theme Deleted Accidentally

Problem: Accidentally deleted a custom theme.

Solutions:

1. Check if you have an exported JSON file
2. Ask your admin to restore from system backup
3. Recreate from memory or screenshots

Import Fails

Problem: Theme import shows an error.

Solutions:

1. Validate the JSON file syntax
2. Ensure all 26 color variables are present
3. Check that color values are valid hex codes (#RRGGBB)
4. Remove any unexpected properties

API Reference

For programmatic theme management:

List All Themes

GET /api/themes

Get Specific Theme

GET /api/themes/:slug

Create Theme

POST /api/themes
Content-Type: application/json

{
  "name": "Ocean Blue",
  "slug": "custom-ocean-blue",
  "definition": "{...json...}"
}

Update Theme

PUT /api/themes/:slug
Content-Type: application/json

{
  "name": "Ocean Blue Updated",
  "definition": "{...json...}"
}

Delete Theme

DELETE /api/themes/:slug

Note: All mutation operations require themes:write permission.

Examples

Example 1: High Contrast Theme

{
  "name": "Ultra High Contrast",
  "slug": "custom-ultra-contrast",
  "definition": {
    "base": "#000000",
    "mantle": "#0a0a0a",
    "crust": "#050505",
    "text": "#ffffff",
    "subtext1": "#e0e0e0",
    "subtext0": "#c0c0c0",
    "overlay2": "#606060",
    "overlay1": "#404040",
    "overlay0": "#303030",
    "surface2": "#404040",
    "surface1": "#303030",
    "surface0": "#202020",
    "lavender": "#bb99ff",
    "blue": "#0099ff",
    "sapphire": "#00ccff",
    "sky": "#00ffff",
    "teal": "#00ff99",
    "green": "#00ff00",
    "yellow": "#ffff00",
    "peach": "#ff9900",
    "maroon": "#cc0066",
    "red": "#ff0000",
    "mauve": "#cc00ff",
    "pink": "#ff00cc",
    "flamingo": "#ff6699",
    "rosewater": "#ffccdd"
  }
}

Example 2: Warm Autumn Theme

{
  "name": "Warm Autumn",
  "slug": "custom-warm-autumn",
  "definition": {
    "base": "#2b1d14",
    "mantle": "#231710",
    "crust": "#1a110c",
    "text": "#f5e6d3",
    "subtext1": "#d4c5b2",
    "subtext0": "#b3a491",
    "overlay2": "#8c7a6a",
    "overlay1": "#6e5c4c",
    "overlay0": "#574736",
    "surface2": "#4a3a2a",
    "surface1": "#3d2e1e",
    "surface0": "#302212",
    "lavender": "#d4a6cc",
    "blue": "#6a89a0",
    "sapphire": "#5c9fa8",
    "sky": "#7eb5c4",
    "teal": "#6ba894",
    "green": "#8ca67c",
    "yellow": "#d4a050",
    "peach": "#d4753e",
    "maroon": "#a8645a",
    "red": "#b8534e",
    "mauve": "#9d7ba8",
    "pink": "#b88ca0",
    "flamingo": "#c49688",
    "rosewater": "#d4aa98"
  }
}

Related Documentation

• Settings - Configure application settings including theme selection

Support

For issues with custom themes:

1. Check the theme validation errors
2. Review the accessibility report
3. Try exporting and re-importing the theme
4. Contact your administrator
5. Report bugs at https://github.com/Yeraze/meshmonitor/issues