android-sdd 1.0.0

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

@@ -0,0 +1,296 @@
+---
+name: compose
+description: >
+  Jetpack Compose fundamentals, patterns, and best practices for Android UI.
+  Load this skill when building any Compose UI, designing composable functions,
+  managing state in Compose, or optimizing recomposition.
+---
+
+# Compose
+
+## Overview
+Jetpack Compose is Android's modern declarative UI toolkit. UI is described as functions of state — when state changes, the UI recomposes automatically. Understanding recomposition, state hoisting, and composable design is essential for correct and performant Compose code.
+
+---
+
+## Core Principles
+
+- UI is a **function of state** — never imperatively mutate UI
+- **Hoist state** to the lowest common ancestor that needs it
+- Keep composables **small and focused** — one responsibility per composable
+- **Stateless composables** are easier to test, preview, and reuse
+- Avoid side effects inside composable functions — use `LaunchedEffect`, `SideEffect`, `DisposableEffect`
+
+---
+
+## Composable Function Design
+
+```kotlin
+// ✅ Stateless composable — accepts state, emits events
+@Composable
+fun UserCard(
+    user: User,
+    onUserClick: (String) -> Unit,
+    modifier: Modifier = Modifier  // always include modifier parameter
+) {
+    Card(
+        modifier = modifier.clickable { onUserClick(user.id) }
+    ) {
+        Column(modifier = Modifier.padding(16.dp)) {
+            Text(text = user.name, style = MaterialTheme.typography.titleMedium)
+            Text(text = user.email, style = MaterialTheme.typography.bodySmall)
+        }
+    }
+}
+
+// ✅ Stateful composable — owns state, delegates to stateless
+@Composable
+fun UserCardScreen(viewModel: UserViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    UserCard(
+        user = state.user,
+        onUserClick = viewModel::onUserClicked
+    )
+}
+```
+
+---
+
+## State Management in Compose
+
+```kotlin
+// ✅ Local UI state — remember
+@Composable
+fun ExpandableCard(title: String, content: String) {
+    var isExpanded by remember { mutableStateOf(false) }
+
+    Card(modifier = Modifier.clickable { isExpanded = !isExpanded }) {
+        Column {
+            Text(title)
+            if (isExpanded) Text(content)
+        }
+    }
+}
+
+// ✅ State that survives rotation — rememberSaveable
+@Composable
+fun SearchBar(onSearch: (String) -> Unit) {
+    var query by rememberSaveable { mutableStateOf("") }
+    TextField(
+        value = query,
+        onValueChange = { query = it },
+        trailingIcon = {
+            IconButton(onClick = { onSearch(query) }) {
+                Icon(Icons.Default.Search, contentDescription = null)
+            }
+        }
+    )
+}
+
+// ✅ Complex state — hoist to ViewModel
+@Composable
+fun ProductScreen(viewModel: ProductViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    ProductContent(
+        state = state,
+        onAddToCart = viewModel::onAddToCart,
+        onQuantityChange = viewModel::onQuantityChange
+    )
+}
+```
+
+---
+
+## State Hoisting Pattern
+
+```kotlin
+// ✅ Hoist state up — pass value and onValueChange
+@Composable
+fun EmailField(
+    value: String,
+    onValueChange: (String) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    OutlinedTextField(
+        value = value,
+        onValueChange = onValueChange,
+        label = { Text("Email") },
+        modifier = modifier
+    )
+}
+
+// ✅ Owner of state composes and passes down
+@Composable
+fun RegisterForm() {
+    var email by rememberSaveable { mutableStateOf("") }
+    var password by rememberSaveable { mutableStateOf("") }
+
+    EmailField(value = email, onValueChange = { email = it })
+    PasswordField(value = password, onValueChange = { password = it })
+}
+```
+
+---
+
+## Side Effects
+
+```kotlin
+// ✅ LaunchedEffect — coroutine tied to composition
+@Composable
+fun UserScreen(userId: String, viewModel: UserViewModel = hiltViewModel()) {
+    LaunchedEffect(userId) {
+        viewModel.loadUser(userId)  // re-runs when userId changes
+    }
+}
+
+// ✅ DisposableEffect — non-coroutine cleanup
+@Composable
+fun LifecycleAwareScreen(onResume: () -> Unit) {
+    val lifecycleOwner = LocalLifecycleOwner.current
+    DisposableEffect(lifecycleOwner) {
+        val observer = LifecycleEventObserver { _, event ->
+            if (event == Lifecycle.Event.ON_RESUME) onResume()
+        }
+        lifecycleOwner.lifecycle.addObserver(observer)
+        onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
+    }
+}
+
+// ✅ SideEffect — sync Compose state to non-Compose code
+@Composable
+fun AnalyticsScreen(screenName: String) {
+    SideEffect {
+        analytics.logScreenView(screenName)  // runs on every successful recomposition
+    }
+}
+
+// ✅ One-time events from ViewModel
+@Composable
+fun OrderScreen(viewModel: OrderViewModel = hiltViewModel()) {
+    val lifecycleOwner = LocalLifecycleOwner.current
+
+    LaunchedEffect(Unit) {
+        viewModel.events
+            .flowWithLifecycle(lifecycleOwner.lifecycle)
+            .collect { event ->
+                when (event) {
+                    is OrderEvent.NavigateToConfirmation -> navController.navigate(...)
+                    is OrderEvent.ShowError -> snackbarHostState.showSnackbar(event.message)
+                }
+            }
+    }
+}
+```
+
+---
+
+## Modifier Best Practices
+
+```kotlin
+// ✅ Always accept modifier as parameter — last before lambdas
+@Composable
+fun MyComponent(
+    text: String,
+    modifier: Modifier = Modifier,  // default to Modifier (empty)
+    onClick: () -> Unit
+) {
+    Box(modifier = modifier.clickable { onClick() }) {
+        Text(text)
+    }
+}
+
+// ✅ Order matters — padding before clickable = larger touch target
+Box(modifier = Modifier
+    .padding(8.dp)
+    .clickable { }  // touch area includes padding
+)
+
+// ✅ Clickable before padding = smaller touch target
+Box(modifier = Modifier
+    .clickable { }
+    .padding(8.dp)  // padding is outside the touch area
+)
+```
+
+---
+
+## Lists
+
+```kotlin
+// ✅ LazyColumn for long lists — only renders visible items
+@Composable
+fun UserList(users: List<User>, onUserClick: (String) -> Unit) {
+    LazyColumn(
+        contentPadding = PaddingValues(16.dp),
+        verticalArrangement = Arrangement.spacedBy(8.dp)
+    ) {
+        items(
+            items = users,
+            key = { user -> user.id }  // ✅ always provide stable key
+        ) { user ->
+            UserCard(user = user, onUserClick = onUserClick)
+        }
+    }
+}
+
+// ✅ Column only for short/fixed lists (< ~10 items)
+@Composable
+fun SettingsMenu(items: List<SettingItem>) {
+    Column {
+        items.forEach { item ->
+            SettingRow(item = item)
+        }
+    }
+}
+```
+
+---
+
+## Previews
+
+```kotlin
+// ✅ Preview stateless composables
+@Preview(showBackground = true)
+@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES)
+@Composable
+private fun UserCardPreview() {
+    AppTheme {
+        UserCard(
+            user = User(id = "1", name = "Ali Rezaei", email = "ali@example.com"),
+            onUserClick = {}
+        )
+    }
+}
+
+// ✅ Preview with multiple states
+@Preview(name = "Loading")
+@Preview(name = "Success")
+@Composable
+private fun UserScreenPreview() {
+    AppTheme {
+        UserContent(state = previewState)
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Side effects directly in composable body — use `LaunchedEffect`/`DisposableEffect`
+- Reading `viewModel.state.value` directly — use `collectAsStateWithLifecycle()`
+- Not providing `key` in `items {}` — causes incorrect animations and recomposition
+- Deeply nested composables — extract to named functions
+- Not passing `modifier` parameter — prevents callers from customizing layout
+- Creating remember/state inside loops or conditions — violates rules of hooks
+- Using `Column` for long scrollable lists — use `LazyColumn`
+
+---
+
+## Related Skills
+- `compose-navigation` — navigation between screens
+- `compose-performance` — recomposition optimization
+- `compose-animation` — animation in Compose
+- `material3` — Material 3 components and theming
+- `state-management` — state patterns with ViewModel
+- `reactive-state-management` — collecting flows in Compose

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

@@ -0,0 +1,281 @@
+---
+name: compose-animation
+description: >
+  Compose animation APIs and patterns for Android UI.
+  Load this skill when adding transitions, animated visibility,
+  motion between screens, or any time-based UI change in Compose.
+---
+
+# Compose Animation
+
+## Overview
+Compose provides a rich animation system ranging from simple animated value changes to complex physics-based motion. Animations improve UX by providing visual continuity and feedback. Choose the simplest API that meets the need.
+
+---
+
+## Core Principles
+
+- Choose the **simplest API** for the job — don't use `Animatable` when `animateFloatAsState` works
+- Animations should **respect user accessibility settings** — check `reduceMotion`
+- Never block the main thread — all Compose animations are coroutine-based
+- Animate **state transitions**, not imperative sequences
+- Use `AnimatedVisibility` and `AnimatedContent` before reaching for custom animations
+
+---
+
+## Animation API Hierarchy
+
+```
+Simple value change      → animateXxxAsState
+Visibility show/hide     → AnimatedVisibility
+Content swap             → AnimatedContent
+Screen transitions       → NavHost transitions
+Multi-value / sequenced  → updateTransition
+Full control / physics   → Animatable
+Infinite                 → rememberInfiniteTransition
+```
+
+---
+
+## animateXxxAsState — Simple Value Animation
+
+```kotlin
+// ✅ Animate a single value when state changes
+@Composable
+fun LikeButton(isLiked: Boolean, onToggle: () -> Unit) {
+    val scale by animateFloatAsState(
+        targetValue = if (isLiked) 1.2f else 1f,
+        animationSpec = spring(dampingRatio = Spring.DampingRatioMediumBouncy),
+        label = "like_scale"  // ✅ always provide label for tooling
+    )
+    val color by animateColorAsState(
+        targetValue = if (isLiked) Color.Red else Color.Gray,
+        label = "like_color"
+    )
+
+    Icon(
+        imageVector = Icons.Default.Favorite,
+        contentDescription = null,
+        tint = color,
+        modifier = Modifier
+            .scale(scale)
+            .clickable { onToggle() }
+    )
+}
+
+// ✅ Animate size
+val size by animateDpAsState(
+    targetValue = if (isExpanded) 200.dp else 100.dp,
+    animationSpec = tween(durationMillis = 300),
+    label = "card_size"
+)
+```
+
+---
+
+## AnimatedVisibility
+
+```kotlin
+// ✅ Show/hide with animation
+@Composable
+fun FilterPanel(isVisible: Boolean, content: @Composable () -> Unit) {
+    AnimatedVisibility(
+        visible = isVisible,
+        enter = slideInVertically() + fadeIn(),
+        exit = slideOutVertically() + fadeOut()
+    ) {
+        content()
+    }
+}
+
+// ✅ List item appearance
+LazyColumn {
+    items(users, key = { it.id }) { user ->
+        AnimatedVisibility(
+            visible = true,
+            enter = fadeIn() + expandVertically()
+        ) {
+            UserCard(user = user)
+        }
+    }
+}
+```
+
+---
+
+## AnimatedContent
+
+```kotlin
+// ✅ Animate between different content states
+@Composable
+fun CounterDisplay(count: Int) {
+    AnimatedContent(
+        targetState = count,
+        transitionSpec = {
+            if (targetState > initialState) {
+                slideInVertically { -it } + fadeIn() togetherWith
+                slideOutVertically { it } + fadeOut()
+            } else {
+                slideInVertically { it } + fadeIn() togetherWith
+                slideOutVertically { -it } + fadeOut()
+            }
+        },
+        label = "counter"
+    ) { targetCount ->
+        Text(text = "$targetCount", style = MaterialTheme.typography.displayLarge)
+    }
+}
+
+// ✅ Switch between loading/content/error states
+@Composable
+fun ScreenContent(state: UiState) {
+    AnimatedContent(
+        targetState = state,
+        label = "screen_content"
+    ) { currentState ->
+        when (currentState) {
+            is UiState.Loading -> LoadingView()
+            is UiState.Success -> ContentView(currentState.data)
+            is UiState.Error   -> ErrorView(currentState.message)
+        }
+    }
+}
+```
+
+---
+
+## updateTransition — Coordinated Multi-Value Animation
+
+```kotlin
+// ✅ Animate multiple values tied to the same state
+@Composable
+fun ExpandableCard(isExpanded: Boolean) {
+    val transition = updateTransition(targetState = isExpanded, label = "card_transition")
+
+    val cornerRadius by transition.animateDp(label = "corner") {
+        if (it) 0.dp else 16.dp
+    }
+    val elevation by transition.animateDp(label = "elevation") {
+        if (it) 8.dp else 2.dp
+    }
+    val backgroundColor by transition.animateColor(label = "bg") {
+        if (it) MaterialTheme.colorScheme.primaryContainer
+        else MaterialTheme.colorScheme.surface
+    }
+
+    Card(
+        shape = RoundedCornerShape(cornerRadius),
+        colors = CardDefaults.cardColors(containerColor = backgroundColor)
+    ) { ... }
+}
+```
+
+---
+
+## Screen Transitions (Compose Navigation)
+
+```kotlin
+// ✅ Global transitions in NavHost
+NavHost(
+    navController = navController,
+    startDestination = HomeRoute,
+    enterTransition = { slideInHorizontally { it } + fadeIn() },
+    exitTransition = { slideOutHorizontally { -it } + fadeOut() },
+    popEnterTransition = { slideInHorizontally { -it } + fadeIn() },
+    popExitTransition = { slideOutHorizontally { it } + fadeOut() }
+) {
+    composable<HomeRoute> { HomeScreen() }
+    composable<DetailRoute> { DetailScreen() }
+}
+
+// ✅ Per-route transitions
+composable<DetailRoute>(
+    enterTransition = { fadeIn(tween(300)) },
+    exitTransition = { fadeOut(tween(300)) }
+) { DetailScreen() }
+```
+
+---
+
+## Animation Specs
+
+```kotlin
+// tween — linear/eased time-based
+tween(durationMillis = 300, easing = FastOutSlowInEasing)
+
+// spring — physics-based, natural feel
+spring(dampingRatio = Spring.DampingRatioMediumBouncy, stiffness = Spring.StiffnessMedium)
+
+// keyframes — precise time-value control
+keyframes {
+    durationMillis = 400
+    0f at 0
+    1.2f at 200
+    1f at 400
+}
+
+// snap — instant, no animation
+snap()
+```
+
+---
+
+## Accessibility — Reduced Motion
+
+```kotlin
+// ✅ Respect user's reduce motion setting
+@Composable
+fun AccessibleAnimation(isVisible: Boolean) {
+    val reduceMotion = LocalReduceMotion.current  // not yet in stable — use workaround
+
+    // Workaround until LocalReduceMotion is stable
+    val animationDuration = if (isSystemInDarkTheme()) 0 else 300
+
+    AnimatedVisibility(
+        visible = isVisible,
+        enter = fadeIn(tween(animationDuration)),
+        exit = fadeOut(tween(animationDuration))
+    ) { ... }
+}
+```
+
+---
+
+## Infinite Animation
+
+```kotlin
+// ✅ Loading shimmer / pulse
+@Composable
+fun PulsingDot() {
+    val infiniteTransition = rememberInfiniteTransition(label = "pulse")
+    val scale by infiniteTransition.animateFloat(
+        initialValue = 0.8f,
+        targetValue = 1.2f,
+        animationSpec = infiniteRepeatable(
+            animation = tween(600),
+            repeatMode = RepeatMode.Reverse
+        ),
+        label = "scale"
+    )
+    Box(modifier = Modifier.scale(scale).size(12.dp).background(Color.Blue, CircleShape))
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Animating on every recomposition — animation state must be stable
+- Missing `label` parameter — breaks Animation Inspector in Android Studio
+- Using `Thread.sleep()` or `delay()` for animation timing — use animation specs
+- Animating too many properties simultaneously — causes jank
+- Not testing with reduced motion — accessibility oversight
+- Using `LaunchedEffect` + manual delay for show/hide — use `AnimatedVisibility`
+
+---
+
+## Related Skills
+- `compose` — Compose fundamentals and state
+- `compose-performance` — avoiding recomposition during animation
+- `material3` — Material 3 motion system
+- `loading-strategy` — animated loading states