ac-framework 1.9.3 → 1.9.5

package/framework/mobile_development/.cline/skills/mobile-design/platform-android.md

@@ -0,0 +1,666 @@
+# Android Platform Guidelines
+
+> Material Design 3 essentials, Android design conventions, Roboto typography, and native patterns.
+> **Read this file when building for Android devices.**
+
+---
+
+## 1. Material Design 3 Philosophy
+
+### Core Material Principles
+
+```
+MATERIAL AS METAPHOR:
+├── Surfaces exist in 3D space
+├── Light and shadow define hierarchy
+├── Motion provides continuity
+└── Bold, graphic, intentional design
+
+ADAPTIVE DESIGN:
+├── Responds to device capabilities
+├── One UI for all form factors
+├── Dynamic color from wallpaper
+└── Personalized per user
+
+ACCESSIBLE BY DEFAULT:
+├── Large touch targets
+├── Clear visual hierarchy
+├── Semantic colors
+└── Motion respects preferences
+```
+
+### Material Design Values
+
+| Value | Implementation |
+|-------|----------------|
+| **Dynamic Color** | Colors adapt to wallpaper/user preference |
+| **Personalization** | User-specific themes |
+| **Accessibility** | Built into every component |
+| **Responsiveness** | Works on all screen sizes |
+| **Consistency** | Unified design language |
+
+---
+
+## 2. Android Typography
+
+### Roboto Font Family
+
+```
+Android System Fonts:
+├── Roboto: Default sans-serif
+├── Roboto Flex: Variable font (API 33+)
+├── Roboto Serif: Serif alternative
+├── Roboto Mono: Monospace
+└── Google Sans: Google products (special license)
+```
+
+### Material Type Scale
+
+| Role | Size | Weight | Line Height | Usage |
+|------|------|--------|-------------|-------|
+| **Display Large** | 57sp | Regular | 64sp | Hero text, splash |
+| **Display Medium** | 45sp | Regular | 52sp | Large headers |
+| **Display Small** | 36sp | Regular | 44sp | Medium headers |
+| **Headline Large** | 32sp | Regular | 40sp | Page titles |
+| **Headline Medium** | 28sp | Regular | 36sp | Section headers |
+| **Headline Small** | 24sp | Regular | 32sp | Subsections |
+| **Title Large** | 22sp | Regular | 28sp | Dialogs, cards |
+| **Title Medium** | 16sp | Medium | 24sp | Lists, navigation |
+| **Title Small** | 14sp | Medium | 20sp | Tabs, secondary |
+| **Body Large** | 16sp | Regular | 24sp | Primary content |
+| **Body Medium** | 14sp | Regular | 20sp | Secondary content |
+| **Body Small** | 12sp | Regular | 16sp | Captions |
+| **Label Large** | 14sp | Medium | 20sp | Buttons, FAB |
+| **Label Medium** | 12sp | Medium | 16sp | Navigation |
+| **Label Small** | 11sp | Medium | 16sp | Chips, badges |
+
+### Scalable Pixels (sp)
+
+```
+sp = Scale-independent pixels
+
+sp automatically scales with:
+├── User font size preference
+├── Display density
+└── Accessibility settings
+
+RULE: ALWAYS use sp for text, dp for everything else.
+```
+
+### Font Weight Usage
+
+| Weight | Use Case |
+|--------|----------|
+| Regular (400) | Body text, display |
+| Medium (500) | Buttons, labels, emphasis |
+| Bold (700) | Rarely, strong emphasis only |
+
+---
+
+## 3. Material Color System
+
+### Dynamic Color (Material You)
+
+```
+Android 12+ Dynamic Color:
+
+User's wallpaper → Color extraction → App theme
+
+Your app automatically adapts to:
+├── Primary color (from wallpaper)
+├── Secondary color (complementary)
+├── Tertiary color (accent)
+├── Surface colors (derived)
+└── All semantic colors adjust
+
+RULE: Implement dynamic color for personalized feel.
+```
+
+### Semantic Color Roles
+
+```
+Surface Colors:
+├── Surface → Main background
+├── SurfaceVariant → Cards, containers
+├── SurfaceTint → Elevation overlay
+├── InverseSurface → Snackbars, tooltips
+
+On-Surface Colors:
+├── OnSurface → Primary text
+├── OnSurfaceVariant → Secondary text
+├── Outline → Borders, dividers
+├── OutlineVariant → Subtle dividers
+
+Primary Colors:
+├── Primary → Key actions, FAB
+├── OnPrimary → Text on primary
+├── PrimaryContainer → Less emphasis
+├── OnPrimaryContainer → Text on container
+
+Secondary/Tertiary: Similar pattern
+```
+
+### Error, Warning, Success Colors
+
+| Role | Light | Dark | Usage |
+|------|-------|------|-------|
+| Error | #B3261E | #F2B8B5 | Errors, destructive |
+| OnError | #FFFFFF | #601410 | Text on error |
+| ErrorContainer | #F9DEDC | #8C1D18 | Error backgrounds |
+
+### Dark Theme
+
+```
+Material Dark Theme:
+
+├── Background: #121212 (not pure black by default)
+├── Surface: #1E1E1E, #232323, etc. (elevation)
+├── Elevation: Higher = lighter overlay
+├── Reduce saturation on colors
+└── Check contrast ratios
+
+Elevation overlays (dark mode):
+├── 0dp → 0% overlay
+├── 1dp → 5% overlay
+├── 3dp → 8% overlay
+├── 6dp → 11% overlay
+├── 8dp → 12% overlay
+├── 12dp → 14% overlay
+```
+
+---
+
+## 4. Android Layout & Spacing
+
+### Layout Grid
+
+```
+Android uses 8dp baseline grid:
+
+All spacing in multiples of 8dp:
+├── 4dp: Component internal (half-step)
+├── 8dp: Minimum spacing
+├── 16dp: Standard spacing
+├── 24dp: Section spacing
+├── 32dp: Large spacing
+
+Margins:
+├── Compact (phone): 16dp
+├── Medium (small tablet): 24dp
+├── Expanded (large): 24dp+ or columns
+```
+
+### Responsive Layout
+
+```
+Window Size Classes:
+
+COMPACT (< 600dp width):
+├── Phones in portrait
+├── Single column layout
+├── Bottom navigation
+
+MEDIUM (600-840dp width):
+├── Tablets, foldables
+├── Consider 2 columns
+├── Navigation rail option
+
+EXPANDED (> 840dp width):
+├── Large tablets, desktop
+├── Multi-column layouts
+├── Navigation drawer
+```
+
+### Canonical Layouts
+
+| Layout | Use Case | Window Class |
+|--------|----------|--------------|
+| **List-Detail** | Email, messages | Medium, Expanded |
+| **Feed** | Social, news | All |
+| **Supporting Pane** | Reference content | Medium, Expanded |
+
+---
+
+## 5. Android Navigation Patterns
+
+### Navigation Components
+
+| Component | Use Case | Position |
+|-----------|----------|----------|
+| **Bottom Navigation** | 3-5 top-level destinations | Bottom |
+| **Navigation Rail** | Tablets, foldables | Left side, vertical |
+| **Navigation Drawer** | Many destinations, large screens | Left side, hidden/visible |
+| **Top App Bar** | Current context, actions | Top |
+
+### Bottom Navigation
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│         Content Area                │
+│                                     │
+├─────────────────────────────────────┤
+│  🏠     🔍     ➕     ❤️     👤    │ ← 80dp height
+│ Home   Search  FAB   Saved  Profile│
+└─────────────────────────────────────┘
+
+Rules:
+├── 3-5 destinations
+├── Icons: Material Symbols (24dp)
+├── Labels: Always visible (accessibility)
+├── Active: Filled icon + indicator pill
+├── Badge: For notifications
+├── FAB can integrate (optional)
+```
+
+### Top App Bar
+
+```
+Types:
+├── Center-aligned: Logo apps, simple
+├── Small: Compact, scrolls away
+├── Medium: Title + actions, collapses
+├── Large: Display title, collapses to small
+
+┌─────────────────────────────────────┐
+│  ☰   App Title              🔔 ⋮  │ ← 64dp (small)
+├─────────────────────────────────────┤
+│                                     │
+│         Content Area                │
+└─────────────────────────────────────┘
+
+Actions: Max 3 icons, overflow menu ( ⋮ ) for more
+```
+
+### Navigation Rail (Tablets)
+
+```
+┌───────┬─────────────────────────────┐
+│  ≡    │                             │
+│       │                             │
+│  🏠   │                             │
+│ Home  │       Content Area          │
+│       │                             │
+│  🔍   │                             │
+│Search │                             │
+│       │                             │
+│  👤   │                             │
+│Profile│                             │
+└───────┴─────────────────────────────┘
+
+Width: 80dp
+Icons: 24dp
+Labels: Below icon
+FAB: Can be at top
+```
+
+### Back Navigation
+
+```
+Android provides system back:
+├── Back button (3-button nav)
+├── Back gesture (swipe from edge)
+├── Predictive back (Android 14+)
+
+Your app must:
+├── Handle back correctly (pop stack)
+├── Support predictive back animation
+├── Never hijack/override back unexpectedly
+└── Confirm before discarding unsaved work
+```
+
+---
+
+## 6. Material Components
+
+### Buttons
+
+```
+Button Types:
+
+┌──────────────────────┐
+│    Filled Button     │  ← Primary action
+└──────────────────────┘
+
+┌──────────────────────┐
+│    Tonal Button      │  ← Secondary, less emphasis
+└──────────────────────┘
+
+┌──────────────────────┐
+│   Outlined Button    │  ← Tertiary, lower emphasis
+└──────────────────────┘
+
+    Text Button           ← Lowest emphasis
+
+Heights:
+├── Small: 40dp (when constrained)
+├── Standard: 40dp
+├── Large: 56dp (FAB size when needed)
+
+Min touch target: 48dp (even if visual is smaller)
+```
+
+### Floating Action Button (FAB)
+
+```
+FAB Types:
+├── Standard: 56dp diameter
+├── Small: 40dp diameter
+├── Large: 96dp diameter
+├── Extended: Icon + text, variable width
+
+Position: Bottom right, 16dp from edges
+Elevation: Floats above content
+
+┌─────────────────────────────────────┐
+│                                     │
+│         Content                     │
+│                                     │
+│                              ┌────┐ │
+│                              │ ➕ │ │ ← FAB
+│                              └────┘ │
+├─────────────────────────────────────┤
+│       Bottom Navigation             │
+└─────────────────────────────────────┘
+```
+
+### Cards
+
+```
+Card Types:
+├── Elevated: Shadow, resting state
+├── Filled: Background color, no shadow
+├── Outlined: Border, no shadow
+
+Card Anatomy:
+┌─────────────────────────────────────┐
+│           Header Image              │ ← Optional
+├─────────────────────────────────────┤
+│  Title / Headline                   │
+│  Subhead / Supporting text          │
+├─────────────────────────────────────┤
+│      [ Action ]    [ Action ]       │ ← Optional actions
+└─────────────────────────────────────┘
+
+Corner radius: 12dp (M3 default)
+Padding: 16dp
+```
+
+### Text Fields
+
+```
+Types:
+├── Filled: Background fill, underline
+├── Outlined: Border all around
+
+┌─────────────────────────────────────┐
+│  Label                              │ ← Floats up on focus
+│  ________________________________________________
+│  │     Input text here...          │ ← Leading/trailing icons
+│  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
+│  Supporting text or error           │
+└─────────────────────────────────────┘
+
+Height: 56dp
+Label: Animates from placeholder to top
+Error: Red color + icon + message
+```
+
+### Chips
+
+```
+Types:
+├── Assist: Smart actions (directions, call)
+├── Filter: Toggle filters
+├── Input: Represent entities (tags, contacts)
+├── Suggestion: Dynamic recommendations
+
+┌───────────────┐
+│  🏷️ Filter   │  ← 32dp height, 8dp corner radius
+└───────────────┘
+
+States: Unselected, Selected, Disabled
+```
+
+---
+
+## 7. Android-Specific Patterns
+
+### Snackbars
+
+```
+Position: Bottom, above navigation
+Duration: 4-10 seconds
+Action: One optional text action
+
+┌─────────────────────────────────────────────────┐
+│  Archived 1 item                    [ UNDO ]    │
+└─────────────────────────────────────────────────┘
+
+Rules:
+├── Brief message, single line if possible
+├── Max 2 lines
+├── One action (text, not icon)
+├── Can be dismissed by swipe
+└── Don't stack, queue them
+```
+
+### Bottom Sheets
+
+```
+Types:
+├── Standard: Interactive content
+├── Modal: Blocks background (with scrim)
+
+Modal Bottom Sheet:
+┌─────────────────────────────────────┐
+│                                     │
+│        (Scrim over content)         │
+│                                     │
+├═════════════════════════════════════┤
+│  ─────  (Drag handle, optional)     │
+│                                     │
+│        Sheet Content                │
+│                                     │
+│        Actions / Options            │
+│                                     │
+└─────────────────────────────────────┘
+
+Corner radius: 28dp (top corners)
+```
+
+### Dialogs
+
+```
+Types:
+├── Basic: Title + content + actions
+├── Full-screen: Complex editing (mobile)
+├── Date/Time picker
+├── Confirmation dialog
+
+┌─────────────────────────────────────┐
+│              Title                  │
+│                                     │
+│       Supporting text that          │
+│       explains the dialog           │
+│                                     │
+│           [ Cancel ]  [ Confirm ]   │
+└─────────────────────────────────────┘
+
+Rules:
+├── Centered on screen
+├── Scrim behind (dim background)
+├── Max 2 actions aligned right
+├── Destructive action can be on left
+```
+
+### Pull to Refresh
+
+```
+Android uses SwipeRefreshLayout pattern:
+
+┌─────────────────────────────────────┐
+│         ○ (Spinner)                 │ ← Circular progress
+├─────────────────────────────────────┤
+│                                     │
+│         Content                     │
+│                                     │
+└─────────────────────────────────────┘
+
+Spinner: Material circular indicator
+Position: Top center, pulls down with content
+```
+
+### Ripple Effect
+
+```
+Every touchable element needs ripple:
+
+Touch down → Ripple expands from touch point
+Touch up → Ripple completes and fades
+
+Color: 
+├── On light: Black at ~12% opacity
+├── On dark: White at ~12% opacity
+├── On colored: Appropriate contrast
+
+This is MANDATORY for Android feel.
+```
+
+---
+
+## 8. Material Symbols
+
+### Usage Guidelines
+
+```
+Material Symbols: Google's icon library
+
+Styles:
+├── Outlined: Default, most common
+├── Rounded: Softer, friendly
+├── Sharp: Angular, precise
+
+Variable font axes:
+├── FILL: 0 (outline) to 1 (filled)
+├── wght: 100-700 (weight)
+├── GRAD: -25 to 200 (emphasis)
+├── opsz: 20, 24, 40, 48 (optical size)
+```
+
+### Icon Sizes
+
+| Size | Usage |
+|------|-------|
+| 20dp | Dense UI, inline |
+| 24dp | Standard (most common) |
+| 40dp | Larger touch targets |
+| 48dp | Emphasis, standalone |
+
+### States
+
+```
+Icon States:
+├── Default: Full opacity
+├── Disabled: 38% opacity
+├── Hover/Focus: Container highlight
+├── Selected: Filled variant + tint
+
+Active vs Inactive:
+├── Inactive: Outlined
+├── Active: Filled + indicator
+```
+
+---
+
+## 9. Android Accessibility
+
+### TalkBack Requirements
+
+```
+Every interactive element needs:
+├── contentDescription (what it is)
+├── Correct semantics (button, checkbox, etc.)
+├── State announcements (selected, disabled)
+└── Grouping where logical
+
+Jetpack Compose:
+Modifier.semantics {
+    contentDescription = "Play button"
+    role = Role.Button
+}
+
+React Native:
+accessibilityLabel="Play button"
+accessibilityRole="button"
+accessibilityState={{ disabled: false }}
+```
+
+### Touch Target Size
+
+```
+MANDATORY: 48dp × 48dp minimum
+
+Even if visual element is smaller:
+├── Icon: 24dp visual, 48dp touch area
+├── Checkbox: 20dp visual, 48dp touch area
+└── Add padding to reach 48dp
+
+Spacing between targets: 8dp minimum
+```
+
+### Font Scaling
+
+```
+Android supports font scaling:
+├── 85% (smaller)
+├── 100% (default)
+├── 115%, 130%, 145%...
+├── Up to 200% (largest)
+
+RULE: Test your UI at 200% font scale.
+Use sp units and avoid fixed heights.
+```
+
+### Reduce Motion
+
+```kotlin
+// Check motion preference
+val reduceMotion = Settings.Global.getFloat(
+    contentResolver,
+    Settings.Global.ANIMATOR_DURATION_SCALE,
+    1f
+) == 0f
+
+if (reduceMotion) {
+    // Skip or reduce animations
+}
+```
+
+---
+
+## 10. Android Checklist
+
+### Before Every Android Screen
+
+- [ ] Using Material 3 components
+- [ ] Touch targets ≥ 48dp
+- [ ] Ripple effect on all touchables
+- [ ] Roboto or Material type scale
+- [ ] Semantic colors (dynamic color support)
+- [ ] Back navigation works correctly
+
+### Before Android Release
+
+- [ ] Dark theme tested
+- [ ] Dynamic color tested (if supported)
+- [ ] All font sizes tested (200% scale)
+- [ ] TalkBack tested
+- [ ] Predictive back implemented (Android 14+)
+- [ ] Edge-to-edge display (Android 15+)
+- [ ] Different screen sizes tested (phones, tablets)
+- [ ] Navigation patterns match platform (back, gestures)
+
+---
+
+> **Remember:** Android users expect Material Design. Custom designs that ignore Material patterns feel foreign and broken. Use Material components as your foundation, customize thoughtfully.