agy-superpowers 5.1.1 → 5.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +22 -2
  2. package/package.json +1 -1
  3. package/template/agent/.shared/mobile-uiux-promax/data/accessibility.csv +25 -0
  4. package/template/agent/.shared/mobile-uiux-promax/data/animation.csv +22 -0
  5. package/template/agent/.shared/mobile-uiux-promax/data/components.csv +21 -0
  6. package/template/agent/.shared/mobile-uiux-promax/data/gestures.csv +26 -0
  7. package/template/agent/.shared/mobile-uiux-promax/data/layout.csv +21 -0
  8. package/template/agent/.shared/mobile-uiux-promax/data/navigation.csv +27 -0
  9. package/template/agent/.shared/mobile-uiux-promax/data/onboarding.csv +17 -0
  10. package/template/agent/.shared/mobile-uiux-promax/data/platform.csv +22 -0
  11. package/template/agent/.shared/mobile-uiux-promax/data/stacks/flutter.csv +19 -0
  12. package/template/agent/.shared/mobile-uiux-promax/data/stacks/jetpack-compose.csv +18 -0
  13. package/template/agent/.shared/mobile-uiux-promax/data/stacks/react-native.csv +20 -0
  14. package/template/agent/.shared/mobile-uiux-promax/data/stacks/swiftui.csv +18 -0
  15. package/template/agent/.shared/mobile-uiux-promax/data/ux-laws.csv +16 -0
  16. package/template/agent/.shared/mobile-uiux-promax/scripts/mobile-search.py +157 -0
  17. package/template/agent/.shared/ui-ux-pro-max/data/charts.csv +26 -0
  18. package/template/agent/.shared/ui-ux-pro-max/data/colors.csv +97 -0
  19. package/template/agent/.shared/ui-ux-pro-max/data/landing.csv +31 -0
  20. package/template/agent/.shared/ui-ux-pro-max/data/products.csv +97 -0
  21. package/template/agent/.shared/ui-ux-pro-max/data/prompts.csv +24 -0
  22. package/template/agent/.shared/ui-ux-pro-max/data/stacks/flutter.csv +53 -0
  23. package/template/agent/.shared/ui-ux-pro-max/data/stacks/html-tailwind.csv +56 -0
  24. package/template/agent/.shared/ui-ux-pro-max/data/stacks/nextjs.csv +53 -0
  25. package/template/agent/.shared/ui-ux-pro-max/data/stacks/react-native.csv +52 -0
  26. package/template/agent/.shared/ui-ux-pro-max/data/stacks/react.csv +54 -0
  27. package/template/agent/.shared/ui-ux-pro-max/data/stacks/svelte.csv +54 -0
  28. package/template/agent/.shared/ui-ux-pro-max/data/stacks/swiftui.csv +51 -0
  29. package/template/agent/.shared/ui-ux-pro-max/data/stacks/vue.csv +50 -0
  30. package/template/agent/.shared/ui-ux-pro-max/data/styles.csv +59 -0
  31. package/template/agent/.shared/ui-ux-pro-max/data/typography.csv +58 -0
  32. package/template/agent/.shared/ui-ux-pro-max/data/ux-guidelines.csv +100 -0
  33. package/template/agent/.shared/ui-ux-pro-max/scripts/__pycache__/core.cpython-313.pyc +0 -0
  34. package/template/agent/.shared/ui-ux-pro-max/scripts/core.py +236 -0
  35. package/template/agent/.shared/ui-ux-pro-max/scripts/search.py +61 -0
  36. package/template/agent/.tests/TESTS.md +119 -0
  37. package/template/agent/.tests/mobile-uiux-promax/test_search.py +266 -0
  38. package/template/agent/.tests/run_tests.py +86 -0
  39. package/template/agent/patches/skills-patches.md +20 -0
  40. package/template/agent/skills/brainstorming/SKILL.md +57 -0
  41. package/template/agent/skills/frontend-design/SKILL.md +147 -0
  42. package/template/agent/skills/frontend-design/reference/color-and-contrast.md +117 -0
  43. package/template/agent/skills/frontend-design/reference/interaction-design.md +159 -0
  44. package/template/agent/skills/frontend-design/reference/motion-design.md +150 -0
  45. package/template/agent/skills/frontend-design/reference/responsive-design.md +161 -0
  46. package/template/agent/skills/frontend-design/reference/spatial-design.md +122 -0
  47. package/template/agent/skills/frontend-design/reference/typography.md +124 -0
  48. package/template/agent/skills/frontend-design/reference/ux-writing.md +127 -0
  49. package/template/agent/skills/mobile-uiux-promax/SKILL.md +139 -0
  50. package/template/agent/skills/subagent-driven-development/implementer-prompt.md +4 -1
  51. package/template/agent/skills/verification-before-completion/SKILL.md +11 -0
  52. package/template/agent/skills/writing-plans/SKILL.md +4 -1
  53. package/template/agent/workflows/mobile-uiux-promax.md +137 -0
  54. package/template/agent/workflows/ui-ux-pro-max.md +231 -0
@@ -0,0 +1,124 @@
1
+ # Typography
2
+
3
+ ## Classic Typography Principles
4
+
5
+ ### Vertical Rhythm
6
+ Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony — text and space share a mathematical foundation.
7
+
8
+ ### Modular Scale & Hierarchy
9
+ The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.
10
+
11
+ **Use fewer sizes with more contrast.** A 5-size system covers most needs:
12
+
13
+ | Role | Typical Ratio | Use Case |
14
+ |------|---------------|----------|
15
+ | xs | 0.75rem | Captions, legal |
16
+ | sm | 0.875rem | Secondary UI, metadata |
17
+ | base | 1rem | Body text |
18
+ | lg | 1.25–1.5rem | Subheadings, lead text |
19
+ | xl+ | 2–4rem | Headlines, hero text |
20
+
21
+ Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
22
+
23
+ ### Readability & Measure
24
+ Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length — narrow columns need tighter leading, wide columns need more.
25
+
26
+ **Non-obvious**: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05–0.1 to your normal line-height.
27
+
28
+ ---
29
+
30
+ ## Font Selection & Pairing
31
+
32
+ ### Choosing Distinctive Fonts
33
+ **Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal — but if you want distinctive design, look elsewhere.
34
+
35
+ **Better Google Fonts alternatives**:
36
+ - Instead of Inter → **Instrument Sans**, **Plus Jakarta Sans**, **Outfit**
37
+ - Instead of Roboto → **Onest**, **Figtree**, **Urbanist**
38
+ - Instead of Open Sans → **Source Sans 3**, **Nunito Sans**, **DM Sans**
39
+ - For editorial/premium feel → **Fraunces**, **Newsreader**, **Lora**
40
+
41
+ **System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider for apps where performance > personality.
42
+
43
+ ### Pairing Principles
44
+ **The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces.
45
+
46
+ When pairing, contrast on multiple axes:
47
+ - Serif + Sans (structure contrast)
48
+ - Geometric + Humanist (personality contrast)
49
+ - Condensed display + Wide body (proportion contrast)
50
+
51
+ **Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.
52
+
53
+ ### Web Font Loading
54
+ The layout shift problem: fonts load late, text reflows, users see content jump. The fix:
55
+
56
+ ```css
57
+ /* 1. Use font-display: swap for visibility */
58
+ @font-face {
59
+ font-family: 'CustomFont';
60
+ src: url('font.woff2') format('woff2');
61
+ font-display: swap;
62
+ }
63
+
64
+ /* 2. Match fallback metrics to minimize shift */
65
+ @font-face {
66
+ font-family: 'CustomFont-Fallback';
67
+ src: local('Arial');
68
+ size-adjust: 105%;
69
+ ascent-override: 90%;
70
+ descent-override: 20%;
71
+ line-gap-override: 10%;
72
+ }
73
+
74
+ body {
75
+ font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
76
+ }
77
+ ```
78
+
79
+ ---
80
+
81
+ ## Modern Web Typography
82
+
83
+ ### Fluid Type
84
+ Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport.
85
+
86
+ **Use fluid type for**: Headings and display text on marketing/content pages.
87
+ **Use fixed `rem` scales for**: App UIs, dashboards, data-dense interfaces. Body text should also be fixed.
88
+
89
+ ### OpenType Features
90
+ Use these for polish — most developers don't know they exist:
91
+
92
+ ```css
93
+ /* Tabular numbers for data alignment */
94
+ .data-table { font-variant-numeric: tabular-nums; }
95
+
96
+ /* Proper fractions */
97
+ .recipe-amount { font-variant-numeric: diagonal-fractions; }
98
+
99
+ /* Small caps for abbreviations */
100
+ abbr { font-variant-caps: all-small-caps; }
101
+
102
+ /* Disable ligatures in code */
103
+ code { font-variant-ligatures: none; }
104
+
105
+ /* Enable kerning */
106
+ body { font-kerning: normal; }
107
+ ```
108
+
109
+ ---
110
+
111
+ ## Typography System Architecture
112
+
113
+ Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
114
+
115
+ ## Accessibility
116
+
117
+ - **Never disable zoom**: `user-scalable=no` breaks accessibility
118
+ - **Use rem/em for font sizes**: Respects user browser settings. Never `px` for body text
119
+ - **Minimum 16px body text**: Smaller strains eyes and fails WCAG on mobile
120
+ - **Adequate touch targets**: Text links need padding creating 44px+ tap targets
121
+
122
+ ---
123
+
124
+ **Avoid**: More than 2–3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.
@@ -0,0 +1,127 @@
1
+ # UX Writing
2
+
3
+ ## The Button Label Problem
4
+
5
+ **Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
6
+
7
+ | Bad | Good | Why |
8
+ |-----|------|-----|
9
+ | OK | Save changes | Says what will happen |
10
+ | Submit | Create account | Outcome-focused |
11
+ | Yes | Delete message | Confirms the action |
12
+ | Cancel | Keep editing | Clarifies what "cancel" means |
13
+ | Click here | Download PDF | Describes the destination |
14
+
15
+ **For destructive actions**, name the destruction:
16
+ - "Delete" not "Remove" (delete is permanent, remove implies recoverable)
17
+ - "Delete 5 items" not "Delete selected" (show the count)
18
+
19
+ ---
20
+
21
+ ## Error Messages: The Formula
22
+
23
+ Every error should answer: (1) What happened? (2) Why? (3) How to fix it?
24
+
25
+ - ✅ `"Email address isn't valid. Please include an @ symbol."`
26
+ - ❌ `"Invalid input"`
27
+
28
+ ### Templates per Situation
29
+
30
+ | Situation | Template |
31
+ |-----------|----------|
32
+ | **Format error** | "[Field] needs to be [format]. Example: [example]" |
33
+ | **Missing required** | "Please enter [what's missing]" |
34
+ | **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
35
+ | **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
36
+ | **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
37
+
38
+ ### Don't Blame the User
39
+ Reframe errors:
40
+ - ✅ `"Please enter a date in MM/DD/YYYY format"`
41
+ - ❌ `"You entered an invalid date"`
42
+
43
+ ---
44
+
45
+ ## Empty States Are Opportunities
46
+
47
+ Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value, (3) Provide a clear action.
48
+
49
+ - ✅ "No projects yet. Create your first one to get started."
50
+ - ❌ "No items"
51
+
52
+ ---
53
+
54
+ ## Voice vs Tone
55
+
56
+ **Voice** is your brand's personality — consistent everywhere.
57
+ **Tone** adapts to the moment:
58
+
59
+ | Moment | Tone Shift |
60
+ |--------|------------|
61
+ | Success | Celebratory, brief: "Done! Your changes are live." |
62
+ | Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
63
+ | Loading | Reassuring: "Saving your work..." |
64
+ | Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
65
+
66
+ **Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
67
+
68
+ ---
69
+
70
+ ## Writing for Accessibility
71
+
72
+ - **Link text** must have standalone meaning — "View pricing plans" not "Click here"
73
+ - **Alt text** describes information, not the image — "Revenue increased 40% in Q4" not "Chart"
74
+ - Use `alt=""` for decorative images
75
+ - **Icon buttons** need `aria-label`
76
+
77
+ ---
78
+
79
+ ## Writing for Translation
80
+
81
+ ### Plan for Expansion
82
+
83
+ | Language | Expansion |
84
+ |----------|-----------|
85
+ | German | +30% |
86
+ | French | +20% |
87
+ | Finnish | +30–40% |
88
+ | Chinese | −30% (fewer chars, same width) |
89
+
90
+ ### Translation-Friendly Patterns
91
+ - Keep numbers separate ("New messages: 3" not "You have 3 new messages")
92
+ - Use full sentences as single strings (word order varies by language)
93
+ - Avoid abbreviations ("5 minutes ago" not "5 mins ago")
94
+ - Give translators context about where strings appear
95
+
96
+ ---
97
+
98
+ ## Consistency: The Terminology Problem
99
+
100
+ Pick one term and stick with it:
101
+
102
+ | Inconsistent | Consistent |
103
+ |--------------|------------|
104
+ | Delete / Remove / Trash | Delete |
105
+ | Settings / Preferences / Options | Settings |
106
+ | Sign in / Log in / Enter | Sign in |
107
+ | Create / Add / New | Create |
108
+
109
+ Build a terminology glossary and enforce it. Variety creates confusion.
110
+
111
+ ---
112
+
113
+ ## Avoid Redundant Copy
114
+
115
+ If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
116
+
117
+ ## Loading States
118
+
119
+ Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
120
+
121
+ ## Confirmation Dialogs: Use Sparingly
122
+
123
+ Most confirmation dialogs are design failures — **consider undo instead**. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
124
+
125
+ ---
126
+
127
+ **Avoid**: Jargon without explanation. Blaming users ("Invalid input" → "Please include @"). Vague errors. Varying terminology for variety. Humor for error states.
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: mobile-uiux-promax
3
+ description: Use when designing or building mobile app UI for iOS, Android, React Native, Flutter, SwiftUI, or Jetpack Compose
4
+ ---
5
+
6
+ # Mobile UI/UX Pro Max
7
+
8
+ Data-grounded mobile design intelligence. Every design decision is backed by platform-authoritative data from Apple HIG, Material Design 3, and stack-specific best practices.
9
+
10
+ ## When to Activate
11
+
12
+ Activate this skill when the request involves:
13
+ - Designing any mobile screen, flow, or component
14
+ - Reviewing mobile UI for platform-appropriateness
15
+ - Choosing between navigation patterns for mobile apps
16
+ - Implementing gesture-driven or haptic-rich interactions
17
+ - Advising on iOS vs Android design conventions
18
+ - Building onboarding flows or paywall timing
19
+ - Animation and motion design for mobile
20
+
21
+ ## Workflow
22
+
23
+ Run the 4-step search sequence from: `.agent/workflows/mobile-uiux-promax.md`
24
+
25
+ **Read the workflow file before responding.** It contains the exact search commands to run.
26
+
27
+ ## Core Design Principles (Memorize These)
28
+
29
+ ### 1. Platform-First, Not Platform-Only
30
+ - Follow platform conventions by default
31
+ - Deviate only when there's clear UX benefit to users
32
+ - Cross-platform apps must feel native on each platform, not identical
33
+ - iOS users expect swipe-back + tab bar at bottom; Android users expect system back + nav structure
34
+
35
+ ### 2. Thumb Zone Above All
36
+ - Primary actions belong in the bottom 60% of the screen
37
+ - Top-left corner = hardest to reach one-handed
38
+ - Platform back buttons (iOS top-left) are the only justified exception
39
+
40
+ ### 3. Gesture + Haptic + Visual = One Interaction
41
+ - Every interaction should engage all three senses when appropriate
42
+ - Swipe reveals → haptic at threshold + visual action button
43
+ - Toggle → haptic on state change + visual state update simultaneously
44
+ - Pull-to-refresh → haptic on trigger + spinner animation + announce to screen readers
45
+
46
+ ### 4. Accessibility Is Not Optional
47
+ - Minimum touch target: 44pt (iOS) / 48dp (Android)
48
+ - Every tappable element without visible text needs `accessibilityLabel`
49
+ - Every gesture needs an accessible alternative action
50
+ - Test with VoiceOver (iOS) and TalkBack (Android) before shipping
51
+ - Support Dynamic Type / sp font scaling (never lock font size)
52
+
53
+ ### 5. Reduce Motion Is a Hard Requirement
54
+ - Check `UIAccessibility.isReduceMotionEnabled` (iOS) and `LocalReduceMotion` (Compose) everywhere you animate
55
+ - Replace slides with fades; replace springs with eases; reduce or eliminate particle effects
56
+ - Haptics are NOT animation — keep them even when reducing motion
57
+
58
+ ### 6. Safe Area = Non-Negotiable
59
+ - Never hardcode padding for device-specific areas
60
+ - Always use `safeAreaInsets` / `SafeAreaView` / `WindowInsets` APIs
61
+ - Test on iPhone SE (small), iPhone 14 Pro (Dynamic Island), and latest iPad
62
+
63
+ ## Pre-Delivery Checklist
64
+
65
+ Before presenting any design decision, implementation, or code:
66
+
67
+ **Layout & Ergonomics**
68
+ - [ ] Touch targets ≥ 44pt / 48dp everywhere
69
+ - [ ] Safe area insets respected on all edges
70
+ - [ ] Primary actions in thumb-reachable zone (bottom 60%)
71
+ - [ ] Content not hidden behind notch / Dynamic Island / home indicator
72
+ - [ ] Keyboard avoidance implemented for any screen with text inputs
73
+
74
+ **Platform Conventions**
75
+ - [ ] Back navigation: iOS swipe-back enabled + button; Android system back handled
76
+ - [ ] Navigation pattern matches platform idiom (tab bar on iOS; nav bar or drawer on Android)
77
+ - [ ] Status bar style contrasts with content behind it
78
+ - [ ] Haptic feedback added for primary interactions (where hardware supports)
79
+
80
+ **Accessibility**
81
+ - [ ] VoiceOver/TalkBack labels on all interactive elements
82
+ - [ ] Heading traits applied to screen titles and section headers
83
+ - [ ] Custom gesture actions available via accessibility Actions menu
84
+ - [ ] Dynamic Type / sp units used (no fixed font sizes)
85
+ - [ ] Color contrast ≥ 4.5:1 for body text; ≥ 3:1 for large text / UI
86
+ - [ ] Color information supplemented with shape/icon/text
87
+
88
+ **Motion**
89
+ - [ ] `reduceMotion` check before every animation
90
+ - [ ] Animation duration appropriate (200-400ms for most; <200ms for micro)
91
+ - [ ] Spring used for natural feel on expand/appear; ease-out for dismiss/collapse
92
+
93
+ **Dark Mode**
94
+ - [ ] All colors defined as adaptive (no hardcoded hex for any UI color)
95
+ - [ ] Test on OLED (true black matters for pure black backgrounds)
96
+ - [ ] Images and media contrast tested in both appearances
97
+
98
+ ## Stack-Specific Reminders
99
+
100
+ ### React Native
101
+ - Use `react-native-safe-area-context` not built-in SafeAreaView
102
+ - Use `react-native-reanimated` for gesture-driven animations
103
+ - Use `react-native-gesture-handler` for complex touch interactions
104
+ - FlatList not ScrollView for lists with 20+ items
105
+ - `useNativeDriver: true` on every `Animated.timing()`
106
+
107
+ ### Flutter
108
+ - `ListView.builder` not `Column + ForEach` for long lists
109
+ - `const` constructors everywhere possible
110
+ - `GoRouter` for navigation with deep link support
111
+ - `Riverpod` for state management
112
+ - `cached_network_image` for network images
113
+
114
+ ### SwiftUI
115
+ - `NavigationStack` not deprecated `NavigationView` (iOS 16+)
116
+ - `@StateObject` not `@ObservedObject` for own ViewModels
117
+ - `LazyVStack` not `VStack` for long lists
118
+ - `matchedGeometryEffect` for hero-like shared element transitions
119
+ - `@Environment(\.accessibilityReduceMotion)` before any animation
120
+
121
+ ### Jetpack Compose
122
+ - `LazyColumn` with `key = { it.id }` for lists
123
+ - `derivedStateOf` for computed state values
124
+ - `StatefulShellRoute` for tab persistence in GoRouter
125
+ - `collectAsStateWithLifecycle()` in all state collection
126
+ - `WindowCompat.setDecorFitsSystemWindows(window, false)` for edge-to-edge
127
+
128
+ ## Key Data Sources Baked Into Database
129
+
130
+ | Domain | Authority |
131
+ |--------|-----------|
132
+ | iOS conventions | Apple Human Interface Guidelines |
133
+ | Android conventions | Material Design 3 |
134
+ | React Native patterns | React Navigation docs + RN official docs |
135
+ | Flutter patterns | Flutter official docs + pub.dev best packages |
136
+ | SwiftUI patterns | Apple developer documentation |
137
+ | Compose patterns | Android Jetpack documentation |
138
+ | Accessibility | WCAG 2.1 + iOS Accessibility + Android Accessibility |
139
+ | Animation timing | Platform-standard specs (iOS spring / MD3 motion) |
@@ -32,7 +32,10 @@ Task tool (general-purpose):
32
32
  1. Implement exactly what the task specifies
33
33
  2. Write tests (following TDD if task says to)
34
34
  3. Verify implementation works
35
- 4. Commit your work
35
+ 4. Commit your work (if auto_commit is enabled)
36
+ - Read `.agent/config.yml` to check the `auto_commit` setting
37
+ - If `auto_commit: true` (or not set): `git add` changed files + `git commit`
38
+ - If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). Files left as modified for manual commit."
36
39
  5. Self-review (see below)
37
40
  6. Report back
38
41
 
@@ -99,6 +99,17 @@ Skip any step = lying, not verifying
99
99
  ❌ "Tests pass, phase complete"
100
100
  ```
101
101
 
102
+ **`.agent/.tests/` check (if applicable):**
103
+
104
+ If work involved modifying any `.agent/skills/<skill>/` or `.agent/.shared/<tool>/`, run tests before claiming done:
105
+ ```bash
106
+ python3 .agent/.tests/run_tests.py <skill-name>
107
+ ```
108
+ ```
109
+ ✅ Run command → Paste full verbose output → All pass → Claim done
110
+ ❌ "Should still pass" / Skip running because "I didn't change the data"
111
+ ```
112
+
102
113
  **Agent delegation:**
103
114
  ```
104
115
  ✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
@@ -95,12 +95,15 @@ def function(input):
95
95
  Run: `pytest tests/path/test.py::test_name -v`
96
96
  Expected: PASS
97
97
 
98
- - [ ] **Step 5: Commit**
98
+ - [ ] **Step 5: Commit (if auto_commit enabled)**
99
99
 
100
+ Check `.agent/config.yml` for `auto_commit` setting:
101
+ - If `auto_commit: true` (default):
100
102
  ```bash
101
103
  git add tests/path/test.py src/path/file.py
102
104
  git commit -m "feat: add specific feature"
103
105
  ```
106
+ - If `auto_commit: false`: skip commit and staging. Print: "Skipping commit (auto_commit: false)."
104
107
  ````
105
108
 
106
109
  ## Remember
@@ -0,0 +1,137 @@
1
+ ---
2
+ description: Plan and implement mobile app UI (iOS, Android, React Native, Flutter, SwiftUI, Compose)
3
+ ---
4
+
5
+ # Mobile UI/UX Pro Max
6
+
7
+ Data-driven mobile design intelligence. Runs a 4-step search sequence — style layer (web tool) → mobile behavior layer → stack guidelines → synthesize — before presenting any mobile UI design.
8
+
9
+ ## Prerequisites
10
+
11
+ ```bash
12
+ python3 --version # 3.8+ required
13
+ ```
14
+
15
+ ## When to Use
16
+
17
+ When asked to design, build, or review mobile app UI. Activate for any request involving:
18
+ - Mobile app screen design
19
+ - iOS or Android UI
20
+ - React Native, Flutter, SwiftUI, or Jetpack Compose UI
21
+ - Navigation, gestures, onboarding, or mobile-specific UX patterns
22
+
23
+ ## 4-Step Search Sequence
24
+
25
+ ### Step 1 — Style Layer (web tool, same as web flow)
26
+
27
+ Search for style, color, typography, and product inspiration:
28
+
29
+ ```bash
30
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<app type>" --domain product
31
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<style keywords>" --domain style
32
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<industry mood>" --domain color
33
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<mood>" --domain typography
34
+ ```
35
+
36
+ ### Step 2 — Mobile Behavior Layer (mobile tool)
37
+
38
+ Search for mobile-specific UX patterns and platform conventions:
39
+
40
+ ```bash
41
+ # Step 2: Mobile behavior (navigation, gestures, components, layout, platform, animation, onboarding, accessibility, ux-laws)
42
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<nav pattern>" --domain navigation
43
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<gesture>" --domain gestures
44
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<component>" --domain components
45
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<layout topic>" --domain layout
46
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<platform difference>" --domain platform
47
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<animation type>" --domain animation
48
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<onboarding pattern>" --domain onboarding
49
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<a11y concern>" --domain accessibility
50
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<psychology principle>" --domain ux-laws
51
+ ```
52
+
53
+ ### Step 3 — Stack Guidelines
54
+
55
+ Search for your specific stack's implementation patterns:
56
+
57
+ ```bash
58
+ # React Native
59
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<topic>" --stack react-native
60
+
61
+ # Flutter
62
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<topic>" --stack flutter
63
+
64
+ # SwiftUI
65
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<topic>" --stack swiftui
66
+
67
+ # Jetpack Compose
68
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<topic>" --stack jetpack-compose
69
+ ```
70
+
71
+ Use `-n 5` to get more results: `--domain navigation -n 5`
72
+
73
+ ### Step 4 — Synthesize and Design
74
+
75
+ Combine all search results to inform:
76
+ - Visual style (from Step 1)
77
+ - Navigation structure and gestures (from Step 2)
78
+ - Platform conventions and component choices (from Step 2)
79
+ - Stack-specific implementation patterns (from Step 3)
80
+
81
+ Present as **screen flows** not isolated component lists.
82
+
83
+ ## Pre-Delivery Checklist
84
+
85
+ Before presenting any mobile UI design or implementation:
86
+
87
+ - [ ] All touch targets ≥ 44pt (iOS) / 48dp (Android)
88
+ - [ ] Safe areas respected (notch, Dynamic Island, home indicator)
89
+ - [ ] Haptic feedback for key interactions (selection toggle success error)
90
+ - [ ] `prefers-reduced-motion` / Reduce Motion respected on both platforms
91
+ - [ ] Platform back navigation supported (iOS swipe-back + Android system back)
92
+ - [ ] Accessibility labels on all interactive elements
93
+ - [ ] Dark mode tested on both platforms
94
+ - [ ] No hardcoded pixel values (use responsive units: pt/sp not px)
95
+
96
+ ## Domain Reference
97
+
98
+ | Domain | When to search |
99
+ |--------|---------------|
100
+ | `navigation` | Nav structure, tab bar vs drawer, modals, deep links |
101
+ | `gestures` | Swipe pull-to-refresh long press pinch |
102
+ | `components` | Bottom sheet FAB snackbar chips skeleton |
103
+ | `layout` | Safe areas thumb zone spacing keyboard |
104
+ | `platform` | iOS vs Android conventions HIG vs MD3 |
105
+ | `animation` | Transitions micro-interactions haptic timing |
106
+ | `onboarding` | First-time flow permissions paywall signup timing |
107
+ | `accessibility` | Touch targets screen reader labels contrast |
108
+ | `ux-laws` | Psychology principles: Fitts Hick Miller Jakob Goal-Gradient Peak-End Doherty etc. |
109
+
110
+ ## Stack Reference
111
+
112
+ | Stack | When to use |
113
+ |-------|------------|
114
+ | `react-native` | React Native (iOS + Android) |
115
+ | `flutter` | Flutter (iOS + Android) |
116
+ | `swiftui` | SwiftUI (iOS native) |
117
+ | `jetpack-compose` | Jetpack Compose (Android native) |
118
+
119
+ ## Example: Fitness Tracker App (Dark Mode, RN)
120
+
121
+ ```bash
122
+ # Step 1: Style
123
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fitness health tracker" --domain product
124
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "dark energetic bold sport" --domain style
125
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fitness sport energy" --domain color
126
+ python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "bold dynamic" --domain typography
127
+
128
+ # Step 2: Mobile behavior
129
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "tab bar navigation bottom" --domain navigation
130
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "swipe gesture workouts list" --domain gestures
131
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "progress card stat tracker component" --domain components
132
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "dark mode" --domain platform
133
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "spring animation progress" --domain animation
134
+
135
+ # Step 3: Stack
136
+ python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "list performance animation" --stack react-native
137
+ ```