commit 6487becf60c2ccdb80b3a6d7e3571a9e0cd588c3 Author: shihao <3127647737@qq.com> Date: Fri Apr 10 16:52:49 2026 +0800 Initial commit: add all skills files Co-Authored-By: Claude Opus 4.6 (1M context) diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..e587e28 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,7 @@ +{ + "permissions": { + "allow": [ + "Bash(cd:*)" + ] + } +} diff --git a/android-native-dev/SKILL.md b/android-native-dev/SKILL.md new file mode 100644 index 0000000..a42a363 --- /dev/null +++ b/android-native-dev/SKILL.md @@ -0,0 +1,782 @@ +--- +name: android-native-dev +description: Android native application development and UI design guide. Covers Material Design 3, Kotlin/Compose development, project configuration, accessibility, and build troubleshooting. Read this before Android native application development. +license: MIT +metadata: + version: "1.0.0" + category: mobile + sources: + - Material Design 3 Guidelines (material.io) + - Android Developer Documentation (developer.android.com) + - Google Play Quality Guidelines + - WCAG Accessibility Guidelines +--- + +## 1. Project Scenario Assessment + +Before starting development, assess the current project state: + +| Scenario | Characteristics | Approach | +|----------|-----------------|----------| +| **Empty Directory** | No files present | Full initialization required, including Gradle Wrapper | +| **Has Gradle Wrapper** | `gradlew` and `gradle/wrapper/` exist | Use `./gradlew` directly for builds | +| **Android Studio Project** | Complete project structure, may lack wrapper | Check wrapper, run `gradle wrapper` if needed | +| **Incomplete Project** | Partial files present | Check missing files, complete configuration | + +**Key Principles**: +- Before writing business logic, ensure `./gradlew assembleDebug` succeeds +- If `gradle.properties` is missing, create it first and configure AndroidX + +### 1.1 Required Files Checklist + +``` +MyApp/ +├── gradle.properties # Configure AndroidX and other settings +├── settings.gradle.kts +├── build.gradle.kts # Root level +├── gradle/wrapper/ +│ └── gradle-wrapper.properties +├── app/ +│ ├── build.gradle.kts # Module level +│ └── src/main/ +│ ├── AndroidManifest.xml +│ ├── java/com/example/myapp/ +│ │ └── MainActivity.kt +│ └── res/ +│ ├── values/ +│ │ ├── strings.xml +│ │ ├── colors.xml +│ │ └── themes.xml +│ └── mipmap-*/ # App icons +``` + +--- + +## 2. Project Configuration + +### 2.1 gradle.properties + +```properties +# Required configuration +android.useAndroidX=true +android.enableJetifier=true + +# Build optimization +org.gradle.parallel=true +kotlin.code.style=official + +# JVM memory settings (adjust based on project size) +# Small projects: 2048m, Medium: 4096m, Large: 8192m+ +# org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8 +``` + +> **Note**: If you encounter `OutOfMemoryError` during build, increase `-Xmx` value. Large projects with many dependencies may require 8GB or more. + +### 2.2 Dependency Declaration Standards + +```kotlin +dependencies { + // Use BOM to manage Compose versions + implementation(platform("androidx.compose:compose-bom:2024.02.00")) + implementation("androidx.compose.ui:ui") + implementation("androidx.compose.material3:material3") + + // Activity & ViewModel + implementation("androidx.activity:activity-compose:1.8.2") + implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.7.0") +} +``` + +### 2.3 Build Variants & Product Flavors + +Product Flavors allow you to create different versions of your app (e.g., free/paid, dev/staging/prod). + +**Configuration in app/build.gradle.kts**: + +```kotlin +android { + // Define flavor dimensions + flavorDimensions += "environment" + + productFlavors { + create("dev") { + dimension = "environment" + applicationIdSuffix = ".dev" + versionNameSuffix = "-dev" + + // Different config values per flavor + buildConfigField("String", "API_BASE_URL", "\"https://dev-api.example.com\"") + buildConfigField("Boolean", "ENABLE_LOGGING", "true") + + // Different resources + resValue("string", "app_name", "MyApp Dev") + } + + create("staging") { + dimension = "environment" + applicationIdSuffix = ".staging" + versionNameSuffix = "-staging" + + buildConfigField("String", "API_BASE_URL", "\"https://staging-api.example.com\"") + buildConfigField("Boolean", "ENABLE_LOGGING", "true") + resValue("string", "app_name", "MyApp Staging") + } + + create("prod") { + dimension = "environment" + // No suffix for production + + buildConfigField("String", "API_BASE_URL", "\"https://api.example.com\"") + buildConfigField("Boolean", "ENABLE_LOGGING", "false") + resValue("string", "app_name", "MyApp") + } + } + + buildTypes { + debug { + isDebuggable = true + isMinifyEnabled = false + } + release { + isDebuggable = false + isMinifyEnabled = true + proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro") + } + } +} +``` + +**Build Variant Naming**: `{flavor}{BuildType}` → e.g., `devDebug`, `prodRelease` + +**Gradle Build Commands**: + +```bash +# List all available build variants +./gradlew tasks --group="build" + +# Build specific variant (flavor + buildType) +./gradlew assembleDevDebug # Dev flavor, Debug build +./gradlew assembleStagingDebug # Staging flavor, Debug build +./gradlew assembleProdRelease # Prod flavor, Release build + +# Build all variants of a specific flavor +./gradlew assembleDev # All Dev variants (debug + release) +./gradlew assembleProd # All Prod variants + +# Build all variants of a specific build type +./gradlew assembleDebug # All flavors, Debug build +./gradlew assembleRelease # All flavors, Release build + +# Install specific variant to device +./gradlew installDevDebug +./gradlew installProdRelease + +# Build and install in one command +./gradlew installDevDebug && adb shell am start -n com.example.myapp.dev/.MainActivity +``` + +**Access BuildConfig in Code**: + +> **Note**: Starting from AGP 8.0, `BuildConfig` is no longer generated by default. You must explicitly enable it in your `build.gradle.kts`: +> ```kotlin +> android { +> buildFeatures { +> buildConfig = true +> } +> } +> ``` + +```kotlin +// Use build config values in your code +val apiUrl = BuildConfig.API_BASE_URL +val isLoggingEnabled = BuildConfig.ENABLE_LOGGING + +if (BuildConfig.DEBUG) { + // Debug-only code +} +``` + +**Flavor-Specific Source Sets**: + +``` +app/src/ +├── main/ # Shared code for all flavors +├── dev/ # Dev-only code and resources +│ ├── java/ +│ └── res/ +├── staging/ # Staging-only code and resources +├── prod/ # Prod-only code and resources +├── debug/ # Debug build type code +└── release/ # Release build type code +``` + +**Multiple Flavor Dimensions** (e.g., environment + tier): + +```kotlin +android { + flavorDimensions += listOf("environment", "tier") + + productFlavors { + create("dev") { dimension = "environment" } + create("prod") { dimension = "environment" } + + create("free") { dimension = "tier" } + create("paid") { dimension = "tier" } + } +} +// Results in: devFreeDebug, devPaidDebug, prodFreeRelease, etc. +``` + +--- + +## 3. Kotlin Development Standards + +### 3.1 Naming Conventions + +| Type | Convention | Example | +|------|------------|---------| +| Class/Interface | PascalCase | `UserRepository`, `MainActivity` | +| Function/Variable | camelCase | `getUserName()`, `isLoading` | +| Constant | SCREAMING_SNAKE | `MAX_RETRY_COUNT` | +| Package | lowercase | `com.example.myapp` | +| Composable | PascalCase | `@Composable fun UserCard()` | + +### 3.2 Code Standards (Important) + +**Null Safety**: +```kotlin +// ❌ Avoid: Non-null assertion !! (may crash) +val name = user!!.name + +// ✅ Recommended: Safe call + default value +val name = user?.name ?: "Unknown" + +// ✅ Recommended: let handling +user?.let { processUser(it) } +``` + +**Exception Handling**: +```kotlin +// ❌ Avoid: Random try-catch in business layer swallowing exceptions +fun loadData() { + try { + val data = api.fetch() + } catch (e: Exception) { + // Swallowing exception, hard to debug + } +} + +// ✅ Recommended: Let exceptions propagate, handle at appropriate layer +suspend fun loadData(): Result { + return try { + Result.success(api.fetch()) + } catch (e: Exception) { + Result.failure(e) // Wrap and return, let caller decide handling + } +} + +// ✅ Recommended: Unified handling in ViewModel +viewModelScope.launch { + runCatching { repository.loadData() } + .onSuccess { _uiState.value = UiState.Success(it) } + .onFailure { _uiState.value = UiState.Error(it.message) } +} +``` + +### 3.3 Threading & Coroutines (Critical) + +**Thread Selection Principles**: + +| Operation Type | Thread | Description | +|----------------|--------|-------------| +| UI Updates | `Dispatchers.Main` | Update View, State, LiveData | +| Network Requests | `Dispatchers.IO` | HTTP calls, API requests | +| File I/O | `Dispatchers.IO` | Local storage, database operations | +| Compute Intensive | `Dispatchers.Default` | JSON parsing, sorting, encryption | + +**Correct Usage**: +```kotlin +// In ViewModel +viewModelScope.launch { + // Default Main thread, can update UI State + _uiState.value = UiState.Loading + + // Switch to IO thread for network request + val result = withContext(Dispatchers.IO) { + repository.fetchData() + } + + // Automatically returns to Main thread, update UI + _uiState.value = UiState.Success(result) +} + +// In Repository (suspend functions should be main-safe) +suspend fun fetchData(): Data = withContext(Dispatchers.IO) { + api.getData() +} +``` + +**Common Mistakes**: +```kotlin +// ❌ Wrong: Updating UI on IO thread +viewModelScope.launch(Dispatchers.IO) { + val data = api.fetch() + _uiState.value = data // Crash or warning! +} + +// ❌ Wrong: Executing time-consuming operation on Main thread +viewModelScope.launch { + val data = api.fetch() // Blocking main thread! ANR +} + +// ✅ Correct: Fetch on IO, update on Main +viewModelScope.launch { + val data = withContext(Dispatchers.IO) { api.fetch() } + _uiState.value = data +} +``` + +### 3.4 Visibility Rules + +```kotlin +// Default is public, declare explicitly when needed +class UserRepository { // public + private val cache = mutableMapOf() // Visible only within class + internal fun clearCache() {} // Visible only within module +} + +// data class properties are public by default, be careful when used across modules +data class User( + val id: String, // public + val name: String +) +``` + +### 3.5 Common Syntax Pitfalls + +```kotlin +// ❌ Wrong: Accessing uninitialized lateinit +class MyViewModel : ViewModel() { + lateinit var data: String + fun process() = data.length // May crash +} + +// ✅ Correct: Use nullable or default value +class MyViewModel : ViewModel() { + var data: String? = null + fun process() = data?.length ?: 0 +} + +// ❌ Wrong: Using return in lambda +list.forEach { item -> + if (item.isEmpty()) return // Returns from outer function! +} + +// ✅ Correct: Use return@forEach +list.forEach { item -> + if (item.isEmpty()) return@forEach +} +``` + +### 3.6 Server Response Data Class Fields Must Be Nullable + +```kotlin +// ❌ Wrong: Fields declared as non-null (server may not return them) +data class UserResponse( + val id: String = "", + val name: String = "", + val avatar: String = "" +) + +// ✅ Correct: All fields declared as nullable +data class UserResponse( + @SerializedName("id") + val id: String? = null, + @SerializedName("name") + val name: String? = null, + @SerializedName("avatar") + val avatar: String? = null +) +``` + +### 3.7 Lifecycle Resource Management + +```kotlin +// ❌ Wrong: Only adding Observer, not removing +class MyView : View { + override fun onAttachedToWindow() { + super.onAttachedToWindow() + activity?.lifecycle?.addObserver(this) + } + // Memory leak! +} + +// ✅ Correct: Paired add and remove +class MyView : View { + override fun onAttachedToWindow() { + super.onAttachedToWindow() + activity?.lifecycle?.addObserver(this) + } + + override fun onDetachedFromWindow() { + activity?.lifecycle?.removeObserver(this) + super.onDetachedFromWindow() + } +} +``` + +### 3.8 Logging Level Usage + +```kotlin +import android.util.Log + +// Info: Key checkpoints in normal flow +Log.i(TAG, "loadData: started, userId = $userId") + +// Warning: Abnormal but recoverable situations +Log.w(TAG, "loadData: cache miss, fallback to network") + +// Error: Failure/error situations +Log.e(TAG, "loadData failed: ${error.message}") +``` + +| Level | Use Case | +|-------|----------| +| `i` (Info) | Normal flow, method entry, key parameters | +| `w` (Warning) | Recoverable exceptions, fallback handling, null returns | +| `e` (Error) | Request failures, caught exceptions, unrecoverable errors | + +--- + +## 4. Jetpack Compose Standards + +### 4.1 @Composable Context Rules + +```kotlin +// ❌ Wrong: Calling Composable from non-Composable function +fun showError(message: String) { + Text(message) // Compile error! +} + +// ✅ Correct: Mark as @Composable +@Composable +fun ErrorMessage(message: String) { + Text(message) +} + +// ❌ Wrong: Using suspend outside LaunchedEffect +@Composable +fun MyScreen() { + val data = fetchData() // Error! +} + +// ✅ Correct: Use LaunchedEffect +@Composable +fun MyScreen() { + var data by remember { mutableStateOf(null) } + LaunchedEffect(Unit) { + data = fetchData() + } +} +``` + +### 4.2 State Management + +```kotlin +// Basic State +var count by remember { mutableStateOf(0) } + +// Derived State (avoid redundant computation) +val isEven by remember { derivedStateOf { count % 2 == 0 } } + +// Persist across recomposition (e.g., scroll position) +val scrollState = rememberScrollState() + +// State in ViewModel +class MyViewModel : ViewModel() { + private val _uiState = MutableStateFlow(UiState()) + val uiState: StateFlow = _uiState.asStateFlow() +} +``` + +### 4.3 Common Compose Mistakes + +```kotlin +// ❌ Wrong: Creating objects in Composable (created on every recomposition) +@Composable +fun MyScreen() { + val viewModel = MyViewModel() // Wrong! +} + +// ✅ Correct: Use viewModel() or remember +@Composable +fun MyScreen(viewModel: MyViewModel = viewModel()) { + // ... +} +``` + +--- + +## 5. Resources & Icons + +### 5.1 App Icon Requirements + +Must provide multi-resolution icons: + +| Directory | Size | Purpose | +|-----------|------|---------| +| mipmap-mdpi | 48x48 | Baseline | +| mipmap-hdpi | 72x72 | 1.5x | +| mipmap-xhdpi | 96x96 | 2x | +| mipmap-xxhdpi | 144x144 | 3x | +| mipmap-xxxhdpi | 192x192 | 4x | + +Recommended: Use Adaptive Icon (Android 8+): + +```xml + + + + + +``` + +### 5.2 Resource Naming Conventions + +| Type | Prefix | Example | +|------|--------|---------| +| Layout | layout_ | `layout_main.xml` | +| Image | ic_, img_, bg_ | `ic_user.png` | +| Color | color_ | `color_primary` | +| String | - | `app_name`, `btn_submit` | + +### 5.3 Avoid Android Reserved Names (Important) + +Variable names, resource IDs, colors, icons, and XML elements **must not** use Android reserved words or system resource names. Using reserved names causes build errors or resource conflicts. + +**Common Reserved Names to Avoid**: + +| Category | Reserved Names (Do NOT Use) | +|----------|----------------------------| +| Colors | `background`, `foreground`, `transparent`, `white`, `black` | +| Icons/Drawables | `icon`, `logo`, `image`, `drawable` | +| Views | `view`, `text`, `button`, `layout`, `container` | +| Attributes | `id`, `name`, `type`, `style`, `theme`, `color` | +| System | `app`, `android`, `content`, `data`, `action` | + +**Examples**: + +```xml + +#FFFFFF +#000000 + + +#FFFFFF +#000000 +``` + +```kotlin +// ❌ Wrong: Variable names conflict with system +val icon = R.drawable.my_icon +val background = Color.White + +// ✅ Correct: Use descriptive names +val appIcon = R.drawable.my_icon +val screenBackground = Color.White +``` + +```xml + + + + + +``` + +--- + +## 6. Build Error Diagnosis & Fixes + +### 6.1 Common Error Quick Reference + +| Error Keyword | Cause | Fix | +|---------------|-------|-----| +| `Unresolved reference` | Missing import or undefined | Check imports, verify dependencies | +| `Type mismatch` | Type incompatibility | Check parameter types, add conversion | +| `Cannot access` | Visibility issue | Check public/private/internal | +| `@Composable invocations` | Composable context error | Ensure caller is also @Composable | +| `Duplicate class` | Dependency conflict | Use `./gradlew dependencies` to investigate | +| `AAPT: error` | Resource file error | Check XML syntax and resource references | + +### 6.2 Fix Best Practices + +1. **Read the complete error message first**: Locate file and line number +2. **Check recent changes**: Problems usually in latest modifications +3. **Clean Build**: `./gradlew clean assembleDebug` +4. **Check dependency versions**: Version conflicts are common causes +5. **Refresh dependencies if needed**: Clear cache and rebuild + +### 6.3 Debugging Commands + +```bash +# Clean and build +./gradlew clean assembleDebug + +# View dependency tree (investigate conflicts) +./gradlew :app:dependencies + +# View detailed errors +./gradlew assembleDebug --stacktrace + +# Refresh dependencies +./gradlew --refresh-dependencies +``` + +--- + +## 7. Material Design 3 Guidelines + +Review Android UI files for compliance with Material Design 3 Guidelines and Android best practices. + +### Design Philosophy + +#### M3 Core Principles + +| Principle | Description | +|-----------|-------------| +| **Personal** | Dynamic color based on user preferences and wallpaper | +| **Adaptive** | Responsive across all screen sizes and form factors | +| **Expressive** | Bold colors and typography with personality | +| **Accessible** | Inclusive design for all users | + +#### M3 Expressive (Latest) + +The latest evolution adds emotion-driven UX through: +- Vibrant, dynamic colors +- Intuitive motion physics +- Adaptive components +- Flexible typography +- Contrasting shapes (35 new shape options) + +### App Style Selection + +**Critical Decision**: Match visual style to app category and target audience. + +| App Category | Visual Style | Key Characteristics | +|--------------|--------------|---------------------| +| Utility/Tool | Minimalist | Clean, efficient, neutral colors | +| Finance/Banking | Professional Trust | Conservative colors, security-focused | +| Health/Wellness | Calm & Natural | Soft colors, organic shapes | +| Kids (3-5) | Playful Simple | Bright colors, large targets (56dp+) | +| Kids (6-12) | Fun & Engaging | Vibrant, gamified feedback | +| Social/Entertainment | Expressive | Brand-driven, gesture-rich | +| Productivity | Clean & Focused | Minimal, high contrast | +| E-commerce | Conversion-focused | Clear CTAs, scannable | + +See [Design Style Guide](references/design-style-guide.md) for detailed style profiles. + +### Quick Reference: Key Specifications + +#### Color Contrast Requirements + +| Element | Minimum Ratio | +|---------|---------------| +| Body text | **4.5:1** | +| Large text (18sp+) | **3:1** | +| UI components | **3:1** | + +#### Touch Targets + +| Type | Size | +|------|------| +| Minimum | 48 × 48dp | +| Recommended (primary actions) | 56 × 56dp | +| Kids apps | 56dp+ | +| Spacing between targets | 8dp minimum | + +#### 8dp Grid System + +| Token | Value | Usage | +|-------|-------|-------| +| xs | 4dp | Icon padding | +| sm | 8dp | Tight spacing | +| md | 16dp | Default padding | +| lg | 24dp | Section spacing | +| xl | 32dp | Large gaps | +| xxl | 48dp | Screen margins | + +#### Typography Scale (Summary) + +| Category | Sizes | +|----------|-------| +| Display | 57sp, 45sp, 36sp | +| Headline | 32sp, 28sp, 24sp | +| Title | 22sp, 16sp, 14sp | +| Body | 16sp, 14sp, 12sp | +| Label | 14sp, 12sp, 11sp | + +#### Animation Duration + +| Type | Duration | +|------|----------| +| Micro (ripples) | 50-100ms | +| Short (simple) | 100-200ms | +| Medium (expand/collapse) | 200-300ms | +| Long (complex) | 300-500ms | + +#### Component Dimensions + +| Component | Height | Min Width | +|-----------|--------|-----------| +| Button | 40dp | 64dp | +| FAB | 56dp | 56dp | +| Text Field | 56dp | 280dp | +| App Bar | 64dp | - | +| Bottom Nav | 80dp | - | + +### Anti-Patterns (Must Avoid) + +#### UI Anti-Patterns +- More than 5 bottom navigation items +- Multiple FABs on same screen +- Touch targets smaller than 48dp +- Inconsistent spacing (non-8dp multiples) +- Missing dark theme support +- Text on colored backgrounds without contrast check + +#### Performance Anti-Patterns +- Startup time > 2 seconds without progress indicator +- Frame rate < 60 FPS (> 16ms per frame) +- Crash rate > 1.09% (Google Play threshold) +- ANR rate > 0.47% (Google Play threshold) + +#### Accessibility Anti-Patterns +- Missing contentDescription on interactive elements +- Element type in labels (e.g., "Save button" instead of "Save") +- Complex gestures in kids apps +- Text-only buttons for non-readers + +### Review Checklist + +- [ ] 8dp spacing grid compliance +- [ ] 48dp minimum touch targets +- [ ] Proper typography scale usage +- [ ] Color contrast compliance (4.5:1+ for text) +- [ ] Dark theme support +- [ ] contentDescription on all interactive elements +- [ ] Startup < 2 seconds or shows progress +- [ ] Visual style matches app category + +### Design References + +| Topic | Reference | +|-------|-----------| +| Colors, Typography, Spacing, Shapes | [Visual Design](references/visual-design.md) | +| Animation & Transitions | [Motion System](references/motion-system.md) | +| Accessibility Guidelines | [Accessibility](references/accessibility.md) | +| Large Screens & Foldables | [Adaptive Screens](references/adaptive-screens.md) | +| Android Vitals & Performance | [Performance & Stability](references/performance-stability.md) | +| Privacy & Security | [Privacy & Security](references/privacy-security.md) | +| Audio, Video, Notifications | [Functional Requirements](references/functional-requirements.md) | +| App Style by Category | [Design Style Guide](references/design-style-guide.md) | diff --git a/android-native-dev/references/accessibility.md b/android-native-dev/references/accessibility.md new file mode 100644 index 0000000..e1eba6b --- /dev/null +++ b/android-native-dev/references/accessibility.md @@ -0,0 +1,209 @@ +# Accessibility Guidelines + +Comprehensive accessibility requirements for Android applications. + +## Core Requirements + +### Minimum Standards + +| Requirement | Specification | +|-------------|---------------| +| Color contrast (text) | 4.5:1 minimum | +| Color contrast (large text) | 3:1 minimum | +| Color contrast (UI components) | 3:1 minimum | +| Touch targets | 48 × 48dp minimum | +| Content descriptions | All interactive elements | +| Focus indicators | Clearly visible | +| Screen reader support | Proper semantics | + +## Content Labels + +### contentDescription + +Use for non-text interactive elements. + +**When to use:** +- ImageView, ImageButton +- CheckBox, Switch (state description) +- Custom drawable views +- Icons that convey meaning + +**When NOT to use:** +- TextView (uses text content automatically) +- Decorative images (set to null) +- Elements with labelFor relationship + +### android:hint + +Use for editable text fields to show placeholder text. + +**Important**: Don't use contentDescription on EditText—it interferes with accessibility services. + +### android:labelFor + +Link labels to input fields by setting labelFor on the TextView to reference the EditText ID. + +## Label Best Practices + +### Do's + +| Practice | Example | +|----------|---------| +| Be concise | "Save" not "Click here to save" | +| Describe action/purpose | "Delete message" | +| Be unique in context | "Delete item 3" not just "Delete" | +| Update dynamically | "Pause" ↔ "Play" based on state | + +### Don'ts + +| Avoid | Reason | +|-------|--------| +| Include element type | TalkBack announces "button" automatically | +| Say "button", "image", etc. | Redundant with accessibility info | +| Use "click" or "tap" | Input method varies | +| Leave empty/generic | "Button" or "Image" is unhelpful | + +### Examples + +| Bad | Good | +|-----|------| +| "Save button" | "Save" | +| "Click here to submit" | "Submit" | +| "Image" | "Profile photo of John" | +| "Button 1" | "Add to cart" | + +## Focus and Navigation + +### Focus Groups + +Group related elements using `screenReaderFocusable="true"` on the container and `focusable="false"` on child elements. TalkBack will announce all children's content in a single utterance. + +### Headings + +Mark section headers with `accessibilityHeading="true"`. Users can navigate between headings for quick scanning. + +### Pane Titles + +Identify screen regions with `accessibilityPaneTitle`. Accessibility services announce pane changes. + +### Focus Order + +- Natural reading order (top-to-bottom, start-to-end) +- Use `accessibilityTraversalBefore/After` for custom order +- Ensure all interactive elements are focusable +- Skip decorative elements + +## Decorative Elements + +Skip elements that don't convey information: +- Set `contentDescription="@null"` +- Or set `importantForAccessibility="no"` + +## Custom Accessibility Actions + +### Adding Actions + +Provide alternatives for gesture-based interactions using `ViewCompat.addAccessibilityAction()`. This exposes swipe actions to accessibility services. + +### Replacing Action Labels + +Make default actions more descriptive using `ViewCompat.replaceAccessibilityAction()`. Example: "Double tap and hold to add to favorites" instead of generic "long press". + +## Color and Visual Cues + +### Don't Rely on Color Alone + +Combine color with other indicators: + +| Information | Color + Alternative | +|-------------|---------------------| +| Error state | Red + error icon + text | +| Success | Green + checkmark + text | +| Required field | Red asterisk + "Required" label | +| Selected item | Highlight + checkmark + bold | +| Link text | Blue + underline | + +### Contrast Testing + +Use tools to verify contrast: +- Android Accessibility Scanner +- Contrast Checker plugins +- Manual calculation: (L1 + 0.05) / (L2 + 0.05) + +## Touch Targets + +### Minimum Sizes + +| Element | Minimum | Recommended | +|---------|---------|-------------| +| Standard | 48 × 48dp | 48 × 48dp | +| Primary actions | 48 × 48dp | 56 × 56dp | +| Kids apps | 56 × 56dp | 64 × 64dp | + +### Spacing + +- Minimum 8dp between adjacent touch targets +- Visual element can be smaller if touch area is adequate (use padding) + +## Screen Reader Announcements + +### Live Regions + +Announce dynamic content changes using `accessibilityLiveRegion`: + +| Mode | Usage | +|------|-------| +| polite | Announces when user is idle | +| assertive | Interrupts current speech | +| none | No automatic announcements | + +### Custom Announcements + +Use `announceForAccessibility()` sparingly—prefer live regions. + +## Keyboard and Hardware Navigation + +### Focus Indicators + +- Visible focus state for all interactive elements +- Don't remove default focus indicators +- Custom focus: 2dp+ border or background change + +### Keyboard Shortcuts + +- Support Tab navigation +- Enter/Space for activation +- Arrow keys for lists/grids +- Escape for dismissal + +## Testing Accessibility + +### Manual Testing + +1. **TalkBack**: Navigate entire app with screen reader +2. **Switch Access**: Test with switch navigation +3. **Keyboard**: Navigate with external keyboard only +4. **Magnification**: Test with zoom enabled +5. **Large text**: Test with 200% font scale +6. **High contrast**: Test with high contrast mode + +### Automated Testing + +| Tool | Purpose | +|------|---------| +| Accessibility Scanner | On-device scanning | +| Espresso Accessibility Checks | Automated UI tests | +| Lint checks | Static analysis | + +### Checklist + +- [ ] All interactive elements have descriptions +- [ ] Touch targets are 48dp minimum +- [ ] Color contrast meets requirements +- [ ] Focus order is logical +- [ ] Headings are properly marked +- [ ] Custom actions have descriptive labels +- [ ] Live regions announce important changes +- [ ] Keyboard navigation works +- [ ] Works with TalkBack enabled +- [ ] Works with large text (200%) diff --git a/android-native-dev/references/adaptive-screens.md b/android-native-dev/references/adaptive-screens.md new file mode 100644 index 0000000..d371113 --- /dev/null +++ b/android-native-dev/references/adaptive-screens.md @@ -0,0 +1,231 @@ +# Adaptive Screens Guidelines + +Requirements for large screens, tablets, foldables, and multi-window support. + +## Adaptive Quality Tiers + +Google defines three progressive quality tiers for adaptive apps: + +### Tier 3: Adaptive Ready (Basic) + +Minimum requirements for all apps: + +| Requirement | Description | +|-------------|-------------| +| Full screen | App fills display, no letterboxing | +| Configuration changes | Handles rotation, folding, resizing | +| Multi-window | Supports split-screen mode | +| Basic input | Keyboard, mouse, trackpad support | + +### Tier 2: Adaptive Optimized (Better) + +Enhanced experience: + +| Requirement | Description | +|-------------|-------------| +| Layout optimization | Responsive layouts for all sizes | +| Enhanced input | Full keyboard shortcuts, mouse hover states | +| Continuity | Seamless state preservation | + +### Tier 1: Adaptive Differentiated (Best) + +Device-specific excellence: + +| Requirement | Description | +|-------------|-------------| +| Multitasking | Drag and drop, activity embedding | +| Foldable postures | Table-top mode, book mode support | +| Stylus | Full stylus input support | +| Desktop | Windowed mode optimization | + +## Screen Size Classes + +### Width-Based Classes + +| Class | Width | Typical Devices | +|-------|-------|-----------------| +| Compact | < 600dp | Phone portrait | +| Medium | 600-840dp | Tablet portrait, phone landscape | +| Expanded | > 840dp | Tablet landscape, desktop | + +### Layout Strategies + +| Screen Class | Navigation | Content Layout | +|--------------|------------|----------------| +| Compact | Bottom nav | Single pane | +| Medium | Nav rail | List-detail (optional) | +| Expanded | Nav drawer/rail | List-detail, multi-pane | + +## Configuration Changes + +### Must Handle + +| Change | Trigger | +|--------|---------| +| Rotation | Device rotated | +| Fold/Unfold | Foldable state change | +| Window resize | Multi-window adjustment | +| Split screen | Enter/exit split mode | +| Keyboard | External keyboard attach/detach | + +### Configuration Handling + +| Approach | Description | +|----------|-------------| +| Let system handle | Default, activity recreated | +| Handle manually | Declare configChanges, implement onConfigurationChanged | + +### State Preservation + +- Use ViewModel for UI state +- Use SavedStateHandle for process death +- Test with "Don't keep activities" enabled + +## Multi-Window Support + +### Requirements + +| Feature | Status | +|---------|--------| +| resizeableActivity | true (default API 24+) | +| Minimum size | Support 220dp width | +| State handling | Preserve across resize | + +### Best Practices + +- Don't assume full-screen ownership +- Handle onConfigurationChanged gracefully +- Test at minimum supported size +- Support free-form windows (desktop mode) + +## Foldable Devices + +### Postures + +| Posture | Description | Use Case | +|---------|-------------|----------| +| Flat | Fully open | Normal tablet use | +| Half-opened (tabletop) | Hinged at ~90° horizontal | Video calls, media | +| Half-opened (book) | Hinged at ~90° vertical | Reading, productivity | +| Folded | Closed | Compact phone mode | + +### Design Considerations + +- Avoid placing interactive elements on the fold +- Consider separate content for each screen segment +- Support continuity when fold state changes +- Use WindowInfoTracker to detect fold state + +## External Input Devices + +### Keyboard Support + +| Requirement | Implementation | +|-------------|----------------| +| Tab navigation | Focusable elements in order | +| Enter/Space | Activates focused element | +| Arrow keys | Navigate lists, grids | +| Shortcuts | Common actions (Ctrl+S, etc.) | +| Focus indicators | Visible focus states | + +### Mouse/Trackpad Support + +| Requirement | Implementation | +|-------------|----------------| +| Hover states | Visual feedback on hover | +| Right-click | Context menu support | +| Scroll | Smooth scrolling | +| Pointer cursor | Appropriate cursor types | + +### Stylus Support + +| Feature | Implementation | +|---------|----------------| +| Pressure sensitivity | Variable stroke width | +| Palm rejection | Ignore palm touches | +| Tilt detection | Shading effects | +| Hover preview | Show cursor before touch | + +## Navigation Patterns + +### By Screen Width + +| Width | Primary Nav | Secondary Nav | +|-------|-------------|---------------| +| < 600dp | Bottom nav (3-5 items) | Hamburger menu | +| 600-840dp | Navigation rail | Drawer on demand | +| > 840dp | Permanent drawer or rail | Drawer or none | + +### Navigation Rail Specs + +| Property | Value | +|----------|-------| +| Width | 80dp | +| Icon size | 24dp | +| Touch target | 56dp | +| Items | 3-7 destinations | +| FAB | Optional, at top | + +### Permanent Navigation Drawer + +| Property | Value | +|----------|-------| +| Width | 256-360dp | +| Position | Left edge (LTR) | +| Behavior | Always visible | +| Content | Full labels, icons | + +## Responsive Layouts + +### Breakpoints + +| Class | Width Range | +|-------|-------------| +| COMPACT | < 600dp | +| MEDIUM | 600-840dp | +| EXPANDED | > 840dp | + +Use WindowSizeClass to determine current breakpoint and adapt layout accordingly. + +## Content Considerations + +### Text Readability + +- Line length: 45-75 characters max +- Use multiple columns on wide screens +- Maintain hierarchy with consistent spacing + +### Media + +- Support multiple aspect ratios +- Provide high-resolution assets +- Consider picture-in-picture for video + +### Touch vs. Precise Input + +- Large screens often use mouse/keyboard +- Don't assume touch-only interaction +- Provide hover states and tooltips + +## Testing + +### Device Matrix + +| Device Type | Test Priority | +|-------------|---------------| +| Phone (portrait) | Required | +| Phone (landscape) | Required | +| Tablet (both orientations) | Required | +| Foldable (all postures) | High | +| Desktop/Chromebook | Medium | + +### Test Cases + +- [ ] App fills screen in all configurations +- [ ] No letterboxing or black bars +- [ ] State preserved across configuration changes +- [ ] Multi-window works at minimum size +- [ ] Keyboard navigation functional +- [ ] Mouse hover states present +- [ ] Foldable postures handled (if applicable) +- [ ] Navigation adapts to screen width diff --git a/android-native-dev/references/design-style-guide.md b/android-native-dev/references/design-style-guide.md new file mode 100644 index 0000000..7a17d06 --- /dev/null +++ b/android-native-dev/references/design-style-guide.md @@ -0,0 +1,365 @@ +# Design Style Guide + +Match visual design to app category and target audience for cohesive user experience. + +## Style Selection Principle + +> **The visual style must match the app's purpose and audience.** +> A finance app should feel trustworthy, not playful. +> A children's app should feel fun, not corporate. + +## Style Selection Matrix + +| App Category | Visual Style | Color Palette | Typography | Interaction | +|--------------|--------------|---------------|------------|-------------| +| Utility/Tool | Minimalist | Neutral + 1 accent | Clean sans-serif | Direct, efficient | +| Finance/Banking | Professional Trust | Blue/Green/Navy | Conservative | Secure, deliberate | +| Health/Wellness | Calm & Natural | Soft greens, earth tones | Rounded, friendly | Gentle, encouraging | +| Kids (3-5) | Playful Simple | Bright primary colors | Large, rounded | Big targets, forgiving | +| Kids (6-12) | Fun & Engaging | Vibrant, varied | Bold, readable | Gamified feedback | +| Social/Entertainment | Expressive | Brand-driven | Dynamic | Gesture-rich | +| Productivity | Clean & Focused | Minimal, high contrast | Professional | Keyboard-friendly | +| E-commerce | Conversion-focused | Brand + CTA colors | Scannable | Quick actions | +| Gaming | Immersive | Theme-driven | Stylized | Custom gestures | + +## Detailed Style Profiles + +### Minimalist / iOS-like (Utility Apps) + +**When to use**: Tools, utilities, calculators, file managers, settings apps + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | 2-3 colors max, neutral base | +| Whitespace | Generous, 24-48dp margins | +| Typography | Single font family, clear hierarchy | +| Icons | Line-based, consistent stroke | +| Shadows | Subtle or none | +| Borders | Thin (1dp) or none | +| Shapes | Subtle corners (8-12dp) | + +**Interaction Style**: +- Direct manipulation +- Immediate feedback +- No unnecessary animations +- Efficient task completion + +**Color Palette**: + +| Role | Light Mode | Dark Mode | +|------|------------|-----------| +| Background | #FAFAFA | #1C1C1E | +| Surface | #FFFFFF | #2C2C2E | +| Primary | #007AFF | #0A84FF | +| Text | #000000 | #FFFFFF | +| Secondary | #8E8E93 | #8E8E93 | + +**Reference Apps**: iOS Settings, Apple Notes, Google Calculator + +--- + +### Professional Trust (Finance/Business) + +**When to use**: Banking, investment, enterprise, B2B applications + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | Blues, greens, navy (trust colors) | +| Whitespace | Structured, grid-based | +| Typography | Formal, conservative weights | +| Icons | Filled or outlined, consistent | +| Data visualization | Clear, accurate charts | +| Security indicators | Prominent locks, badges | + +**Interaction Style**: +- Confirmatory (double-check important actions) +- Deliberate (not rushed) +- Secure-feeling +- Clear feedback on transactions + +**Color Palette**: + +| Role | Color | Name | +|------|-------|------| +| Primary | #00695C or #1565C0 | Teal 800 / Blue 800 | +| Secondary | #37474F | Blue Grey 800 | +| Accent | #FFC107 | Amber | +| Background | #ECEFF1 | Blue Grey 50 | +| Success | #2E7D32 | Green 800 | +| Error | #C62828 | Red 800 | + +**Key Patterns**: +- Balance summaries prominent +- Transaction history easily scannable +- Secure entry for sensitive data +- Biometric authentication prompts + +**Reference Apps**: Banking apps, Trading platforms, Enterprise tools + +--- + +### Calm & Wellness (Health Apps) + +**When to use**: Meditation, fitness tracking, health monitoring, therapy + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | Soft, muted, natural | +| Whitespace | Abundant (breathing room) | +| Typography | Rounded, friendly fonts | +| Shapes | Organic, soft corners (16dp+) | +| Animation | Gentle, slow transitions | +| Imagery | Nature, soft gradients | + +**Interaction Style**: +- Encouraging, not demanding +- Progress-oriented +- Gentle reminders +- Celebration of achievements + +**Color Palette**: + +| Role | Color | Name | +|------|-------|------| +| Primary | #4CAF50 | Green 500 | +| Secondary | #81C784 | Green 300 | +| Tertiary | #B2DFDB | Teal 100 | +| Background | #F1F8E9 | Light Green 50 | +| Text | #33691E | Light Green 900 | +| Accent | #FFB74D | Orange 300 | + +**Key Patterns**: +- Progress rings and charts +- Streak tracking +- Motivational messages +- Quiet notification style + +**Reference Apps**: Headspace, Calm, Apple Fitness + +--- + +### Playful & Kid-Friendly (Children's Apps) + +**When to use**: Educational games, children's content, family apps + +#### Ages 3-5 + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | Bright, saturated primary colors | +| Touch targets | 56dp minimum, 64dp recommended | +| Shapes | Very rounded (full radius) | +| Typography | Large (18sp+ minimum), simple fonts | +| Icons | Large, colorful, recognizable | +| Animation | Frequent, rewarding | + +**Interaction Style**: +- Simple gestures only (tap, drag) +- No multi-finger gestures +- Forgiving error handling +- Immediate, multi-sensory feedback (sound + visual + haptic) +- No text-only buttons + +**Color Palette**: + +| Role | Color | Name | +|------|-------|------| +| Primary | #F44336 | Red 500 | +| Secondary | #FFEB3B | Yellow 500 | +| Tertiary | #2196F3 | Blue 500 | +| Background | #FFFFFF | White or soft pastels | +| Accent | #4CAF50 | Green 500 | + +#### Ages 6-12 + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | Vibrant, varied palette | +| Touch targets | 48dp minimum | +| Shapes | Rounded but can be varied | +| Typography | Bold, readable, can include text | +| Icons | Stylized, character-driven | +| Animation | Gamified, achievement-based | + +**Interaction Style**: +- Can introduce some complexity +- Gamification elements +- Progress and rewards +- Some text is acceptable + +**Key Patterns for All Kids Apps**: +- Icon-based navigation (no text-only) +- Home button always visible +- Back navigation clear +- Parent gate for settings (math problem, hold button) +- Multi-sensory feedback +- Encouraging error states (no punishment) +- Joint engagement opportunities with parents + +**Reference Apps**: PBS Kids, Khan Academy Kids, Duolingo ABC + +--- + +### Expressive & Social (Entertainment Apps) + +**When to use**: Social media, content creation, entertainment + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | Bold brand colors | +| Typography | Dynamic, personality-driven | +| Media | Rich, prominent | +| Animation | Expressive, delightful | +| Shapes | Brand-specific | + +**Interaction Style**: +- Gesture-rich +- Quick actions +- Social interactions prominent +- Content-first design + +**Key Patterns**: +- Feed-based layouts +- Quick action buttons (like, share, comment) +- Stories/ephemeral content +- Creation tools accessible +- Notification badges + +**Reference Apps**: Instagram, TikTok, Snapchat + +--- + +### Clean & Focused (Productivity Apps) + +**When to use**: Note-taking, task management, email, documents + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | High contrast, minimal | +| Whitespace | Strategic, content-focused | +| Typography | Highly readable, clear hierarchy | +| Icons | Functional, consistent | +| Density | Adjustable (compact to comfortable) | + +**Interaction Style**: +- Keyboard-friendly +- Batch operations +- Drag and drop +- Quick capture +- Search-centric + +**Color Palette**: + +| Role | Light Mode | Dark Mode | +|------|------------|-----------| +| Primary | #1976D2 | #64B5F6 | +| Background | #FFFFFF | #121212 | +| Surface | #F5F5F5 | #1E1E1E | +| Text | #212121 | #E0E0E0 | +| Accent/Priority | #FF5722 | #FF7043 | + +**Key Patterns**: +- List views with swipe actions +- Quick add buttons +- Checkbox interactions +- Due dates and reminders +- Tags and categories + +**Reference Apps**: Notion, Todoist, Google Tasks + +--- + +### Conversion-Focused (E-commerce) + +**When to use**: Shopping, marketplace, booking apps + +**Visual Characteristics**: + +| Element | Specification | +|---------|---------------| +| Colors | Brand + clear CTA colors | +| Images | High quality, zoomable | +| Typography | Scannable, price prominent | +| Cards | Product-focused | +| Badges | Sale, new, limited | + +**Interaction Style**: +- Quick add to cart +- Easy checkout flow +- Comparison features +- Reviews accessible +- Wishlist/save for later + +**Key Patterns**: +- Grid and list view toggle +- Filter and sort +- Product detail with gallery +- Cart always accessible +- One-tap purchase options + +**Reference Apps**: Amazon, Shopify apps, Booking.com + +--- + +## Consistency Principles + +### Match Style to Subject Matter + +| App Purpose | Style Should Feel | +|-------------|-------------------| +| Utility | Efficient, invisible | +| Finance | Trustworthy, secure | +| Health | Supportive, calm | +| Kids | Safe, fun | +| Social | Expressive, personal | +| Productivity | Focused, powerful | +| Shopping | Exciting, trustworthy | + +### Internal Consistency Rules + +| Rule | Implementation | +|------|----------------| +| Same icon style | All outlined OR all filled | +| Consistent color meaning | Red = destructive, Green = success | +| Uniform spacing | Use 8dp grid | +| Predictable interaction | Same gesture = same result | +| Typography system | Use M3 type scale | + +## Anti-Patterns: Style Mismatch + +| Mismatch | Problem | +|----------|---------| +| Playful colors in banking app | Undermines trust | +| Complex gestures in kids app | Frustrates young users | +| Cluttered UI in wellness app | Defeats calming purpose | +| Boring visuals in entertainment | Fails to engage | +| Aggressive CTAs in health app | Feels manipulative | +| Childish design in professional tool | Lacks credibility | +| Dense information in casual app | Overwhelms users | + +## Implementation Checklist + +- [ ] Identified app category and target audience +- [ ] Selected appropriate style profile +- [ ] Color palette matches style +- [ ] Typography matches style +- [ ] Interaction patterns match style +- [ ] Touch targets appropriate for audience +- [ ] Animation style consistent +- [ ] Internal consistency maintained +- [ ] No style mismatches +- [ ] Tested with target users diff --git a/android-native-dev/references/functional-requirements.md b/android-native-dev/references/functional-requirements.md new file mode 100644 index 0000000..2d19627 --- /dev/null +++ b/android-native-dev/references/functional-requirements.md @@ -0,0 +1,229 @@ +# Functional Requirements + +Audio, video, notifications, and other functional behavior requirements. + +## Audio + +### Playback Initialization + +| Requirement | Specification | +|-------------|---------------| +| Response time | < 1 second | +| If delayed | Show visual progress indicator | +| User feedback | Immediate acknowledgment of action | + +### Audio Focus Rules + +| Event | Required Action | +|-------|-----------------| +| Another app requests focus | Pause or reduce volume | +| Focus regained | Resume or restore volume | +| Playback stops | Abandon focus | + +### Audio Focus Handling + +| Focus Change | Action | +|--------------|--------| +| AUDIOFOCUS_LOSS | Stop playback | +| AUDIOFOCUS_LOSS_TRANSIENT | Pause playback | +| AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK | Reduce volume | +| AUDIOFOCUS_GAIN | Resume playback | + +### Background Playback + +| Requirement | Implementation | +|-------------|----------------| +| Continue when backgrounded | Use Foreground Service | +| Notification | MediaStyle notification required | +| Media controls | System media controls integration | +| Session | MediaSession for system integration | + +## Video + +### Picture-in-Picture (PiP) + +| Requirement | Specification | +|-------------|---------------| +| Video apps | Should support PiP | +| Aspect ratio | 16:9 to 2.39:1 | +| Auto-enter | When user navigates away during playback | + +### Video Encoding + +| Standard | Requirement | +|----------|-------------| +| Compression | HEVC (H.265) recommended | +| Fallback | H.264 for compatibility | +| Quality | Adaptive based on network | + +### Video Player Requirements + +| Feature | Implementation | +|---------|----------------| +| Fullscreen | Support landscape | +| Controls | Play, pause, seek, volume | +| Captions | Support closed captions | +| Resume | Remember playback position | + +## Notifications + +### Channel Best Practices + +| Practice | Reason | +|----------|--------| +| Multiple channels | User can control each type | +| Descriptive names | User understands purpose | +| Appropriate importance | Match user expectation | +| Don't share channels | Different content = different channel | + +### Notification Priority + +| Importance | Usage | +|------------|-------| +| HIGH | Time-sensitive (messages, calls) | +| DEFAULT | Normal notifications | +| LOW | Background info | +| MIN | Minimal interruption | + +### Notification Content Rules + +| Do | Don't | +|-----|-------| +| Relevant information | Cross-promotion | +| Clear, concise text | Advertising other products | +| Actionable content | Unnecessary interruptions | +| Set timeouts | Persistent non-ongoing notifications | + +### Messaging Apps Requirements + +| Feature | Description | +|---------|-------------| +| MessagingStyle | Use for conversation notifications | +| Direct reply | Support inline reply action | +| Conversation shortcuts | Enable direct share | +| Bubbles | Support floating conversations | + +### Notification Grouping + +Group related notifications together with a summary notification. Set appropriate group keys and summary flags. + +## Sharing + +### Android Sharesheet + +Use the system sharesheet for sharing content. Create an ACTION_SEND intent with appropriate type and extras, then use createChooser(). + +### Direct Share + +Provide conversation shortcuts for Direct Share ranking: +- Create ShortcutInfo for each conversation +- Set appropriate categories +- Push dynamic shortcuts + +## Background Services + +### Service Restrictions + +| Rule | Implementation | +|------|----------------| +| Avoid long-running services | Use WorkManager | +| No background starts (API 26+) | Use foreground service or JobScheduler | +| Battery-efficient | Batch work, respect Doze | + +### Poor Background Service Uses + +| Don't Use For | Alternative | +|---------------|-------------| +| Maintaining network connection | FCM (push notifications) | +| Persistent Bluetooth | Companion device manager | +| Keeping GPS on | Geofencing, fused location | +| Polling server | FCM or WorkManager | + +## State Management + +### State Preservation Requirements + +| Scenario | Required Behavior | +|----------|-------------------| +| App switcher return | Exact previous state | +| Device wake | Exact previous state | +| Process death | Restore critical state | +| Configuration change | Seamless transition | + +### State Categories + +| State Type | Storage | +|------------|---------| +| UI state (scroll, selection) | ViewModel + SavedState | +| User input (forms) | SavedState | +| Navigation | NavController state | +| Persistent data | Room database | + +## Navigation + +### Back Button/Gesture + +| Requirement | Implementation | +|-------------|----------------| +| System back | Navigate to previous screen | +| Gesture navigation | Support back gesture | +| No custom back buttons | Use system navigation | +| Predictable | User knows what back does | + +## Gestures + +### Gesture Navigation Support + +| Gesture | Default Action | +|---------|----------------| +| Swipe from left edge | Back | +| Swipe up from bottom | Home | +| Swipe up and hold | Recent apps | + +### Custom Gestures + +| Practice | Reason | +|----------|--------| +| Avoid edge swipes | Conflicts with navigation | +| Provide alternatives | Not all users gesture-capable | +| Test with gesture nav | Ensure no conflicts | + +Handle system gesture insets to avoid conflicts with edge gestures. + +## Functional Checklist + +### Audio +- [ ] Playback starts within 1 second +- [ ] Audio focus requested and released +- [ ] Responds to focus changes (duck/pause) +- [ ] Background playback with notification +- [ ] MediaSession integration + +### Video +- [ ] Picture-in-picture supported +- [ ] HEVC encoding used +- [ ] Playback position remembered +- [ ] Captions supported + +### Notifications +- [ ] Appropriate channels defined +- [ ] Correct importance levels +- [ ] No promotional content +- [ ] Grouped when appropriate +- [ ] Timeouts set where applicable + +### Messaging (if applicable) +- [ ] MessagingStyle used +- [ ] Direct reply supported +- [ ] Conversation shortcuts +- [ ] Bubbles supported + +### Background +- [ ] WorkManager for background work +- [ ] No long-running services +- [ ] Battery-efficient design + +### Navigation +- [ ] Standard back behavior +- [ ] Gesture navigation supported +- [ ] State preserved across lifecycle diff --git a/android-native-dev/references/motion-system.md b/android-native-dev/references/motion-system.md new file mode 100644 index 0000000..c0dd87e --- /dev/null +++ b/android-native-dev/references/motion-system.md @@ -0,0 +1,203 @@ +# Motion System Guidelines + +Animation and transition specifications for Material Design 3. + +## Motion Principles + +### Four Core Characteristics + +| Principle | Description | +|-----------|-------------| +| **Responsive** | Quickly responds to user input at the point of interaction | +| **Natural** | Follows real-world physics (gravity, friction, momentum) | +| **Aware** | Elements are aware of surroundings and other elements | +| **Intentional** | Guides focus to the right place at the right time | + +## Duration Guidelines + +### By Interaction Type + +| Type | Duration | Usage | +|------|----------|-------| +| Micro | 50-100ms | Ripples, state changes, hover | +| Short | 100-200ms | Simple transitions, toggles | +| Medium | 200-300ms | Expanding, collapsing, revealing | +| Long | 300-500ms | Complex choreography, page transitions | + +### By Device Type + +| Device | Typical Duration | Adjustment | +|--------|------------------|------------| +| Mobile | 300ms | Baseline | +| Tablet | 390ms | +30% slower | +| Desktop | 150-200ms | Faster, more responsive | +| Wearable | 210ms | -30% faster | + +### Duration Rules + +- **Maximum**: Keep under 400ms for most transitions +- **User-initiated**: Faster (closer to instant feedback) +- **System-initiated**: Can be slightly longer +- **Loading states**: Use indeterminate indicators for unknown duration + +## Easing Curves + +### Standard Curves + +| Curve | Usage | Characteristics | +|-------|-------|-----------------| +| **Standard** | Most common transitions | Quick acceleration, slow deceleration | +| **Emphasized** | Important/significant transitions | More dramatic curve | +| **Decelerate** | Elements entering screen | Starts fast, ends slow | +| **Accelerate** | Elements leaving screen permanently | Starts slow, ends fast | +| **Sharp** | Elements temporarily leaving | Quick, snappy motion | + +### Curve Values (Cubic Bezier) + +| Curve | Value | +|-------|-------| +| Standard | cubic-bezier(0.2, 0.0, 0.0, 1.0) | +| Emphasized | cubic-bezier(0.2, 0.0, 0.0, 1.0) | +| Decelerate | cubic-bezier(0.0, 0.0, 0.0, 1.0) | +| Accelerate | cubic-bezier(0.3, 0.0, 1.0, 1.0) | + +## Movement Patterns + +### Arc Motion + +- Use natural, concave arcs for diagonal movement +- Single-axis movement (horizontal/vertical only) stays straight +- Elements entering/exiting screen move on single axis + +### Choreography + +- **Stagger**: Offset timing for related elements (20-40ms between) +- **Cascade**: Sequential reveal from a focal point +- **Shared motion**: Elements that move together maintain relationship + +## Transition Patterns + +### Container Transform + +Best for: Navigation from card/list item to detail screen + +- Origin container morphs into destination +- Maintains visual continuity +- Content fades during transformation + +### Shared Axis + +Best for: Same-level navigation (tabs, stepper) + +| Axis | Direction | Usage | +|------|-----------|-------| +| X-axis | Horizontal | Tabs, horizontal paging | +| Y-axis | Vertical | Vertical lists, feeds | +| Z-axis | Depth | Parent-child relationships | + +### Fade Through + +Best for: Unrelated screen transitions + +- Outgoing content fades out +- Incoming content fades in +- Brief overlap period +- No shared elements + +### Fade + +Best for: Show/hide single elements + +- Simple opacity change +- Optionally combine with scale +- Quick duration (100-200ms) + +## Component-Specific Motion + +### FAB + +| State | Animation | +|-------|-----------| +| Appear | Scale up + fade in | +| Disappear | Scale down + fade out | +| Transform | Morph to extended FAB | +| Press | Elevation change (3dp → 8dp) | + +### Bottom Sheet + +| State | Animation | +|-------|-----------| +| Expand | Slide up with decelerate curve | +| Collapse | Slide down with accelerate curve | +| Dismiss | Swipe down with velocity-based duration | + +### Navigation + +| Pattern | Animation | +|---------|-----------| +| Push | Incoming slides from right, outgoing shifts left | +| Pop | Incoming slides from left, outgoing shifts right | +| Modal | Slide up from bottom | + +### Cards + +| State | Animation | +|-------|-----------| +| Expand | Container transform to detail | +| Press | Subtle elevation increase | +| Reorder | Follow finger with physics | + +## Loading & Progress + +### Indeterminate Indicators + +- Use for unknown duration +- Continuous, looping animation +- M3 Expressive: Customizable waveform and thickness + +### Determinate Indicators + +- Use when progress is measurable +- Smooth, linear progression +- Update frequently for responsiveness + +### Skeleton Screens + +- Show layout structure immediately +- Subtle shimmer animation +- Replace with content as it loads + +## Accessibility Considerations + +### Reduced Motion + +- Respect prefers-reduced-motion setting +- Provide alternatives: + - Instant transitions (no animation) + - Simple fade instead of complex motion + - Static loading indicators + +### Motion Duration + +- Keep essential feedback < 100ms +- Avoid motion that could trigger vestibular issues +- Test with motion sensitivity settings enabled + +## Implementation Notes + +### Android Animation APIs + +| API | Usage | +|-----|-------| +| MotionLayout | Complex, coordinated animations | +| Transition | Activity/Fragment transitions | +| Animator | Property animations | +| AnimatedContent | Compose content transitions | +| animateContentSize | Compose size changes | + +### Performance Tips + +- Use hardware layers for complex animations +- Avoid animating layout properties (use transform) +- Profile with GPU rendering tools +- Target 60 FPS (16ms per frame) diff --git a/android-native-dev/references/performance-stability.md b/android-native-dev/references/performance-stability.md new file mode 100644 index 0000000..209fbc2 --- /dev/null +++ b/android-native-dev/references/performance-stability.md @@ -0,0 +1,223 @@ +# Performance & Stability Guidelines + +Android Vitals thresholds, performance requirements, and stability best practices. + +## Android Vitals Thresholds + +### Core Metrics (Google Play) + +Exceeding these thresholds affects app visibility on Google Play: + +| Metric | Overall Threshold | Per Phone Model | Per Watch Model | +|--------|-------------------|-----------------|-----------------| +| User-perceived crash rate | **1.09%** | 8% | 4% | +| User-perceived ANR rate | **0.47%** | 8% | 5% | +| Excessive battery usage | 1% | - | 1% | +| Excessive wake locks | 5% | - | - | + +### Consequences of Exceeding Thresholds + +- Reduced app visibility in Google Play +- Warning label on store listing +- Lower ranking in search results +- Negative impact on user trust + +## Startup Performance + +### Requirements + +| Metric | Target | Maximum | +|--------|--------|---------| +| Cold start | < 1 second | 2 seconds | +| Warm start | < 500ms | 1 second | +| Hot start | < 100ms | 500ms | + +### If Startup Exceeds 2 Seconds + +Must provide visual feedback: +- Progress indicator +- Splash screen with animation +- Loading skeleton + +### Optimization Techniques + +| Technique | Impact | +|-----------|--------| +| Lazy initialization | Defer non-critical work | +| Async loading | Move I/O off main thread | +| View hierarchy optimization | Reduce layout depth | +| App Startup library | Initialize components efficiently | +| Baseline Profiles | Pre-compile hot paths | + +## Rendering Performance + +### Frame Rate Requirements + +| Target | Frame Time | Notes | +|--------|------------|-------| +| 60 FPS | ≤ 16.67ms | Standard requirement | +| 90 FPS | ≤ 11.11ms | High refresh rate displays | +| 120 FPS | ≤ 8.33ms | Premium devices | + +### Jank Detection + +| Metric | Threshold | Severity | +|--------|-----------|----------| +| Slow frames | > 16ms | Warning | +| Frozen frames | > 700ms | Critical | +| Jank rate | > 1% of frames | Poor experience | + +### Common Rendering Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| Overdraw | Multiple layers drawn | Reduce background stacking | +| Deep hierarchy | Complex view nesting | Use ConstraintLayout, Compose | +| Main thread work | Blocking operations | Move to background thread | +| Large bitmaps | Unoptimized images | Downsample, use vector | + +## ANR Prevention + +### ANR Triggers + +| Scenario | Timeout | +|----------|---------| +| Input dispatch | 5 seconds | +| Broadcast receiver | 10 seconds | +| Service start | 20 seconds | + +### Prevention Strategies + +- Never perform network calls on main thread +- Never perform database operations on main thread +- Never perform file I/O on main thread +- Use coroutines, RxJava, or other async mechanisms +- Reduce synchronized block contention + +### Common ANR Causes + +| Cause | Solution | +|-------|----------| +| Network on main thread | Use coroutines/RxJava | +| Database on main thread | Use Room with suspend | +| File I/O on main thread | Use Dispatchers.IO | +| Lock contention | Reduce synchronized blocks | +| Dead locks | Careful threading design | + +## Battery Optimization + +### Wake Lock Guidelines + +| Rule | Implementation | +|------|----------------| +| Minimize duration | Release as soon as possible | +| Use appropriate type | PARTIAL_WAKE_LOCK only when needed | +| Always release | Use try-finally or lifecycle | +| Prefer WorkManager | System-managed scheduling | + +### Background Restrictions + +| Feature | Best Practice | +|---------|---------------| +| Background services | Use WorkManager instead | +| Location | Request only when necessary | +| Network | Batch requests, respect connectivity | +| Alarms | Use inexact alarms when possible | + +### Doze and App Standby + +| Mode | Behavior | Adaptation | +|------|----------|------------| +| Doze | Limited network, alarms delayed | Use FCM for high-priority | +| App Standby | Background work restricted | Use expedited WorkManager | +| Buckets | Frequency limits by usage | Design for infrequent execution | + +## Memory Management + +### Memory Best Practices + +| Practice | Benefit | +|----------|---------| +| Avoid memory leaks | Prevent OutOfMemoryError | +| Use weak references | Allow garbage collection | +| Recycle bitmaps | Reduce memory pressure | +| Monitor heap | Profile regularly | + +### Common Memory Issues + +| Issue | Detection | Solution | +|-------|-----------|----------| +| Activity leak | LeakCanary | Fix lifecycle references | +| Bitmap leak | Memory profiler | Recycle, use Glide/Coil | +| Context leak | Static analysis | Use application context | +| Handler leak | Lint warning | Use WeakReference | + +## StrictMode + +### What StrictMode Detects + +| Category | Issues | +|----------|--------| +| Thread | Disk reads/writes, network, slow calls | +| VM | Leaked objects, unsafe intents, content URI exposure | + +Enable StrictMode in debug builds to detect violations during development. + +## SDK Requirements + +### Version Requirements + +| Property | Requirement | +|----------|-------------| +| targetSdk | Latest Android SDK (Google Play requirement) | +| compileSdk | Latest Android SDK | +| minSdk | Based on target audience | + +### Third-Party SDK Management + +| Practice | Reason | +|----------|--------| +| Keep updated | Security fixes, compatibility | +| Audit regularly | Remove unused dependencies | +| Monitor crashes | SDKs can cause issues | +| Check permissions | SDKs may request excessive permissions | + +### Non-SDK Interface Restrictions + +- Don't use reflection for hidden APIs +- Use Android Studio lint to detect +- APIs may break in future versions + +## Monitoring and Profiling + +### Tools + +| Tool | Purpose | +|------|---------| +| Android Studio Profiler | CPU, memory, network, energy | +| Android Vitals (Play Console) | Production crash/ANR data | +| Firebase Performance | Real-time performance monitoring | +| Perfetto | Advanced system tracing | +| Benchmark library | Reproducible measurements | + +### Key Metrics to Track + +| Metric | Tool | +|--------|------| +| Startup time | Macrobenchmark | +| Frame timing | JankStats | +| Memory usage | Memory Profiler | +| Network latency | Network Profiler | +| Battery drain | Energy Profiler | + +## Performance Checklist + +- [ ] Cold startup < 2 seconds +- [ ] Rendering at 60 FPS +- [ ] No StrictMode violations +- [ ] Crash rate < 1.09% +- [ ] ANR rate < 0.47% +- [ ] No memory leaks +- [ ] Background work uses WorkManager +- [ ] Wake locks properly released +- [ ] SDKs up to date diff --git a/android-native-dev/references/privacy-security.md b/android-native-dev/references/privacy-security.md new file mode 100644 index 0000000..807739e --- /dev/null +++ b/android-native-dev/references/privacy-security.md @@ -0,0 +1,244 @@ +# Privacy & Security Guidelines + +Security best practices and privacy requirements for Android applications. + +## Permissions + +### Principle of Least Privilege + +| Rule | Implementation | +|------|----------------| +| Request minimum | Only permissions essential for core features | +| Request when needed | At point of use, not app startup | +| Explain why | Show rationale before system dialog | +| Degrade gracefully | App works (limited) if denied | + +### Permission Request Flow + +1. Check if already granted +2. If not, show educational UI (rationale) +3. Request permission +4. Handle result (grant or denial) +5. If denied, offer alternative or reduced functionality + +### Sensitive Permissions + +| Permission | Consideration | +|------------|---------------| +| Location | Use coarse if fine not needed | +| Camera | Request only when capturing | +| Microphone | Request only when recording | +| Contacts | Consider contact picker intent | +| Storage | Use scoped storage | +| SMS/Call Log | Restricted, needs approval | + +### Alternative Approaches + +| Instead of... | Consider... | +|---------------|-------------| +| READ_CONTACTS | Contact picker intent | +| ACCESS_FINE_LOCATION | Coarse location | +| READ_EXTERNAL_STORAGE | Storage Access Framework | +| CAMERA | Camera intent | + +## Data Storage + +### Storage Types + +| Type | Security | Usage | +|------|----------|-------| +| Internal storage | Private to app | Sensitive data | +| External storage | World-readable | Shared files only | +| SharedPreferences | Private, unencrypted | Non-sensitive settings | +| EncryptedSharedPreferences | Private, encrypted | Sensitive settings | +| Room database | Private, optional encryption | Structured data | + +### Sensitive Data Rules + +| Rule | Implementation | +|------|----------------| +| Store internally | Use internal storage, not external | +| Encrypt at rest | Use EncryptedSharedPreferences, SQLCipher | +| Don't log | Never log PII or credentials | +| Clear on logout | Wipe user data completely | + +### Data Logging + +Never log sensitive data such as passwords, emails, tokens, or personal information. Only log non-sensitive operational information. + +## Network Security + +### HTTPS Requirements + +- All network traffic must use SSL/TLS +- Configure Network Security Config +- Don't allow cleartext traffic + +### Network Security Config + +Define a network security configuration that: +- Disables cleartext traffic +- Specifies trusted certificate authorities +- Optionally implements certificate pinning for high-security apps + +### Certificate Pinning (Optional) + +For high-security apps, pin certificates to prevent MITM attacks. Include backup pins and plan for certificate rotation. + +## User Identity + +### Credential Manager + +Integrate Credential Manager for unified sign-in supporting: +- Passkeys +- Federated identity +- Traditional passwords + +### Biometric Authentication + +Use biometric authentication for sensitive operations like: +- Financial transactions +- Accessing sensitive documents +- Confirming identity + +### Autofill Support + +Provide autofill hints on input fields: +- emailAddress, username for identity fields +- password for credential fields +- creditCardNumber, postalCode for payment fields + +## App Components Security + +### Exported Components + +| Component | Exported Rule | +|-----------|---------------| +| Launcher Activity | exported="true" with intent-filter | +| Internal Activity | exported="false" | +| Internal Service | exported="false" | +| Content Provider (shared) | exported="true" with permissions | + +Always explicitly set the exported attribute on all components. + +### Custom Permissions + +Use signature-level protection for custom permissions that control access between your own apps. + +### Intent Validation + +- Validate all intent data before use +- Check URI scheme and host +- Use explicit intents when possible +- Don't trust extras from unknown sources + +### PendingIntent Security + +Use FLAG_IMMUTABLE for PendingIntents unless mutability is required. This prevents other apps from modifying the intent. + +## WebView Security + +### Safe WebView Configuration + +| Setting | Recommendation | +|---------|----------------| +| JavaScript | Disabled unless required | +| File access | Disabled | +| Content access | Disabled | +| Universal file access | Never enable | + +### Avoid Dangerous Practices + +| Don't | Why | +|-------|-----| +| setAllowUniversalAccessFromFileURLs(true) | Security vulnerability | +| addJavascriptInterface() with untrusted content | Code injection risk | +| Load untrusted URLs | XSS, phishing | + +## Cryptography + +### Use Platform APIs + +- Use Android Keystore for key storage +- Use standard algorithms (AES-GCM, RSA) +- Never implement custom cryptography +- Use SecureRandom for random generation + +### Avoid + +- Custom encryption implementations +- Weak algorithms (MD5, SHA1 for security) +- Hardcoded keys or secrets +- Non-cryptographic random generators + +## Code Security + +### No Dynamic Code Loading + +| Don't | Do Instead | +|-------|------------| +| Load code at runtime | Android App Bundles | +| Download DEX files | Play Feature Delivery | +| Execute scripts | Predefined functionality | + +### Debug Code Removal + +- Set debuggable=false in release builds +- Enable minification (R8/ProGuard) +- Remove debug libraries from production + +## Device Identifiers + +### Don't Use Hardware IDs + +| Identifier | Status | +|------------|--------| +| IMEI | Don't use | +| MAC address | Don't use | +| Serial number | Don't use | +| Android ID | Limited use only | + +### Recommended Alternatives + +| Use Case | Solution | +|----------|----------| +| Analytics | Firebase Analytics ID | +| Advertising | Advertising ID (resettable) | +| App instance | Generate UUID on install | +| User identity | Account-based ID | + +## Google Play Policies + +### Data Safety + +- Declare all data collected +- Explain data usage +- Provide privacy policy +- Allow data deletion requests + +### User Data Policy + +| Rule | Requirement | +|------|-------------| +| Transparency | Clear disclosure of data use | +| Security | Protect user data appropriately | +| Minimization | Collect only what's needed | +| Control | Allow users to manage data | + +## Security Checklist + +- [ ] Permissions requested only when needed +- [ ] Permissions explained to user +- [ ] Sensitive data stored internally +- [ ] No sensitive data in logs +- [ ] All network traffic over HTTPS +- [ ] Network security config defined +- [ ] Components export status explicit +- [ ] Custom permissions use signature protection +- [ ] Intents validated before use +- [ ] PendingIntents use FLAG_IMMUTABLE +- [ ] WebView configured securely +- [ ] Platform crypto APIs used +- [ ] No debug code in production +- [ ] No hardware IDs used +- [ ] Privacy policy available diff --git a/android-native-dev/references/visual-design.md b/android-native-dev/references/visual-design.md new file mode 100644 index 0000000..b1599e1 --- /dev/null +++ b/android-native-dev/references/visual-design.md @@ -0,0 +1,246 @@ +# Visual Design Guidelines + +Detailed specifications for colors, typography, spacing, elevation, and shapes in Material Design 3. + +## Color System + +### Color Roles (Tokens) + +Material Design 3 uses a token-based color system with three accent groups: + +| Role | Usage | +|------|-------| +| **Primary** | Key components, FAB, prominent buttons | +| **Secondary** | Less prominent components, filters, chips | +| **Tertiary** | Accent, complementary elements | +| **Error** | Error states, destructive actions | +| **Surface** | Backgrounds, cards, dialogs | + +Each role includes variants: base color, onColor, container, onContainer. + +### Color Contrast Requirements + +| Element | Minimum Contrast Ratio | Notes | +|---------|----------------------|-------| +| Body text | **4.5:1** | WCAG AA compliance | +| Large text (18sp+) | **3:1** | 14sp bold also qualifies | +| UI components | **3:1** | Icons, borders, controls | +| Focus indicators | **3:1** | Must be clearly visible | + +### Recommended Color Palettes + +#### Modern Professional (Business Apps) + +| Role | Color | Name | +|------|-------|------| +| Primary | #1976D2 | Blue 700 | +| Secondary | #455A64 | Blue Grey 700 | +| Tertiary | #00897B | Teal 600 | +| Background | #FAFAFA | Grey 50 | + +#### Vibrant & Playful (Consumer Apps) + +| Role | Color | Name | +|------|-------|------| +| Primary | #6200EE | Deep Purple | +| Secondary | #03DAC6 | Teal Accent | +| Tertiary | #FF5722 | Deep Orange | +| Background | #FFFFFF | White | + +#### Dark & Elegant (Premium Apps) + +| Role | Color | Name | +|------|-------|------| +| Primary | #BB86FC | Purple 200 | +| Secondary | #03DAC6 | Teal 200 | +| Tertiary | #CF6679 | Red 200 | +| Background | #121212 | Dark surface | + +#### Nature & Wellness (Health Apps) + +| Role | Color | Name | +|------|-------|------| +| Primary | #4CAF50 | Green 500 | +| Secondary | #8BC34A | Light Green 500 | +| Tertiary | #FFEB3B | Yellow 500 | +| Background | #F1F8E9 | Light Green 50 | + +#### Finance & Trust (Banking Apps) + +| Role | Color | Name | +|------|-------|------| +| Primary | #00695C | Teal 800 | +| Secondary | #37474F | Blue Grey 800 | +| Tertiary | #FFC107 | Amber 500 | +| Background | #ECEFF1 | Blue Grey 50 | + +### Dark Theme Requirements + +- Background: #121212 or darker +- Surface colors use elevation-based tonal overlay +- Primary colors should be lighter variants (200-300 range) +- Maintain contrast ratios in dark mode +- Test all states (hover, focus, pressed) in dark mode + +## Typography System + +### Type Scale + +| Style | Size | Weight | Line Height | Usage | +|-------|------|--------|-------------|-------| +| Display Large | 57sp | 400 | 64sp | Hero text | +| Display Medium | 45sp | 400 | 52sp | Large headers | +| Display Small | 36sp | 400 | 44sp | Section headers | +| Headline Large | 32sp | 400 | 40sp | Screen titles | +| Headline Medium | 28sp | 400 | 36sp | Subsection titles | +| Headline Small | 24sp | 400 | 32sp | Card titles | +| Title Large | 22sp | 400 | 28sp | App bar titles | +| Title Medium | 16sp | 500 | 24sp | List item titles | +| Title Small | 14sp | 500 | 20sp | Tabs | +| Body Large | 16sp | 400 | 24sp | Primary body text | +| Body Medium | 14sp | 400 | 20sp | Secondary body text | +| Body Small | 12sp | 400 | 16sp | Captions | +| Label Large | 14sp | 500 | 20sp | Button text | +| Label Medium | 12sp | 500 | 16sp | Navigation labels | +| Label Small | 11sp | 500 | 16sp | Badges | + +### Recommended Fonts + +| Category | Fonts | +|----------|-------| +| Primary | Roboto (system default) | +| Display | Roboto Serif, Google Sans | +| Monospace | Roboto Mono, JetBrains Mono | + +### Text Readability + +- **Line length**: 45-75 characters per line (including spaces) +- **Paragraph spacing**: 1.5x line height between paragraphs +- **Letter spacing**: Use default unless brand requires adjustment +- **Text alignment**: Left-aligned for body text (LTR languages) + +## Spacing & Layout + +### 8dp Grid System + +All spacing values should be multiples of 8dp (with 4dp for fine adjustments). + +| Token | Value | Usage | +|-------|-------|-------| +| xs | 4dp | Icon padding, fine adjustments | +| sm | 8dp | Tight spacing, inline elements | +| md | 16dp | Default padding, card content | +| lg | 24dp | Section spacing | +| xl | 32dp | Large gaps, group separation | +| xxl | 48dp | Screen margins, major sections | + +### Component Dimensions + +| Component | Height | Min Width | Notes | +|-----------|--------|-----------|-------| +| Button | 40dp | 64dp | Touch target 48dp | +| FAB | 56dp | 56dp | Standard size | +| Mini FAB | 40dp | 40dp | Secondary actions | +| Extended FAB | 56dp | 80dp | With text label | +| Text Field | 56dp | 280dp | Including label | +| App Bar | 64dp | - | Top app bar | +| Bottom Nav | 80dp | - | With labels | +| Nav Rail | - | 80dp | Tablet/desktop | +| List Item | 56-88dp | - | Depends on content | +| Chip | 32dp | - | Filter/action chips | + +### Touch Targets + +| Type | Size | Notes | +|------|------|-------| +| Minimum | 48 × 48dp | WCAG requirement | +| Recommended | 56 × 56dp | Primary actions | +| Kids apps | 56dp+ | Larger for motor skills | +| Spacing | 8dp minimum | Between adjacent targets | + +## Elevation & Shadows + +### Elevation Levels + +| Level | Elevation | Usage | +|-------|-----------|-------| +| Level 0 | 0dp | Flat surfaces | +| Level 1 | 1dp | Cards, elevated buttons | +| Level 2 | 3dp | FAB (resting), raised elements | +| Level 3 | 6dp | Navigation drawer, bottom sheet | +| Level 4 | 8dp | FAB (pressed), menus | +| Level 5 | 12dp | Dialogs, modal surfaces | + +### Shadow Guidelines + +- Use elevation consistently for same component types +- Higher elevation = more important/prominent +- In dark theme, use surface tint instead of shadows +- Avoid excessive elevation (keeps UI grounded) + +## Shape System + +### Corner Radius + +| Size | Radius | Usage | +|------|--------|-------| +| None | 0dp | Sharp edges, dividers | +| Extra Small | 4dp | Badges, small chips | +| Small | 8dp | Buttons, chips, small cards | +| Medium | 12dp | Cards, dialogs, text fields | +| Large | 16dp | FAB, bottom sheets | +| Extra Large | 28dp | Large sheets, expanded cards | +| Full | 50% | Pills, avatars, circular buttons | + +### M3 Expressive Shapes + +Material 3 Expressive introduces 35 new decorative shapes: +- Organic curves +- Asymmetric corners +- Cut corners +- Scalloped edges + +Use sparingly for brand differentiation and visual interest. + +### Shape Consistency Rules + +- Same component type = same shape +- Related components should share shape family +- Don't mix too many shape styles on one screen +- Consider shape in dark/light theme transitions + +## Icons + +### Size Specifications + +| Size | Dimensions | Usage | +|------|------------|-------| +| Small | 20 × 20dp | Compact UI, inline | +| Standard | 24 × 24dp | Default for most uses | +| Large | 40 × 40dp | Emphasis, empty states | + +### Icon Guidelines + +- **Touch target**: Always wrap in 48dp minimum clickable area +- **Style**: Outlined (default), Filled (selected/active states) +- **Stroke width**: 2dp for outlined icons +- **Optical alignment**: May need visual adjustments +- **Color**: Use semantic colors (primary, error, etc.) + +### Recommended Icon Sets + +| Set | Usage | +|-----|-------| +| Material Symbols | Recommended, variable font support | +| Material Icons | Legacy, still widely used | + +### Adaptive Icons (App Icon) + +| Property | Value | +|----------|-------| +| Canvas size | 108 × 108dp | +| Safe zone | 66 × 66dp (centered circle) | +| Logo size | 48-66dp | +| Max display | 72 × 72dp | +| Layers | Foreground + Background (both 108dp) | +| Android 13+ | Include monochrome layer for theming | diff --git a/frontend-design/SKILL.md b/frontend-design/SKILL.md new file mode 100644 index 0000000..5be498e --- /dev/null +++ b/frontend-design/SKILL.md @@ -0,0 +1,42 @@ +--- +name: frontend-design +description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. +license: Complete terms in LICENSE.txt +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. + +## Design Thinking + +Before coding, understand the context and commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity. + +Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +Focus on: +- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. +- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. +- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. +- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. +- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. + +NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. + +**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. + +Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision. diff --git a/frontend-dev/SKILL.md b/frontend-dev/SKILL.md new file mode 100644 index 0000000..8856972 --- /dev/null +++ b/frontend-dev/SKILL.md @@ -0,0 +1,567 @@ +--- +name: frontend-dev +description: | + Full-stack frontend development combining premium UI design, cinematic animations, + AI-generated media assets, persuasive copywriting, and visual art. Builds complete, + visually striking web pages with real media, advanced motion, and compelling copy. + Use when: building landing pages, marketing sites, product pages, dashboards, + generating media assets (image/video/audio/music), writing conversion copy, + creating generative art, or implementing cinematic scroll animations. +license: MIT +metadata: + version: "1.0.0" + category: frontend + sources: + - Framer Motion documentation + - GSAP / GreenSock documentation + - Three.js documentation + - Tailwind CSS documentation + - React / Next.js documentation + - AIDA Framework (Elmo Lewis) + - p5.js documentation +--- + +# Frontend Studio + +Build complete, production-ready frontend pages by orchestrating 5 specialized capabilities: design engineering, motion systems, AI-generated assets, persuasive copy, and generative art. + +## Invocation + +``` +/frontend-dev +``` + +The user provides their request as natural language (e.g. "build a landing page for a music streaming app"). + +## Skill Structure + +``` +frontend-dev/ +├── SKILL.md # Core skill (this file) +├── scripts/ # Asset generation scripts +│ ├── minimax_tts.py # Text-to-speech +│ ├── minimax_music.py # Music generation +│ ├── minimax_video.py # Video generation (async) +│ └── minimax_image.py # Image generation +├── references/ # Detailed guides (read as needed) +│ ├── minimax-cli-reference.md # CLI flags quick reference +│ ├── asset-prompt-guide.md # Asset prompt engineering rules +│ ├── minimax-tts-guide.md # TTS usage & voices +│ ├── minimax-music-guide.md # Music prompts & lyrics format +│ ├── minimax-video-guide.md # Camera commands & models +│ ├── minimax-image-guide.md # Ratios & batch generation +│ ├── minimax-voice-catalog.md # All voice IDs +│ ├── motion-recipes.md # Animation code snippets +│ ├── env-setup.md # Environment setup +│ └── troubleshooting.md # Common issues +├── templates/ # Visual art templates +│ ├── viewer.html # p5.js interactive art base +│ └── generator_template.js # p5.js code reference +└── canvas-fonts/ # Static art fonts (TTF + licenses) +``` + +## Project Structure + +### Assets (Universal) + +All frameworks use the same asset organization: + +``` +assets/ +├── images/ +│ ├── hero-landing-1710xxx.webp +│ ├── icon-feature-01.webp +│ └── bg-pattern.svg +├── videos/ +│ ├── hero-bg-1710xxx.mp4 +│ └── demo-preview.mp4 +└── audio/ + ├── bgm-ambient-1710xxx.mp3 + └── tts-intro-1710xxx.mp3 +``` + +**Asset naming:** `{type}-{descriptor}-{timestamp}.{ext}` + +### By Framework + +| Framework | Asset Location | Component Location | +|-----------|---------------|-------------------| +| **Pure HTML** | `./assets/` | N/A (inline or `./js/`) | +| **React/Next.js** | `public/assets/` | `src/components/` | +| **Vue/Nuxt** | `public/assets/` | `src/components/` | +| **Svelte/SvelteKit** | `static/assets/` | `src/lib/components/` | +| **Astro** | `public/assets/` | `src/components/` | + +### Pure HTML + +``` +project/ +├── index.html +├── assets/ +│ ├── images/ +│ ├── videos/ +│ └── audio/ +├── css/ +│ └── styles.css +└── js/ + └── main.js # Animations (GSAP/vanilla) +``` + +### React / Next.js + +``` +project/ +├── public/assets/ # Static assets +├── src/ +│ ├── components/ +│ │ ├── ui/ # Button, Card, Input +│ │ ├── sections/ # Hero, Features, CTA +│ │ └── motion/ # RevealSection, StaggerGrid +│ ├── lib/ +│ ├── styles/ +│ └── app/ # Pages +└── package.json +``` + +### Vue / Nuxt + +``` +project/ +├── public/assets/ +├── src/ # or root for Nuxt +│ ├── components/ +│ │ ├── ui/ +│ │ ├── sections/ +│ │ └── motion/ +│ ├── composables/ # Shared logic +│ ├── pages/ +│ └── assets/ # Processed assets (optional) +└── package.json +``` + +### Astro + +``` +project/ +├── public/assets/ +├── src/ +│ ├── components/ # .astro, .tsx, .vue, .svelte +│ ├── layouts/ +│ ├── pages/ +│ └── styles/ +└── package.json +``` + +**Component naming:** PascalCase (`HeroSection.tsx`, `HeroSection.vue`, `HeroSection.astro`) + +--- + +## Compliance + +**All rules in this skill are mandatory. Violating any rule is a blocking error — fix before proceeding or delivering.** + +--- + +## Workflow +### Phase 1: Design Architecture +1. Analyze the request — determine page type and context +2. Set design dials based on page type +3. Plan layout sections and identify asset needs + +### Phase 2: Motion Architecture +1. Select animation tools per section (see Tool Selection Matrix) +2. Plan motion sequences following performance guardrails + +### Phase 3: Asset Generation +Generate all image/video/audio assets using `scripts/`. NEVER use placeholder URLs (unsplash, picsum, placeholder.com, via.placeholder, placehold.co, etc.) or external URLs. + +1. Parse asset requirements (type, style, spec, usage) +2. Craft optimized prompts, show to user, confirm before generating +3. Execute via scripts, save to project — do NOT proceed to Phase 5 until all assets are saved locally + +### Phase 4: Copywriting & Content +Follow copywriting frameworks (AIDA, PAS, FAB) to craft all text content. Do NOT use "Lorem ipsum" — write real copy. + +### Phase 5: Build UI +Scaffold the project and build each section following Design and Motion rules. Integrate generated assets and copy. All ``, `