Screen Definition

A design mockup shows one state. Three documents in the list, names of a comfortable length, nothing gone wrong. The same screen in a shipped product has many more faces than that. An empty list, a list still loading, a name that runs past twenty characters, someone without access opening the URL directly — each of those is a different screen, and a mockup usually covers none of them.

When teams built from mockups alone, every one of those differences came back as a question. An engineer asks what to show when a team has zero documents, the designer invents an answer on the spot, and two hours later "what if the email format is wrong?" arrives. The answers scatter across chat threads. Two weeks later the same question comes up again and nobody can find what was decided the first time, so it gets decided a second time, differently.

A screen definition collects those questions before anyone builds. You stand each screen up, count everything placed on it, and write down the situations each of those things can be in. The number of questions doesn't shrink. What changes is when they get asked, and whether the answer survives anywhere but someone's memory. Asking them at a table costs an hour; asking them mid-build costs a day each.

Five groups, filled out one screen at a time.

1. Screen identity — the screen's name and URL, plus where users arrive from. If the same invite screen opens from settings and from a share button inside a document, both entry points get written down, because the two paths often need different defaults.
2. Element list — everything placed on the screen, counted exhaustively. Not only buttons and input fields, but helper text, the screen that shows up when there's nothing to show, and the indicator that appears while data loads.
3. State per element — for each item, what it looks like empty, mid-entry, in error, and disabled. This group is the body of the document. A single email field turns into three lines: blank, badly formatted, and already invited. Counting states here is what turns a vague screen into a countable amount of work.
4. Behavior and conditions — what happens on each action, paired with the condition that triggers it. "Pressing send invites the person" is half a line. It's complete once you add what happens when no role was selected and when the seat limit is already reached.
5. Exceptions and error copy — the non-happy paths and the exact sentence that appears on screen. Copy invented during implementation makes the product's voice drift from screen to screen, and nobody notices until a writer reads twelve screens in a row.

What counts as finished goes in acceptance criteria, written as statements someone can check off one at a time. Rules that reach past a single screen belong in a product policy instead, linked from here rather than repeated. Who is allowed to invite people touches every document and every plan, and a rule written in two places eventually gets updated in one.

When a flow crosses several screens, a flow chart draws the order and the branches alongside this document. When one object moves between several states, a state diagram covers the transitions this format handles poorly.

The writer is usually the product manager who owns the feature. When a screen carries many states, the designer fills in group 3 together with them. A common order is to sketch a wireframe first — a rough layout that fixes where elements sit without styling them — and count the items off that sketch.

Three audiences read it, and each one reads a different group.

1. Engineers read behavior, conditions, and exceptions, then answer how long the work takes. A screen they thought had three states and that turns out to have nine triples the estimate.
2. Designers read the element list and the state group to count how many screens they actually have to draw.
3. Whoever owns quality assurance (QA) copies the acceptance criteria and the exception group straight into a test checklist.

Because the groups split that cleanly, you can tell who a gap will hurt before anyone complains. An empty group stops exactly one of those people. Leave out exceptions and engineering still moves, but QA has no basis for calling anything a pass or a fail, and the feature ships on somebody's judgment rather than on a standard.

Writing it isn't a one-time job either. Decisions change during the build, and changes that don't come back to the document leave it stale within two weeks. A stale document is worse than none at all: without one people ask, and with a stale one they trust it and build what it says.

"This screen definition has no empty state. What does a team with zero documents see?"

The element list is there but the state group was left blank.

"Follow the mockup for layout, and use the error copy exactly as written in the definition."

Drawing the line between what the mockup settles and what this document settles.

"The policy changed, so let's fix the screen definition first and then file the engineering ticket."

Changing the implementation without the document leaves the test criteria pointing at the old behavior.

At Pagedeck, Mia wrote the screen definition for the invite flow and sat down with Theo and Noa to read it together. Eleven questions came up in an hour, and nine of them landed on the exception group: what happens when the same address is invited twice, what a team over its seat limit sees, what an expired link shows. All nine were settled at the table and written into the document, and only then did Theo give an estimate.

The most common position is that a mockup makes this document unnecessary. You can see the screen, so there seems to be nothing left to write down. But a mockup shows one state out of many, and the rest exist only as sentences. Build from the mockup alone and every missing state gets decided by whoever hits it during implementation. Those decisions live nowhere, so there's nothing to check the result against later.

The other misreading is that you write it once. It gets taught as an artifact from the stage before building starts, which makes it feel finished at handoff. In practice decisions keep moving, and a document that doesn't move with them splits from the product. When somebody who joined three months later reads it and takes a behavior that no longer exists as fact, correcting the misunderstanding costs several times what writing it accurately would have.