Accessibility in Jetpack Compose: Building Apps Everyone Can Use

// The description says what the control does in its current state.
// IconButton already supplies the button role and click action.
@Composable
fun FavoriteButton(
    isFavorite: Boolean,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
) {
    IconButton(onClick = onClick, modifier = modifier) {
        Icon(
            imageVector = if (isFavorite)
                Icons.Filled.Favorite
            else Icons.Outlined.FavoriteBorder,
            contentDescription = if (isFavorite)
                stringResource(R.string.remove_from_favorites)
            else stringResource(R.string.add_to_favorites),
        )
    }
}

// Decorative image: null means "no semantic meaning"
@Composable
fun DecorativeWave(modifier: Modifier = Modifier) {
    Image(
        painter = painterResource(R.drawable.wave_bg),
        contentDescription = null,
        modifier = modifier,
    )
}

// A subtree that should not be reachable at all
Box(Modifier.semantics { hideFromAccessibility() }) {
    /* purely visual duplicate of content announced elsewhere */
}

// A 24dp icon made clickable. Compose expands the touch area
// beyond the bounds, but the layout still only reserves 24dp,
// so neighbours can sit inside the expanded area.
@Composable
fun SmallCloseButton(onClick: () -> Unit) {
    Icon(
        Icons.Default.Close,
        contentDescription = stringResource(R.string.close),
        modifier = Modifier
            .size(24.dp)
            .clickable(onClick = onClick),
    )
}

// Custom control: reserve 48dp in layout, keep the 24dp visual
@Composable
fun CloseChip(onClick: () -> Unit) {
    Box(
        contentAlignment = Alignment.Center,
        modifier = Modifier
            .minimumInteractiveComponentSize()
            .clickable(
                onClickLabel = stringResource(R.string.close),
                role = Role.Button,
                onClick = onClick,
            ),
    ) {
        Icon(
            Icons.Default.Close,
            contentDescription = null, // the clickable carries the label
            modifier = Modifier.size(24.dp),
        )
    }
}

// Where a Material control fits, use it and describe the icon
@Composable
fun AccessibleCloseButton(onClick: () -> Unit) {
    IconButton(onClick = onClick) {
        Icon(
            Icons.Default.Close,
            contentDescription = stringResource(R.string.close),
        )
    }
}

@Composable
fun ProfileScreen(user: User) {
    LazyColumn {
        item {
            Text(
                text = stringResource(R.string.profile),
                style = MaterialTheme.typography.headlineMedium,
                modifier = Modifier
                    .padding(16.dp)
                    .semantics { heading() },
            )
        }

        item { SectionHeading(stringResource(R.string.personal_information)) }
        item { ProfileField(stringResource(R.string.name), user.name) }
        item { ProfileField(stringResource(R.string.email), user.email) }

        item { SectionHeading(stringResource(R.string.preferences)) }
        item {
            SwitchPreference(
                label = stringResource(R.string.dark_mode),
                checked = user.darkMode,
                onCheckedChange = { /* toggle */ },
            )
        }
    }
}

@Composable
private fun SectionHeading(text: String) {
    Text(
        text = text,
        style = MaterialTheme.typography.titleMedium,
        modifier = Modifier
            .padding(horizontal = 16.dp, vertical = 8.dp)
            .semantics { heading() },
    )
}

@Composable
fun LoginForm(onSubmit: (String, String) -> Unit) {
    var email by remember { mutableStateOf("") }
    var password by remember { mutableStateOf("") }
    var error by remember { mutableStateOf<String?>(null) }

    val passwordFocus = remember { FocusRequester() }

    Column(modifier = Modifier.padding(16.dp)) {
        // Announced when it appears, without interrupting speech
        error?.let { message ->
            Text(
                text = message,
                color = MaterialTheme.colorScheme.error,
                modifier = Modifier.semantics {
                    liveRegion = LiveRegionMode.Polite
                },
            )
        }

        OutlinedTextField(
            value = email,
            onValueChange = { email = it },
            label = { Text(stringResource(R.string.email)) },
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
            keyboardActions = KeyboardActions(
                onNext = { passwordFocus.requestFocus() },
            ),
        )

        OutlinedTextField(
            value = password,
            onValueChange = { password = it },
            label = { Text(stringResource(R.string.password)) },
            visualTransformation = PasswordVisualTransformation(),
            modifier = Modifier.focusRequester(passwordFocus),
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
            keyboardActions = KeyboardActions(
                onDone = { onSubmit(email, password) },
            ),
        )

        Button(
            onClick = { onSubmit(email, password) },
            modifier = Modifier.fillMaxWidth(),
        ) {
            Text(stringResource(R.string.sign_in))
        }
    }
}

// build.gradle.kts
// androidTestImplementation("androidx.compose.ui:ui-test-junit4-accessibility")

@RunWith(AndroidJUnit4::class)
class AccessibilityTest {

    @get:Rule
    val composeTestRule = createAndroidComposeRule<ComponentActivity>()

    @Test
    fun homeScreen_passesAccessibilityChecks() {
        composeTestRule.setContent {
            MyAppTheme { HomeScreen() }
        }

        composeTestRule.enableAccessibilityChecks()

        // Any action runs the checks. This one runs them on the root.
        composeTestRule.onRoot().tryPerformAccessibilityChecks()
    }

    @Test
    fun sectionTitles_areHeadings() {
        composeTestRule.setContent {
            MyAppTheme { ProfileScreen(testUser) }
        }

        composeTestRule
            .onNodeWithText("Preferences")
            .assert(SemanticsMatcher.keyIsDefined(SemanticsProperties.Heading))
    }
}