wize-dev-kit 0.1.4 → 0.2.0

package/src/app-overlay/playbooks/material-design-3.md

@@ -0,0 +1,135 @@
+---
+playbook: material-design-3
+owner: wize-agent-ux-designer   # Mantis
+applies_when: app-overlay active (Android)
+status: ready
+---
+
+# Material Design 3 (Material You) — Mantis Playbook
+
+M3 is a design system that adapts to the user, not the other way around. Tokens drive everything.
+
+## 1. The four pillars
+
+1. **Personal** — colors derive from user wallpaper (Material You).
+2. **Adaptive** — same UI, different layouts on phone / foldable / tablet / desktop.
+3. **Expressive** — bigger type, richer motion, branded but readable.
+4. **Inclusive** — built-in accessibility floor: contrast tiers, large touch targets, dynamic type.
+
+## 2. Tokens (the only acceptable way to ship styles)
+
+### Color roles
+
+| Role | Use for |
+|---|---|
+| `primary` | Brand primary action color, FABs, prominent buttons. |
+| `onPrimary` | Foreground on `primary`. |
+| `primaryContainer` | Tonal surfaces using primary hue. |
+| `onPrimaryContainer` | Foreground on `primaryContainer`. |
+| `secondary` / `tertiary` | Lower-emphasis accents. |
+| `surface` / `surfaceVariant` | Cards, sheets, containers. |
+| `surfaceContainer*` (M3) | New tiers: low, mid, high, highest. Use for elevation-by-color. |
+| `error` / `onError` | Error states. |
+| `outline` / `outlineVariant` | Borders, dividers. |
+
+Never use raw hex. Always tokens. Color is regenerated from the user's seed (dynamic) — hex won't recolor.
+
+### Type scale (M3)
+
+| Token | Use |
+|---|---|
+| `displayLarge` / `Medium` / `Small` | Hero text, rarely. |
+| `headlineLarge` / `Medium` / `Small` | Page-level titles. |
+| `titleLarge` / `Medium` / `Small` | Section, dialog titles. |
+| `bodyLarge` / `Medium` / `Small` | Body content. |
+| `labelLarge` / `Medium` / `Small` | Buttons, chips, captions. |
+
+### Shape
+
+`shape.small` (4dp) / `medium` (12dp) / `large` (16dp) / `extraLarge` (28dp). Cards: medium. Bottom sheets: large. FAB: extraLarge.
+
+### Elevation by color (M3 change)
+
+M3 prefers tonal elevation (surface color tier) over shadow. Use `surfaceContainerLow` → `surfaceContainerHighest` to express depth. Drop shadows are still allowed but secondary.
+
+## 3. Components (a starter set)
+
+| Component | Default | Notes |
+|---|---|---|
+| Top app bar | Small (default) | Center-aligned, medium, large variants for hero pages. |
+| Navigation bar (bottom) | 3–5 destinations | Phones default. |
+| Navigation rail | tablets / foldable open | Side rail for medium widths. |
+| Navigation drawer | tablets / desktops | Persistent sidebar pattern. |
+| FAB | Primary action | 1 per screen max. |
+| Extended FAB | Action + label | When the action is non-obvious. |
+| Cards | Filled / Outlined / Elevated | Pick one variant per surface family. |
+| Chips | Assist / Filter / Input / Suggestion | Match the use-case verb. |
+| Buttons | Elevated / Filled / Tonal / Outlined / Text | Pick by hierarchy, not aesthetics. |
+| Bottom sheet | Modal (standalone) / Standard (inline) | Standard is the new big M3 pattern. |
+
+## 4. Adaptive layouts
+
+Material breakpoints:
+
+| Window class | Width | Layout |
+|---|---|---|
+| Compact | < 600dp | Bottom nav, single pane. |
+| Medium | 600–839dp | Nav rail, list-detail with detail-on-tap. |
+| Expanded | 840–1199dp | Nav rail/drawer, two-pane list-detail. |
+| Large | 1200dp+ | Persistent drawer, multi-pane. |
+
+Mantis designs **at minimum compact + expanded**. Tony picks the technique (foldable awareness, window-size-class) for the chosen stack.
+
+## 5. Motion
+
+| Motion | Duration | Easing |
+|---|---|---|
+| Standard | 300ms | `motion.easingStandard` |
+| Emphasized | 500ms | `motion.easingEmphasized` |
+| Decelerate | 250ms | for incoming |
+| Accelerate | 200ms | for outgoing |
+
+Reduced motion: replace transforms with fades. Test with system "Remove animations" enabled.
+
+## 6. Navigation idioms
+
+- System Back is canonical. Don't reimplement back arrows that conflict with the gesture.
+- Predictive back (Android 14+) needs `OnBackInvokedCallback` to preview the destination.
+- Avoid hamburger menus on phones — use bottom nav.
+
+## 7. Accessibility floor
+
+- Touch targets: **48×48 dp minimum** (HIG-equivalent rule).
+- Talkback labels on every actionable element.
+- `contentDescription` for icons-without-text.
+- Dynamic type via `sp` (never `dp` for text). Support 130% font scale.
+- Contrast follows WCAG AA tokens; M3 tooling validates contrast pairs by default.
+
+## 8. Theming with Material You
+
+If the project allows wallpaper-derived theming:
+
+```kotlin
+// Compose
+val dynamicColors = if (Build.VERSION.SDK_INT >= 31)
+  dynamicColorScheme(LocalContext.current) else darkColorScheme()
+MaterialTheme(colorScheme = dynamicColors) { /* ... */ }
+```
+
+For brand-locked apps, ship a fixed seed but stay in tokens; this preserves accessibility-tier behavior.
+
+## 9. Don'ts
+
+- Hex colors in components.
+- Ignoring tonal elevation in favor of shadow.
+- Bottom nav with > 5 items (use scrollable tabs instead).
+- One FAB per app bar action (rate-limit to one FAB).
+- Dialogs for non-blocking confirmations (use snackbar with undo).
+
+## 10. Cross-platform note
+
+If iOS is shipped too: do not port Material to iOS, and vice versa. The Mantis design system separates **brand tokens** (shared) from **platform tokens** (per-OS). See `apple-hig.md`.
+
+## 11. Hand-off
+
+Mantis annotates screens with Material component names and tokens (`md.sys.color.primary`, `md.sys.typescale.titleLarge`). Tony picks Compose / View system / cross-platform (Flutter, RN). Shuri implements against the component+token contract.

package/src/app-overlay/playbooks/mobile-perf-budgets.md

@@ -0,0 +1,145 @@
+---
+playbook: mobile-perf-budgets
+owner: wize-agent-test-architect   # Hawkeye (with Tony for platform tuning)
+applies_when: app-overlay active
+status: ready
+---
+
+# Mobile Performance Budgets — Hawkeye Playbook
+
+Mobile users measure your app in milliseconds and megabytes. Budgets are how you protect both.
+
+## 1. The numbers that matter
+
+| Metric | Good | Needs work | Poor |
+|---|---|---|---|
+| **Cold start** (launch → first frame) | < 1.5s | 1.5–2.5s | > 2.5s |
+| **Warm start** | < 0.8s | 0.8–1.5s | > 1.5s |
+| **Time to interactive** (TTI) | < 2.0s | 2.0–3.5s | > 3.5s |
+| **Frame rate** (sustained) | 60 fps stable | drops < 5/sec | drops > 5/sec |
+| **Jank** (frames > 16ms) | < 0.5% | 0.5–2% | > 2% |
+| **App size** (download) | < 50 MB | 50–150 MB | > 150 MB |
+| **App size** (installed) | < 200 MB | 200–500 MB | > 500 MB |
+| **Memory** (steady-state) | < 150 MB | 150–300 MB | > 300 MB |
+| **Battery drain** (per hour, foreground) | < 5% | 5–10% | > 10% |
+
+Targets for **mid-range phones, not your flagship**. Hawkeye runs benchmarks on the device matrix (see `device-matrix.md`).
+
+## 2. App size budget
+
+### Per-platform ceiling
+
+- iOS App Store: 200 MB OTA download cellular ceiling. Plan for **< 150 MB** to leave headroom.
+- Google Play: 150 MB APK ceiling; use App Bundle splits. Plan for **< 30 MB** initial download.
+
+### Where size goes
+
+Audit on every release:
+
+| Slice | Tool |
+|---|---|
+| RN / Expo JS bundle | `metro-visualizer`, `react-native-bundle-visualizer` |
+| Native deps | Xcode Linker map / Android Studio APK Analyzer |
+| Assets (images, fonts, video) | Compare to design tokens — anything unused? |
+| Third-party SDKs | Each SDK > 1 MB needs a written justification |
+
+### Reductions that work
+
+1. **Vector over bitmap** wherever the design allows (PDF for iOS asset catalog, VectorDrawable for Android).
+2. **WebP/AVIF over PNG** for bitmaps.
+3. **Subset fonts**; ship one weight, derive others via OS faux-bold when acceptable.
+4. **Tree-shake JS bundle** (Hermes, ProGuard/R8). Verify with the visualizer.
+5. **App Thinning** (iOS) and **App Bundle splits** (Android) so each user downloads only their architecture/density.
+6. **On-demand resources** (iOS) / **Play Asset Delivery** (Android) for content not needed at launch.
+
+## 3. Cold start
+
+Cold start is dominated by:
+
+1. **Process launch** — Apple/Google control, but linking and dyld matter (fewer, smaller binaries help).
+2. **Framework init** — every SDK initialized in `application(_:didFinishLaunching)` adds to it. Defer non-essential to first-screen-rendered.
+3. **First view render** — keep the launch screen → first interactive screen path empty of heavy work.
+
+### Patterns
+
+- Lazy-init analytics, crash reporting, ad SDKs, A/B testing — after first frame.
+- Pre-render the first screen's skeleton; populate from cache; refresh in background.
+- For RN/Expo: enable **Hermes** + **bundleAssetName splitting**.
+- For Android: keep Application.onCreate empty; init via lifecycle observer.
+
+### Measurement
+
+| Platform | Tool |
+|---|---|
+| iOS | Xcode Instruments → "App Launch", Time Profiler |
+| Android | Macrobenchmark library (Jetpack) for ColdStartup. `adb shell am start -W` for rough numbers. |
+| RN | `Performance.now()` markers + Flipper Perf plugin. |
+
+## 4. Frame rate & jank
+
+60 fps = 16.67ms/frame. 120 fps target on ProMotion / 90 Hz Androids = 8.33ms.
+
+### Common culprits
+
+- **Layout thrashing** — measuring layout inside scroll/animation handlers.
+- **Image decoding on main thread** — decode async, cache decoded.
+- **Synchronous bridge calls (RN)** — batch updates, use native modules.
+- **Heavy `onLayout` / `LaunchedEffect` on each render**.
+- **Re-rendering large lists** — use `FlatList` with `keyExtractor` + `getItemLayout`, or `LazyColumn`.
+
+### Measurement
+
+- iOS: Instruments → Core Animation → FPS.
+- Android: GPU profiling overlay + Macrobenchmark FrameTimingMetric.
+- RN: Flipper Perf, `react-native-performance`.
+
+## 5. Memory
+
+- Aim for steady-state **< 150 MB** on mid-range.
+- Audit images caches; cap at `min(50 MB, 100 thumbnails)`.
+- Release video / audio assets on pause.
+- Watch out for retain cycles (iOS) and Activity / Fragment leaks (Android) — use LeakCanary / Xcode memory graph.
+
+## 6. Battery
+
+- Don't poll. Use OS push (silent push), BLE listeners (low-power), location updates with low frequency.
+- Background tasks: respect the OS budget (BGTaskScheduler / WorkManager).
+- Avoid wake-locks; trade off freshness for energy.
+
+## 7. Network
+
+- HTTP/2 minimum; HTTP/3 where supported.
+- gzip / brotli on responses.
+- Aggressive cache headers; SWR (stale-while-revalidate) pattern for read-heavy data.
+- Image CDN with on-the-fly format/quality negotiation.
+- Don't fan out 30 small requests; batch with GraphQL or a dedicated endpoint.
+
+## 8. Build-time enforcement
+
+| Check | Tool |
+|---|---|
+| Bundle size growth > 5% per release | `danger-js` rule on the bundle visualizer output. |
+| Cold start regression > 10% | Macrobenchmark in CI; fail PR on threshold. |
+| Frame timing | Compose Compiler metrics for Android; Hermes profiler for RN. |
+
+## 9. Field measurement
+
+- iOS: `MetricKit` for power, hangs, scroll latency.
+- Android: Firebase Performance + Macrobenchmark.
+- Cross-platform: Sentry Performance, NewRelic Mobile.
+
+Look at **p75** and **p90** in field data. The user is the 75th percentile, not the 50th.
+
+## 10. Hawkeye's gate inputs
+
+For each epic NFR review (`tea/nfr/{epic}.md`):
+
+- Cold start (mid-range device).
+- Bundle size delta vs last release.
+- Steady-state memory.
+- Critical-flow frame rate (one E2E run with FPS capture).
+- Battery (instrumented test with consistent workload).
+
+## 11. Hand-off
+
+Fury sets the targets in `nfr-principles.md`. Tony picks the stack respecting the targets. Mantis designs without animation excess. Shuri implements. Hawkeye verifies on each release; regressions hit Concerns/Fail at the gate.

package/src/app-overlay/playbooks/permissions-ux.md

@@ -0,0 +1,147 @@
+---
+playbook: permissions-ux
+owner: wize-agent-ux-designer   # Mantis (paired with Pepper on copy)
+applies_when: app-overlay active
+status: ready
+---
+
+# Permissions UX — Mantis Playbook
+
+The system dialog you can't customize. Everything *around* it is yours. Use it well — denied permissions are usually a UX failure, not a privacy choice.
+
+## 1. The four states for every permission
+
+1. **Not determined** — system never asked.
+2. **Granted** — you can use the feature.
+3. **Denied** — user said no; system won't re-prompt; only Settings can flip.
+4. **Restricted / Limited** — partial access (iOS photos limited library; Android approximate location).
+
+Design **all four** for every permission your app uses.
+
+## 2. The "pre-flight" pattern
+
+Never trigger the system prompt as the first thing the user sees. Always:
+
+1. **In-context trigger.** The user tries a feature that needs the permission.
+2. **Mantis pre-flight UI.** A custom screen/sheet explains *why*, *what*, *what happens if no*.
+3. **System prompt.** User decides.
+4. **Outcome path.** Granted → feature works. Denied → degraded mode; offer Settings deep-link.
+
+```
+[user taps "Add photo"]
+   ↓
+┌────────────────────────────────────┐
+│ Why we need your photos            │
+│ To attach an image to your post.   │
+│ We never upload without confirm.   │
+│                                    │
+│ [ Not now ]      [ Continue ]      │
+└────────────────────────────────────┘
+   ↓ Continue
+[system prompt — uneditable]
+   ↓
+Granted → flow continues
+Denied → fallback UI + "Open Settings"
+```
+
+## 3. Per-permission guidance
+
+### Camera & microphone
+
+- Ask only when the user starts a recording/capture action.
+- Pre-flight explains what's recorded, stored, and uploaded.
+- If denied: show a permanent banner with "Open Settings" inside the feature; don't auto-re-prompt.
+
+### Photo library
+
+- iOS 14+: **Limited Library is the default**. Embrace it — show a "Manage" button to add more later.
+- Android 13+: granular media access (images / video / audio).
+- Don't ask for full library if you only need one picker — use `PHPickerViewController` / `Photo Picker` which need **no permission** at all.
+
+### Location
+
+- Pre-flight has a *map screenshot* showing the precision and the purpose ("nearby restaurants" vs "your route").
+- Android 12+: approximate location is the default. Justify precise.
+- Background location: **only** if the feature truly needs it (delivery, fitness route). Otherwise foreground-only.
+
+### Notifications
+
+- Don't ask at launch. Ask the first time a notification would actually be useful.
+- Pre-flight: list the categories you'll use (mention, reminder, marketing). Tie each to a setting in-app.
+- Provide per-category opt-in inside the app — match to OS notification channels (Android) / authorization options (iOS).
+
+### Contacts / Calendar / Reminders
+
+- High-friction permission; only when essential.
+- If you just need a single contact, use the system picker — **no permission required**.
+
+### Bluetooth / Local Network
+
+- iOS: bluetooth-LE for peripherals only; Local Network for Bonjour discovery — both prompt.
+- Pre-flight should explain it's for nearby devices, not internet access.
+
+### Health / Motion (iOS)
+
+- HealthKit asks per data type. Group requests by user-task, not by data field.
+- Motion: pre-flight explains it's used for step-count or activity recognition only.
+
+### Tracking (App Tracking Transparency, iOS)
+
+- The system prompt is required if you track across other apps/sites.
+- Apple disallows incentivizing the choice; respect it.
+
+## 4. Copy template (Pepper helps phrase)
+
+Pre-flight title: **"Why we need [permission]"**.
+One-line value statement.
+One-line "what we will not do" (privacy promise).
+Two buttons: **Not now** (no permission requested) and **Continue** (triggers system prompt).
+
+Avoid: "Allow Camera Access" (system already says that).
+
+## 5. Denied state UI
+
+Never silently fail. Show:
+- The state badge ("Camera access off").
+- A one-line reason.
+- A direct **"Open Settings"** button.
+
+```swift
+// iOS
+if let url = URL(string: UIApplication.openSettingsURLString) {
+  UIApplication.shared.open(url)
+}
+```
+
+```kotlin
+// Android
+startActivity(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)))
+```
+
+## 6. Settings mirror inside the app
+
+Every permission you request has a corresponding row in **Settings → Permissions** inside the app. Mirrors the OS state, with the same Open Settings deep-link. This is the user's escape hatch.
+
+## 7. Background work
+
+Some Android/iOS background permissions (location, background refresh, BLE in background) require user education and energy disclosure. Pre-flight mentions battery cost explicitly.
+
+## 8. Don'ts
+
+- Multiple prompts on first launch ("camera, mic, location, notifications" in a row). Cardinal sin.
+- Re-asking immediately after denial — many OSes block; users get frustrated.
+- Using "we can't function without this" as the reason — design for the denied state.
+- Pre-flight that already says "tap Allow" — the system dialog handles that. Just convince them *why*.
+- Modal blocking UI when the user denies. The feature degrades; the app doesn't.
+
+## 9. Audit list
+
+For every release, Hawkeye verifies in `tea-design.md`:
+- Every permission has a pre-flight UI.
+- Every permission has a denied-state UI.
+- Every permission has a Settings deep-link.
+- App functions (degraded) without each non-essential permission.
+
+## 10. Hand-off
+
+Mantis owns flow + copy strings. Pepper polishes copy. Tony picks the entitlement / manifest. Shuri implements; Hawkeye walks the four states (not-asked / granted / denied / limited) per permission.

package/src/app-overlay/playbooks/touch-targets-and-gestures.md

@@ -0,0 +1,127 @@
+---
+playbook: touch-targets-and-gestures
+owner: wize-agent-ux-designer   # Mantis
+applies_when: app-overlay active
+status: ready
+---
+
+# Touch Targets & Gestures — Mantis Playbook
+
+The thumb is the cursor. Design every screen around how it actually reaches the controls.
+
+## 1. Minimum touch target sizes
+
+| Platform | Minimum | Recommended primary |
+|---|---|---|
+| **iOS** (HIG) | 44×44 pt | 48×48+ pt for primary CTAs |
+| **Android** (Material) | 48×48 dp | 56×56 dp for FABs |
+| **Web** (WCAG 2.5.8) | 24×24 CSS px | 44×44 CSS px for primary |
+
+If a visible glyph must be smaller (icon-only toolbar), expand the **hit area** via padding or `hitSlop` — the visual icon stays small but the touch is large.
+
+```swift
+// SwiftUI hit area
+Button { /* */ } label: { Image(systemName: "star") }
+  .contentShape(Rectangle())
+  .frame(minWidth: 44, minHeight: 44)
+```
+
+```kotlin
+// Compose
+Modifier.minimumInteractiveComponentSize() // ≥ 48dp
+```
+
+```jsx
+// React Native
+<Pressable hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}>...</Pressable>
+```
+
+## 2. Spacing between adjacent targets
+
+- **≥ 8 dp/pt** between adjacent interactive elements.
+- Bottom row of nav must clear the home indicator (iOS) / gesture region (Android).
+
+## 3. Thumb reach zones (one-handed use)
+
+Three zones, on a 6.1" phone:
+
+| Zone | Region | Use for |
+|---|---|---|
+| **Easy** | Bottom 1/3 | Primary actions, nav. |
+| **OK** | Middle 1/3 | Secondary, content tap. |
+| **Hard** | Top 1/3 | Status, branding, low-frequency. |
+
+Put destructive or rarely-used controls in the **Hard** zone. Put the primary CTA in **Easy**.
+
+## 4. Standard gestures (use the system's vocabulary)
+
+| Gesture | Reserved meaning |
+|---|---|
+| **Tap** | Default action. |
+| **Long press** | Reveal secondary actions / context menu. Optional path — never the only one. |
+| **Swipe left/right on row** | Quick actions (archive, delete). |
+| **Swipe down on modal** | Dismiss. |
+| **Pull down on list** | Refresh. |
+| **Pinch** | Zoom (content). |
+| **Two-finger drag** | Multi-select (mac/iPad). |
+| **Edge swipe (iOS)** | Back navigation. |
+| **System back gesture (Android)** | Back; **don't** intercept lightly. |
+
+## 5. Custom gestures — pick wisely
+
+If you must invent a gesture:
+
+1. **Don't make it the only path.** Pair with a visible tap affordance.
+2. **Onboard once.** Show the gesture on first launch; never again.
+3. **Make it cancellable.** Mid-gesture the user must be able to abort.
+4. **Don't fight system gestures.** Edge swipes on iOS = back; you'll lose.
+5. **Test with system Voice Control** (iOS) / Switch Access (Android) — discoverable to users who can't gesture.
+
+## 6. Multi-touch caveats
+
+- iOS: `MultipleTouchEnabled = true` per view; default is single.
+- Android: track pointer IDs on every event; don't assume one finger.
+- Two-finger gestures (pinch, rotate) need an alternative for users with motor limitations — usually a button.
+
+## 7. Drag-and-drop
+
+| Platform | Native |
+|---|---|
+| iOS | `UIDragInteraction` / SwiftUI `.draggable + .dropDestination` |
+| Android | `View.startDragAndDrop` / Compose `dragGestures` |
+| React Native | community lib (e.g., `react-native-draggable-flatlist`) |
+
+Drag-and-drop must:
+- Show a visible drag preview.
+- Highlight valid drop targets.
+- Support keyboard equivalent (or selection + "Move to…") for accessibility (WCAG 2.5.7).
+
+## 8. Haptics
+
+| Use | Pattern |
+|---|---|
+| Successful confirmation | Light impact (.light / `VibrationEffect.EFFECT_TICK`) |
+| Failure / invalid | Notification error / double tick |
+| Long-press triggered | Selection change |
+| Pull-to-refresh release | Light impact |
+
+Haptics are noise without a system event behind them. Don't trigger them on every tap.
+
+## 9. Reduce Motion / Reduce Transparency
+
+Reduce gesture-driven motion: replace swipe-to-reveal animations with simple cross-fades. Detect with:
+
+- iOS: `UIAccessibility.isReduceMotionEnabled`
+- Android: `Settings.Global.TRANSITION_ANIMATION_SCALE`
+
+## 10. Don'ts
+
+- Targets smaller than the platform minimum, even if "the icon is small".
+- Hover-only affordances (no hover on touch).
+- Gestures that conflict with system gestures (edge swipes, pull-from-top).
+- Long-press-only access to a critical feature.
+- "Discover this gesture by trial" — onboarding it costs less than the support tickets.
+
+## 11. Hand-off
+
+Mantis annotates every interactive element with: `hit area`, `gesture`, `haptic`, `state on disabled`. Shuri implements; Hawkeye verifies hit-area sizes in `tea-design.md` using device-pixel measurements.