android-sdd 1.0.0

package/skills/UI System/Compose Multiplatform/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: compose-multiplatform
+description: >
+  Compose Multiplatform (CMP) setup and patterns for sharing UI across
+  Android, iOS, Desktop, and Web. Load this skill when building shared
+  UI with CMP, handling platform-specific UI differences, or deciding
+  what UI code belongs in shared vs platform modules.
+---
+
+# Compose Multiplatform
+
+## Overview
+Compose Multiplatform (CMP) by JetBrains extends Jetpack Compose to share UI code across Android, iOS, Desktop (JVM), and Web (Wasm). It builds on top of KMP for shared logic and adds a shared UI layer. The same composable functions render natively on each platform.
+
+---
+
+## Core Principles
+
+- Share UI that is **truly identical** across platforms — don't force sharing where platforms differ
+- Platform-specific UI (navigation bars, status bars, permissions UI) stays **platform-specific**
+- Use `expect/actual` for platform-specific UI components
+- Use `rememberX()` patterns for platform resources (images, fonts)
+- Test shared UI on **all target platforms** — rendering differences exist
+
+---
+
+## Project Structure
+
+```
+project/
+├── composeApp/
+│   ├── src/
+│   │   ├── commonMain/         ← shared UI + business logic
+│   │   │   └── kotlin/
+│   │   │       ├── App.kt      ← root composable
+│   │   │       ├── screens/
+│   │   │       └── components/
+│   │   ├── androidMain/        ← Android entry point + platform UI
+│   │   │   └── kotlin/
+│   │   │       └── MainActivity.kt
+│   │   ├── iosMain/            ← iOS entry point
+│   │   │   └── kotlin/
+│   │   │       └── MainViewController.kt
+│   │   └── desktopMain/        ← Desktop entry point
+│   │       └── kotlin/
+│   │           └── main.kt
+├── shared/                     ← shared business logic (no UI)
+└── iosApp/                     ← Xcode project
+```
+
+---
+
+## Root Composable (commonMain)
+
+```kotlin
+// commonMain/App.kt
+@Composable
+fun App() {
+    AppTheme {
+        // Shared navigation and screens
+        AppNavHost()
+    }
+}
+```
+
+---
+
+## Platform Entry Points
+
+```kotlin
+// androidMain/MainActivity.kt
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent { App() }
+    }
+}
+
+// iosMain/MainViewController.kt
+fun MainViewController() = ComposeUIViewController { App() }
+
+// desktopMain/main.kt
+fun main() = application {
+    Window(title = "MyApp", onCloseRequest = ::exitApplication) {
+        App()
+    }
+}
+```
+
+---
+
+## Platform-Specific Components
+
+```kotlin
+// ✅ expect/actual for platform-specific UI
+// commonMain
+@Composable
+expect fun PlatformStatusBar()
+
+// androidMain
+@Composable
+actual fun PlatformStatusBar() {
+    // Android-specific status bar handling
+}
+
+// iosMain
+@Composable
+actual fun PlatformStatusBar() {
+    // iOS safe area insets handling
+    Spacer(modifier = Modifier.windowInsetsTopHeight(WindowInsets.safeDrawing))
+}
+
+// desktopMain
+@Composable
+actual fun PlatformStatusBar() {
+    // No status bar on desktop
+}
+```
+
+---
+
+## Resources in CMP
+
+```kotlin
+// ✅ Use compose-resources for shared resources
+// commonMain/composeResources/
+//   drawable/logo.png
+//   font/roboto.ttf
+//   values/strings.xml
+
+// Access in shared composable
+@Composable
+fun Logo() {
+    Image(
+        painter = painterResource(Res.drawable.logo),
+        contentDescription = null
+    )
+}
+
+Text(stringResource(Res.string.app_name))
+```
+
+```toml
+# libs.versions.toml
+[libraries]
+compose-resources = { module = "org.jetbrains.compose.components:components-resources" }
+```
+
+---
+
+## Navigation in CMP
+
+```kotlin
+// ✅ Use Navigation Compose (works in CMP)
+// commonMain
+@Composable
+fun AppNavHost() {
+    val navController = rememberNavController()
+    NavHost(navController, startDestination = HomeRoute) {
+        composable<HomeRoute> {
+            HomeScreen(onNavigate = { navController.navigate(DetailRoute(it)) })
+        }
+        composable<DetailRoute> { DetailScreen() }
+    }
+}
+```
+
+---
+
+## Platform Detection
+
+```kotlin
+// ✅ When platform-specific behavior needed in shared code
+expect fun getPlatformName(): String
+
+// androidMain
+actual fun getPlatformName() = "Android"
+
+// iosMain
+actual fun getPlatformName() = "iOS"
+
+// ✅ Use for conditional UI
+@Composable
+fun PlatformAwareLayout() {
+    if (getPlatformName() == "Android") {
+        AndroidSpecificLayout()
+    } else {
+        DefaultLayout()
+    }
+}
+```
+
+---
+
+## Gradle Setup
+
+```kotlin
+// composeApp/build.gradle.kts
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+    alias(libs.plugins.compose.multiplatform)
+    alias(libs.plugins.android.application)
+}
+
+kotlin {
+    androidTarget()
+    iosX64(); iosArm64(); iosSimulatorArm64()
+    jvm("desktop")
+
+    sourceSets {
+        commonMain.dependencies {
+            implementation(compose.runtime)
+            implementation(compose.foundation)
+            implementation(compose.material3)
+            implementation(compose.ui)
+            implementation(compose.components.resources)
+            implementation(libs.navigation.compose)
+        }
+        androidMain.dependencies {
+            implementation(libs.androidx.activity.compose)
+        }
+        val desktopMain by getting {
+            dependencies {
+                implementation(compose.desktop.currentOs)
+            }
+        }
+    }
+}
+```
+
+---
+
+## What to Share vs Platform-Specific
+
+| UI Element | Share | Platform-Specific |
+|------------|-------|------------------|
+| Business screens (list, form, detail) | ✅ | |
+| Design system components | ✅ | |
+| Navigation structure | ✅ | |
+| Status bar / navigation bar | | ✅ |
+| Permission request UI | | ✅ |
+| Platform pickers (date, file) | | ✅ |
+| App entry point | | ✅ |
+
+---
+
+## Anti-Patterns
+
+- Importing `android.*` in `commonMain` — breaks iOS/Desktop compilation
+- Sharing UI that looks wrong on a platform — prefer platform-specific when UX differs
+- Using Android-specific Compose APIs in shared code (e.g., `LocalContext`) — use expect/actual
+- Not testing on iOS — rendering differences are common
+- Placing platform resources in `commonMain/res/` — use `composeResources/` instead
+
+---
+
+## Related Skills
+- `kmp` — Kotlin Multiplatform shared logic
+- `compose` — Compose fundamentals
+- `compose-navigation` — Navigation in CMP
+- `material3` — Material 3 in CMP

package/skills/UI System/Compose Navigation/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: compose-navigation
+description: >
+  Jetpack Compose Navigation setup, patterns, and best practices.
+  Load this skill when setting up NavHost, defining routes, navigating between
+  screens, passing arguments, handling deep links, or managing the back stack
+  in a Compose app.
+---
+
+# Compose Navigation
+
+## Overview
+Jetpack Compose Navigation provides a type-safe way to navigate between composable screens. Navigation is managed by a `NavController` and defined in a `NavHost`. Arguments, deep links, and back stack management are all handled through the navigation graph.
+
+---
+
+## Core Principles
+
+- `NavController` must be created at the **top level** — never inside nested composables
+- Pass `NavController` down **only one level** — deeper screens receive lambdas, not NavController
+- Use **type-safe routes** (Navigation 2.8+) — avoid string-based routes
+- Navigation logic belongs in the **screen-level composable** — not in ViewModel
+- **Never navigate from inside a ViewModel** — emit an event, handle navigation in UI
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+navigation-compose = "2.8.0"
+
+[libraries]
+navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "navigation-compose" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.navigation.compose)
+}
+```
+
+---
+
+## Type-Safe Routes (Navigation 2.8+)
+
+```kotlin
+// ✅ Define routes as serializable objects/data classes
+@Serializable
+object HomeRoute
+
+@Serializable
+object UserListRoute
+
+@Serializable
+data class UserDetailRoute(val userId: String)
+
+@Serializable
+data class EditUserRoute(val userId: String, val isNew: Boolean = false)
+```
+
+---
+
+## NavHost Setup
+
+```kotlin
+// ✅ NavHost at top level — in Activity or root composable
+@Composable
+fun AppNavHost(
+    navController: NavHostController = rememberNavController(),
+    startDestination: Any = HomeRoute
+) {
+    NavHost(
+        navController = navController,
+        startDestination = startDestination
+    ) {
+        composable<HomeRoute> {
+            HomeScreen(
+                onNavigateToUsers = { navController.navigate(UserListRoute) }
+            )
+        }
+
+        composable<UserListRoute> {
+            UserListScreen(
+                onUserClick = { userId ->
+                    navController.navigate(UserDetailRoute(userId))
+                },
+                onBack = { navController.navigateUp() }
+            )
+        }
+
+        composable<UserDetailRoute> { backStackEntry ->
+            val route = backStackEntry.toRoute<UserDetailRoute>()
+            UserDetailScreen(
+                userId = route.userId,
+                onBack = { navController.navigateUp() },
+                onEdit = { navController.navigate(EditUserRoute(route.userId)) }
+            )
+        }
+    }
+}
+```
+
+---
+
+## Reading Arguments in ViewModel
+
+```kotlin
+// ✅ ViewModel reads route args from SavedStateHandle
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val repository: UserRepository
+) : ViewModel() {
+
+    private val route = savedStateHandle.toRoute<UserDetailRoute>()
+    val userId = route.userId
+
+    val user: StateFlow<User?> = repository
+        .observeUser(userId)
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+}
+```
+
+---
+
+## Navigation Patterns
+
+```kotlin
+// ✅ Navigate and clear back stack (login → home)
+navController.navigate(HomeRoute) {
+    popUpTo(navController.graph.startDestinationId) { inclusive = true }
+}
+
+// ✅ Avoid duplicate destinations
+navController.navigate(UserDetailRoute(userId)) {
+    launchSingleTop = true
+}
+
+// ✅ Navigate up (back)
+navController.navigateUp()
+
+// ✅ Pop to specific destination
+navController.popBackStack(UserListRoute, inclusive = false)
+
+// ✅ Navigate with result (pass data back)
+// Sender
+navController.previousBackStackEntry
+    ?.savedStateHandle
+    ?.set("selected_user_id", userId)
+navController.navigateUp()
+
+// Receiver
+val selectedUserId = navController.currentBackStackEntry
+    ?.savedStateHandle
+    ?.getStateFlow<String?>("selected_user_id", null)
+    ?.collectAsStateWithLifecycle()
+```
+
+---
+
+## Passing NavController Down — Lambda Pattern
+
+```kotlin
+// ✅ Only one level deep — screen composables receive lambdas
+@Composable
+fun AppNavHost(navController: NavHostController) {
+    NavHost(navController, startDestination = HomeRoute) {
+        composable<HomeRoute> {
+            // ✅ Pass lambda, not navController
+            HomeScreen(
+                onNavigateToUsers = { navController.navigate(UserListRoute) },
+                onNavigateToSettings = { navController.navigate(SettingsRoute) }
+            )
+        }
+    }
+}
+
+// ✅ Screen receives lambdas — decoupled from navigation
+@Composable
+fun HomeScreen(
+    onNavigateToUsers: () -> Unit,
+    onNavigateToSettings: () -> Unit,
+    viewModel: HomeViewModel = hiltViewModel()
+) {
+    // ...
+}
+
+// ❌ Don't pass NavController into screen composables
+@Composable
+fun HomeScreen(navController: NavController) { // tightly coupled
+    Button(onClick = { navController.navigate(UserListRoute) }) { ... }
+}
+```
+
+---
+
+## Deep Links
+
+```kotlin
+// ✅ Define deep links in NavHost
+composable<UserDetailRoute>(
+    deepLinks = listOf(
+        navDeepLink<UserDetailRoute>(
+            basePath = "https://example.com/users"
+        )
+    )
+) { ... }
+
+// AndroidManifest.xml — declare intent filter
+// (see deep-link skill for full manifest setup)
+```
+
+---
+
+## Navigation with Hilt
+
+```kotlin
+// ✅ hiltViewModel() — scoped to NavBackStackEntry
+composable<UserDetailRoute> {
+    val viewModel: UserDetailViewModel = hiltViewModel()
+    UserDetailScreen(viewModel = viewModel)
+}
+
+// ✅ Shared ViewModel across multiple screens
+composable<CheckoutRoute> { backStackEntry ->
+    val parentEntry = remember(backStackEntry) {
+        navController.getBackStackEntry(CheckoutFlowRoute)
+    }
+    val sharedViewModel: CheckoutViewModel = hiltViewModel(parentEntry)
+    CheckoutScreen(viewModel = sharedViewModel)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Creating `NavController` inside a non-top-level composable — causes recreation
+- Passing `NavController` more than one level deep — tight coupling
+- Navigating from ViewModel — emit event, navigate from UI
+- Using string-based routes in new code — use type-safe routes
+- Not using `launchSingleTop` for bottom nav tabs — duplicates destinations
+- Not handling `navigateUp()` return value — can silently fail at root
+
+---
+
+## Related Skills
+- `navigation` — general navigation patterns and principles
+- `deep-navigation` — nested graphs and deep link handling
+- `nested-navigation` — nested NavHost and graphs
+- `hilt` — ViewModel injection with hiltViewModel()
+- `savedstatehandle` — reading route arguments in ViewModel