Turning twenty setup screens into one you learn once

01 Context

Setting up Yuma means telling the agent how to behave: what it knows, how it sounds, which tasks it should handle, when to hand off to a human. Each of those lived on its own page, Knowledge, Brand Voice, AI Agents, Auto-Pilots, and more, and each had been built at a different time in its own way. I led design across these pages, with the trickiest one, Knowledge, taking six rounds to get right.

02 Problem

The challenge

Every setup page worked differently. One used pencil icons, one used pop-up forms, one used tabs. A merchant who learned to set up one thing had to start over on the next. And some pages did not even show what mattered: on Knowledge, you could upload sources but never ask what the AI had actually concluded, or spot two sources that quietly contradicted each other.

Why it mattered

Setup is the one place a support AI cannot afford to confuse people. If a merchant can't clearly tell the agent what to do, or can't tell what it already believes, they stop trusting it, and they turn the automation off.

Nine pages, nine ways to change a setting, and no way to see what the AI actually knew. People got lost.

How I knew it was the right problem

Lining the pages up side by side made it obvious: nothing shared, nothing you could learn once and reuse. And merchants kept asking a question the UI could not answer: "what does Yuma actually know about my returns policy?"

03 Impact

• One way to set up everything. Learn any page and you can set up the rest, because they all read the same and change the same way.

• Merchants can finally see what the AI believes, and fix it. On Knowledge, they can ask what it knows, catch two sources that disagree, and settle it in plain language.

• A standard the team builds to. New setup pages now start from this system instead of inventing a new pattern each time.

This is strategy and systems work, so the win is in the model, not a single metric. The proof is that the pattern now governs page after page.

04 Solution

One rule for all of it:

Cards read. Chat writes. You see the current setup as plain cards, and you change anything by asking the assistant, the same way on every page.

Why route every change through chat? One place to make changes means the assistant can check what you're asking, confirm before it saves, and undo it in the moment. Scatter the controls across pencils, pop-ups, and dropdowns and you lose all of that. So the rule is strict: no pencil edits, no pop-up forms, no field dropdowns. You read the setup on a card, and you change it by asking.

05 Approach

What I owned

The problem framing, the information architecture, and the system itself, written up as a reference the team builds from. Knowledge took six rounds of prototypes to land, and those rounds are what proved the pattern before I applied it everywhere.

The honest path

I first tried making one page do everything, and it didn't work. On Knowledge, a Shopify product table and the chat kept fighting for space. So I split tabular content onto its own full-width view and kept the chat for everything else. That lesson, let each job have the surface it needs, is what turned a single page into a system.

06 Execution

The same pattern, page after page. Same layout, same way to change things, different content:

Knowledge: seeing what the AI believes

Topics are grouped automatically from what the AI has learned, each showing what it knows and flagging conflicts. When two sources disagree, a step-by-step widget walks the merchant through them one at a time, with links to what each source says and the option to override both.

Brand Voice, Auto-Pilots, and the rest

Brand Voice uses the same cards to describe how the agent should sound. Auto-Pilots group the tasks it runs by theme, orders, returns, shipping. Guidelines, Onboarding, and the others all inherit the same layout and the same read-on-a-card, change-by-asking behaviour.

07 Reflection

What worked

Proving the pattern on the hardest page first. Knowledge was the messiest topic, so once the approach held there, applying it to every other page was easy.

What I'd do differently

Build a working reference page sooner. A written system convinces designers; a real screen convinces everyone else faster.

Transferable insight

The highest-leverage design work is sometimes a rule, not a screen. Decide how something should work once, and every future page inherits it.