Accessibility APIs & Semantics

Copy code// ImageView: always set contentDescription
imageView.contentDescription = "Profile photo of ${user.name}"

// For decorative images (no information), mark as unimportant
decorativeImageView.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO

// Custom click action description
button.accessibilityDelegate = object : View.AccessibilityDelegate() {
    override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {
        super.onInitializeAccessibilityNodeInfo(host, info)
        info.addAction(AccessibilityNodeInfo.AccessibilityAction(
            AccessibilityNodeInfo.ACTION_CLICK,
            "Submit order"  // instead of generic "double tap to activate"
        ))
    }
}

Copy code// Content description for images
Image(
    painter = painterResource(R.drawable.logo),
    contentDescription = "Company logo"  // null for decorative images
)

// Custom semantic properties
Box(
    modifier = Modifier.semantics {
        contentDescription = "Shopping cart, 3 items"
        role = Role.Button
        onClick(label = "Open cart") { navigateToCart(); true }
    }
)

// Merge children semantics (accessibility sees the whole card, not individual elements)
Card(
    modifier = Modifier.semantics(mergeDescendants = true) {}
) {
    Row {
        Image(/* product thumbnail */)
        Column {
            Text(product.name)
            Text(product.price.format())
        }
    }
}
// TalkBack reads: "Product name, $29.99" as a single item

Copy code// Custom Modifier
fun Modifier.minimumTouchTarget(minSize: Dp = 48.dp): Modifier = this.then(
    Modifier.layout { measurable, constraints ->
        val minPx = minSize.roundToPx()
        val placeable = measurable.measure(constraints)
        val width = maxOf(placeable.width, minPx)
        val height = maxOf(placeable.height, minPx)
        layout(width, height) {
            val offsetX = (width - placeable.width) / 2
            val offsetY = (height - placeable.height) / 2
            placeable.placeRelative(offsetX, offsetY)
        }
    }
)

// For small icons, use padding instead
IconButton(
    onClick = { /* */ },
    modifier = Modifier.size(48.dp)  // minimum touch target
) {
    Icon(Icons.Default.Close, contentDescription = "Close dialog")
}

Copy code// Announce changes to screen reader users without focus moving
statusText.accessibilityLiveRegion = View.ACCESSIBILITY_LIVE_REGION_POLITE

// In Compose
Text(
    text = statusMessage,
    modifier = Modifier.semantics {
        liveRegion = LiveRegionMode.Polite  // announces when text changes
    }
)

// Example: announce upload progress
if (uploadProgress == 100) {
    Text(
        "Upload complete",
        modifier = Modifier.semantics { liveRegion = LiveRegionMode.Polite }
    )
}

Copy code@Composable
fun ArticleScreen(article: Article) {
    Column {
        Text(
            article.title,
            style = MaterialTheme.typography.headlineLarge,
            modifier = Modifier.semantics { heading() }  // marks as heading for TalkBack navigation
        )

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

        Text(article.authorName)

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

        Text(article.body)
    }
}

Copy code// Let TalkBack users swipe to delete without needing precise touch control
LazyColumn {
    items(messages) { message ->
        MessageRow(
            message = message,
            modifier = Modifier.semantics {
                customActions = listOf(
                    CustomAccessibilityAction("Delete message") {
                        deleteMessage(message.id)
                        true
                    },
                    CustomAccessibilityAction("Mark as read") {
                        markRead(message.id)
                        true
                    }
                )
            }
        )
    }
}

Copy code// Compose UI test
@Test
fun `all images have content descriptions`() {
    composeTestRule.setContent { FeedScreen(posts = testPosts) }

    // Find nodes without content descriptions (should be none for informational images)
    composeTestRule.onAllNodes(hasNoSemantics())
        .fetchSemanticsNodes()
        .filter { node -> node.config.contains(SemanticsProperties.Role) }
        .forEach { node ->
            fail("Node ${node.id} has no content description")
        }
}