Ha Android UI

HA Android UI

Use this skill when creating or changing screens, ViewModels, navigation, or widgets.

The screen pattern is documented in depth at https://developers.home-assistant.io/docs/android/ui_architecture.

Compose Only

• All new UI uses Jetpack Compose; no new XML, databinding, or viewbinding. Legacy XML screens are migrated over time.
• All new widgets use Jetpack Glance; legacy RemoteViews widgets must not be extended.

Design System

• Use io.homeassistant.companion.android.common.compose.theme.HATheme and the HA* components (HAButton, HAText, HATextField, HACheckbox, HALoading, HADropdownMenu, HAModalBottomSheet, ...) instead of Material components directly. Apply the theme in setContent, not inside the screen composable.
• Never mix Material 2 and Material 3 in a screen; use HATextStyle for typography, HADimens.SPACE* tokens for spacing and sizes — no magic numbers for padding.
• Access colors via LocalHAColorScheme.current with the tokens from HAColorScheme; never hardcode colors. Raw Material 3 elements get the wrong light/dark colors — if an HA* wrapper is missing, create it first (own PR, added to the Compose catalog with screenshots) instead of styling a Material component inline.
• Use Snackbars for errors and transient feedback, not Toasts.
• All displayed strings live in the value files in :common, English only, accessed with stringResource(R.string.*) — never hardcode displayed text. Only edit common/src/main/res/values/strings.xml: translations come from Lokalise and the translated values-*/strings.xml files are gitignored — never add or edit them.

Screen Structure

Name composables descriptively after the UI component (SettingsScreen.kt, UserCard.kt). Split every screen into a stateful entry point and a stateless content composable, hoisting state:

@Composable
internal fun SettingsScreen(viewModel: SettingsViewModel) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    SettingsScreenContent(uiState = state, onToggleSetting = viewModel::onToggleSetting)
}

@Composable
internal fun SettingsScreenContent(uiState: SettingsUiState, onToggleSetting: (String) -> Unit) {
    // Stateless: renders uiState and reports interactions through callbacks.
}

Recurring review feedback on screen composables:

• Keep composables small: split large screens into small private composables (see recent screens like AssistSettingsScreen), and move a composable to its own file when the file grows too big.
• Pass child composables only the parameters they need, never the whole ViewState.
• No logic in the UI layer: no filtering, sorting, or mapping collections inside a composable — the ViewState carries display-ready data (for example a prebuilt HADropdownItem list). remember any value that must be computed in composition so it doesn't rebuild on every recomposition.
• Name the stateless layer *Screen/*Content; *View is legacy.
• Set the semantic Role on custom clickable rows (e.g. Modifier.clickable(role = Role.Checkbox)) for accessibility.
• Disable/gate action buttons on input validity via the ViewState, and surface errors to the user (snackbar or state), with validation living in the ViewModel.
• Don't seed local UI state once from a value that can still change (LaunchedEffect(Unit) reading a flow-backed field) — derive it from the current state so it stays in sync.

Add a @Preview for major composables using HAThemeForPreview:

@Preview
@Composable
private fun SettingsScreenPreview() {
    HAThemeForPreview {
        SettingsScreenContent(uiState = SettingsUiState.Default, onToggleSetting = {})
    }
}