Redesigning WPML with Claude Code — and what I’m learning about building with AI

I’m the founder of OnTheGoSystems. This week I’ve been personally redesigning the admin UI of WPML, our largest product. Not managing the project. Not reviewing someone else’s work. Sitting with Claude Code and doing the actual design work myself.

Two reasons.

First, a cleaner, more intuitive admin is the number-one thing our customers ask us to fix. For years they’ve told us WPML has too many screens, that settings are spread across unrelated areas, that important features are hard to find. When something matters that much to customers, I want to lead it with my own hands — not from a distance.

Second, I wanted to learn firsthand what building real product with AI looks like today. Not what demos show. Not what thought leaders claim. Actual product work, on a codebase that real customers will see, with all the messiness that comes with it. I’d rather discover what works by doing the work myself than have someone report back to me.

What I found surprised me in both directions. Some things I expected to be easy turned out to be hard — particularly keeping the AI aligned with reality when it was tempted to invent features that sounded plausible but weren’t in our product. Other things I expected to be hard turned out to be nearly trivial — like producing thirteen consistent HTML files for a new section in under an hour, each with working JavaScript for state toggles and search indexing, and every one of them usable as a design reference for the team implementing the real thing.

The speed, honestly, was the smaller surprise. The bigger one was how much the method matters. Get the method right and you get compounding results — better output, faster, with documentation ready to hand off. Get it wrong and you just reach mediocrity faster.

What follows is the full method I used — the prompts that worked, the mistakes I made, the review rounds that caught AI-fabricated features before they could ship. It’s written primarily for OTGS developers who want to run projects like this themselves, but anyone building UI with AI today can probably take something from it.

The one rule that makes this work 

Plan in text before you produce code.

Claude Code will happily build HTML the moment you ask. It will also build the wrong HTML, politely, quickly, and in large quantities. Every time you save by skipping a planning round, you pay double in rework — and the rework is harder than the original planning because now there’s code you don’t want to throw away.

Every successful branch in the WPML session had the same shape:

1. Amir stated a problem or intent.
2. Claude asked clarifying questions.
3. Amir answered concisely.
4. Claude proposed a plan in text.
5. Amir confirmed or edited the plan.
6. Only then did Claude build.

Every place that shape broke down, we backtracked. If you remember nothing else from this guide, remember the six steps above.

The eight phases of a session 

1. Frame the problem, not the solution 

Start with the pain the user feels, not the screen you want to change.

Bad opener:

“Add a new settings page for AI translation billing.”

Good opener (how the WPML session actually began):

“Users report that WPML feels overwhelming and unintuitive due to:

• Too many different translation-related screens.
• Settings distributed across multiple, sometimes unrelated areas.
• Prominent but low-priority options that distract from the main translation workflows.
• Related sections spread across different screens without clear dependencies or navigation paths.
• Lack of cross-linking between related functionalities…”

The second version gives Claude a scope to reason about. It knows the user’s pain, it can spot other things that contribute to that pain, and it can push back if your proposed solution doesn’t address the root cause. The first version reduces Claude to a typist.

In the WPML session the problem framing led directly to decisions Claude could not have made alone: that Payments & Maintenance was one screen too many, that Packages shouldn’t be top-level, that the Communication log was in the wrong menu, that Glossary was neither a setting nor a billing item. None of those land if you start with “redesign Settings.”

2. Gather your material before the session starts 

Put everything the AI needs into the working directory before you prompt:

• Screenshots of the current UI. Every screen you might touch. In the WPML session they lived in Current/ — WPML settings.jpg, debug-main.jpg, td-invoices.jpg, td-translators.jpg, etc. Ten-odd JPGs covering everything in scope.
• An instructions.txt stating the problem, the scope, and the output expectation. See ../instructions.txt for the actual one — notice how it grew across three passes (--- 1 ---, --- 2 ---, --- 3 ---) as new scope was added, rather than being rewritten each time.
• Any pre-existing design in an already-updated/ folder. The WPML session started with one styled ai-translation.html that Claude used as the visual template for everything else produced in the session — the Tailwind config, the card class, the back-link pattern, the flash animation for anchor jumps. That single file saved ~30 minutes of visual-system decisions.
• External links you want Claude to consult. For Troubleshooting, the WPML minimum-requirements page (wpml.org/home/minimum-requirements/) drove the warnings-panel design.

Claude works better when it can see the source of truth. Screenshots let it verify claims against reality. External links let it do research via subagents (see phase 8) without pestering you for background.

3. End every brief with “ask me questions, don’t assume” 

This is the single highest-leverage sentence in the guide. Every instruction set in the WPML session ended with some version of:

“Before starting the design, review everything, create a list of questions and ask me. Don’t assume.”

Without it, Claude defaults to acting on your brief directly. With it, Claude spends a turn mapping out what it doesn’t know and asks you. That turn saves hours.

When Claude asks questions back, answer them tersely. You do not owe paragraphs. From the WPML session:

Q: “Menu label — keep as ‘Payment for AI translation’? (reads slightly awkward)”
A: “AI Translation Billing”

Q: “Page structure — one long page with sections, or sub-pages?”
A: “Sub pages, following a similar structure to how you built the Settings page. We’ll need to plan before you implement.”

One-line answers are fine. Full sentences are fine. Complete paragraphs are usually a sign you’re doing Claude’s job for it.

4. Loop through question rounds before any implementation 

The Billing section of the WPML session went through two full question rounds before a single line of HTML was written.

Round 1 — 8 questions covering: menu label, page structure, state variations, the redundant connected-sites counter, Glossary placement, Who-can-use placement, scope of billing, owner-only action handling.

Round 2 — 7 more focused questions: overview vs. index, the “Tired of assigning credits” CTA, usage-reports content, transfer-credits UX, PAYG-active state fields, prepaid-active state, owner-only scope.

Only after both rounds did Claude propose the file plan. Only after the file plan was confirmed did HTML get written. Total elapsed planning time: maybe fifteen minutes of back-and-forth. Total files produced: five, all correct first time.

The anti-pattern is committing to the output after one round, then regenerating each file two or three times because constraints weren’t fully surfaced. That path feels faster until hour three.

5. Designate mockup-only affordances explicitly 

Mockups often need to show multiple states of the same screen — empty vs. populated, safe vs. warning, plan-active vs. plan-inactive. Two patterns in this session worked well:

The Billing state toggle. The Billing landing has a Preview state: No plan | PAYG active control at the top-right. Clicking either swaps the overview panel between the two states — no-plan shows both acquisition cards, PAYG-active shows the single “Your Pay-As-You-Go plan” panel with card details. Labeled “Preview state:” so reviewers understand this is a mockup affordance, not product UI.

The Troubleshooting warnings toggle. Preview state: Has warnings | All OK shows or hides the yellow minimum-requirements panel. Same labeling, same reason.

Without these, you’d ship two separate HTML files for every screen with a state transition. With them, one file demonstrates the whole design surface. Reviewers see more, faster.

In the YT ticket update, call them out explicitly:

“There’s a toggle at the top: ‘Preview state: No plan / PAYG active’. Use it to see both states. Of course, this is only part of the mockup and not for the actual UI.“

The italicized clause matters. Otherwise a dev will ask why the product has a state toggle.

6. Do a review round comparing mockups to source 

After everything is built, before you commit to the handoff, run a review round. In this session it was a single prompt:

“All looks good. Do a round of review:

1. Check in details the input screenshots to make sure that you haven’t added things that WPML doesn’t have and haven’t removed things that should be there.
2. Check that the text explanations for each page and each function are descriptive enough for clients to understand what ‘this’ does, what it’s good for and what to expect.”

Claude re-examined every screenshot, compared to every file produced, and returned a structured report. From the WPML Troubleshooting review:

• Missing from my design — five tools present in the current UI that hadn’t been ported: “Remove comments that don’t match the content’s language”, “Messages and notifications / Remove all messages and notifications”, “Correct wpml_language code in WPML setup”, “Reset ATE / Reset Debug log”, and the Installer Log table on the Installer Support page.
• Things I added that don’t exist — the System Check mockup showed 4 connectivity servers; the current product checks only 2. It listed 4 PHP libraries; current shows 2.
• Explanations that need sharpening — Communication log didn’t explain what success/failure looks like; Package management didn’t mention that packages are created automatically by other plugins; Content type linking didn’t explain the visible effect of changing a mapping.

Every item was fixable in a single follow-up turn. None would have been caught without the review prompt. The AI has an advantage here that you don’t — it can re-read every page and every screenshot simultaneously in one turn.

Always do it. Don’t treat it as optional.

7. Write the developer handoff in parallel, not at the end 

The YT ticket update in the WPML session went through several iterations during the session — refined as the design evolved, not assembled in a panic at the end. When PostHog got renamed to “Usage tracking and reporting,” the ticket update reflected it within the same turn.

A good ticket update for a UI-redesign handoff has:

1. A one-paragraph summary of what’s changing.
2. High-level change bullets — what’s moving, what’s being removed, what’s being added.
3. A details table per area — page name, what changed, why. Skip cosmetics when the whole section has been restyled — it’s noise.
4. A migration map table for anything crossing admin menus. Use exact current-UI paths: WPML → Translation Dashboard → Payments & Maintenance → Advanced Translation Editor → Overview → Who can use Automatic Translation? — not summaries, not paraphrases.
5. Open items — what still needs the receiving team’s input.
6. @ mentions of the specific people who need to look at specific areas.

The actual WPML ticket update is about 2,500 words and covers three top-level menus (Settings / AI Translation Billing / Troubleshooting). It’s longer than most tickets because the change surface is large — don’t be afraid of length when the change is complex, but do be disciplined about what belongs in the table (paths and destinations) vs. what belongs in prose (principles and reasoning).

When you want Claude to refresh the ticket as the design evolves, a structured prompt works best:

“I need you to update my message that explains the changes made.

1. It should have a new section about [X].
2. Explain why we’ve [done Y].
3. Include a table with the details of the change. Skip cosmetics because everything in this section has a new appearance.
4. Update the current instructions as now you’ve moved a few controls to [Z].”

Specific, structured, and it tells Claude what to preserve vs. what to change.

8. Use subagents for external research 

When Claude needs information from outside the working directory — vendor documentation, blog posts, minimum requirements — delegate to a subagent. Don’t fetch and paste manually.

The prompt that kicked off the WPML Troubleshooting research:

“Research the WPML plugin’s troubleshooting/debug features on wpml.org (the official documentation site) and return a concise summary of what each feature does and how WPML’s support team typically instructs users to use it. […] Please look up documentation for each of the following and tell me:

• What the tool does (1-2 sentences)
• Who uses it — end-user self-service, or only on support’s instruction
• Is it destructive/risky? (resets data, clears cache, etc.)
• Any known user-confusion the docs call out.”

That subagent returned a structured summary with source links that directly shaped the three-tier (safe / logs / support-only) organization of the Troubleshooting redesign. Without it, we’d have either guessed at who-uses-what, or interrupted flow to read docs ourselves.

When you delegate to a subagent, tell it:

• What you’re trying to accomplish (so it can judge edge cases, not just follow instructions).
• Exactly what format you want back (table? bullets? one sentence each?).
• A word or time budget. Otherwise it returns an essay.

Critical UX principles that came out of the work 

Method is the main thing. But a few principles recurred often enough to be worth knowing going in — they’ll save you a question round or two.

Organize by risk, not by topic 

The current WPML Troubleshooting page is one giant scroll of ~25 tools, mixing “Clear cache” with “Reset WPML entirely” at the same visual weight. Clients can’t tell what’s safe. Supporters can’t point at a URL.

The redesign sorts every tool into one of three tiers with colored badges:

• Safe to run yourself (green) — self-service fixes clients can try without help.
• Logs — read only (blue info) — diagnostics that never change anything.
• Advanced — only when WPML Support asks you to (red, plus a group-level explainer paragraph) — tools that can lose data or break a site when used wrong.

If you find yourself redesigning a dense technical page, ask “what’s the blast radius of each tool?” before asking “what topic does each tool belong to?”

Every tool answers three questions 

For a tool to work as self-service, its copy must tell the user:

1. What it does.
2. When it’s useful.
3. What to expect afterwards.

The WPML “Fix post_parent in translations” tool went from the current product’s terse “Fixes the parent relationships of translated posts.” to:

“Re-links translated child pages (or any hierarchical content) to the translated version of their parent, instead of pointing at the original-language parent. Useful after migrations or bulk imports.”

Same tool, 3× more useful because the user now knows when to reach for it.

Graded safety controls 

Not every destructive action needs the same confirmation pattern. The WPML session ended up with three tiers:

• Safe action → a button.
• Medium-risk action → an “I understand” checkbox arms the button; a red paragraph above it explains the specific risk.
• Nuclear action (Reset WPML entirely) → the checkbox AND a typed RESET WPML phrase must both be correct.

Different risk levels, different friction.

Cross-link, don’t duplicate 

When a tool overlaps with a setting, link instead of owning. The Troubleshooting → Usage reports page cross-links to Settings → AI Translation → “Who can use Automatic Translation” rather than re-implementing that control. One source of truth, one place to maintain, one consistent experience.

Rename for clients 

Internal vendor or acronym names don’t belong in client-facing copy. In this session:

• “PostHog Integration” → “Usage tracking and reporting” (clients don’t know what PostHog is).
• “ATE” as a UI label → “Advanced Translation Editor” (ATE stays as internal shorthand in YT comments only).
• “Credits” → “Words” (pricing-model change — but the UX lesson generalizes: don’t expose vendor or billing internals as user-facing nouns).

Search beats navigation for dense surfaces 

The WPML Settings index has 16 sections; the Troubleshooting page has ~25 tools. Expecting a user to scan and find the right one is unrealistic. A prominent, scoped search with sub-item indexing — so typing “ghost” jumps straight to the ghost-entries tool anchor — solves discoverability better than any navigation cleanup.

The Billing section was different: 4 sub-pages, all with plain-English labels. We added search initially, then removed it after evaluating actual density. The principle:

If a page has ≤6 top-level items with plain-English labels, don’t add search. If it has >10 technical items, search is almost always worth it.

Proactive warnings over passive settings 

If your site doesn’t meet a known requirement, tell the user at the top of the page — don’t wait for them to discover it by failing. The Troubleshooting landing runs every check from WPML’s minimum-requirements list and surfaces failures in a yellow panel above the search. When everything passes, the panel is hidden entirely.

Prompt patterns that worked 

These are the exact phrasings that kept the WPML session on track. Steal them.

Forcing question rounds 

“Before going forward, check everything and ask me for clarifications. Don’t make assumptions.”

“If you have remaining questions, ask.”

“Compile the material and ask me questions before you produce the output.”

Driving review 

“Do a round of review:

1. Check in details the input screenshots to make sure you haven’t added things that WPML doesn’t have and haven’t removed things that should be there.
2. Check that the text explanations for each page and each function are descriptive enough for clients to understand what ‘this’ does, what it’s good for and what to expect.”

Evaluating before acting 

“Actually, I see that the search functionality for the billing section isn’t required. Please evaluate and tell me if there’s a need, based on the content of the sub-pages.”

Asking Claude to evaluate before implementing is how you avoid having to undo something three edits later. In the WPML session this prompt led to search being cleanly stripped from Billing in one step, instead of being half-implemented and then torn out.

Surfacing ambiguity 

“Check for consistency and conflicts. Produce an updated version free of conflicts and ambiguities. Before doing so, ask me questions so you don’t need to assume or invent.”

When asked this, Claude returned a structured list of contradictions in a draft ticket update (“items listed as removed are also listed as moved — which is it?”, “‘ATE’ is ambiguous: Advanced Translation Editor or Automatic Translation Engine?”). Each was resolvable in one reply. Without this prompt those contradictions would have shipped.

Targeted renames and moves 

“Rename ‘X’ to ‘Y’ across the troubleshooting files.”

“Move the yellow block for the minimum requirements to be above the search in troubleshooting.html.”

Surgical. Specific. Always works — as long as the change really is mechanical. For anything requiring judgment, go back to the planning pattern.

Pitfalls to avoid 

• Skipping planning to “save time”. Every skipped planning round costs more rework than it saved.
• Accepting features you haven’t verified exist. Claude initially added 4 connectivity servers to System Check; the product only has 2. Caught in review. You’re responsible for the sanity check — don’t trust plausibility as a proxy for accuracy.
• Naming drift. Once a decision is made (“ATE” is internal only; client UI says “Advanced Translation Editor”), enforce it everywhere. Drift between mockup files and tickets causes dev confusion. Ask Claude to propagate renames — don’t do it manually.
• Unlabeled mockup-only controls. Preview toggles are great for reviews. Without a “Preview state:” label, they read as product UI.
• Forgetting cross-document consistency. When a feature gets renamed, the HTML, the search index, the filename, every href, and the YT ticket all need to update. Tell Claude to propagate — don’t chase it file by file.
• Leaving handoff docs until the end. Write the ticket as you go. When the design stabilizes, the ticket is done.
• Letting the AI decide what matters. Claude is great at execution; it’s mediocre at judgment calls that depend on institutional context. The “we don’t need search here” call at Billing was Amir’s, not Claude’s — and it was right. Don’t abdicate editorial decisions to the tool.

A sample session outline 

If you’ve read this far, here’s the whole workflow condensed:

1. Frame — state the user’s problem, list the screens/areas in scope, attach screenshots.
2. Brief — write an instructions.txt that ends with “review everything, ask me questions, don’t assume.”
3. Question round 1 — let Claude ask 5–10 questions. Answer them tersely.
4. Plan — Claude proposes an overall structure. You confirm or adjust.
5. Question round 2 — fine-grained remaining questions (usually about state variations, edge cases, confirmations).
6. Sub-plan — file list and per-file outline.
7. Build — Claude writes the files. Verify each one as it comes in.
8. Review — comparison against source screenshots; find missing/added items; sharpen copy.
9. Consolidate — draft the YT ticket update and iterate it alongside the design.
10. Handoff — push to the repo, record a short walkthrough video, @mention the receiving team.

Budget for steps 3–5 and step 8 — the rest is mostly execution.

Closing 

The single biggest lesson of the WPML session is that Claude Code is not a designer; it’s a disciplined builder that can execute a well-specified plan at unusual speed. Your value in the loop is judgment, not typing. Give Claude the problem, demand that it ask questions, insist on a plan in text, review the output against the source of truth, and prepare the handoff as you go.

If you do that, the speed you’ll get isn’t a 2× improvement over manual UX work. It’s closer to an order of magnitude — and the output quality is higher, because the review discipline is built into the workflow instead of being something you’d have to remember to do.

This design update goes into WPML 4.10. Like the AI-driven design, we’ll implement this huge update by deploying AI agents to work autonomously, as a team. If you’re interested in a preview, here is a quick video: