android-presentation-mvi
MVI presentation layer for Android/KMP - State, Action, Event, ViewModel, Root/Screen composable split, UI models, UiText error mapping, and process death with SavedStateHandle. Use this skill whenever creating or reviewing a ViewModel, defining screen state, actions, or events, structuring composables, mapping errors to UI strings, or handling process death. Trigger on phrases like "add a ViewModel", "create a screen", "MVI", "state", "action", "event", "screen composable", "UiText", "SavedStateHandle", "ObserveAsEvents", or "UI model".
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.4k
- Forks
- 82
01 前言 Front Matter
- name
- android-presentation-mvi
- description
- MVI presentation layer for Android/KMP - State, Action, Event, ViewModel, Root/Screen composable split, UI models, UiText error mapping, and process death with SavedStateHandle. Use this skill whenever creating or reviewing a ViewModel, defining screen state, actions, or events, structuring composables, mapping errors to UI strings, or handling process death. Trigger on phrases like "add a ViewModel", "create a screen", "MVI", "state", "action", "event", "screen composable", "UiText", "SavedStateHandle", "ObserveAsEvents", or "UI model".
03 SKILL.md 正文
Android / KMP Presentation Layer (MVI)
Overview
Every screen has:
- State — a single data class holding all UI state fields.
- Action (Intent) — a sealed interface of all user-triggered actions.
- Event — a sealed interface of one-time side effects (navigation, snackbar).
- ViewModel — holds
StateFlow<State>, processesAction, emitsEventviaChannel.
State
data class NoteListState(
val notes: List<NoteUi> = emptyList(),
val isLoading: Boolean = false,
val error: UiText? = null
)
Always update state with .update { } — never replace the entire flow:
_state.update { it.copy(isLoading = true) }
Action (Intent)
sealed interface NoteListAction {
data object OnRefreshClick : NoteListAction
data class OnNoteClick(val noteId: String) : NoteListAction
data class OnDeleteNote(val noteId: String) : NoteListAction
}
Event (one-time side effects)
sealed interface NoteListEvent {
data class NavigateToDetail(val noteId: String) : NoteListEvent
data class ShowSnackbar(val message: UiText) : NoteListEvent
}
ViewModel
class NoteListViewModel(
private val noteRepository: NoteRepository
) : ViewModel() {
private val _state = MutableStateFlow(NoteListState())
val state = _state.asStateFlow()
private val _events = Channel<NoteListEvent>()
val events = _events.receiveAsFlow()
fun onAction(action: NoteListAction) {
when (action) {
is NoteListAction.OnRefreshClick -> loadNotes()
is NoteListAction.OnNoteClick -> {
viewModelScope.launch {
_events.send(NoteListEvent.NavigateToDetail(action.noteId))
}
}
}
}
private fun loadNotes() {
viewModelScope.launch {
_state.update { it.copy(isLoading = true) }
noteRepository.getNotes()
.onSuccess { notes ->
_state.update { it.copy(notes = notes.map { it.toNoteUi() }, isLoading = false) }
}
.onFailure { error ->
_state.update { it.copy(isLoading = false) }
_events.send(NoteListEvent.ShowSnackbar(error.toUiText()))
}
}
}
}
Coroutine Dispatchers
Do not inject unless the class is unit-tested and dispatches to a non-main dispatcher. For ViewModel tests, use Dispatchers.setMain(UnconfinedTestDispatcher()) in test setup.
For blocking code that doesn't support suspension, wrap it:
suspend fun compressImage(bytes: ByteArray): ByteArray = withContext(Dispatchers.IO) {
// blocking compression logic
}
Only inject CoroutineDispatcher when:
- The class dispatches to a non-main dispatcher (e.g.,
IO), AND - That class is directly unit-tested.
Mapping Errors to UI Strings
UiText (core:presentation) wraps strings that originate from — or could originate from — a string resource:
sealed interface UiText {
data class DynamicString(val value: String) : UiText
class StringResource(val id: Int, val args: Array<Any> = emptyArray()) : UiText
}
When to use UiText: For any string that comes from a string resource, could be localized, or might be either a resource or a dynamic value depending on context (e.g., error messages that map to R.string.*).
When to use plain String: For values that are always dynamic and never come from resources — e.g., a user's name, a formatted date, a currency amount. These should be exposed as String directly in the state or UI model.
// UiText — error message that maps to a string resource
data class NoteListState(
val error: UiText? = null
)
// Plain String — always dynamic, never a resource
data class NoteUi(
val authorName: String,
val formattedDate: String
)
Define DataError.toUiText() extension functions in core:presentation (or feature presentation) that map error enums to UiText.StringResource.
UI Model (Presentation Model)
When a domain model needs UI-specific formatting (dates, units, currency), create a dedicated UI model in the presentation layer:
data class NoteUi(
val id: String,
val title: String,
val formattedDate: String // e.g. "Mar 15, 2026"
)
fun Note.toNoteUi(): NoteUi = NoteUi(
id = id,
title = title,
formattedDate = date.format(...)
)
UI models are always suffixed with Ui (e.g., NoteUi, TodoItemUi).
Composable Structure
Both the Root and Screen composable live in the same file (e.g., NoteListScreen.kt).
Root Composable (suffixed Root)
Receives the ViewModel (via koinViewModel()) and any callbacks needed for navigation. Observes events. Passes state and onAction down.
Screen Composable (suffixed Screen)
Receives only state and onAction. No ViewModel reference. Can be previewed independently.
// NoteListScreen.kt — Root + Screen in a single file
@Composable
fun NoteListRoot(
onNavigateToDetail: (String) -> Unit,
viewModel: NoteListViewModel = koinViewModel()
) {
val state by viewModel.state.collectAsStateWithLifecycle()
ObserveAsEvents(viewModel.events) { event ->
when (event) {
is NoteListEvent.NavigateToDetail -> onNavigateToDetail(event.noteId)
is NoteListEvent.ShowSnackbar -> { /* show snackbar */ }
}
}
NoteListScreen(
state = state,
onAction = viewModel::onAction
)
}
@Composable
fun NoteListScreen(
state: NoteListState,
onAction: (NoteListAction) -> Unit
) { ... }
@Preview
@Composable
private fun NoteListScreenPreview() {
NoteListScreen(state = NoteListState(), onAction = {})
}
Process Death
When a screen involves complex forms or critical user input, restore essential fields using SavedStateHandle:
class NoteEditorViewModel(
private val savedStateHandle: SavedStateHandle,
private val noteRepository: NoteRepository
) : ViewModel() {
private val _state = MutableStateFlow(
NoteEditorState(
title = savedStateHandle["title"] ?: "",
body = savedStateHandle["body"] ?: ""
)
)
fun onAction(action: NoteEditorAction) {
when (action) {
is NoteEditorAction.OnTitleChange -> {
savedStateHandle["title"] = action.title
_state.update { it.copy(title = action.title) }
}
}
}
}
Only save what truly matters after process death — not the entire state.
Naming Conventions
| Thing | Convention | Example |
|---|---|---|
| ViewModel | <Screen>ViewModel |
NoteListViewModel |
| State | <Screen>State |
NoteListState |
| Action | <Screen>Action |
NoteListAction |
| Event | <Screen>Event |
NoteListEvent |
| Root composable | <Screen>Root |
NoteListRoot |
| Screen composable | <Screen>Screen |
NoteListScreen |
| UI model | <Model>Ui |
NoteUi, TodoItemUi |
Checklist: Adding a New Screen
- [ ] Define
State,Action,Eventinfeature:presentation - [ ] Implement
ViewModelinfeature:presentation - [ ] Create
<Screen>Rootcomposable (holds ViewModel, observes events) - [ ] Create
<Screen>Screencomposable (pure state + onAction, previewable) - [ ] Map any domain errors to
UiTextvia extension functions - [ ] Add
SavedStateHandlefor any form fields that must survive process death
04 同仓库更多 Skills
review-animations
Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.
prototype
Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.
pick-ui-library
Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.
improve-animations
Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.
grilling
Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
grill-with-docs
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.