Theming System

Kowork features a comprehensive JSON-based theming system that allows complete visual customization. Every aspect of the UI can be themed, from colors and typography to shadows and animations.

Overview

The theming system provides:

  • JSON-based theme definitions - complete control over every visual token
  • Built-in themes - default and macOS native themes included
  • Hot-reload support - see theme changes instantly without restart
  • Dark mode overrides - separate color palettes for light and dark modes
  • LLM-assisted theme creation - ask the AI to generate custom themes

Theme Structure

Themes are defined as JSON files with the following structure: 

{
  "name": "My Theme",
  "id": "my-theme",
  "version": "1.0.0",
  "description": "A custom theme",
  "colors": { /* color tokens */ },
  "spacing": { /* spacing scale */ },
  "typography": { /* font settings */ },
  "borderRadius": { /* corner rounding */ },
  "shadows": { /* elevation shadows */ },
  "effects": { /* blur and opacity */ },
  "animation": { /* timing and easing */ },
  "components": { /* component-specific styles */ },
  "darkMode": { /* dark mode overrides */ }
}

Color System

Colors are organized into semantic categories:

Primary Colors

Brand colors with full scale (100-900). Supports multiple palettes like lime, emerald, zinc.

colors.primary.lime.500

Accent Colors

Accent variations for highlights and emphasis.

colors.accent.emerald.400

Background Colors

Surface colors for layouts: primary, secondary, tertiary, elevated, overlay.

colors.background.primary

Text Colors

Typography hierarchy: primary, secondary, tertiary, inverse, disabled.

colors.text.primary

Border Colors

Borders and dividers: default, hover, focus, subtle.

colors.border.focus

Semantic Colors

Status indicators: success, warning, error, info.

colors.semantic.success
"colors": {
  "primary": {
    "lime": {
      "400": "hsl(84 82% 48%)",
      "500": "hsl(84 78% 42%)",
      "600": "hsl(85 75% 36%)"
    }
  },
  "background": {
    "primary": "hsl(0 0% 100%)",
    "secondary": "hsl(220 13% 88%)",
    "tertiary": "hsl(220 13% 91%)"
  },
  "text": {
    "primary": "hsl(222 22% 8%)",
    "secondary": "hsl(220 9% 46%)"
  }
}

Typography

Typography tokens control fonts, sizes, weights, line heights, and letter spacing: 

"typography": {
  "fontFamily": {
    "sans": "'Inter', -apple-system, sans-serif",
    "mono": "'SF Mono', 'Fira Code', monospace"
  },
  "fontSize": {
    "xs": "10px",
    "sm": "11px",
    "base": "12px",
    "lg": "13px",
    "xl": "14px",
    "2xl": "16px",
    "3xl": "20px"
  },
  "fontWeight": {
    "normal": "400",
    "medium": "500",
    "semibold": "600",
    "bold": "700"
  },
  "lineHeight": {
    "tight": "1.25",
    "normal": "1.5",
    "relaxed": "1.75"
  }
}

Spacing & Layout

Consistent spacing scale for margins, padding, and gaps: 

"spacing": {
  "xs": "4px",
  "sm": "8px",
  "md": "12px",
  "lg": "16px",
  "xl": "24px",
  "2xl": "32px",
  "3xl": "48px",
  "4xl": "64px"
}

Border radius tokens for consistent corner rounding: 

"borderRadius": {
  "none": "0",
  "sm": "4px",
  "md": "6px",
  "lg": "8px",
  "xl": "12px",
  "2xl": "16px",
  "full": "9999px"
}

Effects & Animations

Visual effects like shadows, blur, and opacity: 

"shadows": {
  "sm": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
  "md": "0 4px 6px -1px rgba(0, 0, 0, 0.1)",
  "lg": "0 10px 15px -3px rgba(0, 0, 0, 0.1)",
  "xl": "0 20px 25px -5px rgba(0, 0, 0, 0.1)"
},
"effects": {
  "blur": {
    "sm": "4px",
    "md": "8px",
    "lg": "16px",
    "xl": "24px"
  },
  "opacity": {
    "disabled": "0.5",
    "hover": "0.8",
    "overlay": "0.9"
  },
  "backdropBlur": "blur(20px)"
}

Animation tokens for consistent motion: 

"animation": {
  "duration": {
    "fast": "100ms",
    "normal": "150ms",
    "slow": "300ms",
    "slower": "500ms"
  },
  "easing": {
    "ease": "ease",
    "easeIn": "cubic-bezier(0.4, 0, 1, 1)",
    "easeOut": "cubic-bezier(0, 0, 0.2, 1)",
    "easeInOut": "cubic-bezier(0.4, 0, 0.2, 1)"
  }
}

Component Themes

Component-specific styling with token references: 

"components": {
  "button": {
    "primary": {
      "bg": "colors.primary.lime.500",
      "bgHover": "colors.primary.lime.600",
      "text": "colors.text.inverse",
      "radius": "borderRadius.md",
      "shadow": "shadows.sm"
    }
  },
  "input": {
    "bg": "colors.background.secondary",
    "bgFocus": "colors.background.primary",
    "border": "colors.border.default",
    "borderFocus": "colors.border.focus",
    "radius": "borderRadius.md",
    "height": "40px"
  },
  "sidebar": {
    "bg": "colors.background.primary",
    "bgSelected": "colors.surface.selected",
    "backdropBlur": "effects.backdropBlur",
    "itemPadding": "spacing.sm",
    "itemBorderRadius": "borderRadius.md"
  }
}

Dark Mode Support

Dark mode overrides provide alternate colors that are automatically applied when dark mode is enabled: 

"darkMode": {
  "colors": {
    "background": {
      "primary": "hsl(222 22% 5%)",
      "secondary": "hsl(220 13% 11%)",
      "tertiary": "hsl(220 13% 17%)"
    },
    "surface": {
      "default": "hsl(220 13% 11%)",
      "hover": "hsl(220 13% 17%)",
      "active": "hsl(220 13% 21%)"
    },
    "text": {
      "primary": "hsl(0 0% 100%)",
      "secondary": "hsl(0 0% 65%)",
      "tertiary": "hsl(0 0% 45%)"
    },
    "border": {
      "default": "hsl(220 13% 17%)",
      "subtle": "hsla(0 0% 100% / 0.05)"
    }
  }
}

Only colors that differ in dark mode need to be specified. All other tokens are inherited from the base theme.

Built-in Themes

defaultBuilt-in

The default Kollabor theme with lime green accents and modern design tokens. Supports both light and dark modes.

Location: src-tauri/themes/default.json
macos-nativeBuilt-in

macOS Big Sur and Ventura inspired theme with system fonts, native blur effects, and authentic Apple design language. Features blue accents and subtle glassmorphism.

Location: src-tauri/themes/macos-native.json

Creating Custom Themes

There are three ways to create custom themes:

Settings UI

Use the visual theme editor in Settings to customize colors, typography, and components with live preview.

Direct JSON

Edit theme JSON files directly in ~/.kollabor/themes/ for complete control.

LLM-Assisted

Ask the AI to generate themes: "Create a Dracula theme" or "Make a warm sunset color scheme".

Manual Theme Creation

To create a theme manually, create a new JSON file in ~/.kollabor/themes/: 

# Create a new theme file
touch ~/.kollabor/themes/my-theme.json

# Copy a base theme to start from
cp ~/.kollabor/themes/default.json ~/.kollabor/themes/my-theme.json

# Edit the theme
# Update the "id" and "name" fields
# Customize colors, fonts, spacing, etc.

Token References

Component themes can reference other tokens using dot notation: 

"components": {
  "button": {
    "primary": {
      "bg": "colors.primary.lime.500",        // Token reference
      "bgHover": "colors.primary.lime.600",   // Token reference
      "text": "#ffffff",                      // Direct value
      "radius": "borderRadius.md",            // Token reference
      "shadow": "shadows.sm"                  // Token reference
    }
  }
}

Token references are resolved automatically by the ThemeService, making it easy to maintain consistency.

Theme Switching

Themes can be switched at runtime using the useTheme composable: 

import { useTheme } from '@/composables/useTheme';

const { theme, setTheme, toggleTheme, availableThemes } = useTheme();

// Switch to a specific theme
await setTheme('macos');

// Toggle dark mode (preserves current theme)
await toggleTheme();

// List available themes
console.log(availableThemes.value);

Theme changes are applied instantly with hot-reload support. The ThemeService:

  • Loads theme JSON from disk
  • Validates theme structure
  • Resolves token references
  • Generates CSS custom properties
  • Injects CSS into the DOM

Advanced Features

Mode-Specific Overrides

Themes can define overrides for specific modes beyond just dark mode: 

"macosMode": {
  "colors": {
    "background": {
      "primary": "hsl(240 4% 95%)"
    }
  }
}

Theme Metadata

Themes can include metadata to control UI behavior: 

"metadata": {
  "prefersDarkMode": true,           // Default to dark mode
  "showDecorativeShapes": false      // Hide decorative elements
}

Custom Properties

Themes can include custom fields for specific use cases: 

"iconSizes": {
  "sm": "16px",
  "md": "20px",
  "lg": "24px"
},
"customProperty": "any value"

Theme Validation

The ThemeService validates themes on load to ensure they have all required fields:

  • Checks for required fields (name, id, version, colors, etc.)
  • Validates color format (hex, rgb, hsl)
  • Verifies token references are valid
  • Falls back to default theme on validation errors

LLM-Assisted Theme Generation

Kollabor's AI can generate custom themes based on natural language requests:

"Create a Dracula theme with purple accents"
"Make a warm sunset theme with orange and pink gradients"
"Design a minimalist monochrome theme"
"Create a Nord-inspired theme"

The AI will generate a complete theme JSON file with all required tokens, applying the requested color scheme and style consistently across all components.

Get Creative

The theming system gives you complete control over Kollabor's appearance. Experiment with colors, try the built-in themes, or create your own custom designs.