Icons

KDE apps respect the FreeDesktop icon theme and icon naming standards, and make extensive use of themable icons.

KDE's Breeze icon theme complies with the above specifications and contains thousands of icons suitable for a wide range of apps. While the user can change the icon theme to something else, ensure your app looks perfect with Breeze. Browse the library of Breeze icons using Icon Explorer, contained within the plasma-sdk package.

If you find that your app needs a new icon not present in the Breeze icon theme, request one here. Members of KDE's Visual Design Group will create one and add it to the Breeze icon theme so everyone else can use it too.

Many considerations go into choosing the right icon for each button, menu item, and list item in your app:

Universal or specific icons?

The Breeze icon theme — as well as most others — includes icons consisting of just a base shape with a broad meaning, as well as icons consisting of multiple base shapes and/or emblems that narrow the icon's meaning to only a certain type of object or target. We call these universal and specific icons. For example:

Universal
Specific

Prefer universal icons where possible, as their simplicity makes them faster to visually parse and understand. But in some cases, specific ones are more appropriate. Here are the rules for when to use each type:

Examples:

Icons for destructive actions

Actions that destroy content must be consistently indicated as such using icons that are are red or have red elements (in the Breeze icon theme, at least):

• Use a red trash can via the edit-delete icon for actions that delete files or destroy content the user has created.
• Use a red X via the edit-delete-remove icon for actions that remove abstract or standard items in a way that's possible to restore later.
• Use one of the more specific deletion-style icons (e.g. delete-comment) only when appropriate according to the rules for universal vs specific icons.

Avoid the use of icons with red elements or X symbols for non-destructive actions.

“Move to trash” style actions are not destructive in and of themselves, so don't use a red icon for them. Instead, use a black trash can via the trash-empty icon. Give its button or menu item a label that includes the “move to trash” phrasing.

Icons-only buttons

Most buttons should also include text. Only use an icons-only button in the following situations:

• Where it's critical to save horizontal space for user content, text, or other actions.
• For actions not relevant to the app's core workflow where it's not a disaster if the user ignores it, or where groups of related icons reveal each other's meaning by proximity (e.g. icons-only buttons to choose text justification in a word processing app).

In both cases, only proceed with the plan to omit text if an icon can be found that uses instantly recognizable imagery common across all operating systems and apps. Examples include:

	list-add		configure
	go-previous		print
	go-home		player-volume-muted
	search		media-playback-start
	edit-delete		documentinfo
	edit-delete-remove		open-menu

If in doubt, show the button's text. If the app has so many buttons visible at once that this looks overwhelming, rethink the UI. For example:

• Only show buttons relevant to the current context.
• Place buttons in a Contextual Toolview that can be hidden when not relevant.
• Group buttons by function in the tabs of a Kirigami.NavigationTabBar.
• Put the buttons on a Kirigami.ActionToolBar so that buttons without sufficient space get moved into an overflow menu.
• Reduce the length of the buttons' labels.
• Condense related buttons into a single one that opens a menu of actions.

To make a button icons-only, hide the text using the display property. Always set the text property, so it can be read by screen readers.

Icons for menu items and buttons with text

Set an icon on every button and menu item, making sure not to use the same icon for multiple visible buttons or menu items. Choose different icons, or use more specific ones to disambiguate.

For icons on parent menu items or buttons that open menus, use symbolism relevant to all child menu items.

Icons for list items

For icons in the leading position, vary the icons between list items; don't use the same one for every item. If this is impossible, don't show any icons.

For inline action buttons in the trailing position, use icons-only buttons with simple universal icons for obvious actions (delete, edit, etc.). Keep the number of buttons to two at most, and prefer zero to one. If this is impossible because each list item has many possible actions or complex actions that cannot be expressed with simple icons, don't use inline actions. Instead, push a sub-page with a rich UI when the user clicks on the list item.

Symbolic or full-color icons?

Once you've chosen an icon, determine whether it should be symbolic or full-color. At small sizes (especially small and smallMedium), full-color icons can become visual smudges or contribute to a “heavy” appearance when many are shown in a row or column. Prefer symbolic ones by appending -symbolic to the name of the icon you're asking the icon theme to provide. This causes the icon loader to provide a symbolic monochrome icon if the theme has one. Full-color icons are better at medium size and larger.

Always use symbolic icons for menu items and standard-sized buttons.

Always use symbolic icons for the small icon size in list items, and generally at the smallMedium size too. Context dictates whether this makes sense or not: with only a small number of list items, full-color icons may look better. For large or dense lists, prefer symbolic icons.

Overlaying emblems on top of content

When overlaying icons on top of user content or on top of other icons, only use overlay icons whose names begin with emblem-, as they are designed for this purpose.

Implementation details

• Don't bundle custom icons with your app or specify pixmaps for your icons. Instead get them from the system's icon theme using QIcon::IconFromTheme() in C++ code, or using the icon.name property for QML components that accept icons.
• Make the KIconThemes framework a build dependency for your application and call KIconTheme::initTheme before creating the QApplication. See more information here.
• For standard actions, use KStandardActions so that it gets a standard icon, too.
• Use standard icon sizes in any context where the icon size is not automatically chosen for you.

Designing your own icons

Every app needs a great icon. Learn how to make one here.

Learn how to create symbolic action icons here.