Rethink UX

You have a working application but something about the interface is not right. Maybe a screen looks off, a layout feels awkward, or you are stuck on how to reorganize a complex page. Instead of guessing what might work better, you use the spec and Spec Canvas to explore alternatives and validate them visually — before touching the production code.

When This Applies

• An AI coding agent built a screen that works but looks wrong, and you want to see better options.
• A page has grown complex and you need to rethink how blocks are arranged.
• You know something is off but cannot articulate what a better version would look like.
• You want to try a different visual direction without risking the working codebase.

Two Scenarios

Rethinking UX typically falls into one of two patterns: looking for a visual reference, or reworking the spec structure itself.

Scenario 1: Find a Better Visual Reference

You have a spec and a working implementation, but the visual result is not what you want. You use Spec Canvas to generate alternative HTML implementations and pick a better reference.

The Workflow

1. Load your spec into Spec Canvas. Import the UI Spec for your application. If you do not have one yet, reconstruct it from the existing code or screenshots — see Reconstruct an Existing App.

2. Generate implementations from multiple agents. Open the screen that needs improvement and generate HTML implementations from several AI agents. Each agent interprets the same spec differently — different layouts, spacing, typography, visual hierarchy.

3. Pick what works. You might find an implementation that works as a whole — use it as a complete reference. Or you might find that only a specific fragment looks better than what you have — a better card layout, a cleaner header, a more readable table.

4. Hand the reference to your coding agent. Give the selected HTML to your coding agent along with a clear instruction:

• Whole screen: "Restyle this screen to match the reference HTML."
• Specific block: "Restyle the stats section to match how it looks in the reference. Keep everything else as is."
• Global pattern: "Apply the layout approach from the reference to all list screens in the app."

Because Spec Canvas marks every block in the generated HTML with a ui-spec-block-id attribute, the coding agent can map each element in the reference back to the spec — no ambiguity about which part you mean.

Scenario 2: Rework the Spec Structure

The problem is not just visual — the arrangement of blocks, the screen flow, or the information hierarchy needs to change. You rework the spec itself with help from an AI agent, then validate the result visually before committing to code.

The Workflow

1. Give the current spec to an AI agent in a chat. Paste the UI Spec (or the relevant screen) into a conversation. Describe the problem:

• "This dashboard has too many blocks. Reorganize it into tabs or collapsible sections."
• "The settings screen is a long form. Break it into logical groups with better navigation."
• "The user flow from list to detail to edit feels clunky. Suggest a better screen structure."

2. Get an updated spec back. The agent modifies the spec — changes block structure, adds or removes blocks, adjusts purposes, reorganizes screens. You get a spec diff or a full updated spec.

3. Preview the changes in Spec Canvas. Import the updated spec into Spec Canvas and generate HTML implementations for the changed screens. See how the new structure looks as a real interface.

4. Iterate if needed. If the result is not right yet, go back to the chat. Describe what is still off. The agent adjusts the spec again. Import, preview, evaluate. Each round is cheap — you are changing a YAML file and generating HTML, not rewriting production code.

5. Hand off when satisfied. When the new structure works, give the updated spec to your coding agent. The agent knows exactly what changed and what to build.

What You Get

• Visual alternatives generated in minutes, not hours of manual prototyping.
• A way to validate structural UX changes before touching production code.
• Clear references (HTML with block IDs) that a coding agent can follow without ambiguity.
• Confidence that the new direction works as an interface — not just as an idea.

Tips

• Start with the screen that bothers you most. You do not need to rethink the entire app. Fix one screen, see if the approach works, then expand.
• Use multiple agents for visual references. Different agents have different visual sensibilities. An implementation from Claude might look different from one by Gemini — and that difference is the point.
• Separate visual problems from structural problems. If the blocks are right but the look is wrong, use Scenario 1. If the blocks themselves need to change, use Scenario 2. If you are not sure, start with Scenario 1 — generating references often reveals whether the problem is visual or structural.
• Keep your old spec as a revision. Before making changes, save a revision in Spec Canvas or keep a copy of the YAML. You may want to compare or revert.
• Combine with Prepare Handoff. Once you are happy with the updated spec, the handoff workflow applies directly. See Prepare Handoff to AI.

Related

• Explore Product Directions — similar workflow for new apps instead of existing ones.
• Reconstruct an Existing App — how to get a spec if you only have code.
• Patterns & Practices — spec diff, progressive precision, verification layer.
• Prepare Handoff to AI — how to hand off the updated spec for implementation.