Skip to content

po4yka/RIPDPI / .agents/skills/android-compose-patterns

android-compose-patterns

Verified

RIPDPI's own Compose conventions: ViewModel pattern, Route/Screen split, DataStore->StateFlow, RipDpiThemeTokens. Use for how this app does Compose, not generic Compose API questions (see compose).

Android Compose Patterns

Overview

RIPDPI uses Jetpack Compose with Material 3 and a sealed-class navigation system. State flows from DataStore through ViewModels to Composables via StateFlow + collectAsStateWithLifecycle().

Diagnostics UI is a current hotspot in this repo. It layers internal UI models over shared diagnostics contracts, exposes stable automation tags through RipDpiTestTags, and routes callback-style actions such as opening Advanced Settings or candidate-detail sheets through screen-level parameters.

Data Flow

DataStore (proto) -> ViewModel (StateFlow + combine) -> Composable (collectAsStateWithLifecycle)
User action -> ViewModel method -> DataStore.updateData { } or ServiceManager.start/stop
One-shot effects -> Channel<Effect> -> receiveAsFlow() -> LaunchedEffect collector

Navigation

Routes are defined as a sealed class in app/.../ui/navigation/Route.kt.

Adding a New Screen

  1. Add a @Serializable data object (or data class) to the Route sealed class with stableRoute, @StringRes titleRes, and an optional icon. Routes are type-safe; there are no route strings.
  2. If top-level: add it to Route.topLevel. Add it to Route.all and to stableRouteMatchers in RipDpiNavHost.kt.
  3. Register composable<Route.YourRoute> { ... }. RipDpiNavHost.kt is at the 1,000-line arch-health limit: put the route in a feature graph file such as ImportNavigation.kt or HistoryNavigation.kt in ui/navigation/.
  4. Navigate with the object: navController.navigate(Route.YourRoute) { launchSingleTop = true }.
  5. Update the two expectation maps in RipDpiNavHostLogicTest and the route list in scripts/guide/specs/ui-ux-audit.yaml; both have coverage tests.

Navigation Conventions

  • Use launchSingleTop = true for every navigation; add restoreState = true (with saveState on popUpTo) only for top-level tab switches
  • Bottom bar shows only for isTopLevelDestination() routes
  • Pass ViewModels to route composables, not raw state

ViewModel Pattern

class ExampleViewModel(application: Application) : AndroidViewModel(application) {
    // State: combine multiple sources into single UI state
    val uiState: StateFlow<UiState> = combine(
        application.settingsStore.data,
        _localState,
    ) { settings, local -> UiState(/*...*/) }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), UiState())

    // Effects: one-shot events (navigation, snackbar, permission requests)
    private val _effects = Channel<Effect>(Channel.BUFFERED)
    val effects = _effects.receiveAsFlow()

    // Actions: public methods called by Composables
    fun onAction() { viewModelScope.launch { /* ... */ } }
}

Key Conventions

  • SharingStarted.WhileSubscribed(5_000) for all StateFlow exports
  • AndroidViewModel (not plain ViewModel) when DataStore access needed
  • Mutex for thread-safe state transitions (see MainViewModel.toggleService)
  • Channel<Effect> for one-shot UI events, collected via LaunchedEffect

Composable Pattern

// Route composable: connects ViewModel to screen
@Composable
fun ExampleRoute(viewModel: ExampleViewModel, navController: NavController) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    ExampleScreen(uiState = uiState, onAction = viewModel::onAction)
}

// Screen composable: pure UI, no ViewModel reference
@Composable
fun ExampleScreen(uiState: UiState, onAction: () -> Unit) { /* ... */ }

Conventions

  • Split Route (stateful) from Screen (stateless) composables
  • Use collectAsStateWithLifecycle() (not collectAsState())
  • Pass callbacks, not ViewModel references, to Screen composables
  • Use RipDpiThemeTokens for colors, spacing, typography. RipDpiTheme owns color selection: generated Material 3 seed schemes per contrast level, or the system dynamic scheme when the opt-in setting is on. Do not select or build a ColorScheme anywhere else.

Representative ViewModels

ViewModelLocationPurpose
MainViewModelactivities/MainViewModel.ktConnection state, VPN/proxy toggle, metrics
ConnectionViewModelui/screens/connection/ConnectionViewModel.ktProxy config presets, draft editing, validation
SettingsViewModelui/screens/settings/SettingsViewModel.ktApp settings, theme, DataStore persistence
DiagnosticsViewModelui/screens/diagnostics/state/DiagnosticsViewModel.ktDiagnostics scan orchestration, history, export/share state, and strategy-probe presentation

Diagnostics UI Conventions

  • Keep diagnostics projection logic in the activities/DiagnosticsUi* support files instead of recomputing report metadata directly in composables.
  • Strategy-probe screens now have specialized presentation states such as candidate-aware progress, audit assessment, winners-first layout, and workflow restriction remediation.
  • Prefer stable automation tags from app/src/main/kotlin/com/poyka/ripdpi/ui/testing/RipDpiTestTags.kt for any new externally exercised UI.
  • Route navigation callbacks such as onOpenAdvancedSettings, onSelectCandidate, and sheet-dismiss actions through Route/Screen parameters rather than letting deep child composables navigate directly.

Common Mistakes

MistakeFix
Using collectAsState()Use collectAsStateWithLifecycle() for lifecycle awareness
Passing ViewModel to Screen composablePass uiState and callbacks; keep Screen stateless
Hardcoding colors/spacingUse RipDpiThemeTokens and Material 3 theme
Missing WhileSubscribed(5_000)Required for proper lifecycle handling in all StateFlow exports
Creating ViewModel in ComposableUse viewModel() in Route composable or pass from NavHost

Related Skills

  • compose (.agents/skills/compose/SKILL.md): General Jetpack Compose API reference (guidance docs plus a live-fetch index into the actual androidx source) and the scored RIPDPI Compose quality audit. Use for questions about how Compose APIs work internally, correct API usage patterns, recomposition mechanics, Modifier ordering, side-effects, performance, or accessibility.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall