My App Looks Broken When There's No Data, What Should New Users See?

Your app does not look broken. It looks empty, and to a first-time user those are the same thing. The fix is an empty state: a small, friendly panel that appears wherever a list, table, or dashboard has no data yet, telling the user what belongs there and what to do next. Add one to every screen that starts out with nothing, and the "is this thing working?" moment goes away.

Why this happens

You never saw the empty version. By the time you were testing, you had already created a project, added a task, uploaded a file. Your account is full, so every screen looks alive. A real new user arrives with a blank account, and the exact same screen renders a bare page: no rows, no chart, sometimes just a lonely heading floating above nothing.

An AI agent building "show the user their projects" writes the code that loops over the projects and draws them. If there are zero projects, the loop draws zero things, and you get a blank area. The agent built what you asked for. You did not ask "and what should it say when the list is empty," so nobody wrote that part. It is not a bug. It is a missing screen.

How to check

You need to see your app the way a stranger will, with an account that has nothing in it.

1. Make a fresh account. Sign up with a new email you have never used in the app. Do not reuse your own full account.
2. Visit every main screen without adding any data: dashboard, lists, tables, search results, profile, activity feed, settings.
3. Write down every screen that looks blank, half-drawn, or confusing. A heading with nothing under it, a table with only column names, a chart area that is just empty space. Each one is a missing empty state.

Do the same for the "in-between" cases: a search that finds nothing, a filter that matches nothing, a folder with no items. Those are empty states too, and they are the ones founders forget.

The fix

For each blank screen you found, add a small block that shows only when the data is empty:

1. Detect empty. Wherever you render a list, add a branch: if the count is zero, show the empty state instead of the (empty) list. In most frameworks this is one if items.length === 0 check.
2. Say three things. A short line naming what goes here ("No projects yet"), one sentence of context ("Projects keep your work organised"), and a single clear action, usually the same button that creates the first item.
3. Point at the action. The primary button in an empty state should be the one thing you want a new user to do next. Make it obvious and make it the only button.
4. Cover the three states, not one. Every data area really has three looks: loading, empty, and full. Handle loading so it does not flash blank first (see why your app flashes blank before it loads), then empty, then the real content.
5. Re-test with the fresh account. Walk the same screens again. Every one should now either show data or tell the user, in plain words, that there is none yet and what to do.

The trap to avoid

Do not fill the emptiness with fake sample data to make it "look better." A dashboard that shows invented numbers, or a task list pre-loaded with "Buy milk," teaches new users to distrust everything they see, and it is a nightmare to tell real data from decoration later. If you already have placeholder rows lurking, clear them out (see leftover fake demo data in my app). An honest "nothing here yet, add your first one" always beats a convincing lie.

Where this fits

Empty states are one of the clearest signals of whether an app was actually finished or just demoed once with a full account. They are cheap to add and they change a new user's first ten seconds from "this is broken" to "ah, I see what to do." The free Readiness Report walks your app as a brand-new, empty-account user and flags the screens that render blank, so you find them before your beta testers do. If you would rather have the empty states written and wired in for you, that is what the Finishing Pass covers.