In a design handoff for a cloud admin console's resource table, which behaviours must be annotated because a static mockup cannot show them?

## Why a mockup under-specifies A static mockup is one frame: one screen width, one set of well-behaved data, one moment in time. Real screens load, fail, overflow, resize and change after the user acts. Every behaviour the frame cannot show is decided by *someone* — and if the handoff does not say, it is decided by whoever writes the code, usually late and under deadline. **Behaviour annotations** are the notes that travel with the frame to close that gap. The test for any screen: *what would an engineer have to guess?* Take the instance table in a cloud provider's admin console — a filter bar, a sortable table of virtual machines with a status column, and a row action menu. ## Screen states | State | What the annotation records | |---|---| | Loading | What shows while data arrives; whether the filter bar is usable meanwhile | | First-use empty | No instances exist yet: what the resource is, and the action to create one | | No results | Instances exist but the filter matched none: keep the filter visible, offer to clear it | | Error | Whole table failed versus one region unreachable; what the user can retry | | Permission | The user can view but not act: are actions hidden, or shown with an explanation | First-use empty and no-results empty look alike and are not: collapsing them sends a filtering user toward a create flow, or shows a new user a *clear filters* action that does nothing. ## Content extremes Designers draw with typical data; production data is not typical. The annotation states the rule for: - **Long values** — a 60-character instance name, a long region label: truncate or wrap, and how the full value stays reachable. - **Missing values** — an instance with no public address: a dash, the word *none*, or an empty cell. - **Counts at both ends** — zero rows, one row, ten thousand rows: pagination, virtual scrolling or a *load more* control. - **Translation growth** — labels that grow substantially in other languages, which moves every truncation point. ## Resize and layout rules A frame drawn at one width says nothing about any other width. The handoff says which regions **fill** and which keep their size, which columns **hide first** as the panel narrows, whether the table **scrolls horizontally** or reflows, and where the row actions go when space runs out. On native mobile the same annotation answers what the table becomes on a phone — often a list of cards — and which fields survive. ## Data and interaction rules - **Default sort** and whether the user's choice persists. - **Formats**: relative or absolute time, time zone, units for size and cost. - **Status mapping**: every status the backend can return and the indicator state each maps to — including the ones the designer never drew, such as *stopping* or *unknown*. - **Selection**: whether rows are selectable, what bulk actions appear, what happens to selection when the filter changes. ## Outcomes of actions The frame shows a button; the annotation shows what pressing it does. For *stop instance*: 1. The row's status changes at once to an in-progress state, and the stop action becomes unavailable for that row. 2. The table refreshes the row until the final state arrives. 3. On success the status reads *stopped*; on failure the row returns to *running* and a message says why and where to retry. 4. If an action removes the row entirely, the annotation says where focus goes, because the element that held it no longer exists. ## What the handoff does not need to annotate A design system exists partly so that screens need fewer notes. A system component's own behaviour — a button's hover, pressed, focus and disabled states, the table's built-in sort indicator — is defined once, in the component. Annotating it on every screen adds noise and invites contradictions. The handoff annotates: - **composition** — how this screen's pieces behave together; - **deviations** — anywhere the screen deliberately departs from the component's default; - **gaps** — behaviour the component does not support yet, which becomes a request to the system team rather than a local patch. A short checklist per handoff — states, extremes, resize, data rules, outcomes — makes missing answers visible without turning each screen into a wall of sticky notes.