Initial commit: add all skills files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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%)

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

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

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

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)

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

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

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 |