CogniPrep rebuilt a personality questionnaire last weekend so that its screen
matches the real instrument it practises. The instrument is paged: ten
statements to a page, a seven-point agreement scale, and nothing moves on when
you pick an option.

That last part sounds like a detail and is actually the whole design. An
auto-advancing questionnaire is one tap per statement and no way back. A paged
one is a form: you fill it, you can change your mind, and one button submits the
page. Those are different components, not the same component with a flag.

Two things fell out of building it that generalise past questionnaires.

One state, two layouts, two Next buttons

On a laptop the page is a grid: one row per statement, seven labelled columns
across the top, one Next underneath. On a phone that grid is unreadable, so the
same page becomes one statement at a time, options listed down the screen, with
a Next under each statement and the last one opening the next page.

The naive version of this is two components and two sources of truth. What it
actually needs is one reducer with two submit actions:

/** Phone Next: the statement in view must be answered; then the next one, or the next page. */ | { type: 'NEXT_STATEMENT' } /** Desktop Next: every statement on the page must be answered. */ | { type: 'SUBMIT_PAGE' } 

Everything else is shared. Ratings for the page in hand are drafts, held in a
pageRatings array, changeable as often as you like; they become committed
trials only when the page is submitted. So "you can change your mind until Next"
is not a UI affordance, it is where the data lives.

The useful consequence is that the layout rule became testable without a DOM.
The behavioural difference between desktop and phone lives in the reducer, so
the tests are 130 lines of plain state transitions:

splits 90 statements into nine pages of ten does not advance on selection and lets an answer change before Next refuses a desktop Next with a blank and flags it records the final rating of a changed answer, in the order shown walks a phone through the page one statement at a time 

No render, no jsdom, no user-event. If your layout decision cannot be expressed
as a property of a state machine, that is a hint the decision is still in the
markup.

The phone problem is vertical, and Tailwind cannot see it

Here is the part I did not expect to spend an evening on. On a 320x568 phone,
which is still the floor we design to, one statement needs to show: the
statement itself, seven tappable options, a Next button, and a page counter.
Nothing about that is wide. All of it is tall.

Tailwind's entire breakpoint vocabulary is horizontal. sm, md, lg, xl
are all min-width. There is no short or tall. So the fit was done with
arbitrary variants on a height query:

<div class="px-4 py-5 [@media(max-height:640px)]:py-3 sm:px-6 lg:px-8 lg:py-8"> 

Applied, in the end, to five things:

  • vertical padding and the gaps between options, tightened
  • the statement's font size, 16px down to 15px
  • each option's minimum height, min-h-11 down to min-h-9
  • the instruction line under the heading, hidden
  • the heading itself, hidden, because the page counter is already in the header

That last two are the ones worth copying. On a short screen the cheapest
vertical space is text that repeats something already on screen, and the
second cheapest is a heading that says what the page obviously is.

I will be straight about the option height, because 44px is the number everyone
quotes. min-h-11 is 44px, which is the WCAG 2.5.5 target size guideline at
AAA; min-h-9 is 36px. The AA requirement, 2.5.8, is 24px, and these options
are full-width rows with 4px between them, so 36px clears AA with room. It is
still a trade, and the trade is "all seven options visible at once" against
"each option 8px taller, with scrolling". For a scale where the options are
meaningful only relative to each other, seeing all seven wins.

A refusal that happens off screen is a broken button

The desktop grid refuses a Next while any statement on the page is blank, and
marks each blank with the real test's own wording, "Please select an option".

On a short laptop screen the blank can easily be above or below the fold, and
then the user's experience is a button that does nothing. So the click handler
scrolls the first blank into view before it dispatches:

onClick={() => { // Bring the first blank row into view, so on a short // laptop screen the reason Next did nothing is visible. const first = state.pageRatings.findIndex((r) => r === null); if (first !== -1) { rootRef.current ?.querySelector(`[data-tpaq-row="${first}"]`) ?.scrollIntoView({ block: 'center', behavior: 'smooth' }); } dispatch({ type: 'SUBMIT_PAGE' }); }} 

block: 'center' rather than 'start', because a row scrolled to the very top
of a scroller sits under the sticky column headers. Which is the other grid
detail: the header row is sticky against the one scrolling element on the
screen, so the seven column labels stay visible while the rows move, and the
grid itself is a fixed-layout table sized in percentages so that at exactly
1024px the labels wrap instead of pushing the table wider than its column.

Every target is a whole cell or a whole row, never the 16px circle inside it.
And the controls are tinted with a muted background rather than the card
background, because this project's global stylesheet strips the border off
anything whose class list contains bg-card, which is a trap I have written
about before and still walk into.

See it

The questionnaire itself sits behind an account, but its design is described on
its public page, and the card image on the hub is a capture of the real screen.

  1. Open /games/test-partnership/tpaq. The "How it works" section states the layout in the same terms as this post: pages of ten, a grid on a laptop, one statement at a time on a phone, and nothing moving on when you choose.
  2. Open /games/test-partnership and find the questionnaire's card. The picture is the desktop grid, retaken this weekend, which is why it looks nothing like it did last week.
  3. Try the height variant on your own site. Open DevTools, set a custom device of 320 by 568, and add this to any tall component:
 <div class="[@media(max-height:640px)]:hidden">...</div> 

Then go looking for the text on your screens that is already said somewhere
else. On a small phone in landscape, or any phone with a tall browser bar,
that is where the space is.

  1. To use the thing rather than read about it, sign up from cogniprep.app and open the questionnaire on a phone and then on a laptop. It is the same nine pages either way.