mobile-app-ux-auditor-skill 0.1.0

package/references/mobile-ux-audit-reference.md

@@ -0,0 +1,253 @@
+# Mobile UX Audit Reference
+
+Use this reference when auditing or improving mobile apps across Flutter, React Native, Swift/iOS, Kotlin, Java, Android Views, or Jetpack Compose.
+
+## Current Research Anchors
+
+Prefer current official docs when the user's request depends on latest platform behavior.
+
+- Apple Human Interface Guidelines: navigation, layout, tab bars, accessibility, toolbars, search, Dynamic Type, VoiceOver, platform adaptation.
+- Android app quality: core quality, adaptive quality, Material 3 layout/navigation pairings, accessibility principles, TalkBack, Switch Access, Android vitals.
+- Flutter docs: adaptive/responsive design, `SafeArea`, `MediaQuery`, `LayoutBuilder`, accessibility testing, `Semantics`.
+- React Native docs: `accessible`, `accessibilityLabel`, `accessibilityHint`, `accessibilityRole`, `accessibilityState`, `AccessibilityInfo`, focus order.
+- W3C WCAG 2.2: mobile-relevant criteria including target size, dragging alternatives, redundant entry, focus visibility, consistent help, accessible authentication.
+- Product quality and retention: treat retention as a result of clear value, trust, speed, and useful re-entry. Avoid dark patterns.
+- Public agent-skill patterns such as UI/UX Pro Max and Taste Skill show a useful structure: concise `SKILL.md`, deeper reference files, search/scanner scripts, anti-generic design constraints, and explicit quality gates. Use the structure, not copied prose or persona imitation.
+
+## Cross-Agent Compatibility
+
+This skill is portable when it stays inside the open skill shape:
+
+- `SKILL.md` with YAML frontmatter and Markdown instructions.
+- Optional `references/`, `scripts/`, and `assets/`.
+- Optional `agents/openai.yaml` for Codex UI metadata; Claude Code ignores it.
+- Install locations:
+  - Codex: `~/.codex/skills/mobile-app-ux-auditor/`
+  - Claude Code personal: `~/.claude/skills/mobile-app-ux-auditor/`
+  - Project-local Claude Code: `<repo>/.claude/skills/mobile-app-ux-auditor/`
+
+Avoid relying on platform-specific frontmatter unless the skill is intentionally platform-specific. Put platform-specific execution notes in the body.
+
+## UX Engineer Operating Model
+
+Use this order before proposing changes:
+
+1. **Design read**: category, audience, job, usage environment, platform mix, trust level, density, maturity, visual register, constraints.
+2. **User journey**: first value, primary task, recovery, re-entry, expansion, cancellation/delete.
+3. **Evidence capture**: code scan, screen map, screenshots, simulator/device walkthrough, screen-reader walkthrough, performance/jank signals.
+4. **Friction diagnosis**: confusion, too many choices, too many fields, hidden state, slow feedback, inaccessible control, broken recovery, trust gap.
+5. **Design response**: remove, reorder, relabel, disclose progressively, add feedback, make state visible, improve defaults, strengthen affordance.
+6. **Implementation response**: smallest code changes that improve completion and preserve platform conventions.
+7. **Verification**: prove the new flow works with at least one realistic path and one failure/interruption path.
+
+Do not invent a celebrity-designer persona. Adopt the discipline: evidence, taste, consistency, accessibility, and verification.
+
+## Scorecard
+
+Score each area from 0 to 5. A production app should have no area below 3 and critical flows should average 4+.
+
+| Area | 0-1 | 3 | 5 |
+| --- | --- | --- | --- |
+| Task success | User cannot finish or loses data | Main path works with friction | Main, edge, interruption, and recovery paths are clear |
+| Orientation | User cannot tell where they are | Titles/nav mostly work | Location, state, and next action are always obvious |
+| Navigation | Back/close/deep links are broken | Common paths work | Platform-native, predictable, resumable, and deep-linkable |
+| Forms/input | Placeholder labels, late errors, keyboard issues | Basic labels/errors | Autofill, correct keyboard, persistence, inline recovery |
+| Accessibility | Mouse/touch-only or unlabeled controls | Basic labels | Screen reader, focus order, targets, contrast, dynamic type verified |
+| Adaptive layout | Breaks on devices or keyboard | Common phone sizes pass | Phones, tablets, foldables, landscape, RTL/long text considered |
+| Performance | Slow launch, janky scroll, blocked gestures | Acceptable local feel | Launch, transition, image, render, battery, and gesture latency optimized |
+| System states | Only happy path designed | Loading/error exist | Empty, loading, error, offline, partial, disabled, success are complete |
+| Design consistency | Random styles and components | Repeated components | Tokens, spacing, radius, type, color, motion, and platform fit are coherent |
+| Trust and retention | Dark patterns or unclear consequences | Honest but minimal | Clear value, privacy, pricing, cancellation, and useful return loops |
+
+## Design Consistency Gates
+
+Before calling a redesign good, check:
+
+- **Platform fit**: iOS feels like iOS and Android feels like Android unless the product intentionally owns a cross-platform system.
+- **Typography**: scalable type, readable line lengths, clear hierarchy, no clipping under dynamic type/font scaling.
+- **Spacing**: repeated rhythm and density; controls do not crowd gesture areas, keyboards, or system UI.
+- **Color**: semantic palette with accessible contrast; color is not the only signal.
+- **Shape**: one radius system; buttons, inputs, cards, sheets, tabs, and tags follow a rule.
+- **Elevation**: shadows, surfaces, sheets, and overlays communicate hierarchy rather than decoration.
+- **Iconography**: one icon family and consistent stroke/fill logic; ambiguous icons have labels.
+- **Motion**: purposeful transitions with reduced-motion fallback; no animation that delays task completion.
+- **Copy**: labels are specific, buttons say what happens, errors tell users how to fix the problem.
+- **Aesthetic fit**: style follows audience and product job, not generic AI gradients, repeated cards, or trend imitation.
+
+## Discovery Pass
+
+Inspect before judging. Search for:
+
+```bash
+rg -n "MaterialApp|CupertinoApp|go_router|AutoRoute|Navigator|NavigationBar|BottomNavigationBar|Drawer|TabBar|Semantics|Tooltip|SafeArea|MediaQuery|LayoutBuilder" .
+rg -n "NavigationContainer|createNativeStackNavigator|createBottomTabNavigator|accessibilityLabel|accessibilityHint|accessibilityRole|accessibilityState|SafeAreaView|KeyboardAvoidingView" .
+rg -n "NavigationStack|NavigationView|TabView|toolbar|sheet|accessibilityLabel|accessibilityHint|accessibilityValue|DynamicType|isAccessibilityElement|UIAccessibility|UITabBarController|UINavigationController" .
+rg -n "NavHost|NavController|NavigationBar|NavigationRail|ModalNavigationDrawer|Scaffold|semantics|contentDescription|stateDescription|Role\\.|importantForAccessibility|labelFor" .
+rg -n "onboarding|signup|sign-up|login|auth|permission|notification|paywall|subscribe|checkout|empty|error|loading|offline|analytics|track" .
+```
+
+Run the bundled scanner when available:
+
+```bash
+python scripts/mobile_ux_static_scan.py .
+```
+
+Then produce:
+
+- App type and likely primary user job.
+- Screen inventory and top-level destinations.
+- First-run flow from install/open to first value.
+- Primary task flow with tap count, waits, account gates, permissions, and error paths.
+- Return flow: push/deep link/open from recents/resume state.
+
+## Audit Checklist
+
+### First Launch and Onboarding
+
+- Show value before asking for account creation, payment, contacts, location, camera, photos, notifications, or tracking.
+- Ask permissions only at the moment they support a user action; use a clear pre-permission rationale only when it reduces confusion.
+- Replace static carousel onboarding with interactive setup when possible.
+- Let users skip nonessential setup and return later.
+- Preserve progress if auth, payment, permissions, or network interrupts the flow.
+- Keep copy concrete: what the user can do now, what happens next, and why information is needed.
+
+### Navigation and Information Architecture
+
+- Use bottom navigation/tab bars for a small set of persistent top-level destinations. Keep labels short and destinations stable.
+- Avoid hiding primary destinations behind a drawer on phones when there are only a few key areas.
+- Do not mix multiple primary navigation systems unless one clearly adapts by screen size.
+- Keep the current section visible during lateral navigation.
+- Use platform-native back/up/close behavior: reverse chronological back for Android, hierarchy-aware back/close on iOS modals.
+- Every screen needs an obvious next action, back path, and recovery path.
+- Deep links and notifications should land users at the relevant content with context, not just the home screen.
+
+### Core Task Flow
+
+- Identify the user's main job and count unnecessary taps, repeated fields, modal interruptions, waits, and context switches.
+- Make one primary action visually dominant per state.
+- Use sensible defaults, remembered choices, autofill, recent items, and progressive disclosure.
+- Avoid blocking the task with education, upsells, ratings, or permissions before value.
+- Keep destructive, purchase, and privacy-sensitive actions explicit and reversible where possible.
+
+### Forms, Input, and Errors
+
+- Use visible labels, not placeholder-only labels.
+- Set correct keyboard/input types, autofill hints, capitalization, validation, and password manager compatibility.
+- Validate inline after the user can reasonably correct the field; do not fail only after submit.
+- Keep error messages close to fields, specific, and action-oriented.
+- Avoid redundant entry. Reuse known profile, shipping, billing, and account data when appropriate.
+- On mobile checkout or subscription flows, reduce fields before reducing steps; long unnecessary forms are high-friction.
+
+### Feedback, Loading, Empty, and Offline States
+
+- Show immediate feedback for taps, form submission, saving, syncing, and long-running actions.
+- Use skeletons/progress only when they reflect actual state; avoid fake delays.
+- Empty states should explain what is missing and offer a next action.
+- Error states should say what happened, what the user can do, and whether data is safe.
+- Offline states should preserve read/write where feasible and sync later.
+- Confirm critical success states; do not leave users guessing after payment, booking, upload, or submission.
+
+### Visual Hierarchy and Interaction
+
+- Design for scan order: the most important content/action appears where the platform and reading direction make it easiest to find.
+- Keep text legible under Dynamic Type/font scaling and avoid clipped labels.
+- Maintain safe areas around notches, system bars, home indicators, gesture regions, keyboards, and fold/hinge areas.
+- Use spacing to group related controls and separate unrelated actions.
+- Use familiar iconography and always label ambiguous icons.
+- Motion should clarify state changes, not slow task completion. Respect Reduce Motion.
+- Use haptics sparingly for confirmation, warning, or physical-feeling controls.
+
+### Accessibility
+
+- Test with VoiceOver and TalkBack for all critical flows.
+- Every interactive custom control needs role, name/label, value/state, hint when needed, and action.
+- Focus order must match visual/task order and must not trap users.
+- Touch targets should meet platform expectations: Flutter's guideline API checks 48 by 48 for Android and 44 by 44 for iOS; WCAG 2.2 adds target-size criteria for broader accessibility review.
+- Do not communicate meaning with color alone. Add text, icons, position, shape, pattern, audio, or haptic cues.
+- Support dynamic text, bold text, high contrast, reduced motion, screen readers, switch access, keyboard/external input where relevant, captions/transcripts for media, and accessible authentication.
+- Decorative images should be hidden from assistive technologies; meaningful images need useful labels.
+
+### Adaptive Layout
+
+- Audit compact phone, large phone, tablet, foldable, landscape, split-screen, and keyboard-open states when supported.
+- Switch navigation patterns by size class where appropriate: bottom navigation on compact phones, navigation rail or sidebar/drawer on larger surfaces.
+- Avoid stretching phone layouts across tablets. Use extra width for supporting panes, sidebars, multi-column content, or detail views.
+- Preserve state across rotation, resize, split-screen, process death, and app resume.
+- Test RTL languages and long localized strings if the app is localized.
+
+### Ethical Retention and Engagement
+
+- Define the valuable return reason: unfinished task, fresh content, useful reminder, social response, saved progress, personal insight, or recurring real-world need.
+- Make the home screen answer "what should I do now?" within a few seconds.
+- Use personalization to reduce effort, not to bury controls or create anxiety.
+- Ask for notification permission after the user sees value; provide granular controls and quiet defaults.
+- Use streaks, rewards, and progress indicators only when they support the user's goal. Add forgiveness, pause, and recovery.
+- Make settings, privacy, cancellation, logout, and delete paths findable.
+- Instrument friction: first value time, task completion, abandon points, retry loops, error rates, permission acceptance, uninstall causes, DAU/MAU only when meaningful for the app category.
+
+## Framework-Specific Fix Map
+
+### Flutter
+
+- Navigation: prefer `NavigationBar`, `NavigationRail`, `TabBar`, `Navigator`, `go_router`, or existing app routing. Use `Drawer` only when it fits the hierarchy.
+- Adaptation: use `SafeArea`, `MediaQuery`, `LayoutBuilder`, `OrientationBuilder`, breakpoints, and Material/Cupertino widgets intentionally.
+- Accessibility: add `Semantics`, `MergeSemantics`, `ExcludeSemantics`, `Tooltip` for icon-only controls, semantic labels for meaningful images, and accessibility guideline widget tests.
+- Verification: run widget tests using `meetsGuideline(androidTapTargetGuideline)`, `meetsGuideline(iOSTapTargetGuideline)`, `labeledTapTargetGuideline`, and `textContrastGuideline` when test setup exists.
+
+### React Native
+
+- Navigation: inspect React Navigation/native stack/bottom tabs/drawer usage. Preserve native-stack behavior where possible.
+- Layout: use safe-area handling, `KeyboardAvoidingView` or platform-specific keyboard strategy, responsive spacing, and platform conditionals only where behavior differs.
+- Accessibility: use `accessible`, `accessibilityLabel`, `accessibilityHint`, `accessibilityRole`, `accessibilityState`, `accessibilityActions`, and `importantForAccessibility`. Avoid production reliance on experimental APIs unless the project already accepted that risk.
+- Verification: use simulator/device walkthroughs, VoiceOver/TalkBack, Detox/Appium/accessibility IDs where present.
+
+### Swift, SwiftUI, and UIKit
+
+- Navigation: prefer `NavigationStack`, `TabView`, `sheet`, `toolbar`, `UINavigationController`, `UITabBarController`, and standard Back/Close behavior.
+- Platform fit: use SF Symbols, Dynamic Type, safe areas, system controls, native sheets, confirmation dialogs, and standard search patterns before custom UI.
+- Accessibility: use SwiftUI accessibility modifiers (`accessibilityLabel`, `accessibilityValue`, `accessibilityHint`, actions) or UIKit `UIAccessibility` properties (`isAccessibilityElement`, `accessibilityLabel`, `accessibilityValue`, `accessibilityHint`, traits).
+- Verification: use Accessibility Inspector, VoiceOver, Dynamic Type sizes, Reduce Motion, high contrast, and different device classes.
+
+### Kotlin, Java, Android Views, and Jetpack Compose
+
+- Navigation: inspect Navigation Component, Compose Navigation, `NavHost`, `NavController`, `NavigationBar`, `NavigationRail`, `ModalNavigationDrawer`, `Scaffold`, and XML navigation graphs.
+- Platform fit: use Material 3 components, Android back behavior, edge-to-edge/safe insets, keyboard handling, and adaptive layouts for tablets/foldables.
+- Accessibility in Compose: rely on built-in Material semantics where possible; add `Modifier.semantics`, `contentDescription`, `stateDescription`, `role`, and custom actions for custom components.
+- Accessibility in Views: use `android:contentDescription`, `android:labelFor`, `importantForAccessibility`, proper focus order, and concise labels.
+- Verification: use TalkBack, Accessibility Scanner, Layout Inspector semantics, UIAutomator/Espresso/Compose UI tests where available.
+
+## Report Template
+
+```markdown
+## Findings
+
+| Severity | Flow/Screen | Evidence | User Impact | Fix |
+| --- | --- | --- | --- | --- |
+| P1 | Onboarding step 2 | `path/file.ext:42`, screenshot, or route name | Users must grant notifications before seeing value | Move notification ask after first successful action; add in-app reminder settings |
+
+## Flow Map
+
+Current: Open -> carousel -> permission -> sign in -> blank home
+Recommended: Open -> value preview -> optional setup -> first action -> account save prompt
+
+## Implementation Notes
+
+- Framework-specific files/components to change.
+- Native component or accessibility API to use.
+- Analytics/events to add or inspect.
+
+## Verification
+
+- What was run.
+- What could not be run.
+- Remaining UX risks.
+```
+
+## Common Failure Modes
+
+- Auditing only visuals and missing task completion, permissions, errors, empty states, and return flows.
+- Copying iOS patterns into Android or Material patterns into iOS without adapting navigation, gestures, and accessibility.
+- Recommending more screens instead of removing decisions and fields.
+- Treating retention as addiction instead of repeated successful value.
+- Adding custom buttons, tabs, switches, sliders, or sheets without semantics, focus order, hit targets, and native behavior.
+- Ignoring large text, screen readers, keyboard overlap, safe areas, tablets, foldables, RTL, and slow networks.

package/scripts/mobile_ux_static_scan.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""Static mobile UX signal scanner.
+
+This script detects review signals in Flutter, React Native, Swift/iOS, and
+Android projects. It is evidence gathering, not a full accessibility audit.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+EXCLUDE_DIRS = {
+    ".git",
+    "node_modules",
+    "Pods",
+    "DerivedData",
+    ".gradle",
+    "build",
+    ".dart_tool",
+    ".expo",
+    "coverage",
+    "ios/Pods",
+    "android/build",
+}
+
+EXTENSIONS = {
+    ".dart",
+    ".jsx",
+    ".tsx",
+    ".js",
+    ".ts",
+    ".swift",
+    ".kt",
+    ".kts",
+    ".java",
+    ".xml",
+}
+
+
+@dataclass
+class Finding:
+    severity: str
+    platform: str
+    category: str
+    title: str
+    path: str
+    line: int
+    evidence: str
+    fix: str
+
+
+PATTERNS = [
+    (
+        "P1",
+        "React Native",
+        "Accessibility",
+        "Touchable/Pressable likely missing role or label",
+        re.compile(r"<(?:Pressable|TouchableOpacity|TouchableHighlight|TouchableWithoutFeedback)\b(?![^>\n]*accessibility(?:Role|Label))", re.I),
+        "Add accessibilityRole, accessibilityLabel, accessibilityState, and keyboard/screen-reader behavior.",
+    ),
+    (
+        "P2",
+        "React Native",
+        "Forms",
+        "TextInput placeholder-label risk",
+        re.compile(r"<TextInput\b[^>\n]*placeholder\s*=", re.I),
+        "Verify a persistent visible label and accessibilityLabel are present.",
+    ),
+    (
+        "P1",
+        "React Native",
+        "Images",
+        "Image likely missing accessibility label",
+        re.compile(r"<Image\b(?![^>\n]*(?:accessibilityLabel|alt)\s*=)", re.I),
+        "Add accessibilityLabel for meaningful images or mark decorative images inaccessible.",
+    ),
+    (
+        "P2",
+        "Flutter",
+        "Accessibility",
+        "IconButton likely missing tooltip",
+        re.compile(r"\bIconButton\s*\(", re.I),
+        "Verify tooltip/semanticLabel exists so screen readers and long-press hints are useful.",
+    ),
+    (
+        "P1",
+        "Flutter",
+        "Images",
+        "Image likely missing semantic label",
+        re.compile(r"\bImage\.(?:asset|network|file|memory)\s*\((?![^;\n]*semanticLabel\s*:)", re.I),
+        "Add semanticLabel for meaningful images or exclude decorative images from semantics.",
+    ),
+    (
+        "P2",
+        "Flutter",
+        "Forms",
+        "Text field needs persistent labeling",
+        re.compile(r"\bText(?:Form)?Field\s*\(", re.I),
+        "Verify InputDecoration has labelText/semantic labeling, helper/error text, and keyboard/autofill hints.",
+    ),
+    (
+        "P1",
+        "Swift/iOS",
+        "Accessibility",
+        "Image likely missing accessibility label",
+        re.compile(r"\bImage\s*\([^)]+\)(?![^\n]*accessibilityLabel)", re.I),
+        "Add accessibilityLabel for meaningful images or mark decorative images hidden.",
+    ),
+    (
+        "P2",
+        "Swift/iOS",
+        "Layout",
+        "Broad ignoresSafeArea risk",
+        re.compile(r"\.ignoresSafeArea\s*\(\s*\)", re.I),
+        "Constrain ignored safe areas to intentional background layers, not interactive content.",
+    ),
+    (
+        "P2",
+        "Swift/iOS",
+        "Permissions",
+        "Permission request needs value-first timing",
+        re.compile(r"requestAuthorization|requestWhenInUseAuthorization|requestAlwaysAuthorization", re.I),
+        "Verify permission is requested at the moment of user intent and has a clear rationale.",
+    ),
+    (
+        "P1",
+        "Android Compose",
+        "Accessibility",
+        "Icon likely missing contentDescription",
+        re.compile(r"\bIcon\s*\((?![^)\n]*contentDescription\s*=)", re.I),
+        "Set contentDescription for meaningful icons or null for decorative icons.",
+    ),
+    (
+        "P1",
+        "Android Compose",
+        "Accessibility",
+        "Clickable modifier may need role/state semantics",
+        re.compile(r"\.clickable\s*\(", re.I),
+        "Verify role, stateDescription, custom actions, and target size for custom clickable UI.",
+    ),
+    (
+        "P2",
+        "Android Compose",
+        "Forms",
+        "TextField needs explicit label/error support",
+        re.compile(r"\b(?:OutlinedTextField|TextField)\s*\(", re.I),
+        "Verify label, supportingText/error state, keyboardOptions, and autofill behavior.",
+    ),
+    (
+        "P1",
+        "Android Views",
+        "Accessibility",
+        "ImageView likely missing contentDescription",
+        re.compile(r"<ImageView\b(?![^>\n]*android:contentDescription\s*=)", re.I),
+        "Add android:contentDescription for meaningful images or @null for decorative images.",
+    ),
+    (
+        "P2",
+        "Android Views",
+        "Forms",
+        "EditText likely missing hint/label relationship",
+        re.compile(r"<EditText\b(?![^>\n]*android:hint\s*=)", re.I),
+        "Use hint/labelFor or Material TextInputLayout with clear errors and keyboard input type.",
+    ),
+    (
+        "P2",
+        "All",
+        "Retention",
+        "Notification or permission ask found",
+        re.compile(r"requestPermissions?|POST_NOTIFICATIONS|UNUserNotificationCenter|notifications?\b", re.I),
+        "Check this is value-timed, optional when possible, and paired with granular settings.",
+    ),
+]
+
+
+def iter_files(root: Path) -> Iterable[Path]:
+    for path in root.rglob("*"):
+        if path.is_dir():
+            continue
+        if any(part in EXCLUDE_DIRS for part in path.parts):
+            continue
+        if path.suffix.lower() not in EXTENSIONS:
+            continue
+        if path.stat().st_size > 1_000_000:
+            continue
+        yield path
+
+
+def detect_stack(root: Path) -> list[str]:
+    stack: list[str] = []
+    if (root / "pubspec.yaml").exists():
+        stack.append("Flutter")
+    package_json = root / "package.json"
+    if package_json.exists():
+        try:
+            data = json.loads(package_json.read_text(encoding="utf-8"))
+            deps = " ".join(
+                list((data.get("dependencies") or {}).keys())
+                + list((data.get("devDependencies") or {}).keys())
+            )
+            if "react-native" in deps:
+                stack.append("React Native")
+            if "expo" in deps:
+                stack.append("Expo")
+        except Exception:
+            stack.append("package.json present, unreadable")
+    if list(root.rglob("*.swift")):
+        stack.append("Swift/iOS")
+    if list(root.rglob("*.kt")) or list(root.rglob("*.java")):
+        stack.append("Android Kotlin/Java")
+    if (root / "android").exists():
+        stack.append("Android project")
+    if (root / "ios").exists():
+        stack.append("iOS project")
+    return sorted(set(stack)) or ["Unknown mobile stack"]
+
+
+def global_findings(root: Path, stack: list[str], all_text: str) -> list[Finding]:
+    findings: list[Finding] = []
+    if "Flutter" in stack and "SafeArea" not in all_text:
+        findings.append(
+            Finding("P2", "Flutter", "Layout", "SafeArea not found", ".", 0, "No SafeArea token found", "Verify content avoids notches, system bars, keyboards, and gesture areas.")
+        )
+    if "React Native" in stack and "SafeAreaView" not in all_text and "useSafeAreaInsets" not in all_text:
+        findings.append(
+            Finding("P2", "React Native", "Layout", "Safe-area handling not found", ".", 0, "No SafeAreaView/useSafeAreaInsets token found", "Verify content avoids notches, system bars, and gesture areas.")
+        )
+    if ("Android Kotlin/Java" in stack or "Android project" in stack) and "WindowInsets" not in all_text and "safeDrawing" not in all_text:
+        findings.append(
+            Finding("P2", "Android", "Adaptive layout", "Inset handling not found", ".", 0, "No WindowInsets/safeDrawing token found", "Verify edge-to-edge layouts account for system bars and IME.")
+        )
+    return findings
+
+
+def scan(root: Path) -> tuple[list[str], list[Finding], int]:
+    stack = detect_stack(root)
+    findings: list[Finding] = []
+    files = list(iter_files(root))
+    snippets: list[str] = []
+    for file_path in files:
+        rel = file_path.relative_to(root).as_posix()
+        try:
+            lines = file_path.read_text(encoding="utf-8", errors="ignore").splitlines()
+        except Exception:
+            continue
+        snippets.extend(lines[:2000])
+        for idx, line in enumerate(lines, start=1):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            for severity, platform, category, title, pattern, fix in PATTERNS:
+                if pattern.search(stripped):
+                    findings.append(
+                        Finding(
+                            severity=severity,
+                            platform=platform,
+                            category=category,
+                            title=title,
+                            path=rel,
+                            line=idx,
+                            evidence=stripped[:180],
+                            fix=fix,
+                        )
+                    )
+    findings = global_findings(root, stack, "\n".join(snippets)) + findings
+    return stack, findings, len(files)
+
+
+def render_markdown(root: Path, stack: list[str], findings: list[Finding], file_count: int) -> str:
+    counts = {key: sum(1 for item in findings if item.severity == key) for key in ("P0", "P1", "P2", "P3")}
+    out = [
+        "# Mobile UX Static Scan",
+        "",
+        f"Root: `{root}`",
+        f"Files scanned: `{file_count}`",
+        f"Detected stack: {', '.join(stack)}",
+        f"Findings: P0={counts['P0']} P1={counts['P1']} P2={counts['P2']} P3={counts['P3']}",
+        "",
+        "> Static scan output is a triage signal. Confirm every finding in the app or code before changing behavior.",
+        "",
+    ]
+    if not findings:
+        out.append("No matching static UX signals found.")
+        return "\n".join(out)
+
+    out.extend(["| Severity | Platform | Category | Location | Signal | Evidence | Fix |", "| --- | --- | --- | --- | --- | --- | --- |"])
+    for item in findings[:140]:
+        location = item.path if item.line == 0 else f"{item.path}:{item.line}"
+        evidence = item.evidence.replace("|", "\\|")
+        out.append(
+            f"| {item.severity} | {item.platform} | {item.category} | `{location}` | {item.title} | `{evidence}` | {item.fix} |"
+        )
+    if len(findings) > 140:
+        out.append(f"\nTruncated to 140 findings out of {len(findings)}. Narrow the scan path for more detail.")
+    return "\n".join(out)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Scan a mobile app for static UX review signals.")
+    parser.add_argument("root", nargs="?", default=".", help="Project root or subdirectory to scan")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    if not root.exists():
+        raise SystemExit(f"Path does not exist: {root}")
+    stack, findings, file_count = scan(root)
+    print(render_markdown(root, stack, findings, file_count))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/mobile-app-ux-auditor/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: mobile-app-ux-auditor
+description: Use when reviewing, redesigning, or implementing mobile app UI/UX flows in Flutter, React Native, Swift, SwiftUI, UIKit, Kotlin, Jetpack Compose, Java, or Android Views; especially for navigation, onboarding, retention, accessibility, forms, engagement, screen hierarchy, or platform-native fit.
+---
+
+# Mobile App UX Auditor
+
+## Overview
+
+Audit mobile apps by mapping real user flows, finding friction with evidence, and proposing or implementing improvements that match iOS and Android platform expectations. Optimize for users reaching value quickly and returning willingly, not for manipulative time-on-device.
+
+## Workflow
+
+1. State the design read: app category, audience, job-to-be-done, target platforms, product maturity, visual register, and risk level. For redesigns, preserve working navigation, copy, analytics names, and accessibility wins unless there is evidence they cause harm.
+2. If code is available, run the static signal scan before judging:
+   ```bash
+   python scripts/mobile_ux_static_scan.py <project-root>
+   ```
+   In Claude Code, use `python ${CLAUDE_SKILL_DIR}/scripts/mobile_ux_static_scan.py <project-root>` when the skill is installed. Treat the script as evidence-gathering, not a replacement for expert review.
+3. Inspect routing, screens, design system files, navigation components, analytics events, accessibility props, platform-specific UI primitives, tests, and screenshots before recommending changes.
+4. Build a compact screen and flow map: first launch, onboarding, sign-in, home, primary task, search/discovery, settings, error states, empty states, permission requests, purchase/subscription, and re-entry flows.
+5. Audit flows against platform conventions, accessibility, clarity, effort, trust, feedback, performance, adaptive layout, and ethical retention. Load `references/mobile-ux-audit-reference.md` for the detailed checklist and framework-specific code signals.
+6. Rank issues by user impact:
+   - P0: Blocks core task, causes data loss, or creates severe accessibility failure.
+   - P1: Breaks navigation, trust, comprehension, or completion for many users.
+   - P2: Adds avoidable friction, inconsistency, or weak platform fit.
+   - P3: Polish, delight, or instrumentation improvement.
+7. When editing code, preserve the app's existing architecture and design system. Prefer native platform components and established navigation/accessibility APIs over custom controls unless the product has a clear reason.
+8. Verify with the best available evidence: emulator/simulator walkthrough, screenshots, accessibility scanner, VoiceOver/TalkBack, widget/UI tests, route tests, or static inspection. State any verification that could not be run.
+
+## Quality Bar
+
+Hold the output to a senior mobile product design engineer standard:
+
+- The primary user can understand where they are, what changed, what to do next, and how to recover from mistakes.
+- Core flows handle loading, empty, error, partial, disabled, offline, slow-network, auth-expired, permission-denied, interrupted, and resumed states.
+- The UI has one coherent design system: typography scale, spacing rhythm, radius rules, color roles, interaction states, motion, density, and platform adaptation.
+- Accessibility is built into labels, roles, states, focus order, target size, screen reader output, dynamic type/font scaling, contrast, and reduced-motion behavior.
+- Mobile performance is UX: launch time, route transitions, jank, unnecessary re-renders, heavy images, blocked gestures, keyboard latency, and battery cost all matter.
+- Retention comes from saved progress, useful reminders, reduced effort, trust, and repeated value. Do not optimize for addiction.
+
+## Output Format
+
+Start with findings, not praise. Include:
+
+- A prioritized findings table: severity, screen/flow, evidence, user impact, recommended fix.
+- A before/after flow summary when navigation or onboarding changes.
+- Framework-specific implementation notes for Flutter, React Native, Swift/iOS, or Android as applicable.
+- Static scan findings from `scripts/mobile_ux_static_scan.py` when code is available.
+- Accessibility and adaptive-layout checks.
+- Verification performed and remaining risks.
+
+When asked to improve the app directly, implement the smallest high-impact changes first, then report changed files and validation.
+
+## Non-Negotiables
+
+- Do not recommend "make users stay longer" tactics that rely on confusion, forced continuity, hidden exits, guilt, dark patterns, or notification spam.
+- Do not replace platform conventions with custom UI only for novelty.
+- Do not audit from static screenshots alone when code or an app build is available.
+- Do not give generic advice like "improve onboarding" without naming the exact screen, problem, and change.

package/skills/mobile-app-ux-auditor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mobile App UX Auditor"
+  short_description: "Audit and improve mobile app UI/UX flows"
+  default_prompt: "Use $mobile-app-ux-auditor to review this mobile app flow and propose practical UI/UX improvements."