Skip to content
github-actions[bot] edited this page Nov 9, 2026 · 16 revisions

Themes

Muximux uses CSS custom properties (CSS variables) for theming. You can choose from built-in themes, create your own through the Settings panel, or edit theme CSS files directly.

Configuration

Muximux stores the active theme in config.yaml (by default data/config.yaml):

theme:
  family: default              # Theme family: default, nord, dracula, etc.
  variant: system              # dark, light, system

This is the source of truth. It syncs across all browsers and devices. The browser also caches the current theme in localStorage (the browser's local storage for this site). This lets it apply the theme instantly on page load, without a flash of unstyled content. When the server config loads, the server value always wins.

Built-in Themes

Muximux ships with multiple built-in theme families, each with dark and light variants:

  • Default -- Deep charcoal (dark) or clean and bright (light) with teal accents. This is the default theme.
  • Nord -- Arctic, blue-grey palette inspired by the Nord color scheme.
  • Dracula -- Dark purple tones from the popular Dracula theme.
  • Catppuccin -- Warm, pastel tones from the Catppuccin palette.
  • Solarized -- Ethan Schoonover's precision-crafted color scheme.
  • Tokyo Night -- Inspired by Tokyo city lights at night.
  • Gruvbox -- Retro groove with warm, earthy colors.
  • Cineplex -- Warm amber and gold tones inspired by media player interfaces.
  • Rose Pine -- Soft, muted tones with a natural feel.

You cannot delete built-in themes.

Variant Modes

Each theme supports three variant modes:

  • Dark -- Always use the dark variant of the selected theme.
  • Light -- Always use the light variant of the selected theme.
  • System -- Automatically follow your operating system's preference. This uses the prefers-color-scheme media query. So when you switch your OS between light and dark mode, Muximux updates in real time.

Changing Themes

  1. Open Settings (click the gear icon or press S).
  2. Go to the Appearance tab.
  3. Select a theme family and a variant mode.

Changes apply instantly. Muximux saves them to config.yaml when you click Save. You do not need to restart. If you switch theme from the command palette, you get a preview in that browser only. The next Settings save keeps it.

Theme selector with 9 theme families

Here are a few examples of the available themes applied to the onboarding wizard:

Muximux (Default) Catppuccin Dracula
Default dark Catppuccin Dracula

You can also select a theme during the onboarding wizard when setting up Muximux for the first time.

Custom Themes

You can create fully custom themes through the Settings panel:

  1. Open Settings > Appearance.
  2. Click "New Theme".
  3. Use the theme editor to customize colors, backgrounds, borders, and other visual properties.
  4. Save the theme.

Theme editor with color pickers

A custom theme name must not match a bundled theme's name. If it does, Muximux refuses the save.

Muximux stores custom themes as CSS files in the data/themes/ directory. When you create a theme, Muximux generates a CSS file. The file overrides the default CSS custom properties (variables) with your chosen values.

A theme file starts with a comment that holds @theme-* metadata. One rule scoped to the theme's ID follows it. Muximux does not list a file without any @theme-* line. Here is a minimal hand-written light theme:

/**
 * @theme-name: Paper
 * @theme-is-dark: false
 */
[data-theme="paper"] {
  color-scheme: light;
  --bg-base: #fbfaf7;
  --text-primary: #1c1c1c;
  --accent-primary: #2563eb;
}

The ID in the selector is the file name without .css (data/themes/paper.css here). @theme-is-dark decides which way the derived status, accent and form-control colours go (see Status and accent tokens). So set it correctly for a light theme.

Theme CSS Variables

Themes control the visual appearance through CSS custom properties defined on :root. The main variable groups are:

  • Background colors -- Page background, surface, elevated surface
  • Text colors -- Primary, secondary, muted
  • Accent/brand colors -- Used for highlights, active states, and interactive elements
  • Border colors and radii -- Controls the look and roundness of UI elements
  • Shadow definitions -- Drop shadows for depth and layering
  • Navigation-specific colors -- Background, text, and active state colors for the navigation bar

You do not need to override every variable. Any variable you omit falls back to the base theme's default.

Status and accent tokens

Status boxes, pills, inline messages, form control borders and the danger button read these variables. A theme may override any of them. Muximux derives the omitted ones from the theme's own --status-* and --accent-primary colours (see below).

token used for derived when omitted
--success-text, --success-bg, --success-border success notices and pills (text, translucent background, border) --status-success mixed 40% / 12% (transparent) / 60% as described below
--warning-text, --warning-bg, --warning-border warnings, "Unsaved changes", the discard prompt the same recipe from --status-warning
--danger-text, --danger-bg, --danger-border errors, failed saves, destructive hints the same recipe from --status-error
--info-text, --info-bg, --info-border informational pills the same recipe from --status-info
--danger-solid, --danger-solid-hover, --danger-on-solid the solid danger button fill, its hover fill and its text --danger-border, that fill mixed 90% with the ink, #111111 on dark or #ffffff on light
--accent-text the accent used as text: links, the active tab and the active navigation item --accent-primary mixed 51% with the ink
--accent-on-primary text on an accent-filled button #ffffff or #000000, whichever reads better on --accent-primary (worked out at runtime, see below)
--border-focus the keyboard focus outline on every control --accent-primary
--border-input the boundary of form controls: inputs, selects, textareas, checkboxes and the locale picker the ink at 50% over transparent

Every bundled theme defines the status and accent tokens with values that meet WCAG 2.1 AA on that theme's surfaces: 4.5:1 for text, 3:1 for borders and the focus outline. --border-input meets 3:1 on the base, surface, elevated and overlay backgrounds, so a form control stays visible wherever it sits. Card and divider borders (--border-subtle, --border-default, --border-strong) are unchanged.

A custom theme that omits the tokens gets values derived from its --status-* and --accent-primary colours. The "ink" is white on a dark theme and black on a light one. Text uses 40% of the status colour mixed with the ink. Borders use 60%. Backgrounds are a 12% tint of the status colour. These pass AA for every bundled palette.

The theme's @theme-is-dark header decides which way to go. The app turns this header into a data-color-scheme attribute on the root element. Set @theme-is-dark: false for a light theme. A theme without the @theme-is-dark line counts as dark. If you set the tokens yourself, aim for the same ratios.

The themeContrast test in web/src/lib/themeContrast.test.ts is strict (no list of known failures). It checks every bundled theme and the derived fallback. It is the reference implementation. web/src/lib/builtCss.test.ts guards the compiled CSS against light-dark(). The build would turn that function into a form that ignores the theme's scheme.

We adjusted the bundled themes for contrast:

  • Muted and secondary text is slightly lighter on the dark themes and darker on the light ones. Solarized Light and Tokyo Night Light also darken their primary text.
  • The elevated and overlay surfaces of Catppuccin, Cineplex Dark, Gruvbox, Nord and Solarized Dark are a step darker.
  • Buttons on most themes use dark text on the accent.
  • The focus outline of Cineplex Light, Gruvbox Light, Solarized Light and Tokyo Night Light uses the text-safe accent.

Accent and status base colours are unchanged.

For --accent-on-primary, use #ffffff or #000000, whichever has the higher contrast on your accent. One of the two always reaches at least 4.5:1. When you save a custom theme, the theme editor works this out from your accent colour and writes it for you. It judges a translucent accent over --bg-base.

If a theme file omits --accent-on-primary, Muximux derives it at runtime from the theme's --accent-primary. It uses --bg-base as the backdrop when the accent is translucent. Then it picks white or black. Muximux never overrides a theme that defines the token.

The primary button and the floating navigation button keep their --accent-primary fill on hover. They show the hover with a glow and shadow (--shadow-glow) instead of switching to --accent-secondary.

The interface no longer uses the --color-brand-* palette. Muximux keeps it only for older theme files.

Focus, motion and screen readers

  • Focus. Every focusable element shows the same outline in --border-focus while it has keyboard focus. A field with an error keeps its danger border while focused.
  • Dialogs. Settings and every other dialog keep Tab and Shift+Tab inside them. They make the page behind them inert (not usable until the dialog closes). When they close, they return focus to the control that opened them. Escape closes the topmost dialog. See Keyboard Shortcuts > Keyboard navigation.
  • Links and toasts. Links in running text are underlined, so they do not rely on colour. Toasts use the theme's surface and status tokens instead of always being dark.
  • Reduced motion. When your operating system asks for reduced motion, transitions collapse, spinners slow down and pulses stop.
  • Health indicator. Each status has its own shape (circle, diamond or ring) so it does not rely on colour alone. The indicator has an accessible name and a tooltip that opens with the keyboard. The "Check now" action in that tooltip is mouse-only for now.
  • Screen readers. Screen readers announce errors as alerts and confirmations as status messages. The onboarding wizard announces each step change, and the log level filters report whether they are on or off. Form controls and icon-only buttons have names, and per-row actions name their item or position.

Importing and Exporting Themes

Themes are plain CSS files, so sharing one means copying a file:

  • Import: Copy a .css theme file into the data/themes/ directory. It appears in Settings automatically on the next page load.
  • Export/Share: Copy a theme file from data/themes/ and share it with others or transfer it to another Muximux installation.
  • Manual editing: You can open any theme CSS file in a text editor to adjust individual variables.

Deleting Custom Themes

To delete a custom theme:

  1. Open Settings > Appearance.
  2. Find the custom theme card.
  3. Click the delete button on the theme card.

If the deleted theme was active, Muximux reverts to the default dark theme. You cannot delete built-in themes.

Clone this wiki locally