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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
SKILL.md
View on GitHub---
name: android-compose-patterns
description: "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
```kotlin
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
```kotlin
// 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
| 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.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
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |