Iron Law
NO FLUTTER UI WITHOUT COMPLETING THE MOBILE CHECKPOINT FIRST — load reference/touch-psychology.md and reference/mobile-performance.md before writing any screen
Mobile Design Skill
(Mobile-First · Touch-First · Platform-Respectful)
Philosophy: Touch-first. Battery-conscious. Platform-respectful. Offline-capable.
Core Law: Mobile is NOT a small desktop.
Operating Rule: Think constraints first, aesthetics second.
This skill provides the design thinking layer that must be loaded BEFORE flutter-mobile. It exists to prevent desktop-thinking, AI-defaults, and unsafe assumptions when designing Flutter screens for iOS and Android.
Load this skill first. Complete the Mobile Checkpoint. Then open flutter-mobile to implement.
Mobile Feasibility & Risk Index (MFRI)
Before designing or implementing any mobile feature or screen, assess feasibility.
MFRI Dimensions (1-5)
| Dimension |
Question |
| Platform Clarity |
Is the target platform (iOS / Android / both) explicitly defined? |
| Interaction Complexity |
How complex are gestures, flows, or navigation? |
| Performance Risk |
Does this involve lists, animations, heavy state, or media? |
| Offline Dependence |
Does the feature break or degrade without network? |
| Accessibility Risk |
Does this impact motor, visual, or cognitive accessibility? |
Score Formula
MFRI = (Platform Clarity + Accessibility Readiness)
- (Interaction Complexity + Performance Risk + Offline Dependence)
Range: -10 to +10
Interpretation
| MFRI |
Meaning |
Required Action |
| 6-10 |
Safe |
Proceed normally |
| 3-5 |
Moderate |
Add performance + UX validation |
| 0-2 |
Risky |
Simplify interactions or architecture |
| < 0 |
Dangerous |
Redesign before implementation |
Mandatory Thinking Before Any Work
STOP: Ask Before Assuming
If any of the following are not explicitly stated, you MUST ask before proceeding:
| Aspect |
Question |
Why |
| Platform |
iOS, Android, or both? |
Affects navigation, gestures, typography |
| Framework |
Flutter (this workspace is Flutter-only) |
Determines performance and patterns |
| Navigation |
Tabs, stack, drawer? |
Core UX architecture |
| Offline |
Must it work offline? |
Data and sync strategy |
| Devices |
Phone only or tablet too? |
Layout and density rules |
| Audience |
Consumer, enterprise, accessibility needs? |
Touch and readability |
Flutter note: This workspace uses Flutter 3.41.x exclusively. Framework is not a question — it is Flutter. If the request is for React Native, redirect to the mobile-developer skill.
Never default to your favorite stack or pattern.
Reference Reading Order
Read these files in this order before designing any screen:
| File |
Purpose |
When |
reference/touch-psychology.md |
Fitts' Law, thumb zones, gesture psychology |
Always first |
reference/mobile-performance.md |
Flutter const widgets, Riverpod selectors, 60fps |
Before any list or animation |
reference/platform-ios.md |
iOS HIG, SF Pro, Dynamic Type |
When building iOS-specific UI |
reference/platform-android.md |
Material 3, Roboto, dp system |
When building Android-specific UI |
reference/mobile-backend.md |
Offline sync, push notifications, Firebase |
When feature uses network |
reference/mobile-testing.md |
Device testing, E2E flows, flutter_test |
Before writing tests |
reference/mobile-debugging.md |
Flutter DevTools, Dart Observatory, xcodebuild MCP |
When debugging |
If you have not read touch-psychology.md, you are not allowed to design any UI.
Hard Bans (Flutter-Specific)
Performance Sins
| Never |
Why |
Always |
ListView(children: items.map(...).toList()) |
Renders all items, memory explosion |
ListView.builder or SliverList |
SingleChildScrollView wrapping long lists |
Same problem as above |
ListView.builder |
setState for complex cross-widget state |
Rebuilds entire subtree |
Riverpod providers |
Heavy computation inside build() |
Blocks UI thread, drops frames |
Offload to isolates or services |
| Non-const constructors on static widgets |
Forces unnecessary rebuilds |
const on every eligible widget |
Touch and UX Sins
| Never |
Why |
Always |
| Touch targets below 48dp |
Missed taps, user frustration |
SizedBox padding to min 48dp |
| Gesture-only actions with no button |
Excludes users |
Provide visible button alternative |
| No loading state on async actions |
Feels broken |
Show CircularProgressIndicator |
| No error recovery |
Dead end |
Retry button + error message |
| Ignore platform conventions |
Breaks muscle memory |
iOS edge swipe, Android system back |
Design Token Sins
| Never |
Why |
Always |
Colors.blue or Color(0xFF...) |
Hardcoded, breaks theming |
Theme.of(context).colorScheme.* |
EdgeInsets.all(16) inline |
Magic numbers, no token |
AppSpacing.* tokens |
TextStyle(fontSize: 17) inline |
Bypasses type scale |
Theme.of(context).textTheme.* |
Security Sins
| Never |
Why |
Always |
| Tokens in SharedPreferences |
Easily read without root |
flutter_secure_storage (Keychain/Keystore) |
| Hardcoded API secrets |
Reverse-engineered from APK/IPA |
Environment config + secure storage |
| No certificate pinning |
MITM risk |
Cert pinning via http_certificate_pinning |
| Log sensitive data |
PII leakage |
Never log tokens, passwords, PII |
Platform Unification Matrix
Some elements should be unified across platforms. Others must diverge.
UNIFY DIVERGE
---------------------- -------------------------
Business logic Navigation behavior
Data models Gestures
API contracts Icons
Validation Typography
Error semantics Pickers / dialogs
Platform Defaults
| Element |
iOS |
Android |
| Font |
SF Pro |
Roboto |
| Min touch |
44pt |
48dp |
| Back |
Edge swipe |
System back |
| Sheets |
Bottom sheet |
Dialog / sheet |
| Icons |
SF Symbols |
Material Icons |
In Flutter, use CupertinoWidget variants for iOS-specific elements and Material widgets for Android. For cross-platform, prefer Material with iOS adaptations via Platform.isIOS checks or adaptive constructors where available.
Mobile Checkpoint
Complete this before writing any widget code. If you cannot fill it in, go back and read the reference files.
MOBILE CHECKPOINT
Platform: [ ] iOS [ ] Android [ ] Both
Framework: Flutter 3.41.x
Files Read: [ ] touch-psychology [ ] mobile-performance [ ] platform-specific
MFRI Score: ___ (must be >= 3)
3 Principles I Will Apply:
1.
2.
3.
Anti-Patterns I Will Avoid:
1.
2.
MFRI score < 3: stop and redesign before opening flutter-mobile.
Integration with Workspace
- Load this skill BEFORE
flutter-mobile
- Complete the Mobile Checkpoint above
- Once checkpoint is done and MFRI >= 3, open
flutter-mobile for implementation patterns
- After writing code, dispatch:
riverpod-reviewer, flutter-security-expert, accessibility-auditor
Related Agents
| Agent |
When |
riverpod-reviewer |
After writing any provider or state |
flutter-security-expert |
After adding auth, storage, or network code |
accessibility-auditor |
After building any screen or interactive widget |
Related Skills
flutter-mobile — Implementation patterns, templates, codegenriverpod-patterns — Provider types, AsyncValue, select()ui-standards-tokens — AppSpacing, colorScheme, textTheme tokens
Final Law:
Mobile users are distracted, interrupted, and impatient — often using one hand on a bad network with low battery.
Design for that reality, or your app will fail quietly.
1---2name: mobile-design3description: Mobile-first design doctrine for Flutter (iOS + Android). Load BEFORE flutter-mobile to apply touch psychology, MFRI risk scoring, platform conventions, and performance doctrine before writing any UI code.4---56## Iron Law78**NO FLUTTER UI WITHOUT COMPLETING THE MOBILE CHECKPOINT FIRST — load `reference/touch-psychology.md` and `reference/mobile-performance.md` before writing any screen**910# Mobile Design Skill1112**(Mobile-First · Touch-First · Platform-Respectful)**1314> **Philosophy:** Touch-first. Battery-conscious. Platform-respectful. Offline-capable.15> **Core Law:** Mobile is NOT a small desktop.16> **Operating Rule:** Think constraints first, aesthetics second.1718This skill provides the **design thinking layer** that must be loaded BEFORE `flutter-mobile`. It exists to prevent desktop-thinking, AI-defaults, and unsafe assumptions when designing Flutter screens for iOS and Android.1920Load this skill first. Complete the Mobile Checkpoint. Then open `flutter-mobile` to implement.2122---2324## Mobile Feasibility & Risk Index (MFRI)2526Before designing or implementing any mobile feature or screen, assess feasibility.2728### MFRI Dimensions (1-5)2930| Dimension | Question |31|-----------|----------|32| **Platform Clarity** | Is the target platform (iOS / Android / both) explicitly defined? |33| **Interaction Complexity** | How complex are gestures, flows, or navigation? |34| **Performance Risk** | Does this involve lists, animations, heavy state, or media? |35| **Offline Dependence** | Does the feature break or degrade without network? |36| **Accessibility Risk** | Does this impact motor, visual, or cognitive accessibility? |3738### Score Formula3940```41MFRI = (Platform Clarity + Accessibility Readiness)42 - (Interaction Complexity + Performance Risk + Offline Dependence)43```4445**Range:** `-10 to +10`4647### Interpretation4849| MFRI | Meaning | Required Action |50|------|---------|-----------------|51| **6-10** | Safe | Proceed normally |52| **3-5** | Moderate | Add performance + UX validation |53| **0-2** | Risky | Simplify interactions or architecture |54| **< 0** | Dangerous | Redesign before implementation |5556---5758## Mandatory Thinking Before Any Work5960### STOP: Ask Before Assuming6162If any of the following are not explicitly stated, you MUST ask before proceeding:6364| Aspect | Question | Why |65|--------|----------|-----|66| Platform | iOS, Android, or both? | Affects navigation, gestures, typography |67| Framework | Flutter (this workspace is Flutter-only) | Determines performance and patterns |68| Navigation | Tabs, stack, drawer? | Core UX architecture |69| Offline | Must it work offline? | Data and sync strategy |70| Devices | Phone only or tablet too? | Layout and density rules |71| Audience | Consumer, enterprise, accessibility needs? | Touch and readability |7273**Flutter note:** This workspace uses Flutter 3.41.x exclusively. Framework is not a question — it is Flutter. If the request is for React Native, redirect to the mobile-developer skill.7475Never default to your favorite stack or pattern.7677---7879## Reference Reading Order8081Read these files in this order before designing any screen:8283| File | Purpose | When |84|------|---------|------|85| `reference/touch-psychology.md` | Fitts' Law, thumb zones, gesture psychology | Always first |86| `reference/mobile-performance.md` | Flutter const widgets, Riverpod selectors, 60fps | Before any list or animation |87| `reference/platform-ios.md` | iOS HIG, SF Pro, Dynamic Type | When building iOS-specific UI |88| `reference/platform-android.md` | Material 3, Roboto, dp system | When building Android-specific UI |89| `reference/mobile-backend.md` | Offline sync, push notifications, Firebase | When feature uses network |90| `reference/mobile-testing.md` | Device testing, E2E flows, flutter_test | Before writing tests |91| `reference/mobile-debugging.md` | Flutter DevTools, Dart Observatory, xcodebuild MCP | When debugging |9293If you have not read `touch-psychology.md`, you are not allowed to design any UI.9495---9697## Hard Bans (Flutter-Specific)9899### Performance Sins100101| Never | Why | Always |102|-------|-----|--------|103| `ListView(children: items.map(...).toList())` | Renders all items, memory explosion | `ListView.builder` or `SliverList` |104| `SingleChildScrollView` wrapping long lists | Same problem as above | `ListView.builder` |105| `setState` for complex cross-widget state | Rebuilds entire subtree | Riverpod providers |106| Heavy computation inside `build()` | Blocks UI thread, drops frames | Offload to isolates or services |107| Non-const constructors on static widgets | Forces unnecessary rebuilds | `const` on every eligible widget |108109### Touch and UX Sins110111| Never | Why | Always |112|-------|-----|--------|113| Touch targets below 48dp | Missed taps, user frustration | `SizedBox` padding to min 48dp |114| Gesture-only actions with no button | Excludes users | Provide visible button alternative |115| No loading state on async actions | Feels broken | Show CircularProgressIndicator |116| No error recovery | Dead end | Retry button + error message |117| Ignore platform conventions | Breaks muscle memory | iOS edge swipe, Android system back |118119### Design Token Sins120121| Never | Why | Always |122|-------|-----|--------|123| `Colors.blue` or `Color(0xFF...)` | Hardcoded, breaks theming | `Theme.of(context).colorScheme.*` |124| `EdgeInsets.all(16)` inline | Magic numbers, no token | `AppSpacing.*` tokens |125| `TextStyle(fontSize: 17)` inline | Bypasses type scale | `Theme.of(context).textTheme.*` |126127### Security Sins128129| Never | Why | Always |130|-------|-----|--------|131| Tokens in SharedPreferences | Easily read without root | `flutter_secure_storage` (Keychain/Keystore) |132| Hardcoded API secrets | Reverse-engineered from APK/IPA | Environment config + secure storage |133| No certificate pinning | MITM risk | Cert pinning via `http_certificate_pinning` |134| Log sensitive data | PII leakage | Never log tokens, passwords, PII |135136---137138## Platform Unification Matrix139140Some elements should be unified across platforms. Others must diverge.141142```143UNIFY DIVERGE144---------------------- -------------------------145Business logic Navigation behavior146Data models Gestures147API contracts Icons148Validation Typography149Error semantics Pickers / dialogs150```151152### Platform Defaults153154| Element | iOS | Android |155|---------|-----|---------|156| Font | SF Pro | Roboto |157| Min touch | 44pt | 48dp |158| Back | Edge swipe | System back |159| Sheets | Bottom sheet | Dialog / sheet |160| Icons | SF Symbols | Material Icons |161162In Flutter, use `CupertinoWidget` variants for iOS-specific elements and `Material` widgets for Android. For cross-platform, prefer Material with iOS adaptations via `Platform.isIOS` checks or `adaptive` constructors where available.163164---165166## Mobile Checkpoint167168Complete this before writing any widget code. If you cannot fill it in, go back and read the reference files.169170```171MOBILE CHECKPOINT172Platform: [ ] iOS [ ] Android [ ] Both173Framework: Flutter 3.41.x174Files Read: [ ] touch-psychology [ ] mobile-performance [ ] platform-specific175MFRI Score: ___ (must be >= 3)1761773 Principles I Will Apply:1781.1792.1803.181182Anti-Patterns I Will Avoid:1831.1842.185```186187MFRI score < 3: stop and redesign before opening `flutter-mobile`.188189---190191## Integration with Workspace1921931. Load this skill BEFORE `flutter-mobile`1942. Complete the Mobile Checkpoint above1953. Once checkpoint is done and MFRI >= 3, open `flutter-mobile` for implementation patterns1964. After writing code, dispatch: `riverpod-reviewer`, `flutter-security-expert`, `accessibility-auditor`197198### Related Agents199200| Agent | When |201|-------|------|202| `riverpod-reviewer` | After writing any provider or state |203| `flutter-security-expert` | After adding auth, storage, or network code |204| `accessibility-auditor` | After building any screen or interactive widget |205206---207208## Related Skills209210- `flutter-mobile` — Implementation patterns, templates, codegen211- `riverpod-patterns` — Provider types, AsyncValue, select()212- `ui-standards-tokens` — AppSpacing, colorScheme, textTheme tokens213214---215216> **Final Law:**217> Mobile users are distracted, interrupted, and impatient — often using one hand on a bad network with low battery.218> **Design for that reality, or your app will fail quietly.**
kumaran-is