From 40f5c009044dc23dabc8c94b16efa7feb045b99b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Nov 2025 22:30:07 +0000
Subject: [PATCH 1/2] Initial plan


From 312808b462c225419f9187c4ebfdb0cf1dbad04f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Nov 2025 22:33:50 +0000
Subject: [PATCH 2/2] docs: Fix Shell flyout template to prevent type cast
 errors on Android

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
---
 docs/fundamentals/shell/flyout.md | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/docs/fundamentals/shell/flyout.md b/docs/fundamentals/shell/flyout.md
index a8d2cf54e..01b73a89b 100644
--- a/docs/fundamentals/shell/flyout.md
+++ b/docs/fundamentals/shell/flyout.md
@@ -1,7 +1,7 @@
 ---
 title: ".NET MAUI Shell flyout"
 description: "Learn how to customize and control a .NET MAUI flyout, which is the optional root menu for a .NET MAUI Shell app."
-ms.date: 08/30/2024
+ms.date: 11/28/2025
 ---
 
 # .NET MAUI Shell flyout
@@ -180,8 +180,9 @@ The default <xref:Microsoft.Maui.Controls.DataTemplate> used for each <xref:Micr
                     </VisualState>          
                     <VisualState x:Name="Selected">
                         <VisualState.Setters>
-                            <Setter Property="BackgroundColor"
-                                    Value="{AppThemeBinding Light=Black, Dark=White}" />
+                            <Setter TargetName="FlyoutItemLayout"
+                                    Property="BackgroundColor"
+                                    Value="{AppThemeBinding Light=#1A000000, Dark=#1AFFFFFF}" />
                         </VisualState.Setters>
                     </VisualState>
                 </VisualStateGroup>
@@ -209,19 +210,12 @@ The default <xref:Microsoft.Maui.Controls.DataTemplate> used for each <xref:Micr
         <Label x:Name="FlyoutItemLabel"
                Grid.Column="1"
                Text="{Binding Title}"
+               TextColor="{OnPlatform Android={AppThemeBinding Light=#DE000000, Dark=White}}"
                FontSize="{OnPlatform Android=14, iOS=14}"
                FontAttributes="{OnPlatform iOS=Bold}"
                HorizontalOptions="{OnPlatform WinUI=Start}"
                HorizontalTextAlignment="{OnPlatform WinUI=Start}"
                VerticalTextAlignment="Center">
-            <Label.TextColor>
-                <OnPlatform x:TypeArguments="Color">
-                    <OnPlatform.Platforms>
-                        <On Platform="Android"
-                            Value="{AppThemeBinding Light=Black, Dark=White}" />
-                    </OnPlatform.Platforms>
-                </OnPlatform>
-            </Label.TextColor>
             <Label.Margin>
                 <OnPlatform x:TypeArguments="Thickness">
                     <OnPlatform.Platforms>
@@ -243,6 +237,9 @@ The default <xref:Microsoft.Maui.Controls.DataTemplate> used for each <xref:Micr
 </DataTemplate>
 ```
 
+> [!IMPORTANT]
+> When combining `OnPlatform` with `AppThemeBinding`, avoid nesting `AppThemeBinding` inside an `<OnPlatform>` element with `x:TypeArguments="Color"`, as this can cause type cast errors at runtime on Android. Instead, use the inline markup extension syntax as shown above, or apply colors directly using style classes.
+
 This template can be used for as a basis for making alterations to the existing flyout layout, and also shows the visual states that are implemented for flyout items.
 
 In addition, the <xref:Microsoft.Maui.Controls.Grid>, <xref:Microsoft.Maui.Controls.Image>, and <xref:Microsoft.Maui.Controls.Label> elements all have `x:Name` values and so can be targeted with the Visual State Manager. For more information, see [Set state on multiple elements](~/user-interface/visual-states.md#set-state-on-multiple-elements).