Configuring Zonemaster-GUI using Theming

Background

The Zonemaster-GUI is built to be cloned and customized. You have full control over the styling and layout. That said, to avoid troubles when syncing with the original repository, we recommend following a few simple guidelines:

Start by customizing the theme variables — this is enough for most use cases.
If that's not enough, apply custom CSS targeting specific elements.
For large framework changes, create a new theme and update tsconfig.json.
For interactive components, keep changes minimal to avoid breaking functionality.
Use headless mode for major customizations or when building your own GUI.

For how to use tsconfig.json in connection to theming, see Advanced build-time configuring Zonemaster-GUI using "tsconfig.json". Theming requires rebuilding Zonemaster-GUI, see Build a custom Zonemaster-GUI installation package.

Basic customization

The Zonemaster-GUI is built around a global theme based on CSS variables (./src/themes/default/styles/theme.css). The easiest way to make your own theme is to override theme variables in the ./src/themes/default/styles/custom.css file. You can tweak colors, fonts, spacing, and more. You'll get surprisingly far by just updating the theme variables. All class names are prefixed with zm- to avoid conflicts with other styles. This makes it easy to apply custom CSS on top of the theme to target specific elements.

Available theme variables

The theme includes variables for:

Font sizes and families: --font-xxs through --font-supersize, --font-body-family, etc.
Spacing: --spacing-xxs through --spacing-xxl
Colors: Various color palettes including main, secondary, black, danger, success, info, warning, and error
GUI elements: Background, text, borders, etc.
Buttons: Size, color, padding
Layout: Width, gaps, header height
Breakpoints: For responsive design

Example customization

Here's a simple example of customizing the main color and font in custom.css:

:root {
  /* Change the primary color */
  --color-palette-main-50: #4285f4;
  --color-palette-main-70: #1a73e8;

  /* Change the font */
  --font-body-family: 'Roboto', sans-serif;
}

CSS loading order

The CSS files are loaded in the following order (defined in styles.css):

theme.css (base theme variables)
foundation.css and other core styles
Component-specific CSS files
custom.css (your customizations)

This ensures that your custom styles will override the default styles.

Modifying structure and layout

There are two layers of the GUI.

Framework

The framework is the foundation of the GUI and is built with Astro. These files are located under ./src/themes/default. ' The starting point for these imports are pages. Pages are simple: they consist of a single component wrapped inside a layout. We suggest not modifying the page files. Instead, create your own theme, for example ./src/themes/my-theme. You can still reuse components from the original theme in your new theme and mix and match the imports from your custom theme.

Then update tsconfig.json:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
-     "@theme/*": ["./src/themes/default/*"]
+     "@theme/*": ["./src/themes/my-theme/*"]
    }
  }
}

Interactive components

All interactive components are built with Svelte. These files are located under ./src/lib/components. These are referenced from Astro components. Although care was taken to make the components as self-contained as possible, some components may depend on others. In most cases you won't need to modify these files. A better approach is to modify the CSS.

If you absolutely need to modify these, the suggested method is to create new components in ./src/lib/components/my-theme and reference them from the Astro components. These interactive components contain important functionality that needs to be carefully considered when modifying.

You might be better off creating a new component from scratch and integrate it with the RPCAPI yourself.

Test on different screen sizes: Use your browser's developer tools to test responsive behavior.
Check all interactive states: Verify hover, focus, active, and disabled states for interactive elements.
Test with different content: Make sure your theme works well with both short and long content.
Verify accessibility: Ensure sufficient color contrast and that focus states are visible.

Common issues and solutions

Changes not appearing: Make sure your custom.css file is being loaded. Check the browser's developer tools to verify.
Specificity issues: If your styles aren't overriding the defaults, you might need to increase specificity or use !important (sparingly).
Responsive issues: Check that your customizations work well at all breakpoints.
Component styling conflicts: If styling a specific component, target the component's class directly rather than modifying global variables.

Development workflow

For a smoother development experience:

Start the development server with npm run dev
Make changes to your custom.css file
The changes will be applied immediately thanks to hot module reloading
Use browser developer tools to inspect elements and test different values