mobile-design

Mobile Design System

(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 exists to prevent desktop-thinking, AI-defaults, and unsafe assumptions when designing or building mobile applications.

1. Scope and risk

Use the existing project/platform requirements and preserve its conventions. Ask only for missing information that changes the implementation. Do not require an interview or framework switch for a targeted fix. The former MFRI score was an unvalidated heuristic with inconsistent dimensions/range; it is not a safety or release gate. Record concrete interaction, data, accessibility and performance risks instead.

2. Choose the relevant checks

For a new app, establish platform, framework, audience, device classes, navigation, offline needs and actual output. For existing work, reuse that context. Read only the reference material needed for the changed behavior. User scope and repository instructions take precedence over this skill's suggested ceremony.

3. Mandatory Reference Reading (Enforced)

Reference map (read what the task needs)

Platform-Specific (Conditional)

Read the relevant platform guidance before changing platform-specific behavior.

4. AI Mobile Anti-Patterns (Hard Bans)

🚫 Performance Sins (Non-Negotiable)

🚫 Touch & UX Sins

🚫 Security Sins

5. Platform Unification vs Divergence Matrix

UNIFY                          DIVERGE
──────────────────────────     ─────────────────────────
Business logic                Navigation behavior
Data models                    Gestures
API contracts                  Icons
Validation                     Typography
Error semantics                Pickers / dialogs

Platform Defaults

6. Mobile UX Psychology (Non-Optional)

Fitts’ Law (Touch Reality)

• Finger ≠ cursor
• Accuracy is low
• Reach matters more than precision

Rules:

• Primary CTAs live in thumb zone
• Destructive actions pushed away
• No hover assumptions

7. Performance Doctrine

React Native (fixed-height illustrative pattern)

const Row = React.memo(({ item }) => (
  <View><Text>{item.title}</Text></View>
));

const renderItem = useCallback(
  ({ item }) => <Row item={item} />,
  []
);

<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={(i) => i.id}
  getItemLayout={(_, i) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * i,
    index: i,
  })}
/>

Flutter (illustrative static widget)

class Item extends StatelessWidget {
  const Item({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text('Static');
  }
}

• const everywhere possible
• Targeted rebuilds only

8. Implementation evidence

State the target platform, changed behavior and checks actually performed. Profile representative devices/data; a static pattern scan cannot measure touch targets, contrast, frame rate, battery, platform navigation or secure storage behavior.

9. Framework choice

Preserve an existing stack unless a change is requested. For new work compare team experience, native integrations, accessibility, deployment policies and measured workload constraints. Expo OTA is bounded by runtime compatibility and store policies; it does not authorize bypassing review or delivering arbitrary native code. No framework is universally fastest or smallest.

10. Release Readiness Checklist

Before Shipping

• Platform hit targets checked in logical units
• Offline handled
• Secure storage used
• Lists optimized
• Logs stripped
• Tested on low-end devices
• Accessibility labels present
• Concrete risks and any unavailable checks documented

11. Related Skills

• frontend-design – Visual systems & components
• frontend-dev-guidelines – RN/TS architecture
• backend-dev-guidelines – Mobile-safe APIs
• error-tracking – Crash & performance telemetry

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.

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Audit helper and limits

Run python scripts/mobile_audit.py . --json from the intended project directory. The helper is read-only, bounded and advisory. It never imports project code and never declares compliance; compliant is null. Exit 2 means incomplete inspection or no detected mobile source. Source-pattern hints can match comments or miss behavior spread across files. Validate findings before editing. No simulator, real-device, screen-reader or GPU run was performed in this catalog review.

Use touch guidance, typography, color, navigation and decisions for focused checks. Code blocks are version-sensitive fragments, not certified complete apps; verify current APIs before execution.