Small teams rarely decide to skip accessibility. It slips through gaps. An icon button gets added without a label. A custom card reads out as five separate pieces. A settings screen looks fine until someone turns on the largest text size. None of these take long to fix, but they are easy to miss because the developer building the screen usually isn't using a screen reader or large text.

This post covers the issues that most often get through review in SwiftUI and Jetpack Compose, with fixes for both platforms and a short routine for catching them before release.

1. Icon-only buttons with no label

This is the most common miss. A button made from an SF Symbol or a Material icon looks obvious on screen. A screen reader may announce it as nothing useful, or by its symbol name, which is not the same as what it does.

SwiftUI

Button {
    toggleFavorite()
} label: {
    Image(systemName: isFavorite ? "heart.fill" : "heart")
}
.accessibilityLabel(isFavorite ? "Remove from favorites" : "Add to favorites")

A better option is to use a Label with .labelStyle(.iconOnly). You get the visual you wanted, and the text is still there for VoiceOver.

Compose

IconButton(onClick = { toggleFavorite() }) {
    Icon(
        imageVector = if (isFavorite) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder,
        contentDescription = if (isFavorite) "Remove from favorites" else "Add to favorites"
    )
}

In Compose, contentDescription is a required parameter on Icon and Image, so people tend to pass null just to make the compiler happy. That's the right choice for purely decorative images and the wrong one for anything you can tap. When you see contentDescription = null in code review, ask whether the element can be interacted with.

2. Decorative content that gets announced anyway

The reverse problem is quieter. Background images, separators and icons sitting next to text that already says the same thing all add noise. A row with a calendar icon next to "Tuesday, 3 PM" doesn't need the word "calendar" read first.

  • SwiftUI: use Image(decorative: "name") for asset images, or .accessibilityHidden(true) on the view.
  • Compose: pass contentDescription = null for decorative images, and only for those.

3. Cards that read as fragments

A list row with a title, a subtitle, a timestamp and a badge is one thing visually. By default, a screen reader may treat it as four separate stops. That means four swipes per row, with no context between them.

SwiftUI

HStack {
    VStack(alignment: .leading) {
        Text(item.title)
        Text(item.subtitle).font(.caption)
    }
    Spacer()
    Text(item.relativeDate)
}
.accessibilityElement(children: .combine)

Compose

Row(
    modifier = Modifier
        .clickable { open(item) }
        .semantics(mergeDescendants = true) {}
) {
    Column {
        Text(item.title)
        Text(item.subtitle, style = MaterialTheme.typography.bodySmall)
    }
    Spacer(Modifier.weight(1f))
    Text(item.relativeDate)
}

If a row is clickable, Compose already merges its descendants. The explicit semantics block matters most for rows that aren't clickable. If the merged reading comes out awkward, you can replace it entirely: .accessibilityLabel(...) after combining in SwiftUI, or Modifier.clearAndSetSemantics { contentDescription = "..." } in Compose. Be careful with the second one. It also removes semantics from child elements, including any nested buttons.

4. Rows with more than one action

Once you merge a row, any secondary actions inside it, like a delete button or a share icon, become hard to reach. Expose them as custom actions instead, so screen reader users can get to them from the row itself.

// SwiftUI
.accessibilityAction(named: "Delete") { delete(item) }

// Compose
Modifier.semantics {
    customActions = listOf(
        CustomAccessibilityAction("Delete") { delete(item); true }
    )
}

The same applies to swipe-to-delete. Swipe gestures are not reliably available to people using assistive technology, so the action needs a second route.

5. Headings nobody declared

Screen reader users often move through a screen by heading. If your section titles are just bold text, that navigation does nothing. Marking them takes one line:

// SwiftUI
Text("Upcoming").font(.headline)
    .accessibilityAddTraits(.isHeader)

// Compose
Text("Upcoming", style = MaterialTheme.typography.titleMedium,
    modifier = Modifier.semantics { heading() })

6. Layouts that break at large text sizes

Using system text styles in SwiftUI or sp units in Compose gets you scaling text. It doesn't get you a layout that survives it. Typical failures:

  • Text truncated with an ellipsis inside a fixed-height container.
  • An HStack or Row with a label and a value that collide or wrap one character per line.
  • Icons that stay small while the text next to them grows several times larger.
  • Bottom buttons pushed off screen with no way to scroll to them.

Here are some fixes that work on both platforms:

  • Avoid fixed heights on anything that contains text. Use minimum heights instead.
  • Switch from horizontal to vertical layout at large sizes. In SwiftUI, ViewThatFits or a check on @Environment(\.dynamicTypeSize) with .isAccessibilitySize works well. In Compose, FlowRow often handles this without branching.
  • Scale related icon sizes with the text. In SwiftUI, use @ScaledMetric var iconSize: CGFloat = 24. In Compose, derive the size from LocalDensity.current.fontScale if you need it.
  • Put long forms and onboarding screens inside a scroll container, even if they fit at the default size.

To check this quickly, use the Xcode previews variant feature or .environment(\.dynamicTypeSize, .accessibility3) on iOS. On Android, use @Preview(fontScale = 2f). Keep a large-text preview next to the default one for every screen you build, and you will see breakage while you work rather than after release.

7. Touch targets that are too small

Apple's Human Interface Guidelines recommend touch targets of at least 44 by 44 points. Material recommends 48 by 48 dp. Small close buttons, inline links and compact toolbars often fall short.

  • In Compose, Material 3 components apply minimumInteractiveComponentSize() by default. Custom clickable elements don't, so add it yourself.
  • In SwiftUI, add padding and then .contentShape(Rectangle()) so the padded area is tappable, not just the glyph.

8. State communicated only by color

A red border on an invalid field, or a green dot for "online", tells a sighted user something that a color-blind user or a screen reader user may never get. Pair color with text or an icon, and expose the state:

// SwiftUI
TextField("Email", text: $email)
    .accessibilityValue(emailError ?? "")

// Compose
OutlinedTextField(
    value = email, onValueChange = { email = it },
    isError = emailError != null,
    supportingText = { emailError?.let { Text(it) } }
)

For toggles and selectable chips, make sure the selected state is announced. Standard Toggle and Switch do this. A custom view styled to look like a toggle does not, unless you add .accessibilityAddTraits(.isSelected) or Modifier.toggleable(...) / Modifier.selectable(...).

9. Motion and contrast settings ignored

If your app has large animations, parallax or auto-playing transitions, check the system's reduce-motion setting. In SwiftUI, that's @Environment(\.accessibilityReduceMotion). On Android, you can read the animator duration scale from system settings, and if it's zero, treat that as the user opting out. For contrast, test your palette in both light and dark mode with a contrast checker. Don't trust your eyes on a bright monitor.

A testing routine that fits a small team

You don't need a dedicated QA pass. You need a fixed routine you actually run. Here's one that works:

  1. Automated audit in UI tests. On iOS, recent Xcode versions provide try app.performAccessibilityAudit() in XCUITest. Add it to one test per major screen. On Android, Espresso's accessibility checks and recent Compose UI test versions can flag missing labels and small targets. Check the documentation for the version you use.
  2. Inspector pass. Use Accessibility Inspector in Xcode, or Google's Accessibility Scanner app on an Android device, on each changed screen.
  3. Five-minute screen reader walk. Turn on VoiceOver or TalkBack and complete the app's main task without looking at the screen. Wherever you get lost is a bug.
  4. Largest text size walk. Set the system text size to maximum and open every screen touched in this release.

Put steps 3 and 4 on your release checklist with the screens they cover. They catch things automated audits cannot, like a reading order that is technically labeled but makes no sense.

Wrapping up

Most of the accessibility problems in a typical indie app come from a short list: unlabeled icons, fragmented rows, undeclared headings, fixed layouts that break with large text, small targets, and state shown only by color. Each fix is a modifier or two. The hard part is noticing, so build that into your routine: large-text previews while you work, an audit call in your UI tests, and a short screen reader walk before each release. Do that consistently and these issues stop reaching your users.