Empty, loading and error states that help

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# Empty, loading and error states that help

New users of the production site see the app at its emptiest: no data yet, slow first loads, the odd failed request. Blank screens and spinners that never end make a product feel broken on the day it most needs to impress. Give every screen an empty, loading and error state that says what is happening and what to do.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Redesign screens beyond their states.
- Hide errors without logging them.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Find the gaps

List every screen and component that shows data: lists, tables, dashboards, search results, feeds. For each, note what it shows when there is no data, while it loads, and when the request fails. Flag blank screens, endless spinners and raw error messages.

### 2. Empty states

Each empty state says what will appear here and offers the action that fills it ("No invoices yet. Create your first invoice"), or explains why it is empty for filters and searches with a way to reset them. Reuse one empty-state component.

### 3. Loading states

Use skeletons shaped like the content for loads that take a moment, keep the layout the same size so nothing jumps when data arrives, and show a progress message for long operations. Avoid full-page spinners for partial updates.

### 4. Error states

Failed requests show a short human message and a retry button, keep what the user typed, and log the error. Never show a stack trace or a raw API error to a user.

## Done means

- [ ] Every data screen has an empty, loading and error state.
- [ ] Empty states explain and offer the action that fills them.
- [ ] Loading states keep the layout stable.
- [ ] Errors show a human message with retry, keep user input, and are logged.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.