Why Does My App Look Broken on My Phone? Responsive Design Basics

You built your app on a laptop, and it looks great. Then you open it on your phone: text is tiny, a table runs off the right edge, buttons overlap, and the whole page wobbles sideways when you scroll.

More than half of web traffic comes from phones, so this isn't a small problem. The fix is responsive design — making a layout adapt to whatever screen it's on. The good news: the causes of broken mobile layouts are few and very fixable.

What responsive design means

A responsive page rearranges itself for the screen size. On a wide screen, three cards sit side by side. On a phone, they stack on top of each other. Navigation that's a row of links on a laptop becomes a menu button on a phone.

This is done with CSS rules that apply at certain screen widths — called breakpoints. With Tailwind CSS (which most AI tools use), it looks like this:

<div class="grid grid-cols-1 md:grid-cols-3 gap-4">

"One column by default; three columns on medium screens and up." Tailwind is mobile-first: the plain classes are for phones, and prefixes like md: and lg: add changes for bigger screens.

The five most common causes

1. The page scrolls sideways

The most common mobile bug. Something is wider than the screen — an image, a table, a long word or URL, or an element with a fixed width like width: 800px. Because one thing is too wide, the whole page becomes scrollable sideways.

Fix: find the element (see testing below) and make it flexible: max-width: 100% on images, a horizontally scrollable wrapper for wide tables, break-words for long text, and percentages or w-full instead of fixed pixel widths.

2. Everything is tiny

The page looks like a shrunken desktop site. Usually the viewport meta tag is missing from the page's <head>:

<meta name="viewport" content="width=device-width, initial-scale=1" />

Most frameworks include it automatically, but it's worth checking. Without it, phones pretend to be a wide desktop screen and zoom out.

3. Things are side by side that shouldn't be

A row of cards, a two-column form, or a sidebar next to content that looks fine on a laptop and is squashed on a phone. Fix: stack them on small screens and only place them side by side from a breakpoint up (flex-col md:flex-row, grid-cols-1 md:grid-cols-2).

4. Buttons are too small or too close

Fingers are less precise than mouse pointers. Tiny links packed together cause mis-taps. Aim for tap targets around 44 pixels tall, with space between them.

5. Things hidden behind the keyboard or the browser bar

A "Save" button at the bottom of a form disappears behind the phone's keyboard. A full-height section (100vh) gets cut off by the browser's address bar. Fix: don't rely on fixed bottom elements for forms, and use newer viewport units like dvh (dynamic viewport height), which account for the browser's bars.

How to test properly

Your browser can pretend to be a phone. Open developer tools (right-click → Inspect), then click the device toolbar icon (it looks like a phone and tablet, or press Ctrl+Shift+M / Cmd+Shift+M). Pick a phone size, or drag the width. Check your pages at around 375px wide (a typical phone) and in between sizes, not just the presets.

Find what's too wide: in the console, this snippet outlines every element so the one poking out is easy to spot:

document.querySelectorAll('*').forEach(el => el.style.outline = '1px solid red')

Then test on a real phone. Emulators are good, not perfect. Real devices reveal keyboard behaviour, real tap sizes, and slow connections. Send yourself a preview link. (A localhost link won't work on your phone — here's why.)

Check both orientations, and at least one iPhone and one Android if you can.

Asking your AI tool to fix it

Be specific about what's wrong and where:

On phones (375px wide), the /pricing page scrolls sideways and the three plan cards are squashed side by side. Make the cards stack vertically below the md breakpoint, make sure nothing is wider than the screen, and keep the desktop layout exactly as it is.

A screenshot from your phone helps a lot — most AI tools accept images.

And to prevent the problem in the first place, add it to your project's instructions: "Every page must work at 375px wide with no horizontal scrolling. Build mobile-first." (How to Write a CLAUDE.md.)

A quick mobile checklist

Viewport meta tag present
No sideways scrolling at 375px
Text readable without zooming (16px or larger for body text)
Columns stack on small screens
Buttons and links easy to tap, with space between
Images scale down (max-width: 100%)
Wide tables scroll inside their own box
Forms usable with the keyboard open
Tested on a real phone

EasySpawn gives your app a real URL per branch, so you can open changes on your actual phone before they go live — and Claude Code can fix what you find. See how it works or join the waitlist.