1. SwiftUI: .accessibilityLabel() replaces the visible text

Button("Pay") { pay() }
    .accessibilityLabel("Submit")

On screen the button says "Pay". Its accessibility label is "Submit", and when we dumped every attribute XCUITest exposes for that button, "Pay" appeared nowhere. Someone using voice control who says "Tap Pay" may not reach it, and a screen reader user hears a different word from the one sighted colleagues refer to. This is the case WCAG 2.5.3 Label in Name (Level A) was written for: the accessible name should contain the visible text.

In our UIKit sample the visible title stayed in the tree next to the label; in SwiftUI only the label did (iOS 26.5 Simulator). Keep the visible word in the label, and put extra context in a hint:

Button("Pay") { pay() }
    .accessibilityHint("Pays the parking ticket")

2. SF Symbols can come with a name, but maybe not the right one

An image button using UIImage(systemName: "magnifyingglass") with no label set came out with the accessible name "Search" in our tests (an iOS 26.5 Simulator and an iPhone on iOS 27). We saw this for that one symbol only. It's a generic name for the symbol, not for what your button does. If the button opens a filter or searches something specific, say so:

searchButton.accessibilityLabel = "Search tickets"

On Android, an ImageButton or a Compose Icon button without a description gets no default name from the platform:

IconButton(onClick = onSearch) {
    Icon(Icons.Default.Search, contentDescription = "Search tickets")
}

3. UIKit text doesn't follow the text size setting unless you ask it to

SwiftUI text styles scale with Dynamic Type automatically. UIKit labels need two things, a text-style font and adjustsFontForContentSizeCategory, or they don't update when the text size setting changes. On our two small sample screens, Apple's accessibility audit flagged 3 elements with unsupported Dynamic Type in the UIKit version and 1 in the SwiftUI version. One of the UIKit ones was a text field whose font had simply never been set.

label.font = UIFont.preferredFont(forTextStyle: .body)
label.adjustsFontForContentSizeCategory = true

// Custom font that still scales:
label.font = UIFontMetrics(forTextStyle: .body)
    .scaledFont(for: UIFont(name: "Avenir-Medium", size: 17)!)
label.adjustsFontForContentSizeCategory = true

Both versions need adjustsFontForContentSizeCategory = true.

In SwiftUI, .custom(_:size:) already scales with the body style; add relativeTo: to scale with a different style. Only .custom(_:fixedSize:) stays fixed, so watch for that one.

Text("Payment history").font(.custom("Avenir-Medium", size: 17, relativeTo: .headline))

4. Compose: a button made of several texts is read as all of them

A clickable Compose element merges its children for TalkBack and reads them in order. In our sample, a button built from two Texts ("Pay" and "$25.00") was announced as "Pay, $, 25.00, Button": TalkBack read the amount in two parts. And when one child had a description that didn't match its visible text ("Pay" described as "Submit", followed by "now"), TalkBack said "Submit, now, Button" while the screen showed "Pay now". (Android 16 emulator with TalkBack 16.0.0, and a Pixel 4a on Android 13 with TalkBack 17.0.1.)

If the parts don't read well together, give the whole button one name that contains the visible words:

Button(
    onClick = onPay,
    modifier = Modifier.semantics { contentDescription = "Pay $25.00" }
) {
    Row(Modifier.clearAndSetSemantics { }) {
        Text("Pay")
        Text("$25.00")
    }
}

clearAndSetSemantics clears everything after it in the modifier chain, so put it on the content, not on the Button's own modifier, or the button loses its click action.

5. Hard-coded backgrounds with system-styled controls

In our UIKit sample the screen's background was hard-coded white, while a standard system-styled button (UIButton.Configuration.gray()) kept following the appearance setting. In dark appearance its title measured about 1.48:1 against the light gray behind it, well under the 4.5:1 WCAG 1.4.3 (Contrast (Minimum), AA) asks for normal-size text. In light appearance there was no issue (iOS Simulator). The likely cause: system-styled parts change with the appearance, the hard-coded background doesn't.

Don't mix a hard-coded background with system-styled controls. Use semantic colours throughout:

view.backgroundColor = .systemBackground
label.textColor = .label

The same mismatch is possible on Android when android:windowBackground is fixed but text colours come from a DayNight theme. Check every screen in both light and dark mode.

6. Android: the same screen got a pane title on Android 13 but not on Android 16

TalkBack can announce a pane title when content changes. The same Views screen in our sample had a pane title on an Android 13 Pixel and none on the Android 16 emulator; we didn't find out why. (A pane title is separate from the window or activity title, which TalkBack can also announce.) So don't rely on it happening by itself. Give each activity a meaningful title, and set a pane title explicitly for fragments or panes that change within one window:

ViewCompat.setAccessibilityPaneTitle(paneView, "Payment history")

// Compose
Column(Modifier.semantics { paneTitle = "Payment history" }) { /* ... */ }

Then turn TalkBack on and listen when you move between screens.

7. android:labelFor works for TalkBack, but not every tool sees it

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Ticket number"
    android:labelFor="@id/ticket" />
<EditText
    android:id="@+id/ticket"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

TalkBack reads this field as "Edit box for Ticket number" (Android 16 emulator, TalkBack 16.0.0). But some testing tools build on uiautomator dump, whose output has no attribute for that link, so they may report the field as unlabelled. If a scanner flags a field you labelled with labelFor, check it with TalkBack before changing anything. A TextInputLayout hint is another way to name the field:

<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="Ticket number">
    <com.google.android.material.textfield.TextInputEditText
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
</com.google.android.material.textfield.TextInputLayout>

How to check your own app

• Turn on TalkBack or VoiceOver and swipe through each screen. Does every control have a name that matches what's on screen? Do screens announce a title?
• Turn the text size up to the largest setting while the app is open. Does the text grow? Is anything cut off or out of reach? (Before Android 14 the Settings maximum is usually below 200%; adb shell settings put system font_scale 2.0 tests 200%, and 1.0 sets it back. From Android 14, large text grows non-linearly, so big headings grow less than body text by design.)
• Switch between light and dark mode and look at contrast again.
• Try voice control (Voice Access or Voice Control): can you activate buttons by saying what you see?

Automated checks catch only some accessibility problems. Testing with the screen readers yourself, and with people who use them, is still what counts.

I found these while testing small native sample apps for accessibility. If you've hit other platform quirks like these, I'd like to hear about them in the comments.

This article was created with the help of AI. The findings come from tests I ran with AI tooling on Android emulators, iOS Simulators and real phones (a Pixel 4a and an iPhone SE), on small sample apps.

1. AutomationId is not a name

AutomationId becomes the Android resource id and the iOS accessibilityIdentifier. It's meant for UI tests, not as a name for people. A control that only has an AutomationId has no accessible name, and screen readers handle that unpredictably: in my tests on Android, TalkBack read one such image button aloud as "btnCancelPayment", its raw id. Neither silence nor a developer id tells anyone what the button does.

<!-- No accessible name -->
<ImageButton Source="cancel.png" AutomationId="btnCancelPayment" />

<!-- A name for people, AutomationId kept for UI tests -->
<ImageButton Source="cancel.png"
             AutomationId="btnCancelPayment"
             SemanticProperties.Description="Cancel payment" />

And don't copy the id into the description either: "btnCancelPayment" read aloud is not a name.

Update: this applies to buttons and images. For text fields, don't use SemanticProperties.Description: Microsoft's docs say it stops TalkBack actions working on an Entry or Editor on Android. Use a visible Label plus Placeholder instead (on Android, SemanticProperties.Hint on an Entry also works). Thanks to Mehdi Mohseni in the comments for pointing this out.

2. Headings are almost never set

Screen reader users jump between headings to find their way around a page. In MAUI nothing is a heading unless you say so:

<Label Text="Payment history" SemanticProperties.HeadingLevel="Level1" />

3. Page.Title isn't an Android pane title

On Android, Page.Title shows in the toolbar, but MAUI doesn't set the accessibility pane title from it, so the page has no pane title for screen readers. Android also has a separate window title that TalkBack can announce, so whether people actually hear a title when the page changes varies. Turn TalkBack on and listen when you navigate to a new page.

4. Changing the font size on Android can send the user back to the first page

In an app built from the default template, MainActivity doesn't list FontScale in its ConfigurationChanges. When the user changes the system font size, Android recreates the activity, and the template's App.CreateWindow builds a new AppShell. The app comes back on its first page, and whatever the user was doing is gone. (Not every app loses its place; it depends on how the app restores its state.)

Adding ConfigChanges.FontScale avoids the restart, but then the text keeps its old size until the app is relaunched, unless your app re-applies its fonts itself. So it isn't a fix on its own. Test this on your most important flows: change the font size halfway through and see where you land.

5. On iOS, text may not resize until the app restarts

Before Microsoft.Maui.Controls 10.0.100, MAUI apps on iOS didn't update text while running after the system text size changed, only after the app was terminated and relaunched. It was fixed in 10.0.100 (dotnet/maui#34445).

The catch: when I created a project with dotnet new maui on SDK 10.0.300, it resolved Microsoft.Maui.Controls 10.0.20, which is before the fix. The template's package reference uses $(MauiVersion), so set it explicitly, to 10.0.100 or later:

<PropertyGroup>
  <MauiVersion>10.0.100</MauiVersion>
</PropertyGroup>

Then change the text size in Settings while your app is open and check it grows. (In my tests, Shell tab bar titles on iOS didn't grow with the text size even on the fixed version.)

6. Large text can push controls off the screen

At normal size a page fits. With the font scale at 200% on a small phone, the controls at the bottom get pushed below the edge. If the page has no ScrollView, there may be no way to reach them. I saw this on a Pixel 4a (Android 13, font scale set to 2.0 over adb, since Android 13's own setting stops at 130%): the bottom buttons were cut off, swiping did nothing, and they were missing from the accessibility tree altogether.

Wrap long pages in a ScrollView, and test large text on your smallest supported device, not just the emulator.

7. Check the template's text colours

In the template styles of the MAUI version I tested, a page title came out light grey on white, around 1.7:1 contrast. WCAG 2.2's 1.4.3 Contrast (Minimum) asks for at least 4.5:1 for normal text and 3:1 for large text, so it falls short either way. Because it comes from the template, it's worth checking in your own app's styles.

8. Test both themes

Microsoft's WeatherTwentyOne sample app is a good example of why. When I scanned its first screen in dark mode, automated contrast checks found nothing. In light mode, on both an Android emulator and a Pixel 4a, the same screen had five text elements measured below WCAG 1.4.3's contrast minimum (around 2.1:1 to 2.2:1, under even the 3:1 large-text minimum). Same app, same screen, opposite results. If your app follows the system theme, check both.

How to check your own app

None of these need special tools:

• Turn on TalkBack (Android) or VoiceOver (iOS) and swipe through each screen. Does every control have a sensible name? Do pages announce a title? Can you reach everything?

• Set the system text size to the largest setting while the app is open. Does the text grow? Do you stay on the same page? Is anything cut off or unreachable? Before Android 14 the largest Settings option is usually below the 200% WCAG 1.4.4 refers to (130% on our Pixel 4a); you can test 200% with adb shell settings put system font_scale 2.0 (and set it back with 1.0). On iOS, turn on Larger Accessibility Sizes.

• Switch between light and dark mode and look at the contrast again.

• Rotate the device.

Automated checks catch only some accessibility problems. Testing with the screen readers yourself, and with people who use them, is still what counts.

I found these while testing MAUI apps for accessibility. If you've run into other MAUI accessibility quirks, I'd like to hear about them in the comments.

This article was created with the help of AI. The findings come from my own tests on Android emulators, iOS Simulators and real phones (a Pixel 4a and an iPhone SE).