android-sdd 1.0.0

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

@@ -0,0 +1,274 @@
+---
+name: compose-performance
+description: >
+  Compose recomposition optimization and performance best practices.
+  Load this skill when diagnosing recomposition issues, optimizing list
+  performance, reducing unnecessary work in Compose, or profiling UI jank.
+---
+
+# Compose Performance
+
+## Overview
+Compose performance is primarily about controlling **recomposition** — the process of re-running composable functions when state changes. Unnecessary recomposition wastes CPU and causes UI jank. Understanding what triggers recomposition and how to minimize its scope is the key to performant Compose UIs.
+
+---
+
+## Core Principles
+
+- Recomposition scope is the **smallest enclosing composable** that reads changed state
+- Pass **only the state each composable needs** — not the entire state object
+- Use **stable types** — unstable types cause unnecessary recomposition
+- Move **heavy computation** out of composition — use `remember` or `derivedStateOf`
+- Use `key` in lists — enables smart diffing and avoids full re-render
+
+---
+
+## Stability
+
+```kotlin
+// ✅ Stable types — Compose can skip recomposition if inputs unchanged
+// - All primitive types (Int, String, Boolean, etc.)
+// - Immutable data classes with stable fields
+// - @Stable or @Immutable annotated classes
+
+@Immutable  // ✅ Promise to Compose: this object never changes
+data class UserUiState(
+    val name: String,
+    val email: String,
+    val isActive: Boolean
+)
+
+@Stable  // ✅ Promise: changes are tracked via Snapshot state
+class UserPreferences {
+    var isDarkMode by mutableStateOf(false)
+    var language by mutableStateOf("en")
+}
+
+// ❌ Unstable — List<T> is considered unstable by default
+data class UserListState(
+    val users: List<User>  // triggers recomposition on every emission even if data is same
+)
+
+// ✅ Use ImmutableList from kotlinx-collections-immutable
+data class UserListState(
+    val users: ImmutableList<User>  // stable — Compose can skip recomposition
+)
+```
+
+---
+
+## Passing Minimal State
+
+```kotlin
+// ❌ Passing entire state — entire subtree recomposes on any change
+@Composable
+fun UserCard(state: UserListUiState) {
+    Text(state.selectedUser.name)  // recomposes when anything in state changes
+}
+
+// ✅ Pass only what's needed
+@Composable
+fun UserCard(userName: String, onUserClick: () -> Unit) {
+    Text(userName)  // only recomposes when userName changes
+}
+```
+
+---
+
+## remember and derivedStateOf
+
+```kotlin
+// ✅ remember — cache expensive computation across recompositions
+@Composable
+fun FormattedPrice(priceInCents: Int) {
+    val formatted = remember(priceInCents) {
+        NumberFormat.getCurrencyInstance().format(priceInCents / 100.0)
+    }
+    Text(formatted)
+}
+
+// ✅ derivedStateOf — compute derived state, recompose only when result changes
+@Composable
+fun UserList(users: List<User>) {
+    val activeUserCount by remember {
+        derivedStateOf { users.count { it.isActive } }
+    }
+    // recomposes only when activeUserCount changes, not on every users update
+    Text("Active users: $activeUserCount")
+}
+
+// ✅ derivedStateOf for scroll-based state
+@Composable
+fun ScrollableScreen() {
+    val listState = rememberLazyListState()
+    val showScrollToTop by remember {
+        derivedStateOf { listState.firstVisibleItemIndex > 5 }
+    }
+
+    if (showScrollToTop) {
+        ScrollToTopButton()
+    }
+}
+```
+
+---
+
+## Lambda Stability
+
+```kotlin
+// ❌ Lambda created on each recomposition — causes child recomposition
+@Composable
+fun UserList(users: List<User>, viewModel: UserViewModel) {
+    users.forEach { user ->
+        UserCard(
+            user = user,
+            onClick = { viewModel.onUserClick(user.id) }  // new lambda each time
+        )
+    }
+}
+
+// ✅ Stable lambda reference
+@Composable
+fun UserList(users: List<User>, onUserClick: (String) -> Unit) {
+    users.forEach { user ->
+        UserCard(user = user, onClick = { onUserClick(user.id) })
+    }
+}
+
+// ✅ Use rememberUpdatedState for callbacks that change
+@Composable
+fun Timer(onTick: () -> Unit) {
+    val currentOnTick by rememberUpdatedState(onTick)
+    LaunchedEffect(Unit) {
+        while (true) {
+            delay(1_000)
+            currentOnTick()
+        }
+    }
+}
+```
+
+---
+
+## List Performance
+
+```kotlin
+// ✅ Always provide stable key in LazyColumn/LazyRow
+LazyColumn {
+    items(
+        items = users,
+        key = { user -> user.id }  // stable, unique key
+    ) { user ->
+        UserCard(user = user)
+    }
+}
+
+// ✅ contentType — helps Compose reuse item compositions
+LazyColumn {
+    items(
+        items = feedItems,
+        key = { it.id },
+        contentType = { item ->
+            when (item) {
+                is FeedItem.Post    -> "post"
+                is FeedItem.Ad      -> "ad"
+                is FeedItem.Header  -> "header"
+            }
+        }
+    ) { item ->
+        FeedItemView(item)
+    }
+}
+
+// ✅ Use Pager for full-screen horizontal paging
+HorizontalPager(count = pages.size) { page ->
+    PageContent(pages[page])
+}
+```
+
+---
+
+## Read State at the Lowest Level
+
+```kotlin
+// ❌ Read state high up — entire tree recomposes
+@Composable
+fun Screen(scrollState: ScrollState) {
+    val offset = scrollState.value  // read here — Screen recomposes on every scroll
+    Column(modifier = Modifier.offset(y = offset.dp)) {
+        ExpensiveContent()
+    }
+}
+
+// ✅ Defer state read to Modifier — no recomposition, only layout pass
+@Composable
+fun Screen(scrollState: ScrollState) {
+    Column(
+        modifier = Modifier.graphicsLayer {
+            translationY = scrollState.value.toFloat()  // read inside lambda — no recompose
+        }
+    ) {
+        ExpensiveContent()
+    }
+}
+```
+
+---
+
+## Baseline Profiles
+
+```kotlin
+// ✅ Generate Baseline Profile to pre-compile critical Compose paths
+// See baseline-profile skill for full setup
+
+// Macrobenchmark test
+@RunWith(AndroidJUnit4::class)
+class BaselineProfileGenerator {
+    @get:Rule
+    val rule = BaselineProfileRule()
+
+    @Test
+    fun generate() = rule.collect(packageName = "com.example.app") {
+        startActivityAndWait()
+        device.findObject(By.text("Users")).click()
+        device.waitForIdle()
+    }
+}
+```
+
+---
+
+## Profiling Tools
+
+```
+Layout Inspector → Recomposition counts per composable
+Compose Tracing  → detailed timeline in Perfetto
+Android Studio Profiler → CPU/frame timeline
+```
+
+```kotlin
+// ✅ Add Compose tracing for Perfetto
+dependencies {
+    implementation(libs.androidx.tracing.compose)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Reading `scrollState.value` at the top of a composable — causes excessive recomposition
+- Using `List<T>` in state — use `ImmutableList<T>` for stable collections
+- Creating lambdas inline in items — causes recomposition of every item
+- Not providing `key` in `items {}` — full list recompose on any change
+- Computing derived values without `remember` — recalculates every recomposition
+- Putting heavy logic directly in composable body — use `remember` or move to ViewModel
+
+---
+
+## Related Skills
+- `compose` — Compose fundamentals
+- `compose-animation` — animation without recomposition overhead
+- `baseline-profile` — pre-compiling Compose hot paths
+- `benchmark` — measuring Compose performance
+- `rendering-performance` — frame timing and jank detection

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

@@ -0,0 +1,217 @@
+---
+name: design-system
+description: >
+  Building and maintaining a custom design system on top of Material 3 in
+  Jetpack Compose. Load this skill when defining custom design tokens,
+  extending the M3 theme, creating a component library, managing spacing
+  scales, or enforcing visual consistency across the app.
+---
+
+# Design System
+
+## Overview
+
+A design system extends Material 3 with project-specific tokens (colors, spacing, typography, elevation) and a reusable component library. It acts as the single source of truth for all visual decisions, ensuring consistency and reducing duplication across features.
+
+---
+
+## Core Principles
+
+- Extend M3 — never replace it; build on top of `MaterialTheme`
+- Define all tokens once — consume them everywhere via `CompositionLocal`
+- Components in the design system must have no business logic
+- Every design system component must support preview in both light/dark and LTR/RTL
+- Tokens must be sealed objects or typed wrappers — never raw `Dp` or `Color` literals in UI code
+
+---
+
+## Token Structure
+
+```kotlin
+// ✅ Spacing tokens
+object AppSpacing {
+    val xs  = 4.dp
+    val sm  = 8.dp
+    val md  = 16.dp
+    val lg  = 24.dp
+    val xl  = 32.dp
+    val xxl = 48.dp
+}
+
+// ✅ Elevation tokens
+object AppElevation {
+    val none   = 0.dp
+    val low    = 2.dp
+    val medium = 4.dp
+    val high   = 8.dp
+}
+
+// ✅ Icon size tokens
+object AppIconSize {
+    val sm = 16.dp
+    val md = 24.dp
+    val lg = 32.dp
+}
+```
+
+---
+
+## Extending MaterialTheme
+
+```kotlin
+// ✅ Custom theme extension via CompositionLocal
+data class AppColors(
+    val success: Color,
+    val onSuccess: Color,
+    val warning: Color,
+    val onWarning: Color,
+    val info: Color,
+    val onInfo: Color
+)
+
+val LocalAppColors = staticCompositionLocalOf {
+    AppColors(
+        success = Color(0xFF2E7D32),
+        onSuccess = Color.White,
+        warning = Color(0xFFF57F17),
+        onWarning = Color.Black,
+        info = Color(0xFF0277BD),
+        onInfo = Color.White
+    )
+}
+
+// ✅ Access extension colors
+val appColors = LocalAppColors.current
+Box(modifier = Modifier.background(appColors.success))
+```
+
+---
+
+## Theme Provider
+
+```kotlin
+// ✅ Provide all custom locals alongside MaterialTheme
+@Composable
+fun AppTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit
+) {
+    val appColors = if (darkTheme) darkAppColors() else lightAppColors()
+
+    CompositionLocalProvider(
+        LocalAppColors provides appColors
+    ) {
+        MaterialTheme(
+            colorScheme = if (darkTheme) DarkColorScheme else LightColorScheme,
+            typography = AppTypography,
+            shapes = AppShapes,
+            content = content
+        )
+    }
+}
+```
+
+---
+
+## Design System Component Pattern
+
+```kotlin
+// ✅ Atomic component — no business logic, fully configurable
+@Composable
+fun AppButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    loading: Boolean = false,
+    style: AppButtonStyle = AppButtonStyle.Filled
+) {
+    val colors = when (style) {
+        AppButtonStyle.Filled  -> ButtonDefaults.buttonColors()
+        AppButtonStyle.Tonal   -> ButtonDefaults.filledTonalButtonColors()
+        AppButtonStyle.Outline -> ButtonDefaults.outlinedButtonColors()
+    }
+
+    Button(
+        onClick = onClick,
+        modifier = modifier,
+        enabled = enabled && !loading,
+        colors = colors
+    ) {
+        if (loading) {
+            CircularProgressIndicator(
+                modifier = Modifier.size(AppIconSize.sm),
+                strokeWidth = 2.dp
+            )
+            Spacer(Modifier.width(AppSpacing.sm))
+        }
+        Text(text)
+    }
+}
+
+enum class AppButtonStyle { Filled, Tonal, Outline }
+```
+
+---
+
+## Typography Extension
+
+```kotlin
+// ✅ Custom text styles beyond the M3 scale
+object AppTextStyle {
+    val code = TextStyle(
+        fontFamily = FontFamily.Monospace,
+        fontSize = 13.sp,
+        lineHeight = 20.sp
+    )
+    val caption = TextStyle(
+        fontSize = 11.sp,
+        lineHeight = 16.sp,
+        color = Color.Unspecified  // inherit from context
+    )
+}
+```
+
+---
+
+## Component Catalog Preview
+
+```kotlin
+// ✅ Every component has a catalog preview
+@Preview(name = "Light", uiMode = UI_MODE_NIGHT_NO)
+@Preview(name = "Dark", uiMode = UI_MODE_NIGHT_YES)
+@Preview(name = "RTL", locale = "fa")
+@Composable
+private fun AppButtonPreview() {
+    AppTheme {
+        Column(
+            modifier = Modifier.padding(AppSpacing.md),
+            verticalArrangement = Arrangement.spacedBy(AppSpacing.sm)
+        ) {
+            AppButton("Filled", onClick = {}, style = AppButtonStyle.Filled)
+            AppButton("Tonal", onClick = {}, style = AppButtonStyle.Tonal)
+            AppButton("Loading", onClick = {}, loading = true)
+            AppButton("Disabled", onClick = {}, enabled = false)
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using raw `Color(0xFF...)` literals in UI composables — use tokens
+- Putting business logic inside design system components
+- Overriding `MaterialTheme` colors directly via `MaterialTheme.copy()` in a nested scope — use `CompositionLocalProvider` instead
+- Defining spacing inline (`Modifier.padding(16.dp)`) — use `AppSpacing.md`
+- Mixing M2 and M3 components in the same design system
+
+---
+
+## Related Skills
+
+- `material3` — M3 foundation this system builds on
+- `compose` — Compose fundamentals
+- `rtl` — directional token and layout requirements
+- `resources` — XML resources for legacy interop

package/skills/UI System/Empty State Strategy/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: empty-state-strategy
+description: >
+  Strategies for displaying empty states in Android/Compose applications.
+  Load this skill when building screens that may have no data to show,
+  handling empty search results, first-time user experiences, filtered
+  lists with no matches, or error states that look like empty states.
+---
+
+# Empty State Strategy
+
+## Overview
+An empty state is what the user sees when a screen has no content to display. A well-designed empty state communicates clearly why there's nothing to show and what the user can do about it. Poor empty states leave users confused about whether the app is broken or the feature simply has no data yet.
+
+---
+
+## Core Principles
+
+- Every list screen must account for an empty state — it is never optional
+- Empty state must communicate **why** it's empty and **what the user can do**
+- Distinguish between: no data yet, empty search result, filtered result, and error
+- Empty state is a UI state variant — handle it in the state model, not with an `if` in the composable
+- Never show a blank screen — always provide context and a call to action when possible
+
+---
+
+## Empty State Types
+
+| Type | Cause | Action |
+|------|-------|--------|
+| First-time | User has no data yet | Primary CTA to create |
+| Empty search | Query returned no results | Clear search / change query |
+| Filtered | Active filter hides all items | Clear filters |
+| Error | Failed to load | Retry button |
+| Offline | No connectivity | Retry when online |
+
+---
+
+## UI State Model
+
+```kotlin
+// ✅ Empty is a distinct state, not null data
+sealed interface UiState<out T> {
+    data object Loading : UiState<Nothing>
+    data class Success<T>(val data: T) : UiState<T>
+    data object Empty : UiState<Nothing>
+    data class Error(val message: String) : UiState<Nothing>
+}
+
+// ✅ ViewModel maps domain result to correct state
+fun loadItems() {
+    viewModelScope.launch {
+        _state.value = UiState.Loading
+        repository.getItems().fold(
+            onSuccess = { items ->
+                _state.value = if (items.isEmpty()) UiState.Empty
+                               else UiState.Success(items)
+            },
+            onFailure = { _state.value = UiState.Error(it.message ?: "Error") }
+        )
+    }
+}
+```
+
+---
+
+## Empty State Component
+
+```kotlin
+// ✅ Reusable empty state component
+@Composable
+fun EmptyState(
+    icon: ImageVector,
+    title: String,
+    subtitle: String? = null,
+    actionLabel: String? = null,
+    onAction: (() -> Unit)? = null,
+    modifier: Modifier = Modifier
+) {
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .padding(AppSpacing.xl),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center
+    ) {
+        Icon(
+            imageVector = icon,
+            contentDescription = null,
+            modifier = Modifier.size(64.dp),
+            tint = MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = 0.4f)
+        )
+        Spacer(Modifier.height(AppSpacing.md))
+        Text(
+            text = title,
+            style = MaterialTheme.typography.titleMedium,
+            textAlign = TextAlign.Center,
+            color = MaterialTheme.colorScheme.onSurface
+        )
+        if (subtitle != null) {
+            Spacer(Modifier.height(AppSpacing.sm))
+            Text(
+                text = subtitle,
+                style = MaterialTheme.typography.bodyMedium,
+                textAlign = TextAlign.Center,
+                color = MaterialTheme.colorScheme.onSurfaceVariant
+            )
+        }
+        if (actionLabel != null && onAction != null) {
+            Spacer(Modifier.height(AppSpacing.lg))
+            Button(onClick = onAction) {
+                Text(actionLabel)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Usage Per Type
+
+```kotlin
+// ✅ First-time empty state
+EmptyState(
+    icon = Icons.Outlined.Inbox,
+    title = "No items yet",
+    subtitle = "Create your first item to get started.",
+    actionLabel = "Create Item",
+    onAction = onCreateClick
+)
+
+// ✅ Empty search result
+EmptyState(
+    icon = Icons.Outlined.SearchOff,
+    title = "No results for \"$query\"",
+    subtitle = "Try a different search term.",
+    actionLabel = "Clear Search",
+    onAction = onClearSearch
+)
+
+// ✅ Active filter hides all items
+EmptyState(
+    icon = Icons.Outlined.FilterAltOff,
+    title = "No matches",
+    subtitle = "No items match the active filters.",
+    actionLabel = "Clear Filters",
+    onAction = onClearFilters
+)
+
+// ✅ Error state (looks like empty — distinguish clearly)
+EmptyState(
+    icon = Icons.Outlined.CloudOff,
+    title = "Couldn't load items",
+    subtitle = "Check your connection and try again.",
+    actionLabel = "Retry",
+    onAction = onRetry
+)
+```
+
+---
+
+## Screen Integration
+
+```kotlin
+// ✅ Handle all states in one when block
+@Composable
+fun ItemListScreen(viewModel: ItemListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (state) {
+        is UiState.Loading -> SkeletonList()
+        is UiState.Empty   -> EmptyState(
+            icon = Icons.Outlined.Inbox,
+            title = "Nothing here yet",
+            subtitle = "Add your first item.",
+            actionLabel = "Add Item",
+            onAction = viewModel::onAddClick
+        )
+        is UiState.Success -> ItemList((state as UiState.Success).data)
+        is UiState.Error   -> EmptyState(
+            icon = Icons.Outlined.ErrorOutline,
+            title = "Something went wrong",
+            subtitle = (state as UiState.Error).message,
+            actionLabel = "Retry",
+            onAction = viewModel::loadItems
+        )
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Showing a blank screen when data is empty — always provide context
+- Using `if (list.isEmpty())` inline in a composable instead of a sealed state
+- Confusing error state with empty state — user must know why content is missing
+- Showing a generic "No data" message without context or action
+- Hiding the empty state behind a loading state that never resolves
+
+---
+
+## Related Skills
+- `loading-strategy` — what to show while data is being fetched
+- `state-management` — modeling UI states as sealed classes
+- `error-handling` — error propagation and user-facing error messages
+- `compose` — layout and animation fundamentals