Themes

Customize the visual appearance with a 6-color theme system

xiantong uses a 6-color theme system that lets you customize the visual appearance. You can override specific colors or install preset themes with complete visual styles.

Theme Hierarchy#

Themes are applied in the following order of precedence:

1. Workspace override: Per-workspace theme in Settings → Appearance → Workspace Themes
2. App default: Selected in Settings → Appearance → Default Theme
3. Theme override file: ~/.xiantong/theme.json - Override specific colors
4. Preset themes: ~/.xiantong/themes/{name}.json - Complete theme packages

Workspaces without a custom theme inherit the app default.

Workspace Themes#

Each workspace can have its own color theme that overrides the app default. This lets you visually distinguish between different projects or contexts.

Configuring Workspace Themes#

1. Open Settings → Appearance
2. In the Default Theme section, set your app-wide default
3. In the Workspace Themes section, select a theme for each workspace:

• Use Default - Inherits the app default theme
• Custom theme - Select a specific preset

Theme changes apply immediately across all windows. If you have multiple windows open with the same workspace, they all update in real-time.

Storage Location#

Workspace theme preferences are stored in the workspace config:

~/.xiantong/workspaces/{id}/config.json

{
"id": "ws_abc123",
"name": "My Project",
"defaults": {
"colorTheme": "nord"
}
}

When colorTheme is omitted or undefined, the workspace inherits the app default.

This is the workspace-specific default theme. It overrides the app default for new and existing sessions in that workspace.

6-Color System#

Theme Override File#

Create ~/.xiantong/theme.json to override specific colors:

{
"accent": "oklch(0.58 0.22 293)",
"dark": {
"accent": "oklch(0.65 0.22 293)"
}
}

All fields are optional. Only specify colors you want to override.

Dark Mode Support#

The dark object provides optional overrides for dark mode. When the user’s system is in dark mode:

1. Base colors (top-level) are used as defaults
2. Any colors defined in dark override the base colors

This allows partial dark mode customization - only override what needs to differ.

Preset Themes#

Preset themes are complete theme packages stored at ~/.xiantong/themes/. Each preset is a JSON file with theme colors and metadata.

Preset Theme Schema#

{
"name": "Dracula",
"description": "A dark theme with vibrant colors",
"author": "Zeno Rocha",
"license": "MIT",
"source": "https://draculatheme.com",
"supportedModes": ["dark"],

"background": "oklch(0.22 0.02 280)",
"foreground": "oklch(0.95 0.01 270)",
"accent": "oklch(0.70 0.20 320)",
"info": "oklch(0.78 0.14 70)",
"success": "oklch(0.72 0.18 145)",
"destructive": "oklch(0.65 0.22 28)",

"shikiTheme": {
"light": "github-light",
"dark": "dracula"
}
}

Preset Metadata Fields#

Installing Preset Themes#

1. Download or create a theme JSON file
2. Save it to ~/.xiantong/themes/{name}.json
3. Select the theme in Settings → Appearance

Scenic Mode#

Scenic mode displays a full-window background image with glass-style panels. This creates a visually immersive experience.

Enabling Scenic Mode#

{
"mode": "scenic",
"backgroundImage": "mountains.jpg",

"background": "oklch(0.15 0.02 270 / 0.8)",
"paper": "oklch(0.18 0.02 270 / 0.6)",
"navigator": "oklch(0.12 0.02 270 / 0.7)",
"popoverSolid": "oklch(0.18 0.02 270)"
}

Scenic Mode Properties#

Surface Colors for Glass Panels#

Scenic mode benefits from semi-transparent surface colors:

Scenic themes automatically force dark mode for better contrast with background images.

Color Formats#

Any valid CSS color format is supported:

Recommendation: Use OKLCH for perceptually uniform colors that look consistent across light and dark modes.

OKLCH Reference#

OKLCH format: oklch(lightness chroma hue)

Common hues:

• Red: ~25
• Orange: ~70
• Yellow: ~100
• Green: ~145
• Cyan: ~195
• Blue: ~250
• Purple: ~293
• Pink: ~330

Examples#

Minimal: Just change accent color#

{
"accent": "#3b82f6"
}

Custom brand colors#

{
"accent": "oklch(0.55 0.25 250)",
"info": "oklch(0.70 0.15 200)",
"dark": {
"accent": "oklch(0.65 0.25 250)",
"info": "oklch(0.75 0.12 200)"
}
}

High contrast theme#

{
"background": "#ffffff",
"foreground": "#000000",
"dark": {
"background": "#000000",
"foreground": "#ffffff"
}
}

Live Updates#

Theme changes are applied immediately - no restart needed. Edit theme.json and the UI updates automatically.

Troubleshooting#

Theme not applying

• Verify JSON syntax is valid
• Check file is in correct location (~/.xiantong/theme.json for overrides, ~/.xiantong/themes/ for presets)
• Ensure color values are valid CSS colors

Colors look wrong in dark mode

• Add explicit dark overrides
• OKLCH colors may need higher lightness values for dark mode
• Check if preset has supportedModes that excludes your current mode

Background image not showing

• Ensure mode is set to "scenic"
• Check image path is relative to theme file or a valid URL
• Verify image file exists and is readable

Tips#

Start with just accent

Changing only the accent color is the quickest way to personalize the app.

Use OKLCH for predictability

OKLCH colors behave more consistently across light/dark modes than hex or RGB.

Test in both modes

Always check your theme in both light and dark modes to ensure readability.

Keep contrast accessible

Ensure sufficient contrast between foreground and background colors.