Users finish everyday tasks they still cannot explain. I built the platform that measures why.

People send money, book doctors, and renew licenses online every day. Most finish without errors. Many leave unsure whether the payment left, who will call them, or when a document arrives. Usability research measures time on task, completion rate, and errors. None of those answer: did the user understand what just happened?

Cognitive load describes effort and capacity limits. Cognitive distance describes alignment: whether someone can explain, predict, and transfer the system's logic into their own reasoning. A user who completes in three taps but cannot say if money has left was not overloaded. They were not informed.

The Everyday Services Study operationalises that gap. I designed the construct, built the Cognitive Distance Index (CDI), pre registered five hypotheses, and shipped a live international platform at everydayservices.study. The conceptual paper is under peer review. This page documents the engineering behind the instrument.

The design is deliberately austere. Interface language register is the only variable that moves. Every click, field, and outcome stays identical across arms. If participants diverge on effort or completion time, the manipulation failed.

Between subjects. Each participant sees one register across all three modules. Version A (vA2 today) uses plain language that names who acts next and when. Version B uses institutional copy matching real bank and government services. Module order is balanced across six rotations of banking, medical, and license renewal.

What participants do. They complete three simulated tasks: send a bank transfer, book a specialist appointment, pay and mail a license renewal. After each module they answer prediction questions while the result screen stays visible, write open explanations, and rate ease, effort, understanding, and certainty. Session length is about fifteen minutes.

What the platform measures. CDI scores open explanations against a rubric. Five pre registered hypotheses test whether institutional register raises CDI, widens confidence miscalibration, and shifts which service participants name as most uncertain. Manipulation checks flag arm leakage in real time on the researcher panel.

Research validity depends on isolation. If Version A and Version B differ in layout, timing, or affordances, the data is noise. The engineering job is to make language the only moving part while the participant experience still feels like a real service.

The codebase shares one component tree per module. Copy lives in isolated i18n namespaces per lane (bankingA2, bankingB, and equivalents for medical and license). Silent server side assignment balances arms without participant cookies. Events, answers, and open text stream to Supabase for CDI scoring and hypothesis charts.

A friends and family pilot ran on vA1 clear language against vB institutional copy. Cognitive Distance Index separated the arms sharply: roughly 1 on clear language versus roughly 38 on institutional copy in the pilot sample. The manipulation did what the theory predicted.

Task time told a different story. vA1 clear language was slower than vB. For a study grounded in cognitive load theory, that is the wrong direction. Clear copy should not cost more time if the only change is register. The pilot surfaced a copy and interaction problem, not a platform problem.

The engineering response was deliberate iteration, not a rewrite. Archive vA1 strings under lib/i18n/archive/a1/. Add prototype_version on participants. Route /banking/a2 alongside a1 and b. Point new assignments at vA2. Keep vB unchanged as the control arm. Preserve vA1 rows in the panel for comparison.

Participants never see their arm. A POST to /api/experiment/assign reads live counts from module_runs, picks the underrepresented variant and module order, and writes variant, order, and prototype_version atomically. Events stream to Supabase as the participant moves. Answers and open text feed comprehension scoring on the panel.

The research dataset stores no PII. Participants get a random identifier. Consent timestamps and locale sit on the row. Every screen transition is an event with module, step, and timing metadata. Post task scales and open explanations land in answers with typed question keys so panel charts do not parse free text twice.

prototype_version is the lineage key. Pilot vA1 rows stay queryable. vA2 rows accumulate for open recruitment. Cloud archive snapshots preserve A1 pilot exports without mixing cohorts in live dashboards.

Most participants arrive on a phone. The welcome funnel detects locale before consent, shows a layered privacy summary, and writes nothing to storage until Agree and start. The question dock keeps the result screen visible while prediction and explanation questions slide up from the bottom. Primary actions stay fixed outside the scroll area so the sheet never hides the commit button.

The panel is where comprehension becomes a number. CDI aggregates open explanations against a rubric. Hypothesis views chart directional comparisons with thresholds printed inline. Every verdict is descriptive until the manuscript claims otherwise. Export is one click for researchers who want their own models.

The A1 vs A2 filter is the iteration dashboard. It answers whether vA2 fixed task time while holding the CDI gap. That is the question the pilot raised, and the platform was built to answer it without a redeploy.

Dynamic segments [version] generate static params for a1, a2, and b. Legacy /banking/a aliases resolve to the active clear language lane (vA2). Flow components accept clearPrototype so researcher previews and participant assignment use the same UI code paths.

Versioning is a data and i18n problem, not a fork. The next copy pass is a namespace diff plus a migration default on assignment. vB stays frozen. vA1 stays archived for comparison. vA2 is what new participants see today.

Next.js 16 App Router, React 19, Tailwind CSS 4, TypeScript throughout. Supabase Postgres with Row Level Security. Vercel deployment with /api/health check. No participant cookies. httpOnly session cookie for researcher access only.

The research question needs a platform that isolates language as the only moving variable. Owning the stack means copy can iterate at the speed of insight. vA2 is live. vB is unchanged. vA1 is preserved. The panel reports whether the iteration fixed task time while the CDI gap holds.

This is design engineering in service of evidence: a study participants trust, a dataset reviewers can audit, and a versioning model that treats wording as deployable infrastructure.