po4yka/RIPDPI / .agents/skills/android-compose-patterns
android-compose-patterns
VerifiedRIPDPI'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
- Add a
@Serializable data object(or data class) to theRoutesealed class withstableRoute,@StringRes titleRes, and an optionalicon. Routes are type-safe; there are no route strings. - If top-level: add it to
Route.topLevel. Add it toRoute.alland tostableRouteMatchersinRipDpiNavHost.kt. - Register
composable<Route.YourRoute> { ... }.RipDpiNavHost.ktis at the 1,000-line arch-health limit: put the route in a feature graph file such asImportNavigation.ktorHistoryNavigation.ktinui/navigation/. - Navigate with the object:
navController.navigate(Route.YourRoute) { launchSingleTop = true }. - Update the two expectation maps in
RipDpiNavHostLogicTestand the route list inscripts/guide/specs/ui-ux-audit.yaml; both have coverage tests.
Navigation Conventions
- Use
launchSingleTop = truefor every navigation; addrestoreState = true(withsaveStateonpopUpTo) 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 exportsAndroidViewModel(not plainViewModel) when DataStore access neededMutexfor thread-safe state transitions (seeMainViewModel.toggleService)Channel<Effect>for one-shot UI events, collected viaLaunchedEffect
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()(notcollectAsState()) - Pass callbacks, not ViewModel references, to Screen composables
- Use
RipDpiThemeTokensfor colors, spacing, typography.RipDpiThemeowns 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 aColorSchemeanywhere else.
Representative ViewModels
| ViewModel | Location | Purpose |
|---|---|---|
MainViewModel | activities/MainViewModel.kt | Connection state, VPN/proxy toggle, metrics |
ConnectionViewModel | ui/screens/connection/ConnectionViewModel.kt | Proxy config presets, draft editing, validation |
SettingsViewModel | ui/screens/settings/SettingsViewModel.kt | App settings, theme, DataStore persistence |
DiagnosticsViewModel | ui/screens/diagnostics/state/DiagnosticsViewModel.kt | Diagnostics 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.ktfor any new externally exercised UI. - Route navigation callbacks such as
onOpenAdvancedSettings,onSelectCandidate, and sheet-dismiss actions throughRoute/Screenparameters rather than letting deep child composables navigate directly.
Common Mistakes
| Mistake | Fix |
|---|---|
Using collectAsState() | Use collectAsStateWithLifecycle() for lifecycle awareness |
| Passing ViewModel to Screen composable | Pass uiState and callbacks; keep Screen stateless |
| Hardcoding colors/spacing | Use RipDpiThemeTokens and Material 3 theme |
Missing WhileSubscribed(5_000) | Required for proper lifecycle handling in all StateFlow exports |
| Creating ViewModel in Composable | Use 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |