/mobile-layout-best-practices

Mobile Layout Best Practices

Purpose

Use this skill when designing, building, or reviewing mobile app layouts to ensure the UI works well across:

• iPhone
• iPad
• Android phones
• Android tablets
• Small screens
• Large screens
• Landscape and portrait orientations
• Devices with notches, rounded corners, gesture areas, and dynamic text settings

The main goal is to prevent:

• Text being cut off
• Content overflowing the screen
• Buttons becoming inaccessible
• Inputs being hidden by the keyboard
• Layouts breaking on tablets or landscape mode
• UI elements being too close to screen edges
• Hardcoded sizes causing problems on different devices

When to Use This Skill

Use this skill whenever you are:

• Creating a new screen
• Refactoring a mobile layout
• Reviewing UI code
• Building responsive components
• Fixing overflow, clipping, or cut-off text
• Supporting tablets or iPads
• Handling dynamic font sizes
• Designing forms, lists, cards, modals, or navigation layouts
• Implementing layouts in React Native, SwiftUI, Jetpack Compose, Flutter, or native mobile frameworks

Core Layout Principles

1. Avoid Hardcoded Fixed Heights

Do not rely on fixed heights for containers that include text or dynamic content.

Avoid

height: 48;

Especially for:

• Buttons with text
• Cards
• List rows
• Forms
• Modals
• Headers
• Error messages
• Multiline labels

Prefer

Use flexible sizing:

minHeight: 48;
paddingVertical: 12;
paddingHorizontal: 16;

Text should be allowed to wrap or scale appropriately.

2. Use Safe Areas

Always account for safe areas on devices with:

• Notches
• Dynamic Island
• Rounded corners
• Home indicator
• Gesture navigation
• Status bars
• Navigation bars

iOS

Use safe area-aware containers.

Examples:

• React Native: SafeAreaView or react-native-safe-area-context
• SwiftUI: respect safe areas unless intentionally using .ignoresSafeArea()
• UIKit: use safeAreaLayoutGuide

Android

Account for:

• Status bar
• Navigation bar
• Gesture insets
• Display cutouts

Avoid placing primary actions flush against the bottom edge.

3. Prefer Flexible Layouts Over Absolute Positioning

Absolute positioning should be used sparingly.

Avoid

position: "absolute";
bottom: 0;

Unless paired with safe area insets and tested across devices.

Prefer

Use normal layout flow:

• Flexbox
• Constraint-based layout
• Adaptive stacks
• Scrollable containers
• Safe-area-aware footers

4. Make Screens Scrollable When Content Can Grow

If a screen contains dynamic content, forms, long text, error messages, or translated strings, it should usually be scrollable.

Common scrollable screens

• Forms
• Settings pages
• Profile pages
• Checkout screens
• Onboarding steps
• Detail pages
• Legal or support screens

Rule

If the content might exceed the available height, wrap it in a scroll view.

But avoid nesting multiple vertical scroll views unless necessary.

5. Design for Dynamic Text and Accessibility Font Sizes

Users can increase system font sizes. Layouts must not break when text is larger.

Requirements

• Text should wrap when appropriate.
• Buttons should grow vertically if needed.
• Labels should not be clipped.
• Cards should expand with content.
• Avoid fixed text containers.
• Test with large accessibility text sizes.

Avoid

numberOfLines={1}

Unless truncation is intentional and acceptable.

Prefer

Allow important text to wrap:

<Text numberOfLines={2}>
  Account verification required
</Text>

Or omit numberOfLines for critical text.

6. Never Let Critical Actions Be Cut Off

Primary buttons and form actions should remain reachable.

For bottom actions:

• Respect safe area insets.
• Add bottom padding.
• Handle keyboard appearance.
• Test on small devices.
• Test in landscape mode.

Recommended bottom spacing

Use at least:

• 16px horizontal screen padding
• 16px bottom padding
• Additional safe area inset at the bottom

Example concept:

paddingBottom: Math.max(insets.bottom, 16);

7. Use Responsive Widths

Avoid assuming every device is phone-sized.

On phones

Content usually spans full width with side padding.

Recommended horizontal padding:

paddingHorizontal: 16;

or:

paddingHorizontal: 20;

On tablets and iPads

Do not stretch all content edge-to-edge.

Use a max content width.

Recommended max widths:

• Forms: 480px to 600px
• Reading content: 600px to 720px
• Dashboards: adaptive multi-column layout
• Modals: 480px to 640px

Example:

width: "100%";
maxWidth: 600;
alignSelf: "center";

AI Assistant Instructions

When this skill is active, the assistant should:

• Prioritize mobile layout safety and responsiveness.
• Look for fixed heights, clipped text, and overflow risks.
• Recommend safe-area-aware layouts.
• Recommend scrollable containers for dynamic content.
• Use max-width containers for tablets and iPads.
• Account for Android and iOS differences.
• Consider keyboard behavior on form screens.
• Warn when text truncation could hide important content.
• Suggest test cases for small screens, large screens, tablets, and accessibility text sizes.
• Prefer flexible layouts over hardcoded dimensions.

Output Format for Layout Reviews

When reviewing a layout, respond using this structure:

Mobile Layout Review

1. Main Risks
- ...

2. Recommended Changes
- ...

3. Platform Notes
- iOS:
- iPad:
- Android phone:
- Android tablet:

4. Text and Overflow Safety
- ...

5. Keyboard and Safe Area Handling
- ...

6. Testing Checklist
- ...

Additional Resources

For platform-specific guidance, layout patterns, review checklists, and testing matrix, see reference.md.