A field glossary

Wait until the action pauses, then run it. A search box fetches 300ms after the last keystroke, not on every letter.

Debounce the search input by 300ms. Cancel the in-flight request when a new one starts.

If you cannot name it · You write “don’t spin while I type,” spend five rounds, and still get a request per keystroke.

Change the UI first, wait for the server later. The like turns red immediately; it snaps back if the request fails.

Make favorites optimistic: flip the state on click, roll back and offer retry on failure. Don’t wait for the response to paint.

If you cannot name it · Every button spins for half a second. The page feels like it is apologising.

Grey blocks hold the layout while data loads, so the page does not jump.

Use a skeleton that matches the card layout on first load. No centred spinner.

If you cannot name it · You get a spinner on a blank page, then the layout pops in.

A modal blocks the page until you deal with it. A drawer slides in from the edge and leaves the page behind it.

Edit in a right-hand drawer, not a full-screen modal. Escape and the overlay close it. Trap focus inside.

If you cannot name it · Every confirm, edit, and filter becomes a centred popup that is hard to dismiss on a phone.

The screen when there is nothing yet: why it is empty, and what to press next.

Empty projects: the line “No projects yet,” one button “New project.” Do not render an empty table.

If you cannot name it · The user opens the app, sees a blank sheet, and thinks it is broken.

Pagination has pages you can jump to and share. Infinite scroll is for browsing, not for finding the thing you just saw.

Use pagination, 20 rows per page, in the admin table. Use infinite scroll on the feed, with a back-to-top control.

If you cannot name it · The admin table becomes a TikTok-style feed, and row 87 is gone.

Default, hover, focus, pressed, disabled, loading, error, success. Skip one, and production is missing a piece.

Every button needs default, hover, focus-visible, active, disabled, loading, error, and success. Do not animate the focus ring.

If you cannot name it · You get default and hover. Keyboard users see no focus, and submit can be clicked three times.

Check after blur, not on every letter. An error names what broke and how to fix it.

Validate the email on blur. Error copy: “This is not an email; it needs an @.” Do not turn the box red and stop there.

If you cannot name it · The field goes red mid-word and interrupts the person still typing.

Doing the request twice has the same result as doing it once. Payments and order creation need this.

Create-order carries an idempotency key. Double-submit makes one order. Disable the button while in flight.

If you cannot name it · The network hiccups, the user clicks twice, and the database holds two identical orders.

A later request returns first, and the screen shows a stale result. Search hits this constantly.

Search requests must be cancellable. Only the response for the latest query may render.

If you cannot name it · You search “cat”, then “cat food”, and the page flashes food then jumps back to cat.

Create, read, update, delete. Most “little tools” are these four verbs on one table.

This is CRUD for tasks: list, detail, create, edit, delete. Delete must be undoable.

If you cannot name it · You say “add stuff, change it, take it away,” and the model invents five unrelated tables.

Which objects exist, what the fields are called, how they join. Draw this before the screens.

Objects: user, workspace, project, task. Tasks belong to projects, projects to workspaces. A task has title, status, owner, due date.

If you cannot name it · Each feature adds a table, and the same field is spelled three ways.

How the system recognises you, and for how long. Sign-up, sign-in, sign-out, and reset are one set, not four extras.

Email-and-password auth, 30-day session, sign-out clears the cookie. Unauthenticated /app redirects to /login and returns to the original URL.

If you cannot name it · You get a sign-up page and no sign-in, or a session that dies on refresh.

Not “are you signed in,” but “is this row yours.” Hiding a button is not enough; the API must refuse.

A user may only read and write projects in their workspace. Changing the id in the URL must not leak another row. Enforce it in the database.

If you cannot name it · The list hides other people’s rows; editing the number in the URL shows them. That is a real incident.

Another system knocks when something happens: payment succeeded, email opened, repository pushed.

Mark the order paid from the Stripe webhook, not from the browser return. Verify the signature.

If you cannot name it · The user pays, closes the tab, and the order stays unpaid.

Keep a computed result nearby. Fast, and stale. Say who invalidates it, and when.

Cache the public article for 60 seconds. Publishing must purge that page immediately.

If you cannot name it · You change the title, the public page stays old, and you think save failed.

After the first visit, how you get someone to take one useful action instead of wandering off.

After sign-up, three steps: create a workspace, invite one person, create one task. Skippable, with a back control.

If you cannot name it · You get five slides titled “welcome to our universe,” and no button that does work.

How far free goes, and which step requires money. Write it down; do not intercept halfway by accident.

Free accounts get three projects. The fourth opens a paywall that names what paid unlocks. Closing it leaves you on the same page.

If you cannot name it · It is either forever free or a credit card on the doorstep. No middle.

The code is shipped, but only some people see it. If it breaks, you can shut the door without rolling back the site.

The new editor sits behind a flag, off by default, on for internal accounts. A bug turns the flag off; it does not roll back the site.

If you cannot name it · The new feature hits everyone at once, and a fix is a twenty-minute redeploy.

Is the page assembled on the server, at build time, or in the browser? This changes first paint, search, and logged-in data.

Marketing pages are SSG. Articles are SSR for search. The signed-in /app is client-rendered.

If you cannot name it · The whole site becomes a single-page app, and search engines see “please enable JavaScript.”

The smallest version that tests one hypothesis — not a complete product with fewer buttons.

Version one: sign up, one project, add tasks, mark done. No notifications, no board, no points.

If you cannot name it · You say “keep it simple,” and the model still builds settings, team roles, and dark mode.

The brief you give the model. A good prompt is a ticket: object, constraints, acceptance — not a mood.

Do not write “make it nicer.” Write “primary button contrast ≥ 4.5:1, no purple gradient, no horizontal scroll at 320.”

If you cannot name it · The model guesses your taste, guesses wrong, and you still cannot say what failed.

What the model can see right now: files, errors, the thread. Not memory — papers on the table.

Open the three relevant files and paste the full error. Do not pour the whole repository into the thread.

If you cannot name it · Irrelevant files crowd the window. The model edits the wrong one, confidently.

The model speaks a missing function, library, or config as if it were real. The calmer the tone, the more you should run it.

Do not invent APIs. Read the functions already in this repo before calling them. If unsure, say so.

If you cannot name it · You install a package that is not on npm, then blame the network.

The model does not only talk — it runs commands, edits files, clicks a browser. Each step can drift.

Plan first, then edit. After edits, run the type checker. Do not touch twelve files in one pass.

If you cannot name it · The agent helpfully refactors half the project, and you cannot get back to the version that ran.

The contrast of the change. Reading a diff is cheaper than reading the file, and it is where you act as editor.

This change is the sign-in page only. The PR must not reformat the repository.

If you cannot name it · You thought it was one line of copy. A thousand lines of whitespace moved.

A machine reads the code first. The red text is not an insult; it is cheap acceptance.

After edits, run lint and typecheck. Fix from the errors. Do not disable checks to “make it pass.”

If you cannot name it · White screen, one red line in the console. You paste the whole error back. That error was the spec.