ac-framework 2.3.0 → 2.4.0

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

@@ -1,420 +0,0 @@
-# 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/.antigravity/skills/mobile-design/mobile-debugging.md

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