add-screen
Add a Compose Multiplatform feature screen with its route, encoded arguments, NavGraph entry, ViewModel, Koin registration, shared UI conventions, and validation. Use when adding a screen or changing
SKILL.mdagent-skills/add-screen/SKILL.md
GitHubAdd a screen
Route and navigation
Add the route to ui/navigation/Screen.kt. Encode every dynamic path segment with encodeRouteSegment when navigating and decode it through the navigation argument APIs at the destination.
Register the destination in ui/navigation/NavGraph.kt. Follow nearby destinations for transitions, argument declarations, back navigation, deep links, and scanner integration. Do not pass resource snapshots through routes; pass stable identifiers and load through the repository.
ViewModel and dependency injection
Create a ViewModel for any screen that loads or mutates data. Start work in viewModelScope, cancel or supersede stale loads where the existing feature pattern does so, and represent loading through LoadState<T>.
Register the ViewModel with viewModelOf(::X) in di/AppModule.kt. Register new dependencies in the same module. Missing Koin registrations compile and fail at runtime, so verify the complete constructor graph.
Resolve screen-scoped dependencies with koinViewModel() or koinInject(). Obtain AppPreferences through Koin instead of threading it through NavGraph.
Compose structure
- Use
AppTopBarfor a static title andCollapsingAppTopBarfor an entity-name detail title. - Use
PullToRefreshBoxwithloadState.isRefreshingNow; do not translate content withdistanceFraction. - Render initial loading, error, loaded, empty, and refresh states consistently with neighboring screens.
- Use
AppIcon(AppIcons.X),MaterialTheme.shapes,AppElevation, the stock typography ramp, and motion specs fromAppAnimations.kt. - Reuse shared components in
ui/commonbefore adding a local variant. - Use
collectAsStateWithLifecyclefor lifecycle-bound state.
Documentation and tests
- Update
dev/architecture.mdfor new routes, ViewModels, packages, or dependency injection wiring. - Update
dev/style.mdonly when introducing or changing a UI convention. - Update
dev/platform-parity.mdif either platform behaves differently. - Add an
Unreleasedchangelog entry because a new user-facing screen is visible behavior. - Test extracted deterministic logic in
commonTest; do not invent a screen test harness for a single change.
Verify
./scripts/verify-change.sh
./gradlew :composeApp:compileKotlinIosSimulatorArm64