App best practices

App best practices

The gap between a demo and a product is almost never the happy path. It's the forty small things every user expects and nobody writes down: what the button looks like while it's saving, what the list says when it's empty, what happens when the delete was a mistake, whether the filter survives a refresh.

This skill is that written-down list.

Two modes

BUILD — you're implementing something. Before writing code, open the reference file(s) for what you're building and treat the checklist as part of the requirements. Implement what applies; skip what genuinely doesn't and say which and why in your summary. Do not ask permission to add expected behavior (a delete confirm, a disabled state, an empty state) — it's table stakes, just build it.

AUDIT — you're reviewing existing code or a screen. Follow Audit workflow below.

Pick the mode from the request. If someone says "build the members table," that's BUILD. "What's missing on the members table?" is AUDIT. "Finish this" is both: audit, then fix.

Router

Load only the files you need. Most tasks need one or two. Never load more than four — if a task seems to need more than that, it's several tasks.

Interaction

Building / reviewing	Read
Create, edit, delete, duplicate, archive, bulk actions	references/crud.md
Anything destructive or irreversible	references/destructive-actions.md
Undo/redo stack, edit history, Cmd+Z in an editor or canvas	references/undo-redo.md
Loading, saving, hover/cursor, toasts, optimistic updates, progress	references/feedback.md
Empty, error, offline, partial, loading-forever states	references/states.md
Forms, validation, autosave, unsaved changes, multi-step	references/forms.md
Lists, tables, search, filter, sort, pagination, selection	references/lists-and-tables.md
A settings / preferences / account screen	references/settings.md
Import, export, upload, download, backup, CSV/JSON	references/import-export.md
LLM features: chat UI, streaming, parsing, attachments, cost, failure	references/ai-features.md
Sign-in, sessions, roles, permissions, sharing, invites	references/auth-and-permissions.md
URL/deep links, back button, tabs, modals, refresh persistence	references/navigation-and-state.md
Keyboard, focus, screen readers, contrast, motion, touch targets	references/accessibility.md

Structure & appearance

Building / reviewing	Read
Headers, nav, sidebars, breadcrumbs, footers, the page shell	references/page-anatomy.md
Spacing, type, color, elevation, radius, density, dark mode	references/visual-design.md
Routes, redirects, guards, slugs, 404/410, tenant & locale paths	references/routing.md
Wording: labels, errors, empty states, tone, terminology	references/content-and-microcopy.md

Engineering quality

Building / reviewing	Read
Timeouts, retries, races, concurrency, stale data, rate limits	references/resilience.md
Core Web Vitals, bundle size, images, fonts, perceived speed	references/performance.md
Authz/IDOR, XSS, CSRF, SSRF, headers, secrets, upload safety	references/security.md

Business & obligation

Building / reviewing	Read
Checkout, plans, trials, proration, dunning, refunds, invoices	references/payments-and-billing.md
Transactional email, push, digests, deliverability, notif center	references/notifications-and-email.md
Consent banners, privacy rights, retention, ToS, AI disclosure	references/legal-and-compliance.md
Translation, RTL, timezones, locale formatting, name/address	references/internationalization.md

Cross-cutting rules that apply to everything: references/universal.md. Skim it once per task regardless of which other file you open.

Some files separate a Baseline set (table stakes — a competent app has all of it) from an Advanced set (hardening and maturity). In BUILD mode, treat baseline as required and advanced as a judgement call you surface to the user rather than silently skip.

Audit workflow

1. Scope it. Identify the screens/flows in question and the entry points in code. Don't audit the whole app when asked about one page.
2. Enumerate the surfaces. For each screen list: every action a user can take, every piece of data displayed, every state it can be in.
3. Run the relevant checklists against each surface. Verify in the code — grep for the handler, read the component. A missing disabled attribute is a finding; a suspected missing one is not.
4. Rank by severity:
   • P0 — Data loss, breach, or lockout. Destructive action with no confirm or undo, lost form input, unsaved-changes navigation, silent write failure, missing server-side authorization, exposed secret, cross-tenant leak.
   • P1 — User gets stuck or misled. No error state, infinite spinner, no empty state on a first-run screen, action with zero feedback, double-submit creating duplicates.
   • P2 — Feels unfinished. Missing hover/cursor affordance, no loading skeleton, filters not in URL, no keyboard support, unlabeled icon button.
   • P3 — Polish. Motion, copy tone, density, micro-interaction.
5. Report as a table: Location | Severity | What's missing | Fix. Lead with P0/P1. Cap at ~15 findings unless asked for exhaustive; more than that means summarize by theme instead.
6. Offer to fix, grouped by severity — don't fix during the audit unless the request was "finish this."

Working rules

• Match the codebase. These checklists say what must exist, never how. Use the app's existing toast system, modal, button variants, query layer. If a pattern already exists for one screen, copy it — consistency beats the checklist.
• Don't invent infrastructure. If there's no toast system and the app needs one, say so and propose it; don't quietly add a dependency.
• Never bulk-apply. Ten checklist items landing at once in unrelated files is a bad diff. Do the feature you were asked about.
• Copy matters. Every state you add needs real words, not TODO or "Something went wrong." See references/universal.md for the copy rules.