CmdPal: Enhance font icon classification and visuals (#41573)

## Summary of the Pull Request

- Introduces `FontIconGlyphClassifier` for classifying emojis and
symbols.
- Correctly recognizes multi-codepoint glyphs (e.g., 🧙🏼‍♀️ *woman mage
with medium-light skin tone*).
- Explicitly disallows multi-glyph icons (they would overflow anyway).
- Distinguishes between emojis and regular text characters (letters,
numbers, symbols), since emojis are slightly larger and require
different padding.
- Recognizes Unicode [Variation
Selectors](https://en.wikipedia.org/wiki/Variation_Selectors_(Unicode_block))
to enforce specific styles: VS15 (U+FE0E) for text style (monochrome)
and VS16 (U+FE0F) for emoji style (color). This lets developers choose
which variant to display. By default, characters with both
representations render as text/monochrome (e.g., ▶ `\u25B6`):
<img width="428" height="39" alt="image"
src="https://github.com/user-attachments/assets/c5e6865f-61de-4f45-9f3a-4e15e5e5ceb8"
/>
- Invalid icons are displayed as a dashed circle so extension developers
can spot issues, without being overly distracting if they slip into
production.

- Updates `IconPathConverter` to use the new classifier for improved
icon handling.
- Adds `SampleIconPage` to demonstrate various icon usages and
classifications.
- Adjusts icon alignment in `IconBox` so icons are centered.  
- Scales negative padding for emojis in `IconBox` with control size,
fixing misalignment and clipping (noticeable in tags and the details
pane hero image).
- Applies negative padding to all font icons. This removes the need for
classification in these cases and ensures symbols rendered below the
baseline remain visible.

Based on
[microsoft/terminal#19143](https://github.com/microsoft/terminal/pull/19143):
Co-authored-by: Dustin L. Howett <duhowett@microsoft.com>

Pictures? Pictures!

<img width="1912" height="2394" alt="image"
src="https://github.com/user-attachments/assets/05a16309-b658-4f21-8f9d-9a3f20db6ad8"
/>

Keyboard and flag/country emojis may look a bit off, but that’s how
they’re actually rendered:
<img width="482" height="95" alt="image"
src="https://github.com/user-attachments/assets/dc7d4d0d-3dc8-4df5-9b9f-9e977e7e989f"
/>


<!-- Please review the items on the PR checklist before submitting-->
## PR Checklist

- [x] Closes: 
  - #41489 
  - #41496 
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [ ] **Tests:** Added/updated and all pass
- [ ] **Localization:** All end-user-facing strings can be localized
- [ ] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

<!-- Provide a more detailed description of the PR, other things fixed,
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments

<!-- Describe how you validated the behavior. Add automated tests
wherever possible, but list manual validation steps taken as well -->
## Validation Steps Performed

.github/actions/spell-check/expect.txt

@@ -306,6 +306,7 @@ CXVIRTUALSCREEN
 CYSCREEN
 CYSMICON
 CYVIRTUALSCREEN
+Czechia
 cziplib
 Dac
 dacl
@@ -436,6 +437,7 @@ EDITSHORTCUTS
 EDITTEXT
 EFile
 ekus
+emojis
 ENABLEDELAYEDEXPANSION
 ENABLEDPOPUP
 ENABLETAB
@@ -800,6 +802,7 @@ KEYBOARDMANAGEREDITORLIBRARYWRAPPER
 keyboardmanagerstate
 keyboardmanagerui
 keyboardtester
+keycap
 KEYEVENTF
 KEYIMAGE
 keynum
@@ -1781,10 +1784,13 @@ UACUI
 UAL
 uap
 UBR
+UBreak
+ubrk
 UCallback
 ucrt
 ucrtd
 uefi
+UError
 uesc
 UFlags
 UHash
@@ -1854,6 +1860,7 @@ VFT
 vget
 vgetq
 viewmodels
+virama
 VIRTKEY
 VIRTUALDESK
 VISEGRADRELAY

src/modules/cmdpal/Microsoft.CmdPal.UI/Controls/IconBox.cs

@@ -2,8 +2,10 @@
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using ManagedCommon;
 using Microsoft.CmdPal.Core.ViewModels;
 using Microsoft.CmdPal.UI.Deferred;
+using Microsoft.Terminal.UI;
 using Microsoft.UI.Dispatching;
 using Microsoft.UI.Xaml;
 using Microsoft.UI.Xaml.Controls;
@@ -55,6 +57,8 @@ public partial class IconBox : ContentControl
     {
         TabFocusNavigation = KeyboardNavigationMode.Once;
         IsTabStop = false;
+        HorizontalContentAlignment = HorizontalAlignment.Center;
+        VerticalContentAlignment = VerticalAlignment.Center;
     }
 
     private static void OnSourcePropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
@@ -75,6 +79,8 @@ public partial class IconBox : ContentControl
                     IconSourceElement elem = new()
                     {
                         IconSource = fontIco,
+                        HorizontalAlignment = HorizontalAlignment.Center,
+                        VerticalAlignment = VerticalAlignment.Center,
                     };
                     @this.Content = elem;
                     break;
@@ -98,14 +104,20 @@ public partial class IconBox : ContentControl
             else
             {
                 // TODO GH #239 switch back when using the new MD text block
+                // Switching back to EnqueueAsync has broken icons in tags (they don't show)
                 // _ = @this._queue.EnqueueAsync(() =>
-                @this._queue.TryEnqueue(new(async () =>
+                @this._queue.TryEnqueue(async void () =>
                 {
-                    var requestedTheme = @this.ActualTheme;
-                    var eventArgs = new SourceRequestedEventArgs(e.NewValue, requestedTheme);
-
-                    if (@this.SourceRequested is not null)
+                    try
                     {
+                        if (@this.SourceRequested is null)
+                        {
+                            return;
+                        }
+
+                        var requestedTheme = @this.ActualTheme;
+                        var eventArgs = new SourceRequestedEventArgs(e.NewValue, requestedTheme);
+
                         await @this.SourceRequested.InvokeAsync(@this, eventArgs);
 
                         // After the await:
@@ -130,37 +142,35 @@ public partial class IconBox : ContentControl
                         // So, if the icon we get back was a font icon,
                         // and the glyph for that icon is NOT in the range of
                         // Segoe icons, then let's give the icon some extra space
-                        @this.Padding = new Thickness(0);
-
-                        IconDataViewModel? iconData = null;
-                        if (eventArgs.Key is IconDataViewModel)
+                        var iconData = eventArgs.Key switch
                         {
-                            iconData = eventArgs.Key as IconDataViewModel;
+                            IconDataViewModel key => key,
+                            IconInfoViewModel info => requestedTheme == ElementTheme.Light ? info.Light : info.Dark,
+                            _ => null,
+                        };
+
+                        if (iconData?.Icon is not null && @this.Source is FontIconSource)
+                        {
+                            var iconSize =
+                                !double.IsNaN(@this.Width) ? @this.Width :
+                                !double.IsNaN(@this.Height) ? @this.Height :
+                                @this.ActualWidth > 0 ? @this.ActualWidth :
+                                @this.ActualHeight;
+
+                            @this.Padding = new Thickness(Math.Round(iconSize * -0.2));
                         }
-                        else if (eventArgs.Key is IconInfoViewModel info)
+                        else
                         {
-                            iconData = requestedTheme == ElementTheme.Light ? info.Light : info.Dark;
-                        }
-
-                        if (iconData is not null &&
-                            @this.Source is FontIconSource)
-                        {
-                            if (!string.IsNullOrEmpty(iconData.Icon) && iconData.Icon.Length <= 2)
-                            {
-                                var ch = iconData.Icon[0];
-
-                                // The range of MDL2 Icons isn't explicitly defined, but
-                                // we're using this based off the table on:
-                                // https://docs.microsoft.com/en-us/windows/uwp/design/style/segoe-ui-symbol-font
-                                var isMDL2Icon = ch is >= '\uE700' and <= '\uF8FF';
-                                if (!isMDL2Icon)
-                                {
-                                    @this.Padding = new Thickness(-4);
-                                }
-                            }
+                            @this.Padding = default;
                         }
                     }
-                }));
+                    catch (Exception ex)
+                    {
+                        // Exception from TryEnqueue bypasses the global error handler,
+                        // and crashes the app.
+                        Logger.LogError("Failed to set icon", ex);
+                    }
+                });
             }
         }
     }

src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.cpp

@@ -0,0 +1,177 @@
+#include "pch.h"
+#include "FontIconGlyphClassifier.h"
+#include "FontIconGlyphClassifier.g.cpp"
+
+#include <icu.h>
+#include <utility>
+
+namespace winrt::Microsoft::Terminal::UI::implementation
+{
+    namespace
+    {
+        // Check if the code point is in the Private Use Area range used by Fluent UI icons.
+        [[nodiscard]] constexpr bool _isFluentIconPua(const UChar32 cp) noexcept
+        {
+            static constexpr UChar32 _fluentIconsPrivateUseAreaStart = 0xE700;
+            static constexpr UChar32 _fluentIconsPrivateUseAreaEnd = 0xF8FF;
+            return cp >= _fluentIconsPrivateUseAreaStart && cp <= _fluentIconsPrivateUseAreaEnd;
+        }
+
+        // Determine if the given text (as a sequence of UChar code units) is emoji
+        [[nodiscard]] bool _isEmoji(const UChar* p, const int32_t length) noexcept
+        {
+            if (!p || length < 1)
+            {
+                return false;
+            }
+
+            // https://www.unicode.org/reports/tr51/#Emoji_Variation_Selector_Notes
+            constexpr UChar32 vs15CodePoint = 0xFE0E; // Variation Selectors 15: text variation selector
+            constexpr UChar32 vs16CodePoint = 0xFE0F; // Variation Selectors: 16 emoji variation selector
+
+            // Decode the first code point correctly (surrogate-safe)
+            int32_t i0{ 0 };
+            UChar32 first{ 0 };
+            U16_NEXT(p, i0, length, first);
+
+            for (int32_t i = 0; i < length;)
+            {
+                UChar32 cp{ 0 };
+                U16_NEXT(p, i, length, cp);
+
+                if (cp == vs16CodePoint) { return true; }
+                if (cp == vs15CodePoint) { return false; }
+            }
+
+            return !U_IS_SURROGATE(first) && u_hasBinaryProperty(first, UCHAR_EMOJI_PRESENTATION);
+        }
+    }
+
+    bool FontIconGlyphClassifier::IsLikelyToBeEmojiOrSymbolIcon(const hstring& text)
+    {
+        if (text.empty())
+        {
+            return false;
+        }
+
+        if (text.size() == 1 && !IS_HIGH_SURROGATE(text[0]))
+        {
+            // If it's a single code unit, it's definitely either zero or one grapheme clusters.
+            // If it turns out to be illegal Unicode, we don't really care.
+            return true;
+        }
+
+        if (text.size() >= 2 && text[0] <= 0x7F && text[1] <= 0x7F)
+        {
+            // Two adjacent ASCII characters (as seen in most file paths) aren't a single
+            // grapheme cluster.
+            return false;
+        }
+
+        // Use ICU to determine whether text is composed of a single grapheme cluster.
+        int32_t off{ 0 };
+        UErrorCode status{ U_ZERO_ERROR };
+
+        UBreakIterator* const bi{ ubrk_open(UBRK_CHARACTER,
+                                            nullptr,
+                                            reinterpret_cast<const UChar*>(text.data()),
+                                            static_cast<int>(text.size()),
+                                            &status) };
+        if (bi)
+        {
+            if (U_SUCCESS(status))
+            {
+                off = ubrk_next(bi);
+            }
+            ubrk_close(bi);
+        }
+        return std::cmp_equal(off, text.size());
+    }
+
+    FontIconGlyphKind FontIconGlyphClassifier::Classify(hstring const& text) noexcept
+    {
+        if (text.empty())
+        {
+            return FontIconGlyphKind::None;
+        }
+
+        const size_t textSize{ text.size() };
+        const auto* buffer{ reinterpret_cast<const UChar*>(text.c_str()) };
+
+        // Fast path 1: Single UTF-16 code unit (most common case)
+        if (textSize == 1)
+        {
+            const UChar ch{ buffer[0] };
+
+            if (IS_HIGH_SURROGATE(ch))
+            {
+                return FontIconGlyphKind::Invalid;
+            }
+
+            if (_isFluentIconPua(ch))
+            {
+                return FontIconGlyphKind::FluentSymbol;
+            }
+
+            if (_isEmoji(&ch, 1))
+            {
+                return FontIconGlyphKind::Emoji;
+            }
+
+            return FontIconGlyphKind::Other;
+        }
+
+        // Fast path 2: Common file path pattern - two ASCII printable characters
+        if (textSize >= 2 && buffer[0] <= 0x7F && buffer[1] <= 0x7F)
+        {
+            // Definitely multiple graphemes
+            return FontIconGlyphKind::Invalid;
+        }
+
+        // Expensive path: Use ICU to determine grapheme boundaries
+        UErrorCode status{ U_ZERO_ERROR };
+
+        UBreakIterator* bi{ ubrk_open(UBRK_CHARACTER,
+                                      nullptr,
+                                      buffer,
+                                      static_cast<int32_t>(textSize),
+                                      &status) };
+
+        if (U_FAILURE(status) || !bi)
+        {
+            return FontIconGlyphKind::Invalid;
+        }
+
+        const int32_t start{ ubrk_first(bi) };
+        const int32_t end{ ubrk_next(bi) }; // end of first grapheme
+        ubrk_close(bi);
+
+        // No graphemes found
+        if (end == UBRK_DONE || end <= start)
+        {
+            return FontIconGlyphKind::None;
+        }
+
+        // If there's more than one grapheme, it's not a valid icon glyph
+        if (std::cmp_not_equal(end, textSize))
+        {
+            return FontIconGlyphKind::Invalid;
+        }
+
+        // Exactly one grapheme: classify
+        const UChar* grapheme = buffer + start;
+        const int32_t graphemeLength = end - start;
+
+        if (graphemeLength == 1 && _isFluentIconPua(grapheme[0]))
+        {
+            return FontIconGlyphKind::FluentSymbol;
+        }
+
+        if (_isEmoji(grapheme, graphemeLength))
+        {
+            return FontIconGlyphKind::Emoji;
+        }
+
+        return FontIconGlyphKind::Other;
+    }
+}

src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include "FontIconGlyphClassifier.g.h"
+
+namespace winrt::Microsoft::Terminal::UI::implementation
+{
+    struct FontIconGlyphClassifier
+    {
+        [[nodiscard]] static bool IsLikelyToBeEmojiOrSymbolIcon(const winrt::hstring& text);
+
+        [[nodiscard]] static FontIconGlyphKind Classify(winrt::hstring const& text) noexcept;
+    };
+}
+
+namespace winrt::Microsoft::Terminal::UI::factory_implementation
+{
+    BASIC_FACTORY(FontIconGlyphClassifier);
+}

src/modules/cmdpal/Microsoft.Terminal.UI/FontIconGlyphClassifier.idl

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+namespace Microsoft.Terminal.UI
+{
+    /// <summary>
+    /// Categorizes the type of a single grapheme cluster or input text.
+    /// Used to determine how the input should be handled or rendered (for example,
+    /// whether it should be treated as an emoji, an icon from a symbol font, plain text, etc.).
+    /// </summary>
+    enum FontIconGlyphKind
+    {
+        /// <summary>
+        /// Input is invalid or contains more than one grapheme cluster and therefore cannot be
+        /// treated as a single symbol. Typical for multi-character text like file paths
+        /// or composed strings that include separators.
+        /// </summary>
+        Invalid = -1,
+
+        /// <summary>
+        /// No grapheme present (empty string). Indicates absence of a symbol.
+        /// </summary>
+        None = 0,
+
+        /// <summary>
+        /// A single emoji grapheme cluster. This may consist of multiple Unicode code
+        /// points combined into one visible glyph (e.g., emoji with modifiers or ZWJ sequences).
+        /// </summary>
+        Emoji = 1,
+
+        /// <summary>
+        /// A single glyph from the Segoe Fluent Icons / MDL2 Assets Private Use Area (PUA),
+        /// typically in the Unicode range U+E700–U+F8FF. These are font-based icons (Fluent/MDL2).
+        /// </summary>
+        FluentSymbol = 2,
+
+        /// <summary>
+        /// A single non-emoji grapheme that is not a Fluent/MDL2 PUA symbol.
+        /// Covers ordinary characters, letters, numbers, or other single glyph symbols.
+        /// </summary>
+        Other = 3,
+    };
+
+    /// <summary>
+    /// Static utility class for text and icon analysis
+    /// </summary>
+    static runtimeclass FontIconGlyphClassifier
+    {
+        /// <summary>
+        /// Determines if text represents a single grapheme cluster (emoji/symbol icon).
+        /// Uses ICU for Unicode boundary detection to distinguish icons from file paths.
+        /// </summary>
+        /// <param name="text">Text to analyze</param>
+        /// <returns>True if single grapheme cluster, false for multi-character text or paths</returns>
+        static Boolean IsLikelyToBeEmojiOrSymbolIcon(String text);
+
+        /// <summary>
+        /// Classifies the input into a glyph kind suitable for icon or text rendering.
+        /// </summary>
+        static FontIconGlyphKind Classify(String text);
+    };
+}

src/modules/cmdpal/Microsoft.Terminal.UI/IconPathConverter.cpp

@@ -2,7 +2,7 @@
 #include "IconPathConverter.h"
 #include "IconPathConverter.g.cpp"
 
-// #include "Utils.h"
+ #include "FontIconGlyphClassifier.h"
 
 #include <Shlobj.h>
 #include <Shlobj_core.h>
@@ -110,7 +110,7 @@ namespace winrt::Microsoft::Terminal::UI::implementation
                 if (til::equals_insensitive_ascii(iconUri.Extension(), L".svg"))
                 {
                     typename ImageIconSource<TIconSource>::type iconSource;
-                    winrt::Microsoft::UI::Xaml::Media::Imaging::SvgImageSource source{ iconUri };	
+                    winrt::Microsoft::UI::Xaml::Media::Imaging::SvgImageSource source{ iconUri };
                     iconSource.ImageSource(source);
                     return iconSource;
                 }
@@ -169,41 +169,46 @@ namespace winrt::Microsoft::Terminal::UI::implementation
 
             // If we fail to set the icon source using the "icon" as a path,
             // let's try it as a symbol/emoji.
-            //
-            // Anything longer than 2 wchar_t's _isn't_ an emoji or symbol, so
-            // don't do this if it's just an invalid path.
-            if (!iconSource && iconPath.size() <= 2)
+            if (!iconSource)
             {
                 try
                 {
-                    typename FontIconSource<TIconSource>::type icon;
-                    const auto ch = til::at(iconPath, 0);
+                    const auto glyph_kind = FontIconGlyphClassifier::Classify(iconPath);
 
-                    // The range of MDL2 Icons isn't explicitly defined, but
-                    // we're using this based off the table on:
-                    // https://docs.microsoft.com/en-us/windows/uwp/design/style/segoe-ui-symbol-font
-                    const auto isMDL2Icon = ch >= L'\uE700' && ch <= L'\uF8FF';
-                    if (isMDL2Icon)
+                    winrt::hstring family;
+                    if (glyph_kind == FontIconGlyphKind::Invalid)
                     {
-                        icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ L"Segoe Fluent Icons, Segoe MDL2 Assets" });
+                        family = L"Segoe UI";
                     }
                     else if (!fontFamily.empty())
                     {
-                        icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ fontFamily });
-
+                        family = fontFamily;
+                    }
+                    else if (glyph_kind == FontIconGlyphKind::FluentSymbol)
+                    {
+                        family = L"Segoe Fluent Icons, Segoe MDL2 Assets";
+                    }
+                    else if (glyph_kind == FontIconGlyphKind::Emoji)
+                    {
+                        // Emoji and other symbols go in the Segoe UI Emoji font.
+                        // Some emojis (e.g. 2️⃣) would be rendered as emoji glyphs otherwise.
+                        family = L"Segoe UI Emoji, Segoe UI";
                     }
                     else
                     {
-                        // Note: you _do_ need to manually set the font here.
-                        icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ L"Segoe UI" });
+                        family = L"Segoe UI";
                     }
+
+                    typename FontIconSource<TIconSource>::type icon;
+                    icon.FontFamily(winrt::Microsoft::UI::Xaml::Media::FontFamily{ family });
                     icon.FontSize(targetSize);
-                    icon.Glyph(iconPath);
+                    icon.Glyph(glyph_kind == FontIconGlyphKind::Invalid ? L"\u25CC" : iconPath);
                     iconSource = icon;
                 }
                 CATCH_LOG();
             }
         }
+
         if (!iconSource)
         {
             // Set the default IconSource to a BitmapIconSource with a null source
@@ -326,7 +331,7 @@ namespace winrt::Microsoft::Terminal::UI::implementation
     }
 
     static winrt::Microsoft::UI::Xaml::Media::Imaging::SoftwareBitmapSource _getImageIconSourceForBinary(std::wstring_view iconPathWithoutIndex,
-                                                                                                         int index, 
+                                                                                                         int index,
                                                                                                          int targetSize)
     {
         // Try:

src/modules/cmdpal/Microsoft.Terminal.UI/Microsoft.Terminal.UI.vcxproj

@@ -159,6 +159,9 @@
     <ClInclude Include="ResourceString.h">
       <DependentUpon>ResourceString.idl</DependentUpon>
     </ClInclude>
+    <ClInclude Include="FontIconGlyphClassifier.h">
+      <DependentUpon>FontIconGlyphClassifier.idl</DependentUpon>
+    </ClInclude>
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="init.cpp" />
@@ -178,6 +181,9 @@
       <DependentUpon>ResourceString.idl</DependentUpon>
     </ClCompile>
     <ClCompile Include="$(GeneratedFilesDir)module.g.cpp" />
+    <ClCompile Include="FontIconGlyphClassifier.cpp">
+      <DependentUpon>FontIconGlyphClassifier.idl</DependentUpon>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <Midl Include="Converters.idl" />
@@ -185,6 +191,7 @@
     <Midl Include="RunHistory.idl" />
     <Midl Include="IDirectKeyListener.idl" />
     <Midl Include="ResourceString.idl" />
+    <Midl Include="FontIconGlyphClassifier.idl" />
   </ItemGroup>
   <ItemGroup>
     <None Include="packages.config" />

src/modules/cmdpal/ext/SamplePagesExtension/Pages/SampleIconPage.cs

@@ -0,0 +1,189 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Linq;
+using Microsoft.CommandPalette.Extensions;
+using Microsoft.CommandPalette.Extensions.Toolkit;
+
+namespace SamplePagesExtension.Pages;
+
+internal sealed partial class SampleIconPage : ListPage
+{
+    private readonly IListItem[] _items =
+    [
+        /*
+         * Quick intro to Unicode in source code:
+         * - Every character has a code point (e.g., U+0041 = 'A').
+         * - Code points up to U+FFFF use \u1234 (4 hex digits and lowercase u).
+         * - Code points above that (up to U+10FFFF) use \U12345678 (8 hex digits and capital letter U).
+         * - If your source file is UTF-8, you can type the character directly, but it may not display properly in editors,
+         *   and it's harder to see the actual code point.
+         * - Some symbols (like many emojis) are built from multiple code points
+         *   joined together (e.g., 👋🏻 = U+1F44B + U+1F3FB).
+         *
+         * Examples:
+         *   😍 = "😍" or "\U0001F60D"
+         *   👋🏻 = "👋🏻" or "\U0001F44B\U0001F3FB"
+         *   🧙‍♂️ = "🧙‍♂️" or "\U0001F9D9\u200D\u2642\U0000FE0F"   (male mage)
+         *   🧙🏿‍♀️ = "🧙🏿‍♀️" or "\U0001F9D9\U0001F3FF\u200D\u2640\U0000FE0F" (dark-skinned woman mage)
+         *
+         */
+
+        // Emoji Smiling Face with Heart-Eyes
+        // Unicode: \U0001F60D
+        BuildIconItem("😍", "Standard emoji icon", "Basic emoji character rendered as an icon"),
+
+        // Emoji Smiling Face with Heart-Eyes
+        // Unicode: \U0001F60D\U0001F643\U0001F622
+        BuildIconItem("😍🙃😢", "Multiple emojis", "Use of multiple emojis for icon is not allowed"),
+
+        // Emoji Smiling Face with Sunglasses
+        // Unicode: \U0001F60E
+        BuildIconItem("\U0001F60E", "Unicode escape sequence emoji", "Emoji defined using Unicode escape sequence notation"),
+
+        // Segoe Fluent Icons font icon
+        // Unicode: \uE8D4
+        BuildIconItem("\uE8D4", "Segoe Fluent icon demonstration", "Segoe Fluent/MDL2 icon from system font\nWorks as an icon but won't display properly in button text"),
+
+        // Extended pictographic symbol for keyboard
+        BuildIconItem("\u2328", "Extended pictographic symbol", "Pictographic symbol representing a keyboard"),
+
+        // Capital letter A
+        BuildIconItem("A", "Simple text character as icon", "Basic letter character used as an icon demonstration"),
+
+        // Letter 1
+        // Unicode: \U00000031
+        BuildIconItem("1", "Simple text character as icon", "Basic letter character used as an icon demonstration"),
+
+        // Emoji Keycap Digit Two ... 2️⃣
+        // Unicode: \U00000032\U000020E3
+        // This is a sequence of three code points: the digit '2' (U+0032), and a combining enclosing keycap (U+20E3). No variation selector is used here.
+        BuildIconItem("\U00000032\U000020E3", "Emoji without variation selector", "Emoji character doesn't have VS16 variation selector to render as text"),
+
+        // Emoji Keycap Digit Three ... 3️⃣
+        // Unicode: \U00000033\U0000FE0F\U000020E3
+        // This is a sequence of three code points: the digit '3' (U+0033), a variation selector (U+FE0F) to specify emoji presentation, and a combining enclosing keycap (U+20E3).
+        BuildIconItem("3️⃣", "Emoji with variation selector", "Emoji character using a variation selector to specify emoji presentation"),
+
+        // Symbol #
+        // Unicode: \u0023
+        BuildIconItem("#", "Simple text character as icon", "Basic letter character used as an icon demonstration"),
+
+        // Symbol # keycap
+        // Unicode: \u0023\ufe0f\u20e3
+        // Sequence of 3 code points: symbol #, a variation selector (U+FE0F) to specify emoji presentation, and a combining enclosing keycap (U+20E3).
+        BuildIconItem("\u0023\ufe0f\u20e3", "Simple text character as icon", "Basic letter character used as an icon demonstration"),
+
+        // Capital letter WM
+        // This is two characters, which is not a valid icon representation. It will be replaced by a placeholder signalizing an invalid icon.
+        BuildIconItem("WM", "Invalid icon representation", "String with multiple characters that does not correspond to a valid single icon"),
+
+        // Emoji Mage
+        // Unicode: \U0001F9D9
+        BuildIconItem("🧙", "Single code-point emoji example", "Simple emoji character using a single Unicode code point"),
+
+        // Emoji Male Mage (Mage with gender modifier)
+        // Unicode: \U0001F9D9\u200D\u2642\uFE0F
+        BuildIconItem("🧙‍♂️", "Complex emoji with gender modifier", "Composite emoji using Zero-Width Joiner (ZWJ) sequence for male variant"),
+
+        // Emoji Woman Mage (Mage with gender modifier)
+        // Unicode: \U0001F9D9\u200D\u2640\uFE0F
+        BuildIconItem("\U0001F9D9\u200D\u2640\uFE0F", "Complex emoji with gender modifier", "Composite emoji using Zero-Width Joiner (ZWJ) sequence for female variant"),
+
+        // Emoji Waving Hand
+        // Unicode: \U0001F44B
+        BuildIconItem("👋", "Basic hand gesture emoji", "Standard emoji character representing a waving hand"),
+
+        // Emoji Waving Hand + Light Skin Tone
+        // Unicode: \U0001F44B\U0001F3FB
+        BuildIconItem("👋🏻", "Emoji with light skin tone modifier", "Emoji enhanced with Unicode skin tone modifier (light)"),
+
+        // Emoji Waving Hand + Dark Skin Tone
+        // Unicode: \U0001F44B\U0001F3FF
+        BuildIconItem("\U0001F44B\U0001F3FF", "Emoji with dark skin tone modifier", "Emoji enhanced with Unicode skin tone modifier (dark)"),
+
+        // Flag of Czechia (Czech Republic)
+        // Unicode: \U0001F1E8\U0001F1FF
+        BuildIconItem("\U0001F1E8\U0001F1FF", "Flag emoji using regional indicators", "Emoji flag constructed from regional indicator symbols for Czechia"),
+
+        // Use of ZWJ without emojis
+        // KA (\u0995) + VIRAMA (\u09CD) + ZWJ (\u200D) - shows the half-form KA
+        // Unicode: \u0995\u09CD\u200D
+        BuildIconItem("\u0995\u09CD\u200D", "Use of ZWJ in non-emoji context", "Shows the half-form KA"),
+
+        // Use of ZWJ without emojis
+        // KA (\u0995) + VIRAMA (\u09CD) + Shows full KA with an explicit virama mark (not half-form).
+        // Unicode: \u0995\u09CD
+        BuildIconItem("\u0995\u09CD", "Use of ZWJ in non-emoji context", "Shows full KA with an explicit virama mark"),
+
+        // mahjong tile red dragon (using Unicode escape sequence)
+        // https://en.wikipedia.org/wiki/Mahjong_Tiles_(Unicode_block)
+        // Unicode: \U0001F004
+        BuildIconItem("\U0001F004", "Mahjong tile emoji (red dragon)", "Mahjong tile red dragon emoji character using Unicode escape sequence"),
+
+        // mahjong tile green dragon (non-emoji)
+        // https://en.wikipedia.org/wiki/Mahjong_Tiles_(Unicode_block)
+        // Unicode: \U0001F005
+        BuildIconItem("\U0001F005", "Mahjong tile non-emoji (green dragon)", "Mahjong tile character that is not classified as an emoji"),
+
+        // Play, PlayPause, Stop
+        BuildIconItem("\u25B6", "Play symbol (standalone)", "Play symbol"),
+        BuildIconItem("\u25B6\uFE0E", "Play symbol + VS15 (request text)", "Play symbol with variation specifier requesting rendering as text"),
+        BuildIconItem("\u25B6\uFE0F", "Play symbol + VS16 (request emoji)", "Play symbol with variation specifier requesting rendering as emoji "),
+        BuildIconItem("⏯️", "Play/Pause keycap emoji", "Play/Pause keycap emoji doesn't have plain text variant"),
+        BuildIconItem("⏸️", "Pause keycap emoji", "Pause keycap emoji doesn't have plain text variant"),
+
+        // Copyright and emoji copyright:
+        BuildIconItem("\u00a9", "Copyright symbol (standalone)", "Copyright symbol that is not classified as an emoji"),
+        BuildIconItem("\u00a9\uFE0E", "Copyright symbol + VS15 (request text)", "Copyright symbol that is not classified as an emoji"),
+        BuildIconItem("\u00a9\uFE0F", "Copyright symbol + VS16 (request emoji)", "Copyright symbol that is not classified as an emoji"),
+
+        // Tag flags
+        BuildIconItem("🏳️", "White Flag", "White Flag"),
+        BuildIconItem("\U0001F3F4\u200D\u2620\uFE0F", "Pirate Flag", "Pirate Flag"),
+    ];
+
+    public SampleIconPage()
+    {
+        Icon = new IconInfo("\uE8BA");
+        Name = "Sample Icon Page";
+        ShowDetails = true;
+    }
+
+    public override IListItem[] GetItems() => _items;
+
+    private static ListItem BuildIconItem(string icon, string title, string description)
+    {
+        var iconInfo = new IconInfo(icon);
+
+        return new ListItem(new CopyTextCommand(icon) { Name = "Action with " + icon })
+        {
+            Title = title,
+            Subtitle = description,
+            Icon = iconInfo,
+            Tags = [
+                new Tag("Tag") { Icon = iconInfo },
+            ],
+            Details = new Details
+            {
+                HeroImage = iconInfo,
+                Title = title,
+                Body = description,
+                Metadata = [
+                    new DetailsElement
+                    {
+                        Key = "Unicode Code Points",
+                        Data = new DetailsTags
+                        {
+                            Tags = icon.EnumerateRunes()
+                                .Select(rune => rune.Value <= 0xFFFF ? $"\\u{rune.Value:X4}" : $"\\U{rune.Value:X8}")
+                                .Select(t => new Tag(t))
+                                .ToArray<ITag>(),
+                        },
+                    }
+                ],
+            },
+        };
+    }
+}

src/modules/cmdpal/ext/SamplePagesExtension/SamplesListPage.cs

@@ -4,6 +4,7 @@
 
 using Microsoft.CommandPalette.Extensions;
 using Microsoft.CommandPalette.Extensions.Toolkit;
+using SamplePagesExtension.Pages;
 
 namespace SamplePagesExtension;
 
@@ -37,6 +38,11 @@ public partial class SamplesListPage : ListPage
             Title = "Demo of OnLoad/OnUnload",
             Subtitle = "Changes the list of items every time the page is opened / closed",
         },
+        new ListItem(new SampleIconPage())
+        {
+            Title = "Sample Icon Page",
+            Subtitle = "A demo of using icons in various ways",
+        },
 
         // Content pages
         new ListItem(new SampleContentPage())