At 4:06 PM on May 8, we merged the checkout feature branch into the Packages redesign branch, pushed to an internal host, and sent the reviewer a URL. That part was routine. The page the reviewer loaded was not. Alongside the Packages page stepper redesign, there were 7 annotated review points rendered inline. Each one sat next to the component it described, and each carried a design decision and a checkbox.

It was the first time we had done design review that way. The review-block layer of the engine behind it took 72 minutes to build, on top of a foundation we had laid earlier that day.

How design review had worked before

The platform is a legacy application codebase. For most of our time with it, review worked one way. We built a thing, screenshotted it, pasted the screenshot into a JIRA comment, and waited for the reviewer to tell us what looked off. The comments came back as text pointing at pixels in a frozen image. Nothing linked to anything. If the question was “does this purple match the toggle,” the answer arrived two messages later in a different thread, and we had to look up which toggle and which purple.

We had accepted that as normal. The product was old, so the review process would be clunky, and we weren’t planning to solve it.

That was wrong.

The foundation

The checkout ticket was the event checkout page, a cart-driven Purchase Summary view for event organizers. Around 1 PM, in the middle of wiring the cart model, we built the first layer of what we started calling the visual-walkthrough engine. It had three parts: an include file, a page opt-in mechanism, and JSON sidecars at ai/design/ITEM-XXXX.json. Each sidecar listed the highlights for a page, with anchors that referenced elements by selector. Any page that included the engine file and pointed at a sidecar got the highlights rendered on load. Nothing went in the database, and there were no dependencies outside the repo.

We shipped that as part of checkout Phase 2 and filed a follow-up ticket to build the DB registry and staff sidebar. V1 was already useful for review without those.

The review blocks

The foundation put highlights on the page. It did not carry the design reasoning. A yellow box around a stepper cell does not tell the reviewer why we chose 5 cells instead of 4, or why we picked #5640a3 for the outline instead of a different shade.

Starting at 2:54 PM, we built V2: inline review blocks that hydrated from two fields in the sidecar, designNotes and designDecisions. The designNotes field held the reasoning for each highlight. The designDecisions field held the specific yes/no question. When a block rendered, it showed the note and a checkbox. The reviewer’s response could post back to a small review endpoint, which logged it server-side.

The full brief for the Packages R2 pass lived at ai/design/ITEM-XXXX-r2.md. It had seven highlights, with decisions like these:

  • Does the 1px #5640a3 outline on the stepper cells match the Monthly/Annual toggle?
  • Does the #01b300 active fill read clearly at that size?
  • Does splitting the Accounts section into 2 rows, with three purple subtitles aligned under the columns, feel right, or too busy?

Those questions existed before we built the engine. They were in our heads, in scratch notes, and in prior JIRA comments. Moving them into designNotes and designDecisions in a sidecar file did not create new information. It moved the information to the place where it mattered.

Using it immediately

The merge and push at 4:06 PM ended the session. We updated JIRA comment 60028 to point the reviewer at the walkthrough and moved a cart-model heads-up out of comments into Dev Notes. The reviewer had an internal host and 7 decision points waiting on the live page.

We had not planned to build review tooling that day. Checkout Phase 2 was the job. The tooling emerged because we were already touching the include layer and already writing the design brief for the R2 pass. The gap between “we have these decisions written down somewhere” and “the reviewer can see them on the actual page” turned out to be about 72 minutes.

One thing we were watching was whether the walkthrough would stay lightweight as more pages and more decision points accumulated. A system that adds friction in proportion to the number of reviews it tracks is a system people stop using. The JSON-sidecar model kept each page’s state in its own file, so the complexity stayed local. Whether that holds once the follow-up ticket’s DB registry arrives is still open.

What the commit trail shows

338 commits went out that day across 16 repos, and the walkthrough engine was not the main event. Checkout Phase 2 shipped. The agent dashboard got its inline session spawn working. The calendar composer landed. The nightly cron went live. The walkthrough was one commit in a long day.

It was not a dedicated project with its own sprint slot. It fit into the existing session because the gap it closed was immediate and concrete. The design decisions for the Packages redesign existed, the reviewer needed to see them, and the fastest path was to build the tool and put it on the page.

Now the checkboxes sit next to the stepper cells they ask about. When the reviewer answers whether the 1px #5640a3 outline matches the Monthly/Annual toggle, the outline and the toggle are both on screen with the question. The answer posts back to the review endpoint instead of turning up two messages later in a thread about a frozen screenshot.

What we still can’t say is whether this holds when the follow-up ticket moves the sidecars into a database. Each of those decisions currently lives in one JSON file. We’ll only know the engine stayed lightweight if a page with 7 more decisions is no harder to review than this one.