` hides exactly the questions a review should surface. - **Follow the project's design guidance.** Use its semantic roles (`bg-card`, `text-muted-foreground`) and invent no tokens. If the project locks its palette, an off-palette utility renders as nothing. - **Synthetic data only**, inline in the file. No real personal or health data, no network, no API clients, no auth. - **One state per file.** Reach for a variant file rather than a `useState` toggle inside a screen — the viewer's state switcher is how a reviewer finds states, and a hidden toggle is invisible. ## 5. Link the screens - `useScreenNavigation()` gives `goToScreen(id, { variant })` and `back()`. This is the one to use for a `Button`, an input or a link — anything already interactive. - `` wraps text or a static row. It renders a button of its own, so putting a `Button` inside it nests two buttons and React warns. - `` covers something that is not a control — a chart, a static row, a placeholder for a component nobody has built. Wrap that thing in a `relative` element and put the hotspot inside it with no geometry: it fills the wrapper, so it stays on its target at every viewport. Reach for the `area` prop only over something that scales as one piece, such as a mock image. - **Navigate from a button, a link or a hotspot, never from a `div` with an `onClick`.** The flow map finds links by clicking what a person can reach; a clickable `div` shows no arrow, and it is not reachable from the keyboard either. - **Navigate during the click.** A `goToScreen()` inside a timer or after an `await` is not seen by the map, so the control reads as leading nowhere. Every screen must be reachable from the entry screen. Open **Flow** (`f`) in the viewer: every card should carry an arrow in, none should say **Unreachable**, and there should be no red card — that is a `goToScreen()` naming a screen that does not exist. ## 6. Pin the comments The designer can write these in the viewer — pick a component, then **Comment on …** — and the viewer writes both `annotations.json` and, when the element has no id yet, the `anchor()` in the screen file. Write them here when you are building the prototype in one pass; either way the file is the same. Name the elements a comment is about, and only those: ```tsx ``` Then write the note in `annotations.json`, one per decision an engineer could get wrong: ```json { "id": "home-primary-action", "screen": "home", "target": "book-follow-up", "kind": "spec", "title": "One filled button per screen", "body": "Every other card action is `ghost`.", "author": "Ana" } ``` - `kind` is `spec` (a rule to implement), `flow` (why the next screen is what it is), `question` (undecided) or `todo` (known gap). - **A note says something the screen cannot.** "This button is blue" is not a note. "Only one filled button per screen, so the next step is unambiguous" is. - Ids in `target` are the contract with the engineer. Name the element for what it is (`book-follow-up`), never for where it sits (`third-card-button`). - A note that applies on every screen it appears on leaves `screen` out. ## 7. Name what the engineer will ask about The left rail reads the component tree out of the DOM, and inspect mode (`i`) lets a reviewer click any part of the screen to find its row. Two things make that tree useful, and both are choices you make while building: - **Build from components that stamp `data-slot`.** Every shadcn/ui component does, and that is where the tree gets `Card`, `CardHeader`, `Button` — and what links each row to its Storybook page. A screen of bare divs shows landmarks, and landmarks link nowhere. - **Put `anchor()` on the elements a reviewer will point at**, not only the ones a comment quotes today. The id shows in the tree beside the component, it is the name the engineer will use, and it anchors the links people paste into tickets: a link to a component is the path down from the nearest id above it, so an id nearby keeps that path short and immune to edits elsewhere on the screen. Every component can be linked to either way — ids decide how well those links age. ## 8. Verify before handing it over Run the project's own type check and linter over the new files — the screens are ordinary TSX in the project, so its `tsc` and lint setup cover them. Then open the viewer and check, on each screen: - **Problems tab is empty.** It lists missing default exports, notes pointing at screens that do not exist, and an `entry` that is not there. - **No comment reads "Target missing"** — that means an `anchor()` was renamed or removed. - **Every link goes somewhere**, and Back returns where it came from. The **Flow** map shows all of them at once: no **Unreachable** badge, no red card. - **The browser console is clean.** A nested-button warning means a `Button` ended up inside a `ScreenLink`. - **Each state renders**, including the empty and error ones. Report the deep link to the entry screen (`#/p//`) so the designer can open exactly what you built. ## Common mistakes | Mistake | What happens | | --- | --- | | Two screens for two states of one screen | The state switcher stays empty; reviewers never see them as alternatives. | | `anchor()` id describing position | The first layout change makes the note nonsense. | | Notes restating what the screen shows | The engineer stops reading the notes. | | Handwritten `

` chrome instead of the design system | The review discusses the mock instead of the design. | | A state hidden behind in-screen `useState` | Invisible in the sidebar, so it never gets reviewed. | | A hotspot placed with `area` percentages of a flex container | It sits on its target at one width and drifts off it at every other. | | Navigation on a `div onClick` | No arrow on the flow map, and no way to reach it from the keyboard. | | `goToScreen()` after a timer or an `await` | The map reads the control as leading nowhere. | | Prototypes folder not named `prototypes` | The viewer refuses to start; screen files are recognised by that folder name. | | Prototype built as a Storybook story | No flow, no doc, no comments — the reason this tool exists. |