@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/skills/mobile-design/platform-android.md

@@ -1,666 +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.
+# 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.