Extend the Hermes Dashboard with Custom Themes

Hermes dashboard themes can change palette, typography, layout, component chrome, assets, and carefully scoped CSS without modifying the dashboard application. A good theme improves hierarchy and comfort while preserving every built-in workflow. Treat it as an interface package with compatibility and rollback checks—not a pile of overrides.

Design the system first

Start with the three visual layers documented by Hermes: application background, elevated surfaces, and interactive/accent states. Choose accessible text contrast before decorative effects. Define display and body typography separately, then test long titles, dense tables, code, forms, status chips, alerts, and destructive actions.

Themes live under the Hermes dashboard-theme directory as YAML files. Use image assets only from locations the dashboard can serve safely, and keep them optional so a missing decorative image does not hide content.

Theme checklist

Choose a unique theme name and a clear rollback target.
Define background, surface, border, text, muted, accent, success, warning, and danger colors.
Check contrast for normal, hover, focus, disabled, and selected states.
Test display typography separately from body and monospace text.
Pick a supported layout variant before reaching for raw CSS.
Keep decorative assets lightweight and nonessential.
Scope customCSS narrowly to dashboard-owned selectors.
Verify every built-in page at desktop and mobile widths.
Keep the prior theme available until the new one passes visual QA.

Prefer structured controls

Use palette, typography, layout, chrome, and documented color overrides before raw CSS. Structured fields are easier to validate and less likely to break when dashboard markup changes. Reserve customCSS for a small visual detail the theme schema cannot express.

When CSS is necessary, avoid hiding built-in controls, changing semantic order, replacing focus indicators, or using broad selectors such as button, a, or *. Theme assets become CSS variables; design them as enhancement layers rather than content carriers.

Common pitfalls

Choosing an attractive accent that fails contrast on elevated surfaces.
Using one novelty display font for long body copy and tables.
Hiding overflow to conceal a layout problem and clipping menus or focus rings.
Depending on an image for labels, instructions, or state.
Applying raw CSS to every button and accidentally restyling destructive actions.
Testing only the home dashboard while plugin pages or settings remain unreadable.
Deleting the last known-good theme before the replacement is stable.

Verification steps

Load the theme through the dashboard’s theme controls and confirm it appears by name.
Visit the home, chat, sessions, settings, plugins, and any operational pages in the installation.
Test keyboard focus, hover, selected, disabled, success, warning, error, and destructive states.
Check at narrow phone, tablet, standard desktop, and wide desktop widths for overflow and clipped headings.
Reload the dashboard and restart Hermes to confirm discovery is persistent.
Switch back to the previous theme and verify rollback works without deleting files.
Inspect the browser console for missing assets or CSS errors.

Official documentation

https://hermes-agent.nousresearch.com/docs/user-guide/features/extending-the-dashboard