[A11y] Fix VoiceOver does not announce project description when navigating project cards

[KarthikRajaKalaimani]

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!

Issue Details

The voice-over does not announce the project description when the focus moves to the border element within the item template of the CollectionView on the Mac platform.

Root Cause

SemanticProperties.Description was bound only to the project Name on the parent Border. Because the card is exposed as one accessible/selectable element, VoiceOver does not announce the child labels separately

Description of Change

Combined both Name and Description values into the Border semantic description.

Issues Fixed

Fixes #37142

Tested the behavior in the following platforms.

• Android
• Windows
• iOS
• Mac

Before	After
Before_37142.mov	After_37142.mov

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 37385

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 37385"

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[dotnet-policy-service]

Hey there @@KarthikRajaKalaimani! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Updates the MAUI mobile template project list item semantics so VoiceOver can announce both the project name and its description when navigating project cards (particularly on macOS).

Changes:

• Reworked the Border accessibility description in the Project CollectionView item template to include both Name and Description via a MultiBinding.

[MauiBot]

Expert Review — 3 findings

See inline comments for details.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[moderate] Architectural Layer Placement / Accessibility — Project already exposes AccessibilityDescription (Models/Project.cs:21, $"{Name} Project. {Description}") and Pages/Controls/ProjectCardView.xaml:10 binds SemanticProperties.Description="{Binding AccessibilityDescription}". This inline MultiBinding introduces a second, different announcement string for the same model: the card view announces "Widget Project. Some description" while the list row now announces "Widget, Some description". Concrete effect: the same project is read differently by the screen reader depending on which screen the user is on, and the accessibility text format now lives in two places, so a future edit to AccessibilityDescription silently skips this list row. Binding {Binding AccessibilityDescription} here keeps one source of truth and matches the existing consumer.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[moderate] XAML & Bindings — The enclosing DataTemplate declares x:DataType="models:Project", but the child <Binding Path="Name"/> / <Binding Path="Description"/> elements inside a MultiBinding are added to MultiBinding.Bindings rather than set on a BindableProperty, so XamlC does not compile them (no MultiBinding handling exists in src/Controls/src/Build.Tasks/src/Controls/src/SourceGen). Concrete effect: these two paths resolve by runtime reflection — a rename of Project.Name/Project.Description produces no build-time XC binding diagnostic (unlike the previous {Binding Name, ...} markup-extension form on this same property, which was compiled) and the paths are trim/AOT-unfriendly. Since this file is the shipped reference template, the previous compiled single binding, or {Binding AccessibilityDescription}, keeps compiled-binding coverage.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[minor] Logic and Correctness — Project.Description defaults to string.Empty (Models/Project.cs:9) and is user-editable in this template, so for a project saved without a description the fixed StringFormat="{}{0}, {1}" announces "Widget, " — a dangling separator read by the screen reader. A converter (or AccessibilityDescription, which can guard the empty case in one place) avoids the trailing comma.

[MauiBot]

AI Review Summary

@KarthikRajaKalaimani — new AI review results are available based on commit 33005ab.

---

🗂️ Review Sessions — click to expand

🚦 Gate — Test Before & After Fix

Gate Result: ⚠️ SKIPPED

No tests were detected in this PR.

Recommendation: Add tests to verify the fix using the write-tests-agent.

---

📋 Pre-Flight — Context & Validation

Issue: #37142 - VoiceOver does not announce project description when navigating project cards
PR: #37385 - [A11y] Fix VoiceOver does not announce project description when navigating project cards
Platforms Affected: MacCatalyst/macOS (reported); Android is the requested validation platform
Files Changed: 1 implementation, 0 test

Key Findings

• ProjectListPage.xaml exposes each selectable Border as one accessible element, but the base implementation binds SemanticProperties.Description only to Project.Name.
• The PR replaces that binding with a MultiBinding that formats Name and Description as "{0}, {1}".
• Models/Project.cs already defines the canonical AccessibilityDescription as "{Name} Project. {Description}", and Pages/Controls/ProjectCardView.xaml already binds to it. Reusing it is a distinct, smaller candidate that avoids duplicate and inconsistent formatting.
• Copilot's inline PR review raised the same canonical-property concern. No other human review feedback or edge cases were present.
• The gate was already skipped because the PR adds no tests. Do not rerun the gate or modify gate/content.md.
• No behavioral accessibility automation exists for this template path. The narrow existing regression target is the SimpleTemplateTest.Build sample-content/Debug case; if local template-workload prerequisites block it, record the blocker rather than widening to a full suite.

Code Review Summary

Verdict: SKIPPED
Confidence: N/A
Errors: 0 | Warnings: 0 | Suggestions: 1

The separate expert-review pass is intentionally deferred to STEP 5b. STEP 5a permits only each try-fix invocation's inline expert self-review.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #37385	Compose Name and Description with an inline XAML MultiBinding	Gate skipped	src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml	Duplicates the model's canonical accessibility text

---

🔬 Code Review — Deep Analysis

Expert Evaluation — PR #37385

Independent Assessment

What this changes: The submitted fix replaces the project row's compiled Name binding with an inline MultiBinding that supplies Name and Description to SemanticProperties.Description.

Assessment: The change fixes the reported omission, and the XAML is valid. However, it duplicates the model's existing AccessibilityDescription contract, produces narration that differs from ProjectCardView, and moves the child binding paths out of compiled-binding coverage.

Findings

Severity	Location	Finding
Moderate	ProjectListPage.xaml:37	The new format duplicates and diverges from Project.AccessibilityDescription, already used by ProjectCardView.
Moderate	ProjectListPage.xaml:38	Child bindings in this MultiBinding resolve at runtime rather than retaining the prior compiled-binding coverage.
Minor	ProjectListPage.xaml:39	An empty description produces a trailing separator ("Name, ").

The raw file:line comments are recorded in inline-findings.json.

Blast Radius and Failure Modes

• The change is confined to generated sample-content project rows and does not affect handlers, startup, static state, or lifecycle subscriptions.
• Null/default values do not throw, but the default empty Description exposes the trailing-separator case.
• Recycled CollectionView items receive updated binding values, but the inline format remains inconsistent with the same model's card presentation.
• No external-tool output is classified, so there is no external output contract to trace.

Validation and Evidence

The trusted Gate was skipped because the PR adds no tests. GitHub required-check status could not be retrieved because gh is unauthenticated, so CI coverage remains undetermined.

Verdict: NEEDS_DISCUSSION

Confidence: low for merge safety because no relevant test or required-check evidence is available; high that the implementation findings apply.

Recommended refinement: Bind SemanticProperties.Description directly to the existing AccessibilityDescription property. This preserves the fix while restoring one source of truth and compiled-binding coverage.

---

🛠️ Try-Fix — Analysis & Comparison

Try-Fix Candidates

Candidate 1 — Canonical Model Accessibility Description

Model: claude-opus-5

Approach: Replace the PR's presentation-layer MultiBinding with one compiled binding to the existing Project.AccessibilityDescription property. This reuses the canonical "{Name} Project. {Description}" text already consumed by ProjectCardView.xaml, avoids duplicated formatting, and differs from the PR's strategy of composing two fields in the view.

Files changed: src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml

Result: BLOCKED

Test: pwsh .github/skills/run-integration-tests/scripts/Run-IntegrationTests.ps1 -TestFilter 'FullyQualifiedName=Microsoft.Maui.IntegrationTests.SimpleTemplateTest.Build&DisplayName~--sample-content&DisplayName~Debug' -SkipBuild -SkipInstall

The runner stopped before executing the test because .dotnet/packs/Microsoft.Maui.Sdk is absent. Provisioning or widening the build was outside this bounded phase, so no retest was attempted and no Pass was claimed. EstablishBrokenBaseline.ps1 also rejected the repository-wide dirty state; the attempt preserved the 40 unrelated changes, invoked restore, and returned the target XAML to its exact pre-attempt content.

Self-review: 1 minor finding: the accessibility behavior lacks a regression test. No critical, major, or moderate findings.

Candidate diff:

diff --git a/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml b/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml
--- a/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml
+++ b/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml
@@
-                    <Border 
-                        Background="{AppThemeBinding Light={StaticResource LightSecondaryBackground},Dark={StaticResource DarkSecondaryBackground}}">
-                        <SemanticProperties.Description>
-                            <MultiBinding StringFormat="{}{0}, {1}">
-                                <Binding Path="Name" />
-                                <Binding Path="Description" />
-                            </MultiBinding>
-                        </SemanticProperties.Description>
+                    <Border
+                        Background="{AppThemeBinding Light={StaticResource LightSecondaryBackground},Dark={StaticResource DarkSecondaryBackground}}"
+                        SemanticProperties.Description="{Binding AccessibilityDescription}">

Detailed artifacts: ../try-fix-1/content.md and attempt-1/

Candidate 2 — Separate Accessible Name and Hint

Model: gpt-5.6-sol

Approach: Keep Project.Name in SemanticProperties.Description and bind
Project.Description to SemanticProperties.Hint, using separate accessible identity and
supplementary-help channels rather than concatenating text or using the model's canonical
accessibility property.

Files changed: src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml

Result: BLOCKED

Test: pwsh .github/skills/run-integration-tests/scripts/Run-IntegrationTests.ps1 -TestFilter 'FullyQualifiedName=Microsoft.Maui.IntegrationTests.SimpleTemplateTest.Build&DisplayName~--sample-content&DisplayName~Debug' -SkipBuild -SkipInstall

After one focused shell-quoting correction, the runner stopped before test discovery because
.dotnet/packs/Microsoft.Maui.Sdk is absent. No third invocation or other test was run.
Independent self-review also rejected the strategy for the Android scope: MAUI does not expose a
semantic hint on a non-editable Border equivalently to Apple's AccessibilityHint, so TalkBack
can still omit the project description.

Self-review: 2 findings (1 moderate cross-platform limitation, 1 minor missing behavioral
regression test).

Candidate diff:

diff --git a/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml b/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml
--- a/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml
+++ b/src/Templates/src/templates/maui-mobile/Pages/ProjectListPage.xaml
@@
-                    <Border 
-                        Background="{AppThemeBinding Light={StaticResource LightSecondaryBackground},Dark={StaticResource DarkSecondaryBackground}}">
-                        <SemanticProperties.Description>
-                            <MultiBinding StringFormat="{}{0}, {1}">
-                                <Binding Path="Name" />
-                                <Binding Path="Description" />
-                            </MultiBinding>
-                        </SemanticProperties.Description>
+                    <Border 
+                        Background="{AppThemeBinding Light={StaticResource LightSecondaryBackground},Dark={StaticResource DarkSecondaryBackground}}"
+                        SemanticProperties.Description="{Binding Name}"
+                        SemanticProperties.Hint="{Binding Description}">

Detailed artifacts: ../try-fix-2/content.md and attempt-2/

---

📝 PR Finalize — Recommended Title & Description

Assessment: ✏️ Recommend updating — the current title lacks the MacCatalyst platform and ProjectListPage component, while the description can identify the submitted MultiBinding implementation more precisely.

Recommended title

[MacCatalyst] ProjectListPage: Include project descriptions in card accessibility text

Recommended description

### Issue Details

VoiceOver does not announce the project description when focus moves to the `Border` element within the `CollectionView` item template on MacCatalyst.

### Root Cause

`SemanticProperties.Description` on the parent `Border` was bound only to `Project.Name`. Because the card is exposed as one accessible and selectable element, VoiceOver does not announce the child labels separately.

### Description of Change

Updated the `Border` in `ProjectListPage.xaml` to use a `MultiBinding` that combines `Project.Name` and `Project.Description` in `SemanticProperties.Description`, allowing VoiceOver to announce both values when navigating project cards.

### Issues Fixed

Fixes #37142

**Tested the behavior on the following platforms:**
- [x] Android
- [x] Windows
- [x] iOS
- [x] Mac

| Before | After |
|---|---|
| <video src="https://github.com/user-attachments/assets/20884ac2-7f4c-4907-8d97-02326a093be2" Width="600" Height="400"/> | <video src="https://github.com/user-attachments/assets/c0f63c4e-4e12-4af4-976d-439970db7a67" Width="600" Height="400"/> |

---

🏁 Report — Final Recommendation

⚠️ Final Recommendation: REQUEST CHANGES

Winning Candidate: pr-plus-reviewer

pr-plus-reviewer is the strongest candidate because it fixes the announcement gap through the existing Project.AccessibilityDescription contract. It keeps project narration consistent with ProjectCardView, restores compiled-binding coverage, and is simpler than the submitted per-item MultiBinding.

Comparative Ranking

Rank	Candidate	Approach	Validation	Assessment
1	pr-plus-reviewer	Bind the row directly to AccessibilityDescription	Blocked before discovery: candidate-local .dotnet/dotnet is absent	Winner. Incorporates the expert review's two moderate improvements in the required isolated sandbox.
2	try-fix-1	Bind the row directly to AccessibilityDescription	Blocked before execution: Microsoft.Maui.Sdk pack is absent	Functionally tied with the winner, but superseded by the consolidated reviewer candidate and its directly applicable reviewer.patch.
3	pr	Compose Name and Description with an inline MultiBinding	Gate skipped; no tests detected	Fixes the reported omission, but duplicates canonical narration, loses compiled-binding coverage, and emits a dangling comma for an empty description.
4	try-fix-2	Put Name in Description and project details in Hint	Blocked before execution: SDK pack is absent	Rejected independently of the blocker: a hint on a non-editable Border is not reliably announced on Android, the requested test platform.

No candidate passed or failed a regression test: every available validation path was skipped or blocked before test execution. Therefore, the mandatory pass-over-fail ranking rule does not distinguish these candidates, and no test-pass claim is made.

Expert Review

The single expert pass found the submitted XAML functionally valid but reported:

1. A moderate consistency/ownership issue because Project.AccessibilityDescription already defines the canonical announcement and is used by ProjectCardView.
2. A moderate XAML binding issue because the child bindings in the submitted MultiBinding do not retain the prior compiled-binding coverage.
3. A minor empty-description formatting issue.

The winner resolves the two moderate findings and removes the dangling comma, though the existing canonical model string may still end with punctuation and whitespace when the description is empty. The raw inline findings are in inline-findings.json.

Risk and Required Change

The product diff is localized to generated sample-content XAML and introduces no handler, lifecycle, startup, or shared-state risk. Runtime screen-reader behavior is still unverified, and the trusted Gate was skipped because the PR contains no tests.

Apply pr-plus-reviewer/reviewer.patch to the submitted PR. Because the winning code is not present in the submitted PR HEAD, the recommendation is REQUEST CHANGES.

---

🧭 Next Steps — reviewer patch required (pr-plus-reviewer)

The reviewer-enhanced candidate won, so the submitted PR still needs those changes.

Why: The reviewer-refined candidate reuses Project.AccessibilityDescription, preserving the fix while keeping narration consistent with ProjectCardView and retaining compiled-binding coverage. Its focused validation was blocked by the candidate sandbox's missing local .NET SDK, so no test-pass claim is made.

Apply PRAgent/pr-plus-reviewer/reviewer.patch from the CopilotLogs
artifact (or follow the report's Required submitted-PR change), push the update, and run
the review again.