ac-framework 1.9.3 → 1.9.5

package/framework/mobile_development/.windsurf/skills/mobile-design/mobile-color-system.md

@@ -0,0 +1,420 @@
+# Mobile Color System Reference
+
+> OLED optimization, dark mode, battery-aware colors, and outdoor visibility.
+> **Color on mobile isn't just aesthetics—it's battery life and usability.**
+
+---
+
+## 1. Mobile Color Fundamentals
+
+### Why Mobile Color is Different
+
+```
+DESKTOP:                           MOBILE:
+├── LCD screens (backlit)          ├── OLED common (self-emissive)
+├── Controlled lighting            ├── Outdoor, bright sun
+├── Stable power                   ├── Battery matters
+├── Personal preference            ├── System-wide dark mode
+└── Static viewing                 └── Variable angles, motion
+```
+
+### Mobile Color Priorities
+
+| Priority | Why |
+|----------|-----|
+| **1. Readability** | Outdoor, variable lighting |
+| **2. Battery efficiency** | OLED = dark mode saves power |
+| **3. System integration** | Dark/light mode support |
+| **4. Semantics** | Error, success, warning colors |
+| **5. Brand** | After functional requirements |
+
+---
+
+## 2. OLED Considerations
+
+### How OLED Differs
+
+```
+LCD (Liquid Crystal Display):
+├── Backlight always on
+├── Black = backlight through dark filter
+├── Energy use = constant
+└── Dark mode = no battery savings
+
+OLED (Organic LED):
+├── Each pixel emits own light
+├── Black = pixel OFF (zero power)
+├── Energy use = brighter pixels use more
+└── Dark mode = significant battery savings
+```
+
+### Battery Savings with OLED
+
+```
+Color energy consumption (relative):
+
+#000000 (True Black)  ████░░░░░░  0%
+#1A1A1A (Near Black)  █████░░░░░  ~15%
+#333333 (Dark Gray)   ██████░░░░  ~30%
+#666666 (Medium Gray) ███████░░░  ~50%
+#FFFFFF (White)       ██████████  100%
+
+Saturated colors also use significant power:
+├── Blue pixels: Most efficient
+├── Green pixels: Medium
+├── Red pixels: Least efficient
+└── Desaturated colors save more
+```
+
+### True Black vs Near Black
+
+```
+#000000 (True Black):
+├── Maximum battery savings
+├── Can cause "black smear" on scroll
+├── Sharp contrast (may be harsh)
+└── Used by Apple in pure dark mode
+
+#121212 or #1A1A1A (Near Black):
+├── Still good battery savings
+├── Smoother scrolling (no smear)
+├── Slightly softer on eyes
+└── Material Design recommendation
+
+RECOMMENDATION: #000000 for backgrounds, #0D0D0D-#1A1A1A for surfaces
+```
+
+---
+
+## 3. Dark Mode Design
+
+### Dark Mode Benefits
+
+```
+Users enable dark mode for:
+├── Battery savings (OLED)
+├── Reduced eye strain (low light)
+├── Personal preference
+├── AMOLED aesthetic
+└── Accessibility (light sensitivity)
+```
+
+### Dark Mode Color Strategy
+
+```
+LIGHT MODE                      DARK MODE
+──────────                      ─────────
+Background: #FFFFFF      →      #000000 or #121212
+Surface:    #F5F5F5      →      #1E1E1E
+Surface 2:  #EEEEEE      →      #2C2C2C
+
+Primary:    #1976D2      →      #90CAF9 (lighter)
+Text:       #212121      →      #E0E0E0 (not pure white)
+Secondary:  #757575      →      #9E9E9E
+
+Elevation in dark mode:
+├── Higher = slightly lighter surface
+├── 0dp →  0% overlay
+├── 4dp →  9% overlay
+├── 8dp →  12% overlay
+└── Creates depth without shadows
+```
+
+### Text Colors in Dark Mode
+
+| Role | Light Mode | Dark Mode |
+|------|------------|-----------|
+| Primary | #000000 (Black) | #E8E8E8 (Not pure white) |
+| Secondary | #666666 | #B0B0B0 |
+| Disabled | #9E9E9E | #6E6E6E |
+| Links | #1976D2 | #8AB4F8 |
+
+### Color Inversion Rules
+
+```
+DON'T just invert colors:
+├── Saturated colors become eye-burning
+├── Semantic colors lose meaning
+├── Brand colors may break
+└── Contrast ratios change unpredictably
+
+DO create intentional dark palette:
+├── Desaturate primary colors
+├── Use lighter tints for emphasis
+├── Maintain semantic color meanings
+├── Check contrast ratios independently
+```
+
+---
+
+## 4. Outdoor Visibility
+
+### The Sunlight Problem
+
+```
+Screen visibility outdoors:
+├── Bright sun washes out low contrast
+├── Glare reduces readability
+├── Polarized sunglasses affect
+└── Users shield screen with hand
+
+Affected elements:
+├── Light gray text on white
+├── Subtle color differences
+├── Low opacity overlays
+└── Pastel colors
+```
+
+### High Contrast Strategies
+
+```
+For outdoor visibility:
+
+MINIMUM CONTRAST RATIOS:
+├── Normal text: 4.5:1 (WCAG AA)
+├── Large text: 3:1 (WCAG AA)
+├── Recommended: 7:1+ (AAA)
+
+AVOID:
+├── #999 on #FFF (fails AA)
+├── #BBB on #FFF (fails)
+├── Pale colors on light backgrounds
+└── Subtle gradients for critical info
+
+DO:
+├── Use system semantic colors
+├── Test in bright environment
+├── Provide high contrast mode
+└── Use solid colors for critical UI
+```
+
+---
+
+## 5. Semantic Colors
+
+### Consistent Meaning
+
+| Semantic | Meaning | iOS Default | Android Default |
+|----------|---------|-------------|-----------------|
+| Error | Problems, destruction | #FF3B30 | #B3261E |
+| Success | Completion, positive | #34C759 | #4CAF50 |
+| Warning | Attention, caution | #FF9500 | #FFC107 |
+| Info | Information | #007AFF | #2196F3 |
+
+### Semantic Color Rules
+
+```
+NEVER use semantic colors for:
+├── Branding (confuses meaning)
+├── Decoration (reduces impact)
+├── Arbitrary styling
+└── Status indicators (use icons too)
+
+ALWAYS:
+├── Pair with icons (colorblind users)
+├── Maintain across light/dark modes
+├── Keep consistent throughout app
+└── Follow platform conventions
+```
+
+### Error State Colors
+
+```
+Error states need:
+├── Red-ish color (semantic)
+├── High contrast against background
+├── Icon reinforcement
+├── Clear text explanation
+
+iOS:
+├── Light: #FF3B30
+├── Dark: #FF453A
+
+Android:
+├── Light: #B3261E
+├── Dark: #F2B8B5 (on error container)
+```
+
+---
+
+## 6. Dynamic Color (Android)
+
+### Material You
+
+```
+Android 12+ Dynamic Color:
+
+User's wallpaper → Color extraction → App theme
+
+Your app automatically gets:
+├── Primary (from wallpaper dominant)
+├── Secondary (complementary)
+├── Tertiary (accent)
+├── Surface colors (neutral, derived)
+├── On-colors (text on each)
+```
+
+### Supporting Dynamic Color
+
+```kotlin
+// Jetpack Compose
+MaterialTheme(
+    colorScheme = dynamicColorScheme()
+        ?: staticColorScheme() // Fallback for older Android
+)
+
+// React Native
+// Limited support - consider react-native-material-you
+```
+
+### Fallback Colors
+
+```
+When dynamic color unavailable:
+├── Android < 12
+├── User disabled
+├── Non-supporting launchers
+
+Provide static color scheme:
+├── Define your brand colors
+├── Test in both modes
+├── Match dynamic color roles
+└── Support light + dark
+```
+
+---
+
+## 7. Color Accessibility
+
+### Colorblind Considerations
+
+```
+~8% of men, ~0.5% of women are colorblind
+
+Types:
+├── Protanopia (red weakness)
+├── Deuteranopia (green weakness)
+├── Tritanopia (blue weakness)
+├── Monochromacy (rare, no color)
+
+Design rules:
+├── Never rely on color alone
+├── Use patterns, icons, text
+├── Test with simulation tools
+├── Avoid red/green distinctions only
+```
+
+### Contrast Testing Tools
+
+```
+Use these to verify:
+├── Built-in accessibility inspector (Xcode)
+├── Accessibility Scanner (Android)
+├── Contrast ratio calculators
+├── Colorblind simulation
+└── Test on actual devices in sunlight
+```
+
+### Sufficient Contrast
+
+```
+WCAG Guidelines:
+
+AA (Minimum)
+├── Normal text: 4.5:1
+├── Large text (18pt+): 3:1
+├── UI components: 3:1
+
+AAA (Enhanced)
+├── Normal text: 7:1
+├── Large text: 4.5:1
+
+Mobile recommendation: Meet AA, aim for AAA
+```
+
+---
+
+## 8. Color Anti-Patterns
+
+### ❌ Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| **Light gray on white** | Invisible outdoors | Min 4.5:1 contrast |
+| **Pure white in dark mode** | Eye strain | Use #E0E0E0-#F0F0F0 |
+| **Same saturation dark mode** | Garish, glowing | Desaturate colors |
+| **Red/green only indicator** | Colorblind users can't see | Add icons |
+| **Semantic colors for brand** | Confusing meaning | Use neutral for brand |
+| **Ignoring system dark mode** | Jarring experience | Support both modes |
+
+### ❌ AI Color Mistakes
+
+```
+AI tends to:
+├── Use same colors for light/dark
+├── Ignore OLED battery implications
+├── Skip contrast calculations
+├── Default to purple/violet (BANNED)
+├── Use low contrast "aesthetic" grays
+├── Not test in outdoor conditions
+└── Forget colorblind users
+
+RULE: Design for the worst case.
+Test in bright sunlight, with colorblindness simulation.
+```
+
+---
+
+## 9. Color System Checklist
+
+### Before Choosing Colors
+
+- [ ] Light and dark mode variants defined?
+- [ ] Contrast ratios checked (4.5:1+)?
+- [ ] OLED battery considered (dark mode)?
+- [ ] Semantic colors follow conventions?
+- [ ] Colorblind-safe (not color-only indicators)?
+
+### Before Release
+
+- [ ] Tested in bright sunlight?
+- [ ] Tested dark mode on OLED device?
+- [ ] System dark mode respected?
+- [ ] Dynamic color supported (Android)?
+- [ ] Error/success/warning consistent?
+- [ ] All text meets contrast requirements?
+
+---
+
+## 10. Quick Reference
+
+### Dark Mode Backgrounds
+
+```
+True black (OLED max savings): #000000
+Near black (Material):         #121212
+Surface 1:                     #1E1E1E
+Surface 2:                     #2C2C2C
+Surface 3:                     #3C3C3C
+```
+
+### Text on Dark
+
+```
+Primary:   #E0E0E0 to #ECECEC
+Secondary: #A0A0A0 to #B0B0B0
+Disabled:  #606060 to #707070
+```
+
+### Contrast Ratios
+
+```
+Small text:  4.5:1 (minimum)
+Large text:  3:1 (minimum)
+UI elements: 3:1 (minimum)
+Ideal:       7:1 (AAA)
+```
+
+---
+
+> **Remember:** Color on mobile must work in the worst conditions—bright sun, tired eyes, colorblindness, low battery. Pretty colors that fail these tests are useless colors.

package/framework/mobile_development/.windsurf/skills/mobile-design/mobile-debugging.md

@@ -0,0 +1,122 @@
+# Mobile Debugging Guide
+
+> **Stop console.log() debugging!**
+> Mobile apps have complex native layers. Text logs are not enough.
+> **This file teaches effective mobile debugging strategies.**
+
+---
+
+## 🧠 MOBILE DEBUGGING MINDSET
+
+```
+Web Debugging:      Mobile Debugging:
+┌──────────────┐    ┌──────────────┐
+│  Browser     │    │  JS Bridge   │
+│  DevTools    │    │  Native UI   │
+│  Network Tab │    │  GPU/Memory  │
+└──────────────┘    │  Threads     │
+                    └──────────────┘
+```
+
+**Key Differences:**
+1.  **Native Layer:** JS code works, but app crashes? It's likely native (Java/Obj-C).
+2.  **Deployment:** You can't just "refresh". State gets lost or stuck.
+3.  **Network:** SSL Pinning, proxy settings are harder.
+4.  **Device Logs:** `adb logcat` and `Console.app` are your truth.
+
+---
+
+## 🚫 AI DEBUGGING ANTI-PATTERNS
+
+| ❌ Default | ✅ Mobile-Correct |
+|------------|-------------------|
+| "Add console.logs" | Use Flipper / Reactotron |
+| "Check network tab" | Use Charles Proxy / Proxyman |
+| "It works on simulator" | **Test on Real Device** (HW specific bugs) |
+| "Reinstall node_modules" | **Clean Native Build** (Gradle/Pod cache) |
+| Ignored native logs | Read `logcat` / Xcode logs |
+
+---
+
+## 1. The Toolset
+
+### ⚡ React Native & Expo
+
+| Tool | Purpose | Best For |
+|------|---------|----------|
+| **Reactotron** | State/API/Redux | JS side debugging |
+| **Flipper** | Layout/Network/db | Native + JS bridge |
+| **Expo Tools** | Element inspector | Quick UI checks |
+
+### 🛠️ Native Layer (The Deep Dive)
+
+| Tool | Platform | Command | Why Use? |
+|------|----------|---------|----------|
+| **Logcat** | Android | `adb logcat` | Native crashes, ANRs |
+| **Console** | iOS | via Xcode | Native exceptions, memory |
+| **Layout Insp.** | Android | Android Studio | UI hierarchy bugs |
+| **View Insp.** | iOS | Xcode | UI hierarchy bugs |
+
+---
+
+## 2. Common Debugging Workflows
+
+### 🕵️ "The App Just Crashed" (Red Screen vs Crash to Home)
+
+**Scenario A: Red Screen (JS Error)**
+- **Cause:** Undefined is not an object, import error.
+- **Fix:** Read the stack trace on screen. It's usually clear.
+
+**Scenario B: Crash to Home Screen (Native Crash)**
+- **Cause:** Native module failure, memory OOM, permission usage without declaration.
+- **Tools:**
+    - **Android:** `adb logcat *:E` (Filter for Errors)
+    - **iOS:** Open Xcode → Window → Devices → View Device Logs
+
+> **💡 Pro Tip:** If app crashes immediately on launch, it's almost 100% a native configuration issue (Info.plist, AndroidManifest.xml).
+
+### 🌐 "API Request Failed" (Network)
+
+**Web:** Open Chrome DevTools → Network.
+**Mobile:** *You usually can't see this easily.*
+
+**Solution 1: Reactotron/Flipper**
+- View network requests in the monitoring app.
+
+**Solution 2: Proxy (Charles/Proxyman)**
+- **Hard but powerful.** See ALL traffic even from native SDKs.
+- Requires installing SSL cert on device.
+
+### 🐢 "The UI is Laggy" (Performance)
+
+**Don't guess.** measure.
+- **React Native:** Performance Monitor (Shake menu).
+- **Android:** "Profile GPU Rendering" in Developer Options.
+- **Issues:**
+    - **JS FPS drop:** Heavy calculation in JS thread.
+    - **UI FPS drop:** Too many views, intricate hierarchy, heavy images.
+
+---
+
+## 3. Platform-Specific Nightmares
+
+### Android
+- **Gradle Sync Fail:** Usually Java version mismatch or duplicate classes.
+- **Emulator Network:** Emulator `localhost` is `10.0.2.2`, NOT `127.0.0.1`.
+- **Cached Builds:** `./gradlew clean` is your best friend.
+
+### iOS
+- **Pod Issues:** `pod deintegrate && pod install`.
+- **Signing Errors:** Check Team ID and Bundle Identifier.
+- **Cache:** Xcode → Product → Clean Build Folder.
+
+---
+
+## 📝 DEBUGGING CHECKLIST
+
+- [ ] **Is it a JS or Native crash?** (Red screen or home screen?)
+- [ ] **Did you clean build?** (Native caches are aggressive)
+- [ ] **Are you on a real device?** (Simulators hide concurrency bugs)
+- [ ] **Did you check the native logs?** (Not just terminal output)
+
+> **Remember:** If JavaScript looks perfect but the app fails, look closer at the Native side.