[Windows] Fix Narrator announcing ContentView children twice when Description is set

[praveenkumarkarunanithi]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Root Cause

WinUI TextBlock (used by Label) automatically exposes its Text to UI Automation. ContentPanel uses the default FrameworkElementAutomationPeer, which exposes both the parent’s AutomationProperties.Name and all child elements. Unlike Android (NoHideDescendants) or iOS (AccessibilityElementsHidden), Windows has no single property to hide descendants while keeping the parent accessible. As a result, both Tab navigation and Browse mode announced duplicate content.

Description of Change

Implemented a custom ContentPanelAutomationPeer that overrides three core UI Automation methods (GetAutomationControlTypeCore , GetLocalizedControlTypeCore, GetChildrenCore) to conditionally modify behavior when Description is present.

When a Description exists, the control is exposed as AutomationControlType.Text (enables browse mode navigation; alternatives like Custom announce "custom" suffix, Group causes browse mode to skip the element), the "text" announcement suffix is suppressed via empty GetLocalizedControlTypeCore() return, and child elements are hidden by returning null from GetChildrenCore() to prevent duplication. When no Description is present, default behavior is preserved with AutomationControlType.Custom and children remain accessible.
The HasDescription helper property centralizes the non-empty Description check across all three override methods, ensuring consistent conditional logic following the MAUI `AutomationPeer patterns.

Issues Fixed

Fixes #33373

Platforms Tested

• iOS
• Android
• Windows
• Mac

Screenshots

Before Fix	After Fix
WITHOUTFIX.1.mp4	WITHFIX.1.1.mp4

[Copilot]

Pull request overview

Fixes a Windows Narrator accessibility issue where ContentView content was announced twice when SemanticProperties.Description is set, by customizing the UI Automation peer used by the Windows ContentPanel.

Changes:

• Added a custom AutomationPeer for ContentPanel to alter control type/localized type and hide children when AutomationProperties.Name (Description) is set.
• Updated Windows PublicAPI unshipped list to include the new OnCreateAutomationPeer() override.
• Added Windows device tests validating automation peer behavior with/without Description.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/Core/src/Platform/Windows/ContentPanel.cs	Introduces a custom FrameworkElementAutomationPeer to prevent duplicate Narrator announcements when a Description/Name is present.
src/Core/src/PublicAPI/net-windows/PublicAPI.Unshipped.txt	Records the new protected override as an unshipped Windows API surface change.
src/Controls/tests/DeviceTests/Elements/ContentView/ContentViewTests.Windows.cs	Adds device tests validating control type, localized control type, and child visibility behavior under UIA.

[MauiBot]

🤖 AI Summary

📊 Expand Full Review — a3dd90d · Merge branch 'main' into fix-33373

---

🔍 Pre-Flight — Context & Validation

---

Issue: #33373 - [Windows] SemanticProperties.Description announced twice when set on focusable container cell (Label inside)
PR: #33979 - [Windows] Fix Narrator announcing ContentView children twice when Description is set
Platforms Affected: Windows only
Files Changed: 2 implementation (ContentPanel.cs, PublicAPI.Unshipped.txt), 1 test (ContentViewTests.Windows.cs)

Key Findings

• Root Cause: WinUI TextBlock (used by Label) automatically exposes its Text to UIA. ContentPanel's default FrameworkElementAutomationPeer exposes both the parent's AutomationProperties.Name (set via SemanticProperties.Description) and all child elements, causing Narrator to announce content twice in Tab navigation and Browse mode.
• PR Fix: Added nested ContentPanelAutomationPeer inside ContentPanel.cs that overrides GetChildrenCore(), GetAutomationControlTypeCore(), and GetLocalizedControlTypeCore() to conditionally hide children and expose as AutomationControlType.Text when AutomationProperties.Name is set.
• Gate Result: ❌ FAILED — Both "without fix" and "with fix" builds fail with WindowsAppSDKSelfContained requires a supported Windows architecture in Graphics.csproj. This is a build environment constraint; neither variant could actually run tests.
• Prior Agent Review (2026-03-25): Complete review at SHA 1a425ed; all 4 try-fix attempts were BLOCKED by the same environment issue. Current head is a3dd90d.
• Prior inline review comments (both RESOLVED):
  1. ContentViewTests.Windows.cs: "assert NotEmpty" for no-description case — addressed (Assert.NotEmpty(children) is present).
  2. ContentPanel.cs: Indentation and comment accuracy — addressed (indentation fixed, comment updated to say AutomationProperties.Name is set).
• Remaining concern: ContentPanelAutomationPeer is declared as internal partial class — the partial modifier is unnecessary (not split across files). This is a cosmetic issue.
• Public API: PublicAPI.Unshipped.txt correctly declares override Microsoft.Maui.Platform.ContentPanel.OnCreateAutomationPeer().
• Test helper: GetOrCreateAutomationPeer uses new ContentPanel.ContentPanelAutomationPeer(contentPanel) (direct instantiation), correctly bypassing the WinUI3 CreatePeerForElement() limitation.
• CI pipelines triggered (2026-04-09): maui-pr-uitests and maui-pr-devicetests triggered by team member.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33979	Custom ContentPanelAutomationPeer nested class; hides children and uses AutomationControlType.Text when AutomationProperties.Name is set	❌ FAILED (Gate — build env issue)	ContentPanel.cs, ContentViewTests.Windows.cs, PublicAPI.Unshipped.txt	Gate failure is environment constraint, not code defect

---

🔧 Fix — Analysis & Comparison

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix (claude-opus-4.6)	Set AccessibilityView.Raw on ContentPanel children in UpdateSemantics (ViewExtensions.cs) when description is set	⚠️ BLOCKED	ViewExtensions.cs, ContentViewTests.Windows.cs	Build env: WindowsAppSDKSelfContained architecture error
2	try-fix (claude-sonnet-4.6)	Cached _hasSemanticDescription flag via RegisterPropertyChangedCallback(NameProperty); peer reads field instead of calling GetName()	⚠️ BLOCKED	ContentPanel.cs, PublicAPI.Unshipped.txt	Build env: same architecture error
3	try-fix (gpt-5.3-codex)	MauiPanelAutomationPeer override in MauiPanel base class instead of ContentPanel	⚠️ BLOCKED	MauiPanel.cs, ContentViewTests.Windows.cs	Build env: same architecture error
4	try-fix (gpt-5.4)	Handler-level fix: ContentViewHandler.Windows.cs sets AccessibilityView.Raw on child element when parent has description	⚠️ BLOCKED	ContentViewHandler.Windows.cs, ContentViewTests.Windows.cs	Build env: same architecture error
PR	PR #33979	Custom ContentPanelAutomationPeer nested class; hides children and uses AutomationControlType.Text when name is set	❌ FAILED (Gate — build env)	ContentPanel.cs, ContentViewTests.Windows.cs, PublicAPI.Unshipped.txt	Gate failure is build env issue, not code defect

Cross-Pollination

Model	Round	New Ideas?	Details
claude-opus-4.6	2	NO NEW IDEAS	All 5 approaches cover the two realistic solution categories (custom peer vs. AccessibilityView.Raw). No new variants remain. PR's peer-based approach is the standard WinUI pattern.

Exhausted: Yes — all 4 models queried; cross-pollination complete; no new ideas.
Selected Fix: PR's fix — ContentPanelAutomationPeer approach
Reason: All try-fix alternatives were BLOCKED by the same environment issue. Code analysis confirms the PR's approach is architecturally sound and follows the standard WinUI pattern for this exact problem. No empirically superior alternative could be identified.

---

📋 Report — Final Recommendation

---

⚠️ Final Recommendation: REQUEST CHANGES

Phase Status

Phase	Status	Notes
Pre-Flight	✅ COMPLETE	Windows-only a11y fix; 2 implementation files, 1 test file, 1 public API entry
Gate	❌ FAILED	Windows — both "without fix" and "with fix" failed with WindowsAppSDKSelfContained requires a supported Windows architecture (build env)
Try-Fix	✅ COMPLETE	4 attempts, 0 passing (all BLOCKED by same build env issue); cross-pollination exhausted
Report	✅ COMPLETE

Summary

PR #33979 addresses a real Windows accessibility bug (#33373) where ContentView with SemanticProperties.Description causes Narrator to announce content twice. The fix is architecturally sound and the prior inline review comments have been addressed. However, the Gate ❌ FAILED — both "without fix" and "with fix" builds failed with WindowsAppSDKSelfContained requires a supported Windows architecture in Graphics.csproj. All 4 try-fix attempts encountered the same environment blocker, and cross-pollination found no new ideas.

The Gate failure is a build environment constraint, not a code logic defect. The CI agent running this review lacks a supported Windows architecture for WinAppSDK self-contained deployment. CI pipelines (maui-pr-devicetests) were triggered by a team member on 2026-04-09 and should validate the fix on a proper Windows build agent.

Root Cause (of the Bug)

WinUI TextBlock (used by Label) automatically exposes its Text to UIA. ContentPanel's default FrameworkElementAutomationPeer exposes both AutomationProperties.Name (set via SemanticProperties.Description) and all child elements. Windows has no single built-in API like Android's NoHideDescendants to suppress children while keeping the parent accessible, so both Tab navigation and Browse mode announce duplicate content.

Fix Quality

Implementation (ContentPanel.cs): ✅ Sound

• GetChildrenCore() → null when description is set (prevents duplicate UIA tree traversal)
• GetAutomationControlTypeCore() → Text (enables Browse mode navigation without "group"/"custom" suffixes)
• GetLocalizedControlTypeCore() → "" (suppresses "text" announcement suffix)
• HasDescription cleanly centralizes the non-empty name check
• Follows the existing MauiButtonAutomationPeer pattern in MAUI
• Prior inline review comments (indentation, comment accuracy) are resolved

Tests (ContentViewTests.Windows.cs): ✅ Correct

• GetOrCreateAutomationPeer uses direct new ContentPanel.ContentPanelAutomationPeer(contentPanel) instantiation, correctly bypassing WinUI3 CreatePeerForElement() limitation
• Assert.Null(children) is correct for WinUI3 (null GetChildrenCore() → null GetChildren())
• Assert.NotEmpty(children) for the no-description case validates children remain visible
• [Category(TestCategory.ContentView)] inherited from class-level attribute in ContentViewTests.cs
• Prior inline review comment ("assert NotEmpty") is resolved

Public API (PublicAPI.Unshipped.txt): ✅ Correct

• override Microsoft.Maui.Platform.ContentPanel.OnCreateAutomationPeer() properly declared

Minor issue (cosmetic):

• ContentPanelAutomationPeer is declared as internal partial class — the partial modifier is unnecessary since the class is not split across files. Should be internal class ContentPanelAutomationPeer.

Selected Fix: PR's fix

All try-fix alternatives were BLOCKED by the same environment issue. Code analysis confirms the PR's ContentPanelAutomationPeer approach is the best available solution for the WinUI platform constraints.

Required Action

The PR author should confirm the tests pass on a proper Windows x64 CI environment (maui-pr-devicetests was triggered 2026-04-09). If CI passes, the only remaining change is cosmetic:

1. Remove partial from ContentPanelAutomationPeer declaration:

   - internal partial class ContentPanelAutomationPeer : FrameworkElementAutomationPeer
   + internal class ContentPanelAutomationPeer : FrameworkElementAutomationPeer

---

[praveenkumarkarunanithi]

Looks like the test is failing - could you please verify?

The test has now been updated and verified. It is working as expected.

[sheiksyedm]

/azp run maui-pr-uitests , maui-pr-devicetests

[azure-pipelines]

Azure Pipelines successfully started running 2 pipeline(s).

[kubaflo]

Code Review — PR #33979

Independent Assessment

What this changes: Adds a custom ContentPanelAutomationPeer to ContentPanel (Windows) that conditionally hides child automation peers and changes the control type to Text when AutomationProperties.Name (mapped from SemanticProperties.Description) is set. When no description is set, default behavior is preserved. Also adds two Windows device tests.

Inferred motivation: When a ContentView with SemanticProperties.Description contains a Label, Windows Narrator announces the description twice — once for the ContentView and once for the child Label's text. This is because WinUI's default FrameworkElementAutomationPeer exposes both the parent's Name and all children's text.

Reconciliation with PR Narrative

Agreement: My independent assessment matches the PR description. The root cause analysis is correct — WinUI has no equivalent to Android's ImportantForAccessibility.NoHideDescendants or iOS's AccessibilityElementsHidden. The custom automation peer is the right Windows-specific approach.

Findings

⚠️ Warning — ContentPanel is shared across multiple handlers

ContentPanel is the Windows platform view for ContentViewHandler, BorderHandler, ScrollViewHandler (internal padding shim), and RefreshViewHandler. The custom OnCreateAutomationPeer applies to ALL instances.

Risk assessment: Low. The HasDescription check (AutomationProperties.GetName(Owner)) means behavior only changes when Description is explicitly set on the ContentPanel. For ScrollView/RefreshView internal panels, Description is never set on the inner panel — it's set on the outer control. For Border with Description, hiding children is actually the correct behavior (same duplicate-announcement problem applies).

Recommendation: Consider adding a brief code comment noting that this automation peer affects all ContentPanel usages (not just ContentView) and explaining why that's safe.

⚠️ Warning — No test verifies OnCreateAutomationPeer() integration

The tests create ContentPanelAutomationPeer directly via constructor rather than going through OnCreateAutomationPeer() / FrameworkElementAutomationPeer.CreatePeerForElement(). This tests the peer's behavior correctly but doesn't verify that OnCreateAutomationPeer is wired up. A simple assertion like Assert.IsType<ContentPanel.ContentPanelAutomationPeer>(FrameworkElementAutomationPeer.CreatePeerForElement(contentPanel)) would close that gap.

💡 Suggestion — Unnecessary partial keyword

ContentPanelAutomationPeer is declared as internal partial class but has no other partial definition. The partial keyword is unnecessary. Minor cleanup.

💡 Suggestion — Unnecessary await Task.CompletedTask

Both test methods end with await Task.CompletedTask; which does nothing. Either remove it (making the lambda non-async) or use await Task.Yield(); if async is intentional. This is cosmetic.

✅ Correct — Follows existing automation peer patterns

The approach matches MauiButtonAutomationPeer which also returns null from GetChildrenCore(). The conditional behavior based on HasDescription is a clean extension of this pattern.

✅ Correct — Dynamic description changes handled properly

If SemanticProperties.Description is set then cleared at runtime, HasDescription will return false and children become visible again. GetAutomationControlTypeCore / GetChildrenCore are evaluated on-demand by the UI Automation framework, so dynamic changes work without needing InvalidatePeer.

✅ Correct — PublicAPI entry

Only OnCreateAutomationPeer override needs a public API entry (the inner class is internal). The entry is present and correctly formatted.

✅ Correct — GetLocalizedControlTypeCore returns empty string

When HasDescription is true, returning string.Empty prevents Narrator from appending "text" after the description. When false, it falls back to the base implementation with a ?? string.Empty null guard. Clean.

CI Status

• maui-pr: ✅ All stages pass
• maui-pr-devicetests: ❌ Failures are infrastructure-level ("PowerShell exited with code '1'"), no Helix jobs found — not caused by this PR
• maui-pr-uitests: ❌ Separate pipeline — needs investigation but unlikely related to a Windows-only accessibility change

Devil's Advocate

1. Could hiding children break Tab navigation? When HasDescription is set, GetAutomationControlTypeCore returns Text which is a leaf type — Tab navigation skips into children. This is intentional: the parent's description is the canonical announcement. Without description, Custom type preserves normal Tab-into-children behavior.
2. Could this affect Appium tests that find elements inside ContentView? Appium uses the automation tree. If a ContentView has Description set, its children won't appear in the automation tree. This could cause FindElement failures in existing UI tests. However, this only triggers when SemanticProperties.Description is explicitly set, which is uncommon in test pages.
3. What about nested ContentViews with Description? If both outer and inner ContentView have Description, the inner one's children are hidden independently. The outer one's children (including the inner ContentView itself) are also hidden. The innermost Description wins for Narrator — which is the correct ARIA-like behavior.

Verdict: LGTM with minor suggestions

Confidence: high
Summary: Well-designed accessibility fix following existing MAUI patterns. The conditional HasDescription approach ensures zero behavioral change when Description is not set, making this safe for all ContentPanel consumers. The two suggestions (verify OnCreateAutomationPeer wiring in tests, remove partial keyword) are non-blocking.