Web app interface playbook

An interface playbook for interactive web apps, such as dashboards, customer portals, SaaS products and admin tools. It works for any framework, from React, Vue, Svelte and Angular to plain web components and server-rendered pages with htmx. Each rule says what to build, how, and how to prove it in a test.

Apps fail in ways content sites never do. A list loads forever, a form loses an hour of typing, or a button saves twice. A hidden menu still lets the wrong person delete a record. AI app builders produce the happy path well and skip these cases. This playbook covers the cases they skip.

Start with Data views. Every screen that shows data needs its loading, empty and error states, and most apps miss at least one. Then read Forms and Client and server state.

The website playbook covers what every page needs, such as HTML, speed and accessibility. This playbook links to it instead of repeating it. The API design playbook covers the server side of each screen, and the testing playbook covers tests in general.

Chapters

1. Styles and components

   Keep every colour, size and control in one place. Design tokens hold the values, a component library holds the controls, and a catalogue shows every state.

   • Required 2
   • Recommended 3

2. Data views

   Every panel, list and chart that shows data has a loading, empty, error, partial and success state. Design each one, test each one, and never show a blank box.

   • Required 3
   • Recommended 3

3. Dates and numbers

   Show times in the user's own time zone, keep calendar dates as dates, and read numbers the way people type them. Most off-by-one-day bugs start here.

   • Required 2
   • Recommended 1
   • Optional 1

4. Forms

   Check input at the right moment and put server errors on the right field. Never lose what people typed, and save each form only once.

   • Required 4
   • Recommended 3

5. Client and server state

   Keep server data in one cache, keep screen state in the address, and keep the rest local. Update the screen at once only when you can undo it.

   • Required 5
   • Recommended 2

6. Lists and tables

   Long lists stay fast with paging or virtual scrolling. Sort and filter on the server, key rows by ID, and make tables work by keyboard and screen reader.

   • Required 4
   • Recommended 3

7. Feedback and dialogs

   Confirm finished work in a status message and keep errors where they need fixing. Place focus with care, and let people undo what they delete.

   • Required 4
   • Recommended 2

8. Permissions, flags and failures

   The server decides who may do what, and the screen follows. Contain each crash, time out slow requests, and survive expired sessions and lost networks.

   • Required 4
   • Recommended 4

9. Tests and budgets

   Test every component in every state, catch visual changes with screenshots, and give each route a size budget the build enforces.

   • Required 2
   • Recommended 2

All 54 rules on one page