wize-dev-kit 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -5,6 +5,62 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.1.5] — 2026-06-01
+
+### Added — promises kept
+
+All files that previous releases declared in `module.yaml` but never shipped are now in the kit, with real content (not placeholders).
+
+**Web overlay playbooks** (`src/web-overlay/playbooks/`):
+
+- `wcag-aa.md` — WCAG 2.2 AA checklist for Mantis, with the newer SCs (2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7, 3.3.8) and an audit toolchain.
+- `responsive-breakpoints.md` — mobile-first stack with container queries, fluid typography (`clamp`), layout primitives (Stack/Cluster/Switcher/Sidebar/Grid/Cover/Frame), image strategy.
+- `semantic-html.md` — landmarks, headings, the 12 must-reach-first elements, ARIA rules, common widget patterns with minimum ARIA, anti-patterns.
+- `playwright-vitest.md` — Hawkeye's split (70/20/10), Vitest + Testing Library + MSW setup, Playwright POM pattern, selector hierarchy (role → label → text → testid), CI sketch, anti-patterns.
+- `web-perf-budgets.md` — Core Web Vitals targets, baseline budgets per resource class, image/font strategy, third-party audit checklist, critical rendering path snippet, lighthouse-ci config, field measurement via `web-vitals` beacon.
+
+**App overlay playbooks** (`src/app-overlay/playbooks/`):
+
+- `apple-hig.md` — POUR-equivalent four principles, layout (status bar/nav/tab/safe-area), navigation patterns, SF Symbols, Dynamic Type, motion, common idioms, iPad specifics, do-not list.
+- `material-design-3.md` — pillars, color/type/shape tokens, elevation-by-color, component starter set, adaptive windows (Compact/Medium/Expanded/Large), motion + reduced motion, Material You theming.
+- `touch-targets-and-gestures.md` — minimums per platform (iOS 44pt / Android 48dp / web 24px), hit-area snippets per stack, thumb reach zones, reserved gestures, multi-touch, drag-and-drop with keyboard fallback, haptics, reduce-motion.
+- `permissions-ux.md` — the four states (not-determined/granted/denied/limited), pre-flight pattern, per-permission guidance (camera/photos/location/notifications/contacts/BLE/health/tracking), denied-state UI + Settings deep-link, copy template.
+- `detox-maestro.md` — when to pick each, Maestro YAML + cloud, Detox config + `testID` discipline, cross-platform CI sketch, flakiness rules, critical journeys to cover.
+- `mobile-perf-budgets.md` — cold/warm start, TTI, FPS, jank, app size, memory, battery; per-platform targets; size reductions that work; build-time + field measurement.
+- `device-matrix.md` — three buckets (floor/volume/ceiling), 2026 iOS + Android matrices, cloud farm comparison, accessibility runs, network conditions, locale coverage.
+
+**Stack catalogs**:
+
+- `src/web-overlay/stack-catalog.md` — Tony's reference for the web architecture interview: frameworks (Next/Nuxt/SvelteKit/Astro/Remix/SPA/Laravel-Inertia), back-end (Supabase/PlanetScale/Drizzle/Prisma/tRPC/GraphQL), auth, hosting, styling, state, forms; ADR record path.
+- `src/app-overlay/stack-catalog.md` — Tony's mobile architecture reference: frameworks (RN+Expo / RN bare / Flutter / SwiftUI / Compose / Compose-Multiplatform / Capacitor / native+KMP), build & release, auth, data/sync, state, storage, push, analytics, anti-patterns; ADR record path.
+
+### Added — tests
+
+- `test/playbooks-and-catalogs.test.js`: guards that every playbook declared in an overlay `module.yaml` exists on disk, has frontmatter, and is non-trivial (> 400 chars). Stack catalog presence + size also asserted. Total tests now: **39** (was 33).
+
+### Notes
+
+This release closes Category 1 of the backlog ("promessas vazias"). Categories 2–6 (workflow bodies, `update`/`sync`/`agent create` CLI, polish, Node-24 CI, OIDC return, monorepo & TEA-enforcing) remain on the roadmap.
+
+## [0.1.4] — 2026-06-01
+
+### Added
+
+- **`user_name` prompt at install time.** The installer asks "How should the agents call you?" (default = `$USER`), and persists the answer to `.wize/config/user.toml` under `[user] name`. Wizer and `wize-help` read this file and greet the user by name (e.g., *"Welcome back, [USER_NAME]. {project} — {profiles}. Next: …"*).
+- **Opt-in suggested `.gitignore` block.** The installer asks whether to apply the suggested entries. When accepted, an idempotent block is injected between `# >>> wize-dev-kit (managed) >>>` and `# <<< wize-dev-kit (managed) <<<` markers covering: per-developer files (`user.toml`, `scratch/`, `.local/`, `quick-dev-log.md`) and the generated IDE adapter outputs (`.claude/skills/wize-*`, `.agent/skills/wize-*`, `.cursor/rules/wize-*.mdc`, etc.). Re-running install only updates lines between the markers; everything outside is untouched. Declining keeps `.gitignore` exactly as it was.
+- `tools/installer/setup-helpers.js`: pure-ish helpers for `applyGitignore()` (create / append / replace / unchanged) and `generateUserToml()`.
+- 8 new unit tests covering gitignore idempotency (create, append, idempotent re-run, stale-block replace, dry-run) and user.toml generation (name, escaping, optional role). Total: 33 passing.
+
+### Changed
+
+- Wizer (orchestrator) persona and `wize-help` skill now instruct the agent to read `.wize/config/user.toml` and use `[user] name` when greeting.
+- `project.toml` template comment clarifies "personal preferences live in user.toml".
+
+### Recommended layout (for a team repo)
+
+Commit: `.wize/config/project.toml`, `.wize/config/tea.toml`, `.wize/planning/`, `.wize/solutioning/`, `.wize/implementation/tea/`, `.wize/implementation/retrospective/`, `.wize/knowledge/`, `.wize/custom/`, `AGENTS.md`.
+Ignore (handled by the suggested block): `.wize/config/user.toml`, `.wize/scratch/`, `.wize/.local/`, `.wize/implementation/quick-dev-log.md`, and all generated adapter outputs (each developer runs `npx wize-dev-kit install` for their own IDE target).
+
 ## [0.1.3] — 2026-06-01
 
 ### Added
@@ -83,7 +139,9 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Inspired by [BMAD Method v6.8.0](https://github.com/bmad-code-org/BMAD-METHOD).
 - WDS module inspired by [bmad-method-wds-expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion).
 
-[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.0...v0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/app-overlay/playbooks/apple-hig.md

@@ -0,0 +1,112 @@
+---
+playbook: apple-hig
+owner: wize-agent-ux-designer   # Mantis
+applies_when: app-overlay active (iOS / iPadOS / macOS)
+status: ready
+---
+
+# Apple HIG — Mantis Playbook (iOS / iPadOS)
+
+The HIG isn't a rulebook to memorize — it's a vocabulary. Design so the app feels native first, branded second.
+
+## 1. The four design principles to lead with
+
+1. **Hierarchy** — one primary action per screen. Demote everything else.
+2. **Harmony** — visual language aligned with the system: SF Symbols, system colors, dynamic type.
+3. **Consistency** — same gesture, same outcome, across the app.
+4. **Deference** — content over chrome; let the OS chrome breathe.
+
+## 2. Layout fundamentals
+
+| Region | Rule |
+|---|---|
+| Status bar | Never overlap critical content. Match content scheme (light/dark). |
+| Navigation bar | Use the system component. Title sits in `Large Title` on top, collapses on scroll. |
+| Tab bar | 3–5 tabs. Each is a top-level destination, not a flow step. |
+| Safe area | Always respect; never paint behind home indicator unless intentional. |
+| Touch targets | **44×44 pt minimum** (HIG SC). Spacing ≥ 8 pt between adjacent targets. |
+
+## 3. Navigation patterns
+
+| Pattern | Use when |
+|---|---|
+| **Tab bar** | 3–5 distinct content areas (Home/Search/Library/Profile). |
+| **Navigation stack** | Hierarchical drill-down. Back gesture must work. |
+| **Modal sheet** | Self-contained task (compose, settings detail). Dismissible with swipe-down. |
+| **Full-screen modal** | Multi-step task that needs focus (onboarding, payment flow). |
+| **Page sheet** (iPad) | Inspector-like UI alongside content. |
+| **Popover** (iPad/Mac) | Contextual options anchored to a control. |
+
+## 4. SF Symbols (use them)
+
+- 6000+ glyphs with weights, hierarchical variants, and palette modes.
+- Match symbol weight to your text weight.
+- Use multicolor sparingly — only when meaning depends on color.
+- Never embed glyphs as PNG; SwiftUI/UIKit handle scaling.
+
+```swift
+Image(systemName: "heart.fill")
+  .font(.system(size: 24, weight: .semibold))
+  .foregroundStyle(.tint)
+```
+
+## 5. Typography — Dynamic Type
+
+- Use semantic text styles (`.title`, `.headline`, `.body`, `.callout`, `.footnote`). Never hardcode `font-size`.
+- Support all 7 default text sizes and the 5 accessibility sizes (xxxL → A11Y_XXXL).
+- Test at the largest accessibility size: critical UI must reflow, not clip.
+
+## 6. Color
+
+- Start from **system colors** (`.label`, `.systemBackground`, `.systemBlue`). They handle light/dark/contrast.
+- Brand color stays as a single accent (`tintColor`). Don't recolor system controls.
+- Run in dark mode + Increase Contrast + Reduce Transparency at least once per epic.
+
+## 7. Motion
+
+- Respect `Reduce Motion`. Replace `slide`/`scale` with `cross-fade`.
+- Standard durations: 0.25s (transient), 0.35s (navigation), 0.4s (modal present).
+- Springs over linear curves; physics > eased linear.
+
+## 8. Common idioms
+
+| Idiom | When |
+|---|---|
+| **Pull-to-refresh** | Lists where freshness matters (mail, feed). |
+| **Swipe actions** | Quick row actions (archive, delete). Always pair with a tap-reveal alternative. |
+| **Context menu (long press)** | Secondary actions on a tile. Never the only path. |
+| **Action sheet** | 2–6 mutually exclusive choices on a small screen. |
+| **Confirmation dialog** | Destructive actions — always confirm; phrase the verb on the button. |
+
+## 9. Permissions
+
+- Ask in context, not at launch. (See `permissions-ux.md`.)
+- Provide a pre-flight UI explaining the *why* before the system prompt.
+
+## 10. Privacy nutrition + tracking
+
+- `App Tracking Transparency` prompt is mandatory if you track across other apps/sites.
+- Privacy nutrition label is required on the App Store.
+- Mantis writes the user-facing explanations; Tony coordinates the technical entries.
+
+## 11. iPad specifics
+
+- **Sidebar + content split** when content is hierarchical and lateral nav matters.
+- Support Stage Manager + multitasking (responsive layout, no fixed pixel widths).
+- Apple Pencil hover (iPad Pro) — design hover affordances even for touch-only apps.
+
+## 12. Don'ts
+
+- Custom back arrows. Use the platform's.
+- Hidden gestures as the only path to a feature. Provide a visible tap.
+- Splash screen with branding for > 1 second. Use the launch screen, not a "loading" splash.
+- Reinventing the share sheet. Use `UIActivityViewController` / `ShareLink`.
+- Toast notifications. iOS doesn't have them; use sheets, banners, or system notifications.
+
+## 13. Cross-platform note
+
+If the project also ships Android, **build to platform**, not lowest common denominator. Each idiom (back button vs back gesture, tab bar vs bottom nav, alert vs dialog) belongs to its OS. See `material-design-3.md`.
+
+## 14. Hand-off
+
+Mantis annotates each screen spec with the Apple system component name (`UIKit` or `SwiftUI`), Dynamic Type style, system color tokens. Tony picks UIKit vs SwiftUI vs React Native; Shuri implements against the named components.

package/src/app-overlay/playbooks/detox-maestro.md

@@ -0,0 +1,179 @@
+---
+playbook: detox-maestro
+owner: wize-agent-test-architect   # Hawkeye
+applies_when: app-overlay active
+status: ready
+---
+
+# Mobile E2E — Detox + Maestro Playbook
+
+Two tools, different angles. **Detox** integrates deep into RN/Expo with a real JS bridge and runs on real devices/simulators. **Maestro** is YAML-declarative, multi-platform (RN, Flutter, native), and exceptional for smoke + visual flows. Most teams want one of each, not both heavy.
+
+## 1. Pick one (or both, lean)
+
+| Need | Pick |
+|---|---|
+| RN / Expo only, deep state introspection, fastest iteration | **Detox** |
+| Native, Flutter, RN — mixed shop | **Maestro** |
+| Smoke flow you run on every PR | **Maestro** |
+| Detailed assertions on bridge state, mocks at JS layer | **Detox** |
+| Cross-platform visual regression | **Maestro** snapshots (Cloud) |
+| Tight CI matrix (iOS sim + Android emulator + cloud devices) | **Maestro Cloud** or **MagicPod / BrowserStack** |
+
+Default split (Hawkeye `tea-design.md`):
+
+- **Vitest / Jest** for unit + component (≥ 70%).
+- **Maestro** for smoke (3–8 critical flows on every PR).
+- **Detox** for RN-specific deep flows (auth, deep links, push handling).
+
+## 2. Maestro — getting started
+
+```yaml
+# .maestro/flows/sign-in.yml
+appId: com.qwize.app
+---
+- launchApp
+- assertVisible: "Sign in"
+- tapOn:
+    text: "Email"
+- inputText: "qa@qwize.io"
+- tapOn:
+    text: "Password"
+- inputText: "test1234"
+- tapOn: "Sign in"
+- assertVisible:
+    id: "home-tab"
+    timeout: 10000
+```
+
+Run locally:
+
+```bash
+maestro test .maestro/flows/sign-in.yml
+maestro studio                         # record flows visually
+maestro cloud .maestro/                # run on Maestro Cloud
+```
+
+Tips:
+
+- One flow per file. Compose with `runFlow` for shared steps (sign-in fixture).
+- Prefer `id`-based selectors over text — text changes with locale.
+- Wrap network-dependent waits in `extendedWaitUntil` so they fail loud, not flaky.
+- Snapshots: `takeScreenshot` then commit baseline; Maestro Cloud handles diffing.
+
+## 3. Detox — getting started (RN / Expo)
+
+```bash
+npx detox init -L jest
+```
+
+```jsonc
+// .detoxrc.js (sketch)
+module.exports = {
+  testRunner: 'jest',
+  apps: {
+    'ios.debug':     { type: 'ios.app', binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/App.app', build: 'xcodebuild ...' },
+    'android.debug': { type: 'android.apk', binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk', build: 'cd android && ./gradlew assembleDebug assembleAndroidTest' }
+  },
+  devices: {
+    'ios.sim':  { type: 'ios.simulator', device: { type: 'iPhone 15 Pro' } },
+    'android.emu': { type: 'android.emulator', device: { avdName: 'Pixel_7_API_34' } }
+  },
+  configurations: {
+    'ios.debug':     { device: 'ios.sim',  app: 'ios.debug' },
+    'android.debug': { device: 'android.emu', app: 'android.debug' }
+  }
+};
+```
+
+```ts
+// e2e/sign-in.test.ts
+describe('Sign in', () => {
+  beforeAll(async () => { await device.launchApp(); });
+  beforeEach(async () => { await device.reloadReactNative(); });
+
+  it('lets a known user in', async () => {
+    await element(by.id('email')).typeText('qa@qwize.io');
+    await element(by.id('password')).typeText('test1234');
+    await element(by.id('signin-cta')).tap();
+    await expect(element(by.id('home-tab'))).toBeVisible();
+  });
+});
+```
+
+Hawkeye rules for Detox:
+
+- Always use `testID`. Never text selectors.
+- Reset state between tests (`device.reloadReactNative()`); never share login state silently.
+- Network: prefer **MSW-RN** or in-app mock layer. Don't hit prod.
+- Set `Detox.setReachability` to simulate offline scenarios.
+
+## 4. Cross-platform CI sketch
+
+```yaml
+# .github/workflows/mobile-e2e.yml (sketch)
+jobs:
+  maestro-ios:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - run: brew tap mobile-dev-inc/tap && brew install maestro
+      - run: yarn install --frozen-lockfile
+      - run: yarn build:ios
+      - run: maestro test .maestro/flows/
+  maestro-android:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 34
+          target: google_apis
+          arch: x86_64
+          profile: pixel_7
+          script: |
+            curl -Ls "https://get.maestro.mobile.dev" | bash
+            maestro test .maestro/flows/
+  detox-ios:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - run: yarn install --frozen-lockfile
+      - run: brew tap wix/brew && brew install applesimutils
+      - run: yarn detox build -c ios.debug && yarn detox test -c ios.debug --headless
+```
+
+## 5. Flakiness — non-negotiable rules
+
+1. **No `sleep(N)`.** Use built-in waits (`waitFor`, `extendedWaitUntil`).
+2. Tests must pass 50× in a row in CI before they're trusted.
+3. Reset app state between tests; don't share login.
+4. Don't depend on network for unit/component layer — mock at the boundary.
+5. If a test is flaky once, fix or quarantine it the same day. Don't `retries: 5`.
+
+## 6. Critical journeys to cover (always)
+
+Even MVPs should ship E2E for:
+
+- First-run onboarding through to the home tab.
+- Sign-up + sign-in + sign-out.
+- Primary "value moment" action (the one PRD success criterion exists for).
+- Push notification deep link.
+- Network-failure UX (offline mode, retry).
+
+Everything else is nice-to-have until the team has signal that the critical flows are stable.
+
+## 7. Device matrix
+
+See `device-matrix.md`. Maestro Cloud and BrowserStack expose matrices Hawkeye can declare in YAML and run weekly.
+
+## 8. Don'ts
+
+- E2E tests in the same job as unit tests (slow, blocks faster signal).
+- Selectors by visible text in a multilingual app.
+- Running E2E only at release; broken paths get found at the worst time.
+- "Manual smoke" replacing automated smoke. Maestro flows take a day to write and save weeks per year.
+
+## 9. Hand-off
+
+Tony picks RN / native / Flutter; that decides the Detox feasibility. Hawkeye writes the Maestro flow files alongside the story `tea-design.md`. Shuri owns the `testID`s and accessibility identifiers and treats them as a public API of the app — renaming one is a contract change.

package/src/app-overlay/playbooks/device-matrix.md

@@ -0,0 +1,121 @@
+---
+playbook: device-matrix
+owner: wize-agent-test-architect   # Hawkeye
+applies_when: app-overlay active
+status: ready
+---
+
+# Device Matrix — Hawkeye Playbook
+
+You can't test on every device. You can test on the right ones. Decide the matrix once per release; rotate quarterly.
+
+## 1. The three buckets
+
+Every release ships on three device classes:
+
+| Bucket | Why |
+|---|---|
+| **Floor** (oldest supported / lowest-spec) | Performance & memory pressure catches regressions invisible on flagship. |
+| **Volume** (most-used by your audience) | Where users actually live. Drive default UX decisions here. |
+| **Ceiling** (latest flagship + newest OS) | New-feature opportunity (Live Activities, Predictive Back, etc.) + verify no flagship-only assumption breaks. |
+
+## 2. iOS matrix (2026, generic SaaS audience)
+
+| Bucket | Device | iOS | Notes |
+|---|---|---|---|
+| Floor | iPhone SE (2nd gen, A13) | iOS 17 | 4.7" non-Retina XDR, no Dynamic Island. |
+| Floor | iPhone 11 | iOS 17 | Wide audience tail. |
+| Volume | iPhone 14 | iOS 18 | Mid-range volume sweet spot. |
+| Volume | iPhone 15 | iOS 18 | Dynamic Island, USB-C. |
+| Ceiling | iPhone 17 Pro | iOS 26 (current dev) | ProMotion, latest APIs. |
+| iPad floor | iPad (10th gen) | iPadOS 17 | Non-ProMotion. |
+| iPad ceiling | iPad Pro M4 | iPadOS 18 | Stage Manager, hover, Pencil hover. |
+
+**Min OS:** iOS 17 (cuts ~5% of installed base; recovers a lot of API surface). Adjust per audience.
+
+## 3. Android matrix (2026, generic SaaS audience)
+
+| Bucket | Device | OS | Notes |
+|---|---|---|---|
+| Floor | Pixel 6a or Samsung A14 | Android 13 | 4 GB RAM, Snapdragon 6-series. |
+| Volume | Samsung Galaxy A55 | Android 14 | Mid-range. Big volume in emerging markets. |
+| Volume | Pixel 8 | Android 14 / 15 | Reference device for API behavior. |
+| Ceiling | Pixel 9 Pro / Galaxy S25 Ultra | Android 15 | Foldable / large-screen, edge gestures. |
+| Foldable | Samsung Galaxy Z Fold 6 | Android 14 / 15 | Adaptive layout signal. |
+| Tablet | Pixel Tablet | Android 14 | Window-size-class testing. |
+
+**Min OS:** Android 13 (API 33) — covers ~85% of active devices. Verify via Play Console statistics for your audience.
+
+## 4. Hybrid / web-in-app matrix
+
+If the app uses webviews (Capacitor, Ionic, embedded web docs):
+
+- iOS: WKWebView (always system Safari engine).
+- Android: System WebView (Chromium-based, updated separately). Test on **last 3 Chromium versions**.
+
+## 5. Choosing the volume tier
+
+Don't guess. Pull from:
+
+- **App Store Connect → Analytics → Sources → Devices** (after release).
+- **Google Play Console → Statistics → Devices**.
+- For pre-release: pick the top 3 devices in your target market via StatCounter / DeviceAtlas / Crashlytics-baseline market data.
+
+Rotate volume devices every two quarters as field data shifts.
+
+## 6. How to run the matrix in CI
+
+### Cloud farms
+
+| Provider | iOS | Android | Notes |
+|---|---|---|---|
+| BrowserStack App Live / Automate | ✓ | ✓ | Largest catalog; integrates Detox + Maestro. |
+| Sauce Labs Mobile | ✓ | ✓ | Strong on Appium; price ladder. |
+| Maestro Cloud | ✓ | ✓ | YAML-native; visual diff included. |
+| Firebase Test Lab | (limited) | ✓ | Android-first; cheap, large. |
+| AWS Device Farm | ✓ | ✓ | Real devices; AWS billing. |
+| LambdaTest | ✓ | ✓ | Mid-tier price. |
+
+### Local
+
+- iOS: Xcode simulators for development; **at least one real device per bucket** before release.
+- Android: emulators (`avdmanager` + `system-images;android-34;google_apis;x86_64`); real device per bucket.
+
+### What runs where
+
+- **Every PR:** smoke flow (Maestro) on emulator iOS + Android (volume bucket).
+- **Every merge to main:** full smoke matrix (floor + volume + ceiling).
+- **Nightly:** full E2E suite (Detox + Maestro) on real devices via cloud farm.
+- **Weekly:** perf benchmark suite (cold start, memory, FPS) on the floor + volume buckets.
+
+## 7. Accessibility runs
+
+Add to the device matrix:
+
+- iOS: VoiceOver + Dynamic Type at largest accessibility size.
+- Android: TalkBack + 130% font scale.
+- Color contrast checks at the OS level (Smart Invert / Dark Mode forced).
+- Switch Control (iOS) / Switch Access (Android) on the most-used flow.
+
+## 8. Network conditions
+
+Hawkeye samples network at:
+
+| Condition | Tool |
+|---|---|
+| Offline | Airplane mode flag in CI. |
+| 3G slow | Charles / Proxyman / Maestro `setProxy` + bandwidth throttle. |
+| Lossy WiFi | `tc qdisc` on Linux runner; Network Link Conditioner on Mac. |
+| Captive portal | Manual on weekly cycle. |
+
+A surprising % of production crashes come from network edge cases. Cover at least offline + slow.
+
+## 9. Locale
+
+- Always test **English + the two largest non-English locales** for the audience.
+- RTL (Arabic or Hebrew) at least once per release if the app ships in those markets.
+- Date / number / currency formatting in the relevant locales.
+
+## 10. Hand-off
+
+The device matrix lives at `.wize/planning/app/device-matrix.md` once Mantis + Tony agree on the audience. Hawkeye references it in every `tea-design.md`; CI configs (Maestro / Detox / BrowserStack) read the same matrix to avoid drift.

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.