RonanCodes/variant-compare

variant-compare

When you change an existing surface in a way that's a judgement call (a redesign, a richer layout, a copy overhaul), don't edit it in place and hope it's better. Build the new version next to the old one, wire a local switcher, and let the human flip between both before anything is replaced. Ronan thinks of this as local A/B testing: seeing both beats reading a description or a single before/after.

When to use

• Use it for: page redesigns, layout reworks, substantial copy/tone changes, restructuring how information is presented, any change where "is the new one actually better?" is a real question.
• Skip it for: bug fixes, tiny tweaks, net-new surfaces (nothing to compare against), or changes the human already specified exactly.
• Offer it proactively when a requested change is a redesign rather than a fix, even if the human didn't ask for a switcher. ("This is a redesign, want me to build it beside the current one behind a switcher so you can compare?")

This is a durable preference: default to it for the cases above.

The pattern

1. Keep the old version, intact. Extract the current implementation into its own component verbatim (e.g. FooClassic) if it isn't already isolated. Don't refactor it while extracting; a verbatim move keeps the comparison honest.
2. Build the new version beside it as a sibling component (e.g. FooEnhanced). Share only the data layer / pure helpers; let the two presentations diverge freely.
3. Wire a switcher bound to URL state so the choice is shareable and survives reload:
   • A ?variant=a|b search param (router-validated), defaulting to the current/old version so normal visitors see no change.
   • A small, visible segmented control (e.g. "Original | New") that links between the two param values. Put it somewhere obvious but unobtrusive (a header actions slot works well).
4. Default stays old. Nothing user-facing changes until the human decides. The new version is opt-in via the switcher.
5. Verify both render (screenshot/snapshot each variant; exercise the new one's interactions). Keep the full local gate green.
6. On approval, promote and delete. Replacing old with new is then a one-line default flip plus deleting the old component and the switcher. Do this only when the human says they're happy.

Conventions

• Search-param default = old. The param is opt-in for the new variant; absence of the param renders the original. This keeps the deploy non-destructive.
• Don't fork the data. Both variants read the same source of truth. If the new variant needs extra fields, add them as optional so the old one and any generators are unaffected.
• Shareable preview. Because the variant lives in the URL, the human can be handed …/foo?variant=new to click around the real (or deployed) app, not just a local dev server.
• One switcher, two variants. Resist a third variant; if the new one needs iteration, iterate it in place. The point is a binary choice.
• Commit the switcher and both variants together so the comparison is reproducible. The promotion (delete-old) is a separate, later commit.

Promotion checklist (when the human is happy)

• Flip the default so the new variant renders without the param (or make it the sole component).
• Delete the old component and the switcher.
• Remove the now-dead ?variant handling (or leave a redirect if the param was shared externally).
• Keep tests green; update any that referenced the old layout.

Reference implementation

The dataforce changelog page (2026-06-15): ChangelogClassic (original) and ChangelogEnhanced (filters, search, permalinks, RSS) behind a ?variant=classic|enhanced switcher in the page header, defaulting to classic. Files: src/components/changelog/{changelog-classic,changelog-enhanced,variant-switcher}.tsx, dispatched from src/routes/changelog.tsx via a validateSearch param.

See also

• /ro:close-the-loop — verify the new variant actually works before promoting.
• /ro:visual-diff / /ro:visual-regression — capture both variants for a side-by-side.