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",
    "error": "#FF0066",
    "warning": "#CCFF00",
    "info": "#00FFCC"
  },
  "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",
    "error": "#B3004D",
    "warning": "#99CC00",
    "info": "#00B899"
  }
}

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

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

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.

4.0 KiB Raw Blame History