android-sdd 1.0.0

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

@@ -0,0 +1,214 @@
+---
+name: keyboard-navigation
+description: >
+  Keyboard and IME (soft keyboard) navigation in Android/Compose.
+  Load this skill when managing focus traversal between fields, handling
+  IME actions (Next, Done, Search), avoiding content hidden behind the
+  keyboard, managing keyboard visibility, or supporting hardware keyboards.
+---
+
+# Keyboard Navigation
+
+## Overview
+Keyboard navigation covers two concerns: soft keyboard (IME) management for touch devices, and hardware keyboard support for accessibility and productivity. Both require explicit focus management, correct IME action wiring, and ensuring content remains accessible when the keyboard is visible.
+
+---
+
+## Core Principles
+
+- Always set `imeAction` to match the field's role (`Next` for mid-form, `Done`/`Search` for last)
+- Never let the keyboard obscure active input fields — use `imePadding()` or `imeNestedScroll()`
+- Use `FocusRequester` for programmatic focus — never simulate clicks
+- Form fields must chain focus in logical order — left-to-right, top-to-bottom (LTR) or right-to-left (RTL)
+- Request focus on first field only after the screen is fully composed
+
+---
+
+## IME Actions
+
+```kotlin
+// ✅ Chain fields with Next — last field uses Done/Search/Send
+@Composable
+fun LoginForm(onSubmit: () -> Unit) {
+    val focusManager = LocalFocusManager.current
+    var email by remember { mutableStateOf("") }
+    var password by remember { mutableStateOf("") }
+
+    Column(verticalArrangement = Arrangement.spacedBy(AppSpacing.md)) {
+        OutlinedTextField(
+            value = email,
+            onValueChange = { email = it },
+            label = { Text("Email") },
+            keyboardOptions = KeyboardOptions(
+                keyboardType = KeyboardType.Email,
+                imeAction = ImeAction.Next       // ✅ moves focus to next field
+            ),
+            keyboardActions = KeyboardActions(
+                onNext = { focusManager.moveFocus(FocusDirection.Down) }
+            ),
+            singleLine = true
+        )
+
+        OutlinedTextField(
+            value = password,
+            onValueChange = { password = it },
+            label = { Text("Password") },
+            visualTransformation = PasswordVisualTransformation(),
+            keyboardOptions = KeyboardOptions(
+                keyboardType = KeyboardType.Password,
+                imeAction = ImeAction.Done       // ✅ last field — submit
+            ),
+            keyboardActions = KeyboardActions(
+                onDone = {
+                    focusManager.clearFocus()
+                    onSubmit()
+                }
+            ),
+            singleLine = true
+        )
+    }
+}
+```
+
+---
+
+## FocusRequester
+
+```kotlin
+// ✅ Programmatic focus after screen appears
+@Composable
+fun SearchScreen() {
+    val focusRequester = remember { FocusRequester() }
+
+    OutlinedTextField(
+        modifier = Modifier.focusRequester(focusRequester),
+        value = query,
+        onValueChange = { query = it },
+        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
+        keyboardActions = KeyboardActions(onSearch = { onSearch(query) })
+    )
+
+    LaunchedEffect(Unit) {
+        focusRequester.requestFocus()  // ✅ focus after composition
+    }
+}
+
+// ✅ Chaining focus manually across fields
+@Composable
+fun MultiFieldForm() {
+    val (firstFocus, secondFocus, thirdFocus) = remember { FocusRequester.createRefs() }
+
+    OutlinedTextField(
+        modifier = Modifier.focusRequester(firstFocus),
+        keyboardActions = KeyboardActions(onNext = { secondFocus.requestFocus() }),
+        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
+        ...
+    )
+    OutlinedTextField(
+        modifier = Modifier.focusRequester(secondFocus),
+        keyboardActions = KeyboardActions(onNext = { thirdFocus.requestFocus() }),
+        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
+        ...
+    )
+    OutlinedTextField(
+        modifier = Modifier.focusRequester(thirdFocus),
+        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
+        ...
+    )
+}
+```
+
+---
+
+## Avoiding Content Hidden Behind Keyboard
+
+```kotlin
+// ✅ imePadding on scrollable containers
+@Composable
+fun FormScreen() {
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .imePadding()              // ✅ pushes content above keyboard
+            .padding(AppSpacing.md)
+    ) {
+        // form fields
+    }
+}
+
+// ✅ WindowInsets approach in Scaffold
+Scaffold(
+    modifier = Modifier.imePadding()
+) { padding ->
+    Column(modifier = Modifier.padding(padding)) { ... }
+}
+
+// ✅ For LazyColumn — imeNestedScroll + imePadding
+LazyColumn(
+    modifier = Modifier
+        .fillMaxSize()
+        .imePadding()
+        .imeNestedScroll()
+) { ... }
+```
+
+---
+
+## Keyboard Visibility Control
+
+```kotlin
+// ✅ Show keyboard programmatically (Compose)
+val keyboardController = LocalSoftwareKeyboardController.current
+
+Button(onClick = { keyboardController?.show() }) { Text("Open Keyboard") }
+Button(onClick = { keyboardController?.hide() }) { Text("Close Keyboard") }
+
+// ✅ Hide keyboard on outside tap
+@Composable
+fun DismissKeyboardOnTap(content: @Composable () -> Unit) {
+    val focusManager = LocalFocusManager.current
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .pointerInput(Unit) {
+                detectTapGestures(onTap = { focusManager.clearFocus() })
+            }
+    ) {
+        content()
+    }
+}
+```
+
+---
+
+## Keyboard Type Reference
+
+| KeyboardType | Use For |
+|---|---|
+| `Text` | General text input |
+| `Email` | Email addresses |
+| `Number` | Numeric only |
+| `Phone` | Phone numbers |
+| `Password` | Password (masked) |
+| `NumberPassword` | PIN / numeric password |
+| `Uri` | URLs |
+| `Decimal` | Decimal numbers |
+
+---
+
+## Anti-Patterns
+
+- Not setting `imeAction` — keyboard shows a random action button
+- Using `ImeAction.Done` on non-last fields — breaks tab/next navigation
+- Not adding `imePadding()` to scrollable forms — keyboard hides the active field
+- Calling `requestFocus()` outside `LaunchedEffect` — crashes before composition completes
+- Using `WindowManager.hideSoftInputFromWindow()` directly — deprecated, use `SoftwareKeyboardController`
+- Setting `keyboardType = KeyboardType.Number` for phone numbers — use `Phone` type instead
+
+---
+
+## Related Skills
+- `compose` — Compose fundamentals and Modifier system
+- `bottom-sheet-pattern` — keyboard interaction with bottom sheets
+- `accessibility` — focus order and hardware keyboard support

package/skills/UI System/Loading Strategy/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: loading-strategy
+description: >
+  Strategies for showing loading states in Android/Compose applications.
+  Load this skill when implementing skeleton screens, shimmer effects,
+  pull-to-refresh, progressive loading, pagination loading indicators,
+  or deciding between spinner vs skeleton vs placeholder approaches.
+---
+
+# Loading Strategy
+
+## Overview
+Loading strategy defines how the UI communicates data-fetching progress to the user. The choice between spinner, skeleton, shimmer, and placeholder affects perceived performance significantly. A consistent, well-defined loading strategy prevents layout shifts and provides a smoother user experience.
+
+---
+
+## Core Principles
+
+- Use **skeleton/shimmer** for initial content load — never a full-screen spinner
+- Use **inline spinner** for actions (button submit, pull-to-refresh)
+- Never block the entire screen with a loading overlay unless the action is destructive and non-cancellable
+- Loading state must be part of the UI state model — never a separate boolean flag
+- Skeleton dimensions must match the real content dimensions to prevent layout shift
+
+---
+
+## UI State Model
+
+```kotlin
+// ✅ Loading is part of a sealed state — not a separate flag
+sealed interface UiState<out T> {
+    data object Loading : UiState<Nothing>
+    data class Success<T>(val data: T) : UiState<T>
+    data class Error(val message: String) : UiState<Nothing>
+}
+
+// ✅ In ViewModel
+class UserListViewModel : ViewModel() {
+    private val _state = MutableStateFlow<UiState<List<User>>>(UiState.Loading)
+    val state: StateFlow<UiState<List<User>>> = _state.asStateFlow()
+
+    fun loadUsers() {
+        viewModelScope.launch {
+            _state.value = UiState.Loading
+            _state.value = repository.getUsers().fold(
+                onSuccess = { UiState.Success(it) },
+                onFailure = { UiState.Error(it.message ?: "Unknown error") }
+            )
+        }
+    }
+}
+```
+
+---
+
+## Skeleton Screen
+
+```kotlin
+// ✅ Skeleton matches real item dimensions
+@Composable
+fun UserItemSkeleton(modifier: Modifier = Modifier) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .padding(horizontal = AppSpacing.md, vertical = AppSpacing.sm),
+        horizontalArrangement = Arrangement.spacedBy(AppSpacing.md)
+    ) {
+        // Avatar placeholder
+        Box(
+            modifier = Modifier
+                .size(40.dp)
+                .clip(CircleShape)
+                .shimmer()
+        )
+        Column(verticalArrangement = Arrangement.spacedBy(AppSpacing.xs)) {
+            // Name placeholder
+            Box(
+                modifier = Modifier
+                    .fillMaxWidth(0.5f)
+                    .height(16.dp)
+                    .clip(MaterialTheme.shapes.small)
+                    .shimmer()
+            )
+            // Subtitle placeholder
+            Box(
+                modifier = Modifier
+                    .fillMaxWidth(0.35f)
+                    .height(12.dp)
+                    .clip(MaterialTheme.shapes.small)
+                    .shimmer()
+            )
+        }
+    }
+}
+
+// ✅ Shimmer modifier using animated brush
+@Composable
+fun Modifier.shimmer(): Modifier {
+    val transition = rememberInfiniteTransition(label = "shimmer")
+    val translateAnim by transition.animateFloat(
+        initialValue = 0f,
+        targetValue = 1000f,
+        animationSpec = infiniteRepeatable(
+            animation = tween(durationMillis = 1200, easing = LinearEasing),
+            repeatMode = RepeatMode.Restart
+        ),
+        label = "shimmer_translate"
+    )
+    val brush = Brush.linearGradient(
+        colors = listOf(
+            MaterialTheme.colorScheme.surfaceVariant,
+            MaterialTheme.colorScheme.surface,
+            MaterialTheme.colorScheme.surfaceVariant
+        ),
+        start = Offset(translateAnim - 200f, 0f),
+        end = Offset(translateAnim, 0f)
+    )
+    return this.background(brush)
+}
+```
+
+---
+
+## List Loading
+
+```kotlin
+// ✅ Show skeleton list during initial load
+@Composable
+fun UserListScreen(viewModel: UserListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (state) {
+        is UiState.Loading -> {
+            LazyColumn {
+                items(6) { UserItemSkeleton() }  // fixed count matches expected content
+            }
+        }
+        is UiState.Success -> {
+            LazyColumn {
+                items((state as UiState.Success).data) { user ->
+                    UserItem(user)
+                }
+            }
+        }
+        is UiState.Error -> {
+            ErrorState(message = (state as UiState.Error).message)
+        }
+    }
+}
+```
+
+---
+
+## Pull-to-Refresh
+
+```kotlin
+// ✅ Pull-to-refresh with PullToRefreshBox (M3)
+@Composable
+fun UserListScreen(viewModel: UserListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val isRefreshing = state is UiState.Loading && viewModel.isRefreshing
+
+    PullToRefreshBox(
+        isRefreshing = isRefreshing,
+        onRefresh = viewModel::refresh
+    ) {
+        LazyColumn { ... }
+    }
+}
+```
+
+---
+
+## Button Loading State
+
+```kotlin
+// ✅ Inline loading indicator in action button
+@Composable
+fun SubmitButton(
+    isLoading: Boolean,
+    onClick: () -> Unit
+) {
+    Button(
+        onClick = onClick,
+        enabled = !isLoading
+    ) {
+        AnimatedContent(targetState = isLoading, label = "submit_btn") { loading ->
+            if (loading) {
+                CircularProgressIndicator(
+                    modifier = Modifier.size(18.dp),
+                    strokeWidth = 2.dp,
+                    color = MaterialTheme.colorScheme.onPrimary
+                )
+            } else {
+                Text("Submit")
+            }
+        }
+    }
+}
+```
+
+---
+
+## Pagination Loading
+
+```kotlin
+// ✅ Footer loading indicator for paginated lists
+@Composable
+fun PaginatedList(
+    items: List<Item>,
+    isLoadingMore: Boolean,
+    onLoadMore: () -> Unit
+) {
+    LazyColumn {
+        items(items) { ItemRow(it) }
+
+        if (isLoadingMore) {
+            item {
+                Box(
+                    modifier = Modifier
+                        .fillMaxWidth()
+                        .padding(AppSpacing.md),
+                    contentAlignment = Alignment.Center
+                ) {
+                    CircularProgressIndicator(modifier = Modifier.size(24.dp))
+                }
+            }
+        }
+    }
+
+    // Trigger load more when near end
+    LaunchedEffect(items.size) {
+        if (items.isNotEmpty()) onLoadMore()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Full-screen `CircularProgressIndicator` for content loading — use skeleton instead
+- Using a separate `isLoading: Boolean` flag alongside data state — use sealed state
+- Skeleton with wrong dimensions — causes layout shift when content appears
+- Not disabling interactive elements during loading — allows double submissions
+- Showing spinner on every recomposition — tie to actual async state only
+
+---
+
+## Related Skills
+- `empty-state-strategy` — what to show when loading succeeds but data is empty
+- `state-management` — UI state modeling
+- `compose` — animation and layout fundamentals
+- `paging` — pagination with Paging 3 library