DankMaterialShell/docs/CUSTOM_THEMES.md

Custom Themes

This guide covers creating custom themes for DankMaterialShell. You can define your own color schemes by creating theme files that the shell can load.

Theme Structure

Themes are defined using the same structure as the built-in themes. Each theme must specify a complete set of Material Design 3 colors that work together harmoniously.

Required Core Colors

These are the essential colors that define your theme's appearance:

{
  "dark": {
    "name": "Cyberpunk Electric Dark",
    "primary": "#00FFCC",
    "primaryText": "#000000",
    "primaryContainer": "#00CC99",
    "secondary": "#FF4DFF",
    "surface": "#0F0F0F",
    "surfaceText": "#E0FFE0",
    "surfaceVariant": "#1F2F1F",
    "surfaceVariantText": "#CCFFCC",
    "surfaceTint": "#00FFCC",
    "background": "#000000",
    "backgroundText": "#F0FFF0",
    "outline": "#80FF80",
    "surfaceContainer": "#1A2B1A",
    "surfaceContainerHigh": "#264026",
    "surfaceContainerHighest": "#33553F",
    "error": "#FF0066",
    "warning": "#CCFF00",
    "info": "#00FFCC",
    "matugen_type": "scheme-expressive"
  },
  "light": {
    "name": "Cyberpunk Electric Light",
    "primary": "#00B899",
    "primaryText": "#FFFFFF",
    "primaryContainer": "#66FFDD",
    "secondary": "#CC00CC",
    "surface": "#F0FFF0",
    "surfaceText": "#1F2F1F",
    "surfaceVariant": "#E6FFE6",
    "surfaceVariantText": "#2D4D2D",
    "surfaceTint": "#00B899",
    "background": "#FFFFFF",
    "backgroundText": "#000000",
    "outline": "#4DCC4D",
    "surfaceContainer": "#F5FFF5",
    "surfaceContainerHigh": "#EBFFEB",
    "surfaceContainerHighest": "#E1FFE1",
    "error": "#B3004D",
    "warning": "#99CC00",
    "info": "#00B899",
    "matugen_type": "scheme-expressive"
  }
}

You can define colors at the top level if you do not want "dark" and "light" variants.

For example:

{
  "name": "Theme name",
  "primary": "#eeeeee",
  ....
}

Example Themes

There are example themes you can start from:

• Cyberpunk Electric - Neon green and magenta cyberpunk aesthetic
• Hotline Miami - Retro 80s inspired hot pink and blue
• Miami Vice - Classic teal and pink vice aesthetic
• Synthwave Electric - Electric purple and cyan synthwave vibes

Color Definitions

Primary Colors

• primary - Main accent color used for buttons, highlights, and active states
• primaryText - Text color that contrasts well with primary background
• primaryContainer - Darker/lighter variant of primary for containers

Secondary Colors

• secondary - Supporting accent color for variety and hierarchy
• surfaceTint - Tint color applied to surfaces, usually derived from primary

Surface Colors

• surface - Default surface color for cards, panels, etc.
• surfaceText - Primary text color on surface backgrounds
• surfaceVariant - Alternate surface color for subtle differentiation
• surfaceVariantText - Text color for surfaceVariant backgrounds
• surfaceContainer - Container surface color, slightly different from surface
• surfaceContainerHigh - Elevated container color for layered interfaces
• surfaceContainerHighest - Highest elevation container color for top-level surfaces

Background Colors

• background - Main background color for the entire interface
• backgroundText - Text color for background areas

Outline Colors

• outline - Border and divider color for subtle boundaries

Optional Properties

While the core colors above are required, you can also customize these optional properties:

Semantic Colors

{
  "error": "#f44336",
  "warning": "#ff9800", 
  "info": "#2196f3"
}

• error - Used for error states, delete buttons, and critical warnings
• warning - Used for warning states and caution indicators
• info - Used for informational states and neutral indicators

Matugen Color Scheme Type

{
  "matugen_type": "scheme-monochrome"
}

• matugen_type - Controls the color scheme algorithm used by matugen for system app theming
• Default: scheme-tonal-spot (if not specified)
• Available options:
  • scheme-content - Content-based color extraction
  • scheme-expressive - Expressive, vibrant color schemes
  • scheme-fidelity - High fidelity to source material
  • scheme-fruit-salad - Colorful, fruit salad-like schemes
  • scheme-monochrome - Monochromatic color schemes
  • scheme-neutral - Neutral, subdued color schemes
  • scheme-rainbow - Rainbow-like color schemes
  • scheme-tonal-spot - Tonal spot color schemes (default)

Setting Custom Theme

In settings -> Theme & Colors you can choose "Custom" to choose a path to your theme.

You can also edit ~/.config/DankMaterialShell/settings.json manually

{
  "currentThemeName": "custom",
  "customThemeFile": "/path/to/mytheme.json"
}

Reactivity

Editing the custom theme file will auto-update the shell if it's the current theme.