Skip to content

My App Looks Fine on My Laptop but Breaks on a Phone, How Do I Find and Fix It?

6 min read

Your app looks perfect on your laptop and falls apart on a phone. The direct answer: your layout was built and eyeballed at desktop width, so it never had to survive a 375-pixel-wide screen, and most of your beta users will open it on exactly that. The fix is to test at real phone sizes and correct the handful of layout rules that don't scale down. You can find most of the breaks in about ten minutes.

Why this happens

When you asked your agent to "build the dashboard" or "make a landing page," it built what looked right in the preview window, which is desktop-sized. Nobody asked it to make the layout reflow for a narrow screen, so it often reaches for fixed widths, big fixed paddings, side-by-side columns that never stack, and font sizes tuned for a wide viewport. All of that looks fine at 1440 pixels and overflows, overlaps, or gets comically small at 375.

The agent built what you asked for and not the thing you didn't think to ask for. Mobile is the thing you didn't ask for. It is not a bug in the usual sense, it is a whole screen size the layout was never checked against.

How to check

You do not need a phone to find the breaks. Your browser has phone mode built in.

  1. Open your app in Chrome (or Edge), press F12 to open DevTools, then click the little phone/tablet icon near the top left (or press Ctrl+Shift+M / Cmd+Shift+M).
  2. In the device dropdown at the top, pick iPhone SE (375 wide). This is the small, common size that exposes the most problems. Then check iPhone 14 Pro and one Android size too.
  3. Walk every page and every state: the landing page, the signed-in view, forms, modals, long lists, the menu. Look for four things:
    • Horizontal scroll. If you can swipe sideways, something is wider than the screen. That is the number one giveaway.
    • Overlap. Text sitting on top of a button, a menu covering content.
    • Cut-off content. Text or buttons running off the right edge.
    • Tap targets too small. Buttons or links too tiny or too close to tap.
  4. Also test on your actual phone once. Open the deployed link and try to complete the main task with your thumbs. Emulators miss real-thumb problems.

The fix

You do not need to rebuild anything. Most of these are small, targeted changes.

  1. Kill horizontal overflow first. Find the too-wide element (in DevTools, the offending block highlights when you hover the DOM). The usual culprits are a fixed width in pixels, a large fixed padding, or an image without max-width: 100%. Replace fixed widths with max-width: 100% or width: 100%.
  2. Make columns stack. Side-by-side layouts should become a single column on narrow screens. If you are on Tailwind (most agent apps are), that means default to stacked and only go side-by-side at a breakpoint: for example flex-col md:flex-row or grid-cols-1 md:grid-cols-3. The plain-CSS version is a @media (min-width: 768px) block that turns on the multi-column layout.
  3. Let text and spacing shrink. Oversized headings and fixed paddings crowd a phone. Use responsive sizes (text-2xl md:text-4xl) and smaller padding at the base size.
  4. Fix tap targets. Make buttons and links at least about 44px tall and give them breathing room so thumbs don't miss.
  5. Ask your agent precisely. Give it the exact broken element and size: "On the pricing page at 375px wide, the three cards overflow the screen. Make them stack into one column below 768px and stop the horizontal scroll." Precise beats "make it mobile friendly," which sends it guessing.
  6. Re-check in device mode at 375, then confirm on a real phone.

The trap to avoid

Do not "fix" mobile by zooming the whole page out with a viewport meta tag hack like initial-scale=0.5, and do not just shrink everything until it fits. That makes text unreadable and hides the real problem instead of solving it. The goal is a layout that reflows for a narrow screen, not one that is squeezed to fit it.

Where this fits

Most of your first real users will tap your link on a phone, so a layout that only works on your laptop is a layout most people never see working. This is one of the checks in the free Readiness Report: it walks your app at real phone sizes and flags the pages that overflow or overlap, so you see what your users will see. If you would rather have the breaks fixed in priority order, that is the Finishing Pass. While you are testing narrow screens, it is worth also checking what your app shows with no data and hunting down any buttons and links that go nowhere, since both hide in the same demo that looked fine.