How to document app screens before a legacy redesign

To document app screens before a redesign, build an inventory of every screen and state from both the code and the running app, capture each state as a screenshot with demo data, link the states by the user action that leads from one to the next, and note for each one its route, roles, source file and the rules it enforces. That “as is” record tells the redesign what it must keep, and it finds the states nobody remembers before your users do.

Why write down the app you are about to replace

A legacy app knows things its team has forgotten. A screen behaves differently for an admin, a form rejects a date format for a reason nobody recalls, an export button exists because one large customer asked for it years ago. A redesign that starts from memory drops these quietly, and the gaps come back as support tickets after launch.

A written record gives you:

• a real scope: how many screens and states the redesign covers;
• a checklist for the new version, where every old state is kept, changed or removed on purpose;
• a baseline to compare against, screen by screen;
• a map for the people and the coding agents who will write the new code.

Build the inventory from four sources

No single source lists every screen. Cross the four below: each one catches what the others miss.

Source	What it finds	What it misses
Router or URL configuration	Every declared route, including forgotten ones	Modals, tabs, states behind a condition
Navigation menus and links	What users can actually reach	Deep links from emails, admin-only paths
Server logs or analytics	Which routes people use, and how often	Screens nobody visits, which may still matter
Code conditions and permission checks	States per role, empty and error branches	What the screen looks like

Routes declared in the router but never linked are candidates for removal, or a hidden feature someone relies on: ask before you drop them. Routes that appear in the logs but in no menu usually come from emails, bookmarks or integrations. Keep them working in the new version, or redirect them.

List every state of every screen

A screen is not one picture. An invoice list looks different when it is empty, when a filter matches nothing, when it holds 3000 rows, when the API fails, and when a user without the right permission opens it. For each screen, go through the usual states and write down which ones exist:

• empty on first use, and empty after a filter;
• loading, partial and full;
• validation errors and server errors;
• permission denied, read-only, and each role that sees a different version;
• modals, drawers, tabs and confirmation steps.

The UI states checklist covers these one by one. In a legacy app, the code is often the only place where a state is written down: in the file of each screen, search for the conditions that change what renders, such as if (!items.length), catch blocks and role checks.

Capture each state from the running app

Screenshots of the running app are the honest record. They show what users see today, bugs included, while a redrawn screen tends to fix things without anyone noticing.

1. Run the app on a database seeded with demo data, never on a copy of production.
2. Create one demo account per role.
3. Script the visits with Playwright: one entry per state, with the steps that reach it (open the modal, submit the empty form).
4. Fix the window size, the clock and the locale, so that the next capture matches this one.

Screenshot every page with Playwright has a full script, including sign-in with a saved session. If the app no longer runs locally, which happens with old stacks, capture a staging deployment seeded with demo data, or document those screens from the code and mark them “not captured”.

Record what the picture does not show

A screenshot shows the layout, not the rules. For each state, write down the facts a redesign could break without noticing:

- screen: Invoices
  state: overdue filter
  route: /invoices?status=overdue
  roles: [admin, accountant]
  source: src/pages/invoices/List.tsx
  reached_by: "Click the Overdue chip"
  data: "At least one invoice past its due date"
  rules:
    - "Overdue means due before today, in the account's time zone"
    - "Accountants see amounts, members only see counts"
  known_issues:
    - "Sorting by amount ignores the currency"
  capture: screens/invoices--overdue-filter.jpg

Keep the file in the repository, next to the code, with one entry per state. The rules and known issues are where the redesign discussions will happen; the screenshot is the reference everyone points at.

Map the flows between states

Link each state to the states it leads to, labelled with the user action: “Click Save”, “Submit invalid form”, “Session expires”. Drawn as a graph, the map shows what a list hides:

• dead ends, where the only way out is the browser’s back button;
• loops that make users type the same data twice;
• states you can only reach through an error;
• screens with a single entry point that the redesign might remove by accident.

A user flow diagram that shows every screen state is the same idea, with a notation for decisions and errors.

Keep the record alive during the redesign

The inventory is most useful while the redesign is under way, not as a document written once:

• give each state a status: kept, changed, merged or removed, with who decided;
• capture the old app again before each release of the new one, so the baseline matches what users still see;
• review old and new side by side, state by state, and not only the happy path;
• remove an entry only when the state is gone from both the code and the new design.

Doing it with a coding agent and agentappbuilder

agentappbuilder turns this record into a canvas. Ask Claude Code to capture the screens of your app: once you confirm, it runs a Playwright script on your machine that sends one screenshot per state, with its route, to the Live app canvas. Each screen shows its states side by side with the date of capture, and your agent links them with the user actions that lead from one to the next. The platform never connects to your app, so an app that only runs on your machine works too. Use a demo account and demo data: the platform stores what the screen showed.

When the app does not run at all, your agent reads the code and draws one frame per state as HTML faithful to it. From there, you import the captured states into the prototype, ask for the new design one frame at a time, and use Compare to see the app today next to the proposed version. Concepts explains live frames and captures, and Working with your agent gives the prompts.

Whatever tool you use, the order stays the same: inventory, states, captures, rules, flows. A redesign built on that record changes what you decided to change, and nothing else by accident.