> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/paulmcauley/klassy/llms.txt
> Use this file to discover all available pages before exploring further.

# System Icon Generation

> Understanding Klassy's system icon themes and how they integrate window control icons throughout KDE Plasma

Klassy provides auto-generated system icon themes (`klassy` and `klassy-dark`) that extend your chosen button icons to context menus, MDI applications, GTK applications, and other areas of the Plasma desktop.

## Overview

The Klassy icon themes are **automatically generated** based on your window decoration button configuration. They provide consistent window control icons throughout the desktop environment, not just in window titlebars.

### What Gets Generated

Klassy creates two complete icon themes:

<CodeGroup>
  ```text Klassy (Light) theme={null}
  Location: ~/.local/share/icons/klassy/
  Use: Light color schemes
  Inherits: Configurable (default: breeze)
  ```

  ```text Klassy Dark theme={null}
  Location: ~/.local/share/icons/klassy-dark/
  Use: Dark color schemes  
  Inherits: Configurable (default: breeze-dark)
  ```
</CodeGroup>

### Icon Coverage

The generated themes include window control icons:

* `window-close` / `window-close-symbolic`
* `window-minimize` / `window-minimize-symbolic`
* `window-maximize` / `window-maximize-symbolic`
* `window-restore` / `window-restore-symbolic`
* `window-keep-above` / `window-keep-above-symbolic`
* `window-keep-below` / `window-keep-below-symbolic`
* `window-shade` / `window-shade-symbolic`
* `window-unshade` / `window-unshade-symbolic`
* `window-pin` / `window-pin-symbolic`
* `window-unpin` / `window-unpin-symbolic`
* `application-menu` / `application-menu-symbolic`

Additional icon aliases for compatibility:

* `dialog-close`, `tab-close`, `tab-close-other`
* `gtk-close`, `gtk-no`
* `geany-close-all`, `kontes-close`

<Note>
  All other icons (folders, files, applications, etc.) are inherited from the parent icon theme you configure.
</Note>

## Configuring Icon Generation

### GUI Configuration

<Steps>
  <Step title="Open System Icon Generation dialog">
    In Klassy Settings, navigate to the **Window Decorations** tab and click **System Icon Generation...**
  </Step>

  <Step title="Configure inheritance">
    Set the parent icon theme for non-window-control icons:

    <ParamField path="Klassy icon theme inherits" type="select">
      Choose which icon theme to inherit from for light mode (default: `breeze`)
    </ParamField>

    <ParamField path="Klassy Dark icon theme inherits" type="select">
      Choose which icon theme to inherit from for dark mode (default: `breeze-dark`)
    </ParamField>
  </Step>

  <Step title="Apply settings">
    Click **Apply** or **OK** to generate the icon themes with your chosen inheritance
  </Step>
</Steps>

### Command Line Generation

Regenerate icon themes from the command line:

```bash theme={null}
klassy-settings --generate-system-icons
```

See [Command Line Options](/configuration/command-line-options#generate-system-icons) for details.

## Icon Theme Structure

The generated icon themes follow the Freedesktop Icon Theme specification:

```text theme={null}
~/.local/share/icons/klassy/
├── index.theme              # Theme metadata
├── 16/                      # 16px icons
│   ├── window-close.svg
│   ├── window-minimize.svg
│   └── ...
├── 16@2x/                   # 16px @ 2x scale (HiDPI)
├── 22/                      # 22px icons
├── 24/
├── 32/
├── 48/
├── places/                  # Inherited icons
└── [multiple scale variants]
```

### HiDPI Support

Klassy generates icons at multiple scales for crisp rendering on high-DPI displays:

* 1x (standard)
* 1.25x, 1.5x, 1.75x (intermediate scales)
* 2x (double density)
* 2.25x, 2.5x, 2.75x
* 3x (triple density)

This ensures pixel-perfect rendering at any display scale factor.

## index.theme File

Each generated icon theme includes an `index.theme` metadata file:

```ini theme={null}
[Icon Theme]
Name=Klassy
Comment=Klassy by Paul A McAuley, auto-generated by klassy-settings
DisplayDepth=32
Inherits=breeze
Example=folder
FollowsColorScheme=true

DesktopDefault=48
ToolbarDefault=22
SmallDefault=16
PanelDefault=48

KDE-Extensions=.svg
Directories=16,18,20,22,24,32,48,places/16,places/22,...
ScaledDirectories=16@1.25x,16@1.5x,16@2x,...
```

### Key Properties

<ParamField path="FollowsColorScheme" type="boolean" default="true">
  Icons automatically adapt to the system color scheme
</ParamField>

<ParamField path="Inherits" type="string">
  Parent icon theme for non-window-control icons (configurable)
</ParamField>

<ParamField path="KDE-Extensions" type="string" default=".svg">
  Icon format (SVG for scalability and color scheme integration)
</ParamField>

## How Icons Follow Color Scheme

Klassy-generated icons use SVG with a special "bland" reference color that KDE's icon rendering engine automatically replaces based on the active color scheme.

### Color Adaptation Process

<Steps>
  <Step title="Reference color generation">
    Klassy uses the Application Menu button's foreground color as the reference "bland" color
  </Step>

  <Step title="SVG icon creation">
    Icons are rendered as SVG with the reference color
  </Step>

  <Step title="Runtime color replacement">
    KDE's SVG renderer replaces the reference color with the current color scheme's icon color
  </Step>

  <Step title="Automatic updates">
    When you switch color schemes, icons automatically update without regeneration
  </Step>
</Steps>

This allows icons to seamlessly match any color scheme or accent color.

## Where System Icons Appear

Klassy system icons are used throughout the desktop:

### Context Menus

Window control icons in context menus use the system icon theme:

* Right-click titlebar menu
* Taskbar context menus
* Window list menus

### MDI Applications

Multi-Document Interface applications show consistent button icons:

* Kate editor tabs
* Kdevelop panels
* Konsole tabs
* Any application using KDE MDI widgets

### GTK Applications

GTK applications running on KDE Plasma respect the system icon theme:

* GIMP window controls
* Firefox/Chrome (when using system theme)
* LibreOffice menus
* Gedit toolbar

### Dockable Panels

Panel close buttons and controls in dockable widgets use system icons for consistency.

## Advanced Configuration

### Force Icon Colorization

In Klassy Settings, you can enable **Force Colorize System Icons**:

<ParamField path="Force Colorize System Icons" type="boolean">
  When enabled, ensures system icons always use the configured button colors, even if the parent theme would normally use different colors
</ParamField>

This is useful when inheriting from icon themes that have their own color schemes.

### Manual Icon Theme Selection

After generating Klassy icon themes, select them in System Settings:

<Steps>
  <Step title="Open System Settings">
    Navigate to **Appearance** > **Icons**
  </Step>

  <Step title="Select Klassy theme">
    Choose:

    * **Klassy** for light mode
    * **Klassy Dark** for dark mode
  </Step>

  <Step title="Apply changes">
    Click **Apply** to use the Klassy icon theme system-wide
  </Step>
</Steps>

<Note>
  The Kite global theme automatically sets the appropriate Klassy icon theme. Manual selection is only needed if you're mixing and matching theme components.
</Note>

### Inheritance Chain

Icon lookup follows this inheritance chain:

1. `klassy` or `klassy-dark` (window control icons)
2. Configured parent theme (e.g., `breeze`)
3. Parent theme's inheritance chain (if any)
4. `hicolor` (fallback)

This ensures all icons are available while only window control icons are customized.

## Troubleshooting

### Icons Don't Match Button Style

**Solution:** Regenerate system icons

```bash theme={null}
klassy-settings --generate-system-icons
```

### Icons Appear in Wrong Colors

**Possible causes:**

* Icon theme cache needs clearing
* Parent theme has hard-coded colors

**Solution:**

```bash theme={null}
# Clear icon cache
rm -rf ~/.cache/icon-cache.kcache

# Regenerate icons
klassy-settings -g

# Restart plasmashell
kquitapp6 plasmashell && plasmashell &
```

### GTK Apps Don't Use Klassy Icons

**Solution:** Ensure GTK theme integration is configured:

1. Install `kde-gtk-config`
2. Open System Settings > **Application Style** > **Configure GNOME/GTK Application Style**
3. Verify icon theme is set to "Klassy" or "Klassy Dark"

### Icons Missing at Certain Scales

**Solution:** The icon generator should create all scales automatically. If missing, regenerate:

```bash theme={null}
klassy-settings --generate-system-icons
```

Check that all scale directories exist in `~/.local/share/icons/klassy/`.

## Manual Icon Customization

<Note>
  Manual customization is not recommended as regenerating icons will overwrite changes. Use Klassy Settings to configure button appearance instead.
</Note>

If you need to manually customize icons:

1. Generate icons normally first
2. Copy the generated icon theme to a new name:
   ```bash theme={null}
   cp -r ~/.local/share/icons/klassy ~/.local/share/icons/my-custom-klassy
   ```
3. Edit `~/.local/share/icons/my-custom-klassy/index.theme` and change the `Name` field
4. Modify SVG files in the theme directories
5. Select your custom theme in System Settings

Your custom theme will inherit from Klassy's parent theme but won't be overwritten by regeneration.