Skip to content

just ux-measure: count what each screen holds, and photograph it (#629) - #636

Merged
BattermanZ merged 1 commit into
devfrom
feature/629-ux-measure
Nov 17, 2026
Merged

BattermanZ merged 1 commit into
devfrom
feature/629-ux-measure

Conversation

@BattermanZ

Copy link
Copy Markdown
Member

Summary

just ux-measure <folder> [--everyday] counts the nine measures of docs/research/ux-reading-crowding-and-finding.md section 3 on every screen, photographs it, and writes one table. Closes #629.

ux-measure
  read the dev database's rows            (read-only, fingerprinted)
  copy the dev library                    (SQLite backup on a read-only connection)
  start two throwaway instances           (debug binary, 127.0.0.1, spare ports)
    library: the copy, signed in as the dev account
    empty:   first Person made here, then an Invite, Kitchen and Cookbook Invites, a recovery link
  open the cooking and share screens once (they change the library)
  for each size × Language                (touch screen but the MacBook)
    for each screen
      open, wait 2 s of stillness, hide the browser's own cards
      photograph (English and French)
      measureInPage: Words, Room, Controls, Unmarked actions, Tap size, Gaps, Type and colour, Length, Notices
      or, at 360 px: text cut off, boxes overlapping, sideways scroll
  stop both instances, remove their folder (on Ctrl-C too)
  write measures.csv, details.json, pictures/
  read the dev database's rows again
 ui/tools/
+├── ux-measure.mjs    # instances, coverage, the run, the table
+├── ux-measures.mjs   # measureInPage: every rule, run in the browser
 ├── dev.mjs           # + toolContext, browserCardTitles, a quiet option to openSettled, the cookie on http://localhost
 ├── dev-session.mjs   # + signInAt
 ├── sizes.mjs         # + AUDIT_PHONES (phone-402, phone-412), MOUSE_SIZES
 └── tools.test.js

Not built as the ticket worded it: an option naming the instance to measure. The tool always starts its own two instances, so no run can reach the dev library by mistake.

Evidence

Run times (full run on the reviewed code):

Set Time
Everyday and empty screens (288 rows) 38 m 52 s, summed from each row's own time in the full run
Full set (444 rows, 55 screens, 320 pictures) 50 m 5 s, build included

An earlier --everyday run on its own, before phones became touch screens, took 34 m 2 s.

Spot check: interface and content words, counted by hand on the short recipe at 402 px in English, against the tool:

By hand Tool
Interface words 51: Kamosu, Cook this, Plan this, Tags, Add a tag, Ingredients, Amounts as written, Change, Method, Related recipes, Relate a recipe, Cooked, "Cooked once · last on 20 Oct 2026", the six acts, Delete this recipe, five tabs 51
Content words 21: title 5, ingredient 6, step 7, source 3 23

The 2 apart are the step's number "1": the interface draws it, but it equals a number in the answer, so the note's exact-match rule counts it as content.

Dev untouched: "the dev database is unchanged" after the full run, read row by row. Nothing was left running and no folder was left behind. A Ctrl-C test by saved PID left nothing either.

Tests: just check and just test in full mode. The tools' tests run measureInPage in Chrome against pages they draw:

small button grown to 48 by an invisible layer   -> not under Tap size
24 px button with no layer                       -> under Tap size, 24 across
two layers overlapping                           -> one pair under Gaps; the one beneath tapped 28 across
recipe title between interface words             -> content, and it ends the sentence
a 1 px box, see-through text                     -> no words
360 px: ellipsis, a parent's clip, tab labels on each other, a 400 px box -> cut off ×2, overlaps ×2, sideways 56

Found on the way, filed:

Merge Danger

Door: two-way

A dev tool and shared helpers for the other dev tools. Nothing Kamosu ships changes.

Blast Radius: dev-tools

just screens, just proto-new and just dev-session now open their browser through toolContext and sign in through signInAt, the same steps moved. just screens still writes its nine sizes. Like just test, just ux-measure builds ui/build, which leaves a running vite answering errors until the next just dev-start.

🤖 Generated with Claude Code

https://claude.ai/code/session_013rPDLiRuBoxYfQJUEtSDrB

The UX audit (#627) needs every screen counted the same way, before and
after each fix. `just ux-measure <folder>` counts the nine measures of the
research note's section 3 on every screen, at the audit's sizes and in
every Language, photographs English and French, and writes one table.

It never touches the dev instance: it copies the dev library into a
throwaway instance of the debug binary, starts a second one empty for the
empty screens and the pages a secret link opens, and removes both, Ctrl-C
included. Phones and the iPad are measured as touch screens.

The dev tools share what the new one needed: a tool's browser window
(toolContext), signing in at an /auth door (signInAt), the browser-card
titles, and the two audit phones in sizes.mjs.

Closes #629

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013rPDLiRuBoxYfQJUEtSDrB
@BattermanZ
BattermanZ merged commit b555483 into dev Nov 17, 2026
1 check passed
@BattermanZ
BattermanZ deleted the feature/629-ux-measure branch November 17, 2026 13:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant