Say you already have a "return borrowed equipment" screen at example.com, and you ask your AI agent to improve it. The reply is a new colour palette, a utilization chart, and a shop to buy replacements. The item name and due date are harder to find, and the return action moved.

You asked for a review. You got a replacement.

This is a fictional illustration of how Design Decision Method applies to an existing screen, not a case study or a measured result. The product details are invented for the example.

The method is not only for new UI. The agent procedure says to use it when a task involves designing, reviewing, or implementing a screen.

Check the screen you already have

The live docs ask the agent to read the brief and the product you already have, then name the audience, how often the task happens, what a mistake costs, and the device. Keep known separate from assumed, and do not invent rules or capabilities the product lacks.

A short context note might look like this:

Audience: Members who return a tool they already borrowed.
Task / frequency: Occasional.
Cost of a mistake: Medium — a failed return can leave a due date hanging or mark the wrong item back in.
Device: Phone first.
Known: The screen already shows the item, the due date, a condition note, and a return action. There is no shop, and no utilization dashboard.
Assumed (marked): Offline return was not requested, so none is designed.

That is establish context for a screen that already ships.

Keep the system the project has

Choose the visual system starts the same way on a rework: keep a system the project already has. A request to "improve" the screen is not itself a brief for a new visual identity.

The agent procedure adds a caution: inheriting a theme does not verify new focus, error, disabled, or asynchronous behaviour. If the change repairs an error state, record that it still needs a check.

Run the gate, then record the choices

The docs say to skip the object map when the change does not depend on relationships, such as a restyle that leaves the structure alone. The agent procedure records that decision in one line:

Map: skipped — the return view already exists. This change clarifies the due date and the error state; it does not add object types, routes, or navigation.

The consequential choice belongs in a decision record: keep the single-page return; put the item and due date first; keep the condition note visible at the point of return. The procedure says to present speculative additions — the chart and the shop — as optional, not as required work.

For the review itself, the procedure asks the agent to label each finding keep, change, or defer:

Keep: the existing components and tokens; the single return action.
Change: make the item and due date unmissable; keep the item identity visible if the return fails.
Defer: condition photos; any shop or dashboard.

A small change gets a few lines. The method is a shared procedure, not mandatory for every typo fix.

Label the evidence

Deliver and validate still applies. Deliver the updated screen, the decisions, and a short validation status, with each result labelled:

  • Item and due date stay visible on a narrow viewport. Heuristic review of the layout only.
  • A failed return keeps the item identity on screen and offers retry. Manual test in one phone-sized viewport.
  • Contrast on the return action. Automated check on the colours used — not a claim about the whole product.
  • People complete a return without help. Proposed. Not tested. No user research. Not tested: screen reader pass, the server's error responses, offline behaviour.

Nothing in that note invents a measurement. A mockup cannot establish task-completion rates.

Why this matters

"Improve it" is an easy prompt, and an easy way to lose decisions the current screen already got right. The review path lets you keep those decisions, change only what the brief requires, and defer the rest — with evidence labels instead of a confident "done."

The method does not claim this saves time. That has not been measured. It also does not guarantee a better screen. What it gives you is a way to rework existing UI without starting over.

Try it

Design Decision Method is a lightweight design decision workflow for developers building interfaces with AI agents. It follows the open Agent Skills format and is MIT licensed. Install paths for Claude Code, Cursor, Gemini CLI, and Codex are in the README.