android-skills 1.1.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +22 -171
  2. package/android-ui/SKILL.md +187 -0
  3. package/android-ui/references/anti-slop-checklist.md +61 -0
  4. package/android-ui/references/checklist.md +95 -0
  5. package/android-ui/references/clarifying-questions.md +55 -0
  6. package/android-ui/references/color-and-contrast.md +104 -0
  7. package/android-ui/references/components-intents.md +74 -0
  8. package/android-ui/references/compose-patterns.md +120 -0
  9. package/android-ui/references/compose-risks.md +86 -0
  10. package/android-ui/references/input-and-state.md +77 -0
  11. package/android-ui/references/network-storage.md +87 -0
  12. package/android-ui/references/reconstruction-workflow.md +74 -0
  13. package/android-ui/references/report-template.md +71 -0
  14. package/android-ui/references/sensitive-data-ui.md +73 -0
  15. package/android-ui/references/typography-spacing.md +93 -0
  16. package/android-ui/references/webview.md +105 -0
  17. package/{android-ui-minimal → android-ui}/scripts/contrast.py +8 -8
  18. package/{android-ui-minimal → android-ui}/scripts/gen_tokens.py +11 -11
  19. package/{android-ui-minimal → android-ui}/scripts/lint_ui.py +29 -29
  20. package/{android-ui-security-review → android-ui}/scripts/scan.py +146 -146
  21. package/bin/android-skills.js +10 -10
  22. package/install.py +79 -65
  23. package/opencode/commands/ui.md +13 -0
  24. package/package.json +2 -3
  25. package/android-ui-minimal/SKILL.md +0 -98
  26. package/android-ui-minimal/references/anti-slop-checklist.md +0 -61
  27. package/android-ui-minimal/references/clarifying-questions.md +0 -55
  28. package/android-ui-minimal/references/color-and-contrast.md +0 -104
  29. package/android-ui-minimal/references/compose-patterns.md +0 -120
  30. package/android-ui-minimal/references/reconstruction-workflow.md +0 -74
  31. package/android-ui-minimal/references/typography-spacing.md +0 -93
  32. package/android-ui-security-review/SKILL.md +0 -93
  33. package/android-ui-security-review/references/checklist.md +0 -95
  34. package/android-ui-security-review/references/components-intents.md +0 -74
  35. package/android-ui-security-review/references/compose-risks.md +0 -86
  36. package/android-ui-security-review/references/input-and-state.md +0 -77
  37. package/android-ui-security-review/references/network-storage.md +0 -87
  38. package/android-ui-security-review/references/report-template.md +0 -71
  39. package/android-ui-security-review/references/sensitive-data-ui.md +0 -73
  40. package/android-ui-security-review/references/webview.md +0 -105
  41. package/opencode/commands/ui-minimal.md +0 -9
  42. package/opencode/commands/ui-security.md +0 -9
@@ -0,0 +1,55 @@
1
+ # When to ask
2
+
3
+ Asking is mandatory, not optional, when any of the conditions below holds. The goal is to prevent building the wrong thing and wasting the user's time.
4
+
5
+ ## Trigger conditions
6
+
7
+ 1. **Platform unclear.** It is not visible whether the project uses Jetpack Compose, XML Views, or a mix. Check `build.gradle(.kts)` first (`buildFeatures { compose = true }`). If still unclear, ask.
8
+ 2. **Screen purpose unclear.** "Make a nice page" without knowing what it does.
9
+ 3. **Conflicting visual references.** E.g. the user asks for minimalism but attaches a dense, colorful screenshot.
10
+ 4. **Real data unknown.** What is in the list, how many items, maximum text length, with images or not.
11
+ 5. **Large scope.** The request touches more than 3 screens, or changes the global theme.
12
+ 6. **Brand color mentioned but not given.** The user says "my app's color" without values.
13
+ 7. **A choice that changes a lot of code.** E.g. changing the font, changing navigation, changing the state pattern.
14
+ 8. **Language and content.** UI text in English or another language, or both (needs separate `strings.xml`).
15
+
16
+ ## When not to ask
17
+
18
+ - Small, clear changes (adjust padding, tidy one button).
19
+ - The answer can be read from the existing code. Read the code before asking.
20
+ - Questions whose answer has a safe default. Take the default, state it at the top of the report, and proceed.
21
+
22
+ ## Question format
23
+
24
+ - At most 4 questions at once.
25
+ - One question, one thing.
26
+ - Give 2–4 options and mark the recommendation.
27
+ - Write in the language the user is using.
28
+ - Do not ask what the user already answered in a previous message.
29
+
30
+ ## Template
31
+
32
+ ```
33
+ Before starting, a few things to confirm:
34
+
35
+ 1. Does this project use Compose or XML Views?
36
+ a. Compose (recommended — I see compose = true in build.gradle)
37
+ b. XML Views
38
+ c. Mixed
39
+
40
+ 2. Which accent color?
41
+ a. Keep the current color (#xxxxxx)
42
+ b. Suggest one cool-neutral accent
43
+ c. I'll provide my own hex value
44
+
45
+ 3. How many items does this screen usually show, and are there images?
46
+ (Affects the choice of list, card, or plain rows)
47
+ ```
48
+
49
+ ## After the user answers
50
+
51
+ Summarize the decisions in one short block ("Decision: Compose, accent steel-blue #3B5BA9, plain rows without cards"), then proceed. Do not re-ask the same things.
52
+
53
+ ## If the user does not reply or is unreachable
54
+
55
+ Take the most conservative assumptions, write the assumption list at the top of the report, and make the changes easy to swap (tokens, not scattered values).
@@ -0,0 +1,104 @@
1
+ # Color and contrast
2
+
3
+ Goal: the UI looks calm and clear without looking "lacking" (washed out, flat, boundary-less). The trick is not more colors, but enough neutral depth plus one consistent accent.
4
+
5
+ ## Palette structure
6
+
7
+ A screen only needs these roles:
8
+
9
+ | Role | Function | Material 3 |
10
+ |---|---|---|
11
+ | Background | Screen base | `background` |
12
+ | Surface | Content areas, bars | `surface` |
13
+ | Surface variant (tonal) | Subtle separation, fields, chips | `surfaceVariant`, `surfaceContainer*` |
14
+ | Outline | Thin lines | `outlineVariant` |
15
+ | Text primary | Headings, body | `onSurface` |
16
+ | Text secondary | Descriptions | `onSurfaceVariant` |
17
+ | Accent | Primary actions, active state | `primary` / `onPrimary` |
18
+ | Error | Errors | `error` |
19
+
20
+ If all roles above are filled, the UI rarely looks lacking. The problem usually appears when only two levels exist (white and light gray), so there is no hierarchy.
21
+
22
+ ## Rules so it does not look lacking
23
+
24
+ 1. **At least 3 neutral depth levels** per theme: background, surface, and a higher surface or variant. Luminance difference between levels around 3–6 percent.
25
+ 2. **Use the accent sparingly but consistently**: primary buttons, selected state, focus indicators, links. Do not use it as a large-area background.
26
+ 3. **Secondary text stays readable.** Never lower text opacity below 4.5:1. Avoid `alpha = 0.38` for text that must be read.
27
+ 4. **Separators exist**, but are subtle: space first, then tonal shift, then a 1dp `outlineVariant` line.
28
+ 5. **Status colors** (error, success, warning) may sit outside the single accent, but always paired with text or an icon, not color alone.
29
+ 6. **Dark mode is designed**, not inverted. Dark: background around `#0F1114` to `#141619`, surfaces stepping up. The accent is softened (lower chroma, lighter) so it does not vibrate.
30
+ 7. **Grayscale test.** Convert the screenshot to black and white. The hierarchy must still read.
31
+
32
+ ## Choosing an accent
33
+
34
+ - If the user has a brand color, use it. Derive its tonal steps, do not change the hue.
35
+ - If not, pick one hue with medium chroma. Avoid neon purple-blue and gradients. Safe picks: steel blue, dark teal green, terracotta, olive green, dark indigo.
36
+ - Do not use more than one accent hue. If categories need differentiation, differentiate with shape, labels, or icons.
37
+ - Generate tokens automatically: `python3 scripts/gen_tokens.py "#3B5BA9"`.
38
+
39
+ ## Example palettes (neutral, ready to use)
40
+
41
+ Light:
42
+
43
+ | Token | Hex |
44
+ |---|---|
45
+ | background | `#F7F7F5` |
46
+ | surface | `#FFFFFF` |
47
+ | surfaceVariant | `#EFEFEC` |
48
+ | outlineVariant | `#DADAD5` |
49
+ | onSurface | `#1B1C1A` |
50
+ | onSurfaceVariant | `#5B5D58` |
51
+ | primary | `#3B5BA9` |
52
+ | onPrimary | `#FFFFFF` |
53
+ | error | `#B3261E` |
54
+
55
+ Dark:
56
+
57
+ | Token | Hex |
58
+ |---|---|
59
+ | background | `#121312` |
60
+ | surface | `#1A1B1A` |
61
+ | surfaceVariant | `#252624` |
62
+ | outlineVariant | `#3A3B38` |
63
+ | onSurface | `#E6E6E2` |
64
+ | onSurfaceVariant | `#A9AAA4` |
65
+ | primary | `#9DB4F0` |
66
+ | onPrimary | `#14224A` |
67
+ | error | `#F2B8B5` |
68
+
69
+ Verify before using: `python3 scripts/contrast.py "#5B5D58" "#F7F7F5"`.
70
+
71
+ ## Contrast (WCAG 2.2)
72
+
73
+ - Normal text: at least 4.5:1.
74
+ - Large text (18sp or 14sp bold) and UI components (field borders, action icons): at least 3:1.
75
+ - Disabled state may be lower, but never use it for important information.
76
+ - Text over images: use a solid scrim, do not rely on the image.
77
+
78
+ ## Compose implementation
79
+
80
+ ```kotlin
81
+ private val LightColors = lightColorScheme(
82
+ primary = Color(0xFF3B5BA9),
83
+ onPrimary = Color(0xFFFFFFFF),
84
+ background = Color(0xFFF7F7F5),
85
+ surface = Color(0xFFFFFFFF),
86
+ surfaceVariant = Color(0xFFEFEFEC),
87
+ outlineVariant = Color(0xFFDADAD5),
88
+ onSurface = Color(0xFF1B1C1A),
89
+ onSurfaceVariant = Color(0xFF5B5D58),
90
+ error = Color(0xFFB3261E),
91
+ )
92
+ ```
93
+
94
+ Hex values may only appear in this theme file. In screens, use `MaterialTheme.colorScheme.primary` and so on.
95
+
96
+ Dynamic color (Material You): do not enable by default when the user has a brand color. Make it an option and ask.
97
+
98
+ ## Anti-patterns
99
+
100
+ - Pure white `#FFFFFF` as the main background everywhere, plus pure black text.
101
+ - Pure black `#000000` + pure white text (halos, tiring), except OLED-first.
102
+ - Gray via opacity over other colors (unpredictable results). Use solid colors from tokens.
103
+ - Random color per component for "variety".
104
+ - Accent gradients on buttons, headers, and backgrounds.
@@ -0,0 +1,74 @@
1
+ # Components, intents, deep links
2
+
3
+ ## Exported
4
+
5
+ Since target SDK 31, components with an `intent-filter` require an explicit `android:exported`. Rules:
6
+ - Default `false`. Change to `true` only when other apps must call it.
7
+ - A launcher activity must be exported. Other activities usually are not.
8
+ - Exported services, receivers, and providers must be protected with `android:permission` (signature) unless intentionally public.
9
+ - Check the merged manifest, because libraries can add exported components.
10
+
11
+ ## Activities receiving data from outside
12
+
13
+ Treat `intent.extras`, `intent.data`, and `intent.action` as untrusted input.
14
+
15
+ ```kotlin
16
+ val id = intent.getStringExtra("id")?.takeIf { it.matches(Regex("[A-Za-z0-9_-]{1,64}")) }
17
+ ?: return finish()
18
+ ```
19
+
20
+ Do not:
21
+ - Pass an extra directly into a query, file path, WebView URL, or `startActivity`.
22
+ - Assume the extra type is correct. Use the typed API version (`getParcelableExtra(key, Clazz::class.java)`) and handle null.
23
+ - Trust `callingPackage` as authentication.
24
+
25
+ ## Intent redirection
26
+
27
+ Dangerous pattern:
28
+
29
+ ```kotlin
30
+ val forward = intent.getParcelableExtra<Intent>("next")
31
+ startActivity(forward) // attacker picks the destination, including private components
32
+ ```
33
+
34
+ Fix: do not accept an Intent in extras. If unavoidable, resolve it and restrict the destination to an allowlist of components, strip `FLAG_GRANT_*_URI_PERMISSION`, and do not launch with elevated rights.
35
+
36
+ ## Deep links
37
+
38
+ - Validate scheme, host, path, and every parameter.
39
+ - Use verified App Links (`autoVerify="true"`, `assetlinks.json`) for https.
40
+ - Custom schemes can be hijacked by other apps. Never send tokens over a custom scheme.
41
+ - Do not skip authentication just because the entry came from a deep link. Check the session before showing a sensitive screen.
42
+ - Be careful with `redirect`, `url`, `next` parameters. Allowlist destinations to prevent open redirects.
43
+ - Navigation Compose arguments from deep links are still untrusted input.
44
+
45
+ ## PendingIntent
46
+
47
+ - Always set `FLAG_IMMUTABLE` unless it truly must be filled in later (`FLAG_MUTABLE`).
48
+ - The intent inside is explicit (component or package set). No empty Intent.
49
+ - For notifications, do not embed sensitive data in extras.
50
+
51
+ ## Broadcasts
52
+
53
+ - `registerReceiver` on Android 13+ requires `RECEIVER_NOT_EXPORTED` for internal broadcasts.
54
+ - `sendBroadcast` with sensitive data: restrict to your own package (`setPackage`) or use a permission.
55
+ - Consider in-process alternatives (Flow, SharedFlow) instead of broadcasts.
56
+
57
+ ## FileProvider and file sharing
58
+
59
+ - Define paths as narrow as possible, never `root-path` or `.`
60
+ - Use `FileProvider.getUriForFile`, not `Uri.fromFile`.
61
+ - Grant `FLAG_GRANT_READ_URI_PERMISSION` only to a specific receiver on the Intent being sent; do not make the provider exported.
62
+ - Validate user-supplied file names (strip `..`, path separators) before writing.
63
+
64
+ ## Sharing and receiving content
65
+
66
+ - `ACTION_SEND` activities receive text or Uris from any app. Validate size, MIME type, and Uri scheme (`content` only, not `file`).
67
+ - Copy into private storage before processing. Do not open `content://` with a path from input.
68
+
69
+ ## Tapjacking
70
+
71
+ Screens that trigger sensitive actions with a single tap can be overlaid.
72
+ - Views: `filterTouchesWhenObscured = true`.
73
+ - Compose: read `LocalView.current` and set the same property on the root view, or check `MotionEvent.FLAG_WINDOW_IS_OBSCURED` and refuse the action.
74
+ - For critical confirmations, add an explicit step (a dialog with clear text).
@@ -0,0 +1,120 @@
1
+ # Compose patterns (and XML equivalents)
2
+
3
+ ## File structure
4
+
5
+ ```
6
+ ui/
7
+ theme/Color.kt Type.kt Theme.kt Spacing.kt
8
+ components/ (small reusable components)
9
+ screen/<name>/ <Name>Screen.kt <Name>ViewModel.kt <Name>UiState.kt
10
+ ```
11
+
12
+ Rule: one screen composable receives `state` and `onEvent` (state hoisting). No repository or network access inside composables.
13
+
14
+ ## Screen skeleton
15
+
16
+ ```kotlin
17
+ @Composable
18
+ fun NotesScreen(
19
+ state: NotesUiState,
20
+ onEvent: (NotesEvent) -> Unit,
21
+ modifier: Modifier = Modifier,
22
+ ) {
23
+ Scaffold(
24
+ modifier = modifier,
25
+ topBar = { NotesTopBar(onSearch = { onEvent(NotesEvent.OpenSearch) }) },
26
+ containerColor = MaterialTheme.colorScheme.background,
27
+ ) { inner ->
28
+ when (state) {
29
+ NotesUiState.Loading -> LoadingBox(Modifier.padding(inner))
30
+ is NotesUiState.Error -> ErrorBox(state.message, { onEvent(NotesEvent.Retry) }, Modifier.padding(inner))
31
+ is NotesUiState.Content ->
32
+ if (state.items.isEmpty()) EmptyBox("No notes yet", Modifier.padding(inner))
33
+ else NotesList(state.items, { onEvent(NotesEvent.Open(it)) }, Modifier.padding(inner))
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ ## Plain list rows (no cards)
40
+
41
+ ```kotlin
42
+ @Composable
43
+ fun NoteRow(title: String, subtitle: String, onClick: () -> Unit) {
44
+ Column(
45
+ Modifier
46
+ .fillMaxWidth()
47
+ .clickable(onClick = onClick)
48
+ .heightIn(min = 56.dp)
49
+ .padding(horizontal = Space.lg, vertical = Space.md),
50
+ verticalArrangement = Arrangement.spacedBy(Space.xs),
51
+ ) {
52
+ Text(title, style = MaterialTheme.typography.titleMedium, maxLines = 1, overflow = TextOverflow.Ellipsis)
53
+ Text(subtitle, style = MaterialTheme.typography.bodyMedium,
54
+ color = MaterialTheme.colorScheme.onSurfaceVariant, maxLines = 2, overflow = TextOverflow.Ellipsis)
55
+ }
56
+ }
57
+ ```
58
+
59
+ Divider: `HorizontalDivider(color = MaterialTheme.colorScheme.outlineVariant)` with a 16dp inset.
60
+
61
+ ## Buttons
62
+
63
+ - Primary action: `Button` (one per screen).
64
+ - Secondary: `OutlinedButton` or `TextButton`.
65
+ - Minimum height 48dp. Full width only for the primary action in a form or bottom bar.
66
+
67
+ ## Edge-to-edge and insets
68
+
69
+ ```kotlin
70
+ // Activity
71
+ enableEdgeToEdge()
72
+ // Scaffold already applies inner padding. For manual content:
73
+ Modifier.windowInsetsPadding(WindowInsets.safeDrawing)
74
+ ```
75
+
76
+ Use `imePadding()` for screens with fields.
77
+
78
+ ## Required previews
79
+
80
+ ```kotlin
81
+ @Preview(name = "Light") @Composable private fun P1() = AppTheme(darkTheme = false) { NotesScreen(sampleState, {}) }
82
+ @Preview(name = "Dark", uiMode = UI_MODE_NIGHT_YES) @Composable private fun P2() = AppTheme(darkTheme = true) { NotesScreen(sampleState, {}) }
83
+ @Preview(name = "Large font", fontScale = 1.5f) @Composable private fun P3() = AppTheme { NotesScreen(sampleState, {}) }
84
+ ```
85
+
86
+ ## Accessibility
87
+
88
+ ```kotlin
89
+ Icon(Icons.Outlined.Delete, contentDescription = "Delete note")
90
+ Modifier.semantics { heading() } // section heading
91
+ Modifier.clearAndSetSemantics { } // decorative
92
+ Modifier.minimumInteractiveComponentSize() // 48dp target
93
+ ```
94
+
95
+ ## Basic performance
96
+
97
+ - `remember` for expensive objects, `derivedStateOf` for derived state.
98
+ - Stable lambda parameters. Avoid creating new objects on every recomposition inside a list.
99
+ - `LazyColumn(key = { it.id }, contentType = { ... })`.
100
+ - Images: Coil with fixed sizes so they do not jump.
101
+
102
+ ## XML Views equivalents
103
+
104
+ | Compose | XML |
105
+ |---|---|
106
+ | `MaterialTheme.colorScheme.*` | Theme attributes `?attr/colorSurface`, `?attr/colorOnSurface` |
107
+ | `Space.lg` | `@dimen/space_lg` (in `dimens.xml`) |
108
+ | `typography.titleMedium` | `?attr/textAppearanceTitleMedium` |
109
+ | `Scaffold` | `CoordinatorLayout` + `MaterialToolbar` |
110
+ | `LazyColumn` | `RecyclerView` + `ListAdapter` + `DiffUtil` |
111
+
112
+ No hex colors in XML layouts. Define them in `colors.xml` and `values-night/colors.xml`, reference them via theme attributes.
113
+
114
+ ## Do not
115
+
116
+ - `Color(0xFF...)` inside screens.
117
+ - Ad-hoc `fontSize = 15.sp`.
118
+ - `Modifier.padding(13.dp)` off-scale numbers.
119
+ - Calling `viewModel()` inside a small reusable component.
120
+ - Hiding important content behind gestures without an alternative.
@@ -0,0 +1,86 @@
1
+ # Jetpack Compose-specific risks
2
+
3
+ ## Persisted state
4
+
5
+ - `rememberSaveable` stores values in the Bundle (restorable after process death, visible in debug tools). Do not use it for passwords, PINs, tokens.
6
+ - `SavedStateHandle` in a ViewModel carries the same risk.
7
+ - Use `remember` for secrets and clear it when the screen leaves composition (`DisposableEffect`).
8
+
9
+ ```kotlin
10
+ var pin by remember { mutableStateOf("") }
11
+ DisposableEffect(Unit) { onDispose { pin = "" } }
12
+ ```
13
+
14
+ JVM strings cannot be wiped from memory with certainty. Do not claim "safely deleted"; you only shortened the reference's lifetime.
15
+
16
+ ## Text fields
17
+
18
+ ```kotlin
19
+ OutlinedTextField(
20
+ value = password,
21
+ onValueChange = { password = it },
22
+ visualTransformation = if (visible) VisualTransformation.None else PasswordVisualTransformation(),
23
+ keyboardOptions = KeyboardOptions(
24
+ keyboardType = KeyboardType.Password,
25
+ autoCorrectEnabled = false,
26
+ imeAction = ImeAction.Done,
27
+ ),
28
+ singleLine = true,
29
+ )
30
+ ```
31
+
32
+ - The show-password toggle is temporary. Hide it again when the screen loses focus or the app goes to background.
33
+ - Use `Modifier.semantics { password() }` so accessibility services and autofill treat it as a password.
34
+ - Limit input length (`onValueChange = { if (it.length <= 64) ... }`).
35
+
36
+ ## Semantics and accessibility
37
+
38
+ - `contentDescription` and `stateDescription` are read by accessibility services. Do not put secret data in them.
39
+ - For content that must not be read by accessibility services, use `Modifier.clearAndSetSemantics { }` or `invisibleToUser()` carefully, while still providing an alternative for users who need it.
40
+ - A malicious accessibility service can read the screen. For the most sensitive screens, consider FLAG_SECURE and checking for active accessibility services.
41
+
42
+ ## AndroidView and interop
43
+
44
+ - `AndroidView { WebView(it) }` inherits all WebView risks (see `webview.md`).
45
+ - Release resources in `onRelease`. Do not hold an Activity Context in long-lived objects.
46
+
47
+ ## Navigation
48
+
49
+ - Route arguments are strings on the back stack and in deep links. Do not pass sensitive objects as arguments. Pass an ID, fetch data from the repository.
50
+ - `navDeepLink` exposes the route externally. Check authentication at the destination, not only on the first screen.
51
+ - Make sure `popUpTo` after login/logout clears the back stack so the user cannot return to a sensitive screen.
52
+
53
+ ## Previews and sample data
54
+
55
+ - No real data, tokens, or internal URLs in `@Preview` or sample data. It ends up in the repo.
56
+ - Preview code ships in the APK unless wrapped in the debug source set. Use `debugImplementation` for preview tooling.
57
+
58
+ ## Sensitive screens
59
+
60
+ - Set FLAG_SECURE on the host Activity. Compose single-activity means the flag applies to every screen. Set it dynamically per route:
61
+
62
+ ```kotlin
63
+ @Composable
64
+ fun SecureScreen(content: @Composable () -> Unit) {
65
+ val window = (LocalContext.current as Activity).window
66
+ DisposableEffect(Unit) {
67
+ window.addFlags(WindowManager.LayoutParams.FLAG_SECURE)
68
+ onDispose { window.clearFlags(WindowManager.LayoutParams.FLAG_SECURE) }
69
+ }
70
+ content()
71
+ }
72
+ ```
73
+
74
+ ## Dialogs and overlays
75
+
76
+ - Compose dialogs create their own window. `DialogProperties(securePolicy = SecureFlagPolicy.SecureOn)` sets FLAG_SECURE for sensitive dialogs.
77
+ - Triggers for destructive or financial actions in dialogs are still vulnerable to tapjacking. See `components-intents.md`.
78
+
79
+ ## Side effects
80
+
81
+ - A `LaunchedEffect` that sends data over the network based on user input can fire repeatedly on recomposition or configuration changes. Make effect keys correct so a sensitive action is not sent twice.
82
+
83
+ ## Third-party UI libraries
84
+
85
+ - Review the permissions and components they add via manifest merge.
86
+ - Pin versions and track security updates. Avoid unmaintained libraries for sensitive tasks (WebView wrappers, QR scanners, card input).
@@ -0,0 +1,77 @@
1
+ # Inputs and state from outside
2
+
3
+ Any value not produced directly by your code is untrusted: user input, intent extras, deep links, network responses, file contents, clipboard, `ContentResolver` results, navigation arguments, QR contents.
4
+
5
+ ## Validation
6
+
7
+ - Validate at the entry boundary (ViewModel or use case), not scattered across composables.
8
+ - Use allowlists, not blocklists: length, characters, ranges, enums.
9
+ - Parse into strong types as early as possible (`UUID`, `Int`, `enum`), handle failures.
10
+ - Client validation is for UX only. The server still re-validates.
11
+
12
+ ```kotlin
13
+ fun parseAmount(raw: String): Long? =
14
+ raw.takeIf { it.length <= 12 && it.all(Char::isDigit) }?.toLongOrNull()
15
+ ?.takeIf { it in 1..100_000_000 }
16
+ ```
17
+
18
+ ## Injection
19
+
20
+ | Context | Risk | Prevent |
21
+ |---|---|---|
22
+ | SQLite | SQL injection | Parameter binding, Room |
23
+ | WebView | XSS, JS injection | Do not build HTML/JS, escaped JSON |
24
+ | Intent / URI | Redirection, open redirect | Allowlist schemes and hosts |
25
+ | File | Path traversal | `canonicalPath` + base directory |
26
+ | Regex | ReDoS | Avoid nested-iteration patterns on user input, limit length |
27
+ | String format | Leaks | Never use user input as the format |
28
+
29
+ Path traversal:
30
+
31
+ ```kotlin
32
+ val base = File(context.filesDir, "uploads").canonicalFile
33
+ val target = File(base, name).canonicalFile
34
+ require(target.path.startsWith(base.path + File.separator)) { "invalid path" }
35
+ ```
36
+
37
+ ## Deep links and navigation arguments
38
+
39
+ ```kotlin
40
+ composable("detail/{id}") { entry ->
41
+ val id = entry.arguments?.getString("id")?.toLongOrNull() ?: return@composable
42
+ // check authorization: may this user see this id?
43
+ }
44
+ ```
45
+
46
+ An ID in a URL is not authorization. Check access rights on the server (IDOR).
47
+
48
+ ## QR and camera content
49
+
50
+ - Treat as untrusted URLs. Show the destination to the user before opening.
51
+ - Restrict schemes (`https`). Do not open `intent://` or `javascript:`.
52
+
53
+ ## Network responses
54
+
55
+ - Use typed data models, ignore unknown fields, handle missing fields.
56
+ - Limit response sizes and the number of items rendered.
57
+ - Do not render HTML from responses unless sanitized.
58
+ - Server-provided image URLs: allow https only, limit decode size (`size(...)` in Coil).
59
+
60
+ ## Displayed text
61
+
62
+ - User text shown in `Text` is safe from HTML injection. Risk appears when using `Html.fromHtml`, `AnnotatedString` from markup, or WebView.
63
+ - Limit text length and lines (`maxLines`, `overflow`) so the layout does not break.
64
+ - Watch for bidirectional control characters in file names or usernames shown in confirmation UIs.
65
+
66
+ ## Races and state
67
+
68
+ - Prevent double submission on sensitive actions: disable the button while in flight, use an idempotency key on the server.
69
+ - Do not decide security from UI state (`isAdmin` in the ViewModel). The server decides.
70
+ - After process death, UI state can be restored with stale values. Re-verify the session before sensitive actions.
71
+
72
+ ## Client-side validation that is often wrong
73
+
74
+ - Hiding a button is not access control.
75
+ - Obfuscation (R8) is not encryption.
76
+ - Root or emulator detection is not a security boundary.
77
+ - Client-only PIN attempt limiting can be bypassed.
@@ -0,0 +1,87 @@
1
+ # Network and storage (UI perspective)
2
+
3
+ ## Cleartext
4
+
5
+ - Manifest: do not set `usesCleartextTraffic="true"`.
6
+ - Target SDK 28+ blocks cleartext by default. Exceptions must go through `network_security_config` and stay narrow.
7
+ - All API, image, and WebView URLs use `https://`.
8
+
9
+ ## network_security_config
10
+
11
+ Safe example for release:
12
+
13
+ ```xml
14
+ <network-security-config>
15
+ <base-config cleartextTrafficPermitted="false">
16
+ <trust-anchors>
17
+ <certificates src="system" />
18
+ </trust-anchors>
19
+ </base-config>
20
+ <debug-overrides>
21
+ <trust-anchors>
22
+ <certificates src="user" />
23
+ </trust-anchors>
24
+ </debug-overrides>
25
+ </network-security-config>
26
+ ```
27
+
28
+ Do not trust user CAs (`src="user"`) in release.
29
+
30
+ ## Certificate pinning
31
+
32
+ For high-risk apps (finance, health), pinning reduces fake-CA risk. But:
33
+ - Pin to the public key (SPKI), include at least one backup.
34
+ - Have a rotation and expiry plan. A wrong pin makes the app unable to connect.
35
+ - Pinning is not a replacement for server validation.
36
+
37
+ ```kotlin
38
+ val pinner = CertificatePinner.Builder()
39
+ .add("api.example.com", "sha256/AAAA...=", "sha256/BBBB...=")
40
+ .build()
41
+ ```
42
+
43
+ ## Custom TrustManager and HostnameVerifier
44
+
45
+ Never implement one that accepts all certificates or all hosts, including "temporarily for dev". For dev servers with self-signed certs, register the dev CA in `debug-overrides`.
46
+
47
+ ## Storage
48
+
49
+ | Data type | Where |
50
+ |---|---|
51
+ | Session tokens | Encrypted private storage with an Android Keystore key |
52
+ | Non-sensitive preferences | DataStore or SharedPreferences |
53
+ | Image cache | Private cache, clear on logout |
54
+ | User files | `filesDir` (private) or SAF/MediaStore at the user's choice |
55
+
56
+ Note: `EncryptedSharedPreferences` from `androidx.security:security-crypto` is marked deprecated in recent releases. Check the version you use and consider Keystore directly, or Tink with an encrypted DataStore.
57
+
58
+ Rules:
59
+ - Store the minimum. Short-lived tokens + revocable refresh tokens.
60
+ - Encryption keys never in source or in assets.
61
+ - Use `setUserAuthenticationRequired(true)` for keys guarding the most sensitive data.
62
+ - Do not store passwords. Store tokens.
63
+
64
+ ## Backups
65
+
66
+ - `android:allowBackup="false"`, or define `dataExtractionRules` (Android 12+) and `fullBackupContent` excluding databases, tokens, and sensitive preferences.
67
+
68
+ ## Files and shared storage
69
+
70
+ - Avoid writing sensitive data to external storage or MediaStore.
71
+ - Delete temporary files after use.
72
+ - Be careful with file names from the server or from users.
73
+
74
+ ## Secrets in the app
75
+
76
+ - Anything in the APK can be extracted: strings, resources, BuildConfig, assets, native libraries.
77
+ - API keys that must live on the client (maps, analytics) must be restricted provider-side (package name + SHA-1, API allowlist, quotas).
78
+ - Full-access secrets (server keys, cloud service keys) do not belong on the client. Move them to the backend or a proxy.
79
+ - If one was committed: revoke and rotate first, then clean git history.
80
+ - For BYOK apps (the user enters their own API key): store encrypted in Keystore, do not log, do not put in crash reports, do not send anywhere except the intended provider, mask when displayed.
81
+
82
+ ## Release
83
+
84
+ - Enable R8 (`isMinifyEnabled = true`) and `isShrinkResources` for release.
85
+ - Sign with a key stored securely, not in the repo.
86
+ - Ensure `debuggable` is false, logging off, WebView debugging off.
87
+ - Use the Play Integrity API where needed, with server-side verification.
@@ -0,0 +1,74 @@
1
+ # UI reconstruction workflow
2
+
3
+ Used when the user provides a screenshot, an old screen, or a description and asks for a cleaner rebuild.
4
+
5
+ ## 1. Inventory
6
+
7
+ Write down what is on the screen, without judging:
8
+ - Elements (headings, lists, fields, buttons, navigation)
9
+ - Data displayed
10
+ - Actions available
11
+ - Visible states (empty, loading, error, selected)
12
+
13
+ If from a screenshot, name what cannot be confirmed (font, original sizes, exact colors) and ask if it matters.
14
+
15
+ ## 2. Set the hierarchy
16
+
17
+ Answer three things:
18
+ 1. What is this screen's one primary purpose?
19
+ 2. What is the one primary action?
20
+ 3. What can be dropped or moved to another screen?
21
+
22
+ Elements that do not answer those three questions are candidates for removal or demotion.
23
+
24
+ ## 3. Map to tokens
25
+
26
+ Replace every ad-hoc value with a token:
27
+ - Color: pick the closest role (`surface`, `onSurfaceVariant`, `primary`).
28
+ - Spacing: round to the 4dp scale.
29
+ - Typography: pick the closest style from the scale.
30
+ - Radius: pick from the three levels.
31
+
32
+ Note mappings that change the appearance meaningfully, for the report.
33
+
34
+ ## 4. Simplify
35
+
36
+ Pruning order:
37
+ 1. Remove decoration without function (gradients, stacked shadows, ornamental icons).
38
+ 2. Merge nested containers (card inside card).
39
+ 3. Align everything to one left edge.
40
+ 4. Reduce the number of text styles.
41
+ 5. Reduce colors to one accent + neutrals.
42
+
43
+ ## 5. Build
44
+
45
+ Follow `compose-patterns.md`. Start from state and events, then composition, then previews.
46
+
47
+ ## 6. Verify
48
+
49
+ - Previews: light, dark, font scale 1.5, width 360dp.
50
+ - `python3 scripts/lint_ui.py <path>`.
51
+ - Contrast of the main color pairs.
52
+ - The checklist in `anti-slop-checklist.md`.
53
+
54
+ ## 7. Report
55
+
56
+ Short format:
57
+
58
+ ```
59
+ Done: <screen>
60
+ Decisions: <accent, list structure, etc.>
61
+ Changed: <files>
62
+ Deliberately not done: <things left unchanged and why>
63
+ Needs confirmation: <if any>
64
+ ```
65
+
66
+ ## Preserving behavior
67
+
68
+ Reconstruction must not change behavior. Preserve:
69
+ - Public function names and signatures called from outside the screen
70
+ - Navigation and route arguments
71
+ - Test IDs (`testTag`, `android:id`) already in use
72
+ - Text referenced by tests or localization (change via `strings.xml`, never hardcode)
73
+
74
+ If you must change any of them, state it explicitly in the report.