Customizing the theme¶

This guide walks through customizing the Navigator's visual appearance. For interface details, see Theme Editor Interface.

Recommended workflow¶

1. Open the Theme Editor (http://localhost:8000/theme-editor.html)
2. Start from the default theme or load an existing one with Open
3. Modify settings while checking the effect in the preview
4. Save with Save and copy the file to the project folder
5. Update config.json to point to the new theme
6. Verify in the actual Navigator with a complete scenario

The Theme Editor preview uses a simplified scenario. To see the final result with real content, you need to test in the Navigator.

Branding tips¶

Logo¶

Avoid overly large images: the logo is automatically resized but heavy files slow down loading. Recommended size: maximum 200x60 pixels or equivalent.

The field accepts both external URLs (https://company.com/logo.png) and relative paths (images/logo.png). For distributable projects, prefer relative paths.

Typography tips¶

"System Default" doesn't load external fonts: it uses the device's font. It's the lightest choice and guarantees readability on any system.

Color tips¶

Contrast¶

Text must be readable on the background. Safe combinations:

Accent color¶

The accent color defines the interface personality. Use the main brand color for visual consistency. Verify it's saturated enough to stand out as an interactive element.

Button states¶

Chromatic distinction between buttons helps users orient themselves:

• Available choices: accent color, invites action
• Choices already made: different color (green by default), visual confirmation
• Explored choices: neutral gray, indicates "already seen in another path"

Maintain consistency between button colors and map colors for a uniform visual language.

Saving and applying¶

The Save button generates a JSON file. Rename it with a descriptive name:

theme-company-2024.json
theme-safety-course.json
theme-dark.json

To apply the theme, update config.json:

{
    "scenario": "scenario-course.json",
    "theme": "theme-company-2024.json",
    "showCredits": false
}

Reload the Navigator (Ctrl+Shift+R) to see the applied theme.

Managing multiple themes¶

You can create multiple themes for different contexts:

• Brightness variants: light theme and dark theme
• Different clients: a theme for each client with their branding
• Different contexts: formal theme for compliance, vivid theme for onboarding

Changing the theme value in config.json switches between themes without modifying the scenario. The same content can have completely different appearances.

Modifying the theme via JSON¶

For those who prefer working directly on the file, the structure is:

{
    "brand": {
        "name": "Company Name",
        "logo": "images/logo.png",
        "website": "https://example.com"
    },
    "typography": {
        "fontFamily": "inter"
    },
    "colors": {
        "background": "#ffffff",
        "text": "#1f2937",
        "textSecondary": "#4b5563",
        "accent": "#6366f1"
    },
    "buttons": {
        "choiceBackground": "#6366f1",
        "choiceText": "#ffffff",
        "visitedBackground": "#10b981",
        "visitedText": "#ffffff",
        "exploredBackground": "#e5e7eb",
        "exploredText": "#374151",
        "restartBackground": "#f59e0b",
        "restartText": "#ffffff"
    },
    "map": {
        "nodeCurrent": "#6366f1",
        "nodeCurrentText": "#ffffff",
        "nodeVisited": "#3730a3",
        "nodeVisitedText": "#ffffff",
        "nodeUnvisited": "#f3f4f6",
        "nodeUnvisitedText": "#6b7280",
        "nodeUnvisitedBorder": "#d1d5db",
        "lineVisited": "#6366f1",
        "lineUnvisited": "#d1d5db"
    }
}

All fields are optional. Missing values are taken from defaults.json. This allows creating minimal themes that specify only what changes:

{
    "brand": {
        "name": "Company XYZ",
        "logo": "images/logo-xyz.png"
    },
    "colors": {
        "accent": "#dc2626"
    }
}

Available values for fontFamily: system, inter, roboto, open-sans, lato, montserrat, poppins, source-sans-3, nunito.