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.

1. Enumerate the surfaces. For each screen list: every action a user can

take, every piece of data displayed, every state it can be in.

1. 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.

1. 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.

1. 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.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kopon1
• Source: kopon1/app-best-practices
• License: MIT

Install and usage instructions live in the source repository linked above.