From da683c032285b5b7e4e05d85dd58ee9a37d8999c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yann=20C=C3=A9bron?= <yann.cebron@jetbrains.com>
Date: Wed, 23 Apr 2025 09:55:46 +0200
Subject: [PATCH] ui_faq.md: add "Combining icons"

---
 topics/reference_guide/icons.md            |  2 ++
 topics/user_interface_components/ui_faq.md | 13 +++++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/topics/reference_guide/icons.md b/topics/reference_guide/icons.md
index f2419f8d2..7ec9077bb 100644
--- a/topics/reference_guide/icons.md
+++ b/topics/reference_guide/icons.md
@@ -10,6 +10,8 @@
 
 **UI Guidelines:** [Icons list](https://intellij-icons.jetbrains.design), [](icons_style.md)
 
+**See also**: [UI FAQ - Icons](ui_faq.md#icons)
+
 </tldr>
 
 Icons are used widely by IntelliJ Platform plugins.
diff --git a/topics/user_interface_components/ui_faq.md b/topics/user_interface_components/ui_faq.md
index 5b989c453..4be49ee69 100644
--- a/topics/user_interface_components/ui_faq.md
+++ b/topics/user_interface_components/ui_faq.md
@@ -1,4 +1,4 @@
-<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+<!-- Copyright 2000-2025 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
 # User Interface FAQ
 
@@ -76,8 +76,17 @@ can result in UI layout problems.
 If you use DPI-aware insets in an empty border (`JBUI.Borders.empty()`), then the insets will be updated automatically, for example, if scaling is changed because the <ui-path>IDE Zoom</ui-path> action was performed or for any other reason.
 If you use the insets elsewhere, you need to manually call `JBInsets.update()` in your component's `updateUI()` method to update the insets accordingly.
 
-## Manipulating Icons
+## Icons
+
+### Manipulating Icons
 
 Use [`IconUtil`](%gh-ic%/platform/core-ui/src/util/IconUtil.kt) to scale/colorize/darken/desaturate existing [icons](icons.md) as needed.
 
+### Combining Icons
+
+Use [`RowIcon`](%gh-ic%/platform/core-ui/src/ui/RowIcon.kt) to combine icons horizontally (_\$modifier\$_ _\$element\$_).
+
+To stack icons, use [`LayeredIcon`](%gh-ic%/platform/core-ui/src/ui/LayeredIcon.kt).
+[`IconWithOverlay`](%gh-ic%/platform/core-ui/src/ui/icons/IconWithOverlay.java) additionally allows controlling the shape of the overlay icon.
+
 <include from="snippets.topic" element-id="missingContent"/>