Fix Shell flyout template type cast errors on Android

[Copilot]

• Analyze the issue: Documentation shows AppThemeBinding nested inside OnPlatform element syntax which causes type cast errors on Android
• Review the actual MAUI source code for the correct default template implementation
• Fix the "Default template for FlyoutItems" section:
  • Removed problematic nested <OnPlatform x:TypeArguments="Color"> with AppThemeBinding for TextColor
  • Changed to inline syntax: TextColor="{OnPlatform Android={AppThemeBinding Light=#DE000000, Dark=White}}"
  • Fixed the Selected visual state BackgroundColor to use correct alpha values (#1A000000 and #1AFFFFFF) matching MAUI source
  • Removed redundant TargetName="FlyoutItemLayout" from Selected state setter (VSM is already on the Grid)
  • Added IMPORTANT note warning users about the type cast error issue when nesting markup extensions
• Update ms.date to reflect the documentation change
• Run code review to validate changes
• Run CodeQL security check (no code changes to analyze)
• Address PR feedback: Removed redundant TargetName attribute

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Documentation for Maui Shell Flyout has typecast errors in Android when using the default template provided with AppThemeBinding</issue_title>
<issue_description>### Type of issue

Code doesn't work

Description

When using the default template for Flyout Items provided here:
https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/shell/flyout?view=net-maui-8.0#default-template-for-flyoutitems

Specifically this code below:

<Label.TextColor>
                <OnPlatform x:TypeArguments="Color">
                    <OnPlatform.Platforms>
                        <On Platform="Android"
                            Value="{AppThemeBinding Light=Black, Dark=White}" />
                    </OnPlatform.Platforms>
                </OnPlatform>
            </Label.TextColor>

The App will crash on Android with API 31 and higher (tested on API 31, 32, and 33). I haven't tested in prior versions. It seems there are issues with Maui, Shell, and the Flyout navigation menu and the docs aren't helping because I can't get a Flyout menu to stabile work with the set documentation provided in this page.

I have also raised an issue with the background color not working on the Maui board which when used with this documentation code the bug worse:
dotnet/maui#19141

Also in iOS there is an issue with the header code provided that it causes the first link in iOS in the Flyout menu to to not work:
dotnet/maui#17965

Page URL

https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/shell/flyout?view=net-maui-8.0#default-template-for-flyoutitems

Content source URL

https://github.com/dotnet/docs-maui/blob/main/docs/fundamentals/shell/flyout.md

Document Version Independent Id

05d3c8f0-3066-5129-e6cd-3c3d05fcbb59

Article author

@davidbritch

Metadata

• ID: 05d3c8f0-3066-5129-e6cd-3c3d05fcbb59
• Product: dotnet-mobile
• Technology: dotnet-maui</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Documentation for Maui Shell Flyout has typecast errors in Android when using the default template provided with AppThemeBinding #1928

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/fundamentals/shell/flyout.md	docs/fundamentals/shell/flyout

[learn-build-service-prod]

Learn Build status updates of commit 40f5c00:

✅ Validation status: passed

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 312808b:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/fundamentals/shell/flyout.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[jfversluis]

@copilot VisualStateManager is on the Grid(FlyoutItemLayout) itself, specifying TargetName="FlyoutItemLayout" is redundant and you're targeting the same element that already owns the VSM. So, remove this changes.

[Copilot]

@copilot VisualStateManager is on the Grid(FlyoutItemLayout) itself, specifying TargetName="FlyoutItemLayout" is redundant and you're targeting the same element that already owns the VSM. So, remove ...

Removed the redundant TargetName attribute in commit 19b9cda. The VisualStateManager is already on the Grid element itself, so targeting it explicitly was unnecessary.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 19b9cda:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/fundamentals/shell/flyout.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 2a81687:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/fundamentals/shell/flyout.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.