Repository navigation
Description
Purpose and relationship to the page plan
Implementation follow-up to #111. The word page must accommodate everything it currently knows without letting any one source or repeated field overwhelm the page. Preserve access to the depth while making the default page compact and readable.
The owner has changed the sequence: Phase 1 is an inventory and alternative whole-page mockups; Phase 2 implements the selected design. Do not begin by shipping definition folds. Definitions remain the first implementation priority after the whole-page layout has been reviewed. This sequence supersedes the implementation-first handoff in #111 for this work; #111 remains the source of the broader rationale, baseline measurements, and constraints.
Principles
- Standardize compact defaults, disclosure, attribution, and access to remaining content across the page. Bound both the length of an item and the number of items shown; a list of individually short previews can still be too long.
- Give each content category appropriate presentation: prose, structured senses, pronunciation variants, forms, origins, related words, posters, images, quotations, and moving GIFs need different treatments. Provider-specific attribution and behavior fit within these category templates.
- Keep short content whole. Long text or numerous variants get a clear preview and access to the complete original. No rewritten or generated summaries, lost attribution, or discarded definitions.
- Current content appears because it is available, not because an editor selected it. Use existing ordering for previews unless a layout change is explicitly selected. Future curation can decide what to highlight and what to put in a secondary view; editorial ranking and its data model are outside this work.
- No new tables, provider changes, or pipeline redesign. Preserve existing source links, provenance drawers, stable identifiers, and browser-only GIPHY transport and safeguards.
Phase 1 — inventory and whole-page mockups only
1. Inventory what the page actually contains
Inspect the current application and representative live pages. Produce a complete inventory, including conditional and sparse states. For each item record its content shape, current position, possible length/count growth, existing controls, and a proposed compact default plus route to the rest.
Starting checklist from the current renderer (verify and extend during the inventory):
- Global header and navigation, word-walk trail, and any conditional page notices.
- Headword, pronunciation variants, parts of speech, forms, each etymology and attribution, redirected-from and also-a-form-of information, and source count/byline.
- All source cards: Johnson and Bierce prose; institutional and crowd definitions; Wikipedia; multiple entries, parts of speech, sense groups, examples, relation chips, thumbnails, authors, source links, and provenance controls where present.
- The culture block: Films, Artworks, Images, Texts, and GIFs; provider bylines, item credits, match evidence/About, load-more/browse controls, and loading, empty, unavailable, and error states.
- Related words and their groups, the thing panel, provenance drawer, and conditional content such as demo material.
- Sparse/bare-word, unknown-word, and ambiguous-word states. These need coverage in the inventory even when they do not need a full mockup.
2. Choose two real words with contrasting content
Use love as the initial content-heavy candidate because #111 already measures it. Inspect the current corpus and choose a genuinely lighter word for comparison; do not assume a candidate is sparse or invent source coverage. Record why these examples are representative, their actual sections, and before measurements at 1280 × 900 and 375 × 812.
The pair should expose both long and short definitions and unequal metadata/shelf coverage. If neither exercises a difficult case such as many pronunciations or multiple entries in a card, add a small clearly labelled fixture for that component rather than pretending it belongs to the chosen word. Reuse the same content snapshots across alternatives so comparisons are fair.
3. Compare three coherent page alternatives
Create reviewable browser mockups of the whole page, using the app's existing visual language and built stylesheet. Cover both chosen words at desktop and phone widths, with light and dark screenshots. Store sketches under docs/sketches/word-page/ and screenshots plus the inventory/comparison under docs/discovery/.
Vary meaningful choices such as section placement, grouping, density, and disclosure. Include an alternative retaining the current broad section order and an alternative bringing culture between historical and modern definitions. The third may explore another coherent grouping or compactness strategy. Do not merely recolor the same layout.
Each alternative must account for every item in the inventory: visible, available through disclosure, or absent because that word genuinely lacks it. Show closed and representative expanded states, including long historical prose, multiple definitions, and overflowing headword metadata. Keep short Bierce entries intact; long Bierce and Johnson entries follow the same content-based rules. A per-entry clamp must not allow a multi-entry card to grow without bound.
Cultural content remains distinct by category: poster films, image/artwork cards, quote-first text, and GIF motion controls within consistent shelf framing. Include the GIF design alternatives from #111 in this review so they do not require a disconnected second design exercise. Demonstrate or annotate playback accurately: in-viewport playback and hover/focus/tap playback are different choices, and the recommendation must resolve that ambiguity. Preserve reduced-motion behavior and explicit playback access, attribution, and existing transport safeguards.
Show proposed section navigation and how it behaves at phone widths. Long pronunciation and form lists must receive deliberate overflow treatment, not be exempted because they are metadata. Avoid hiding the whole page behind undiscoverable controls or simply shrinking text to hit a height number.
4. Measure, recommend, and select
For every alternative, report:
- Total closed-page height in pixels and screens at both viewports.
- First definition and first meaningful image positions; which content is visible in the first viewport.
- Closed heights of the headword, definition cards, and culture block.
- Initial visible item counts, preview limits, and how to reach the rest.
- Behavior with missing sections, long content, keyboard navigation, and reduced motion.
- Trade-offs and a recommendation grounded in the same two words.
Use #111's final ≤ 4 desktop / ≤ 7 phone screens on love as a design target to test, not as a claim that mockups have already achieved it. If preserving readable text and useful previews makes the target unrealistic, report the measured trade-off for the owner to resolve. Expanded original text is intentionally not subject to the closed-state height budget.
Phase 1 exit: complete inventory, verified example words, three whole-page alternatives with screenshots and measurements, a recommendation, and an owner-selected direction recorded on this issue. No production UI implementation in this phase. Resolve page order, disclosure behavior, visible limits, GIF behavior, and final acceptance budgets in the selection.
Phase 2 — implement the selected design
Begin only after the owner selects a direction. Translate that selection into explicit acceptance criteria and implement it in reviewable slices:
- Compact historical definition cards first: short entries whole; long entries excerpted; multiple entries bounded at the card level; expansion restores intact originals. Preserve existing source order except where the selected layout explicitly changes it.
- Extend the agreed rules to pronunciation variants, forms, origins, other definition/sense groups, and related content. Keep limits owned by the page data/presentation policy rather than scattered author-specific rules.
- Implement the selected category templates and culture layout, including quote-first text, working GIF behavior, shared shelf framing, and agreed row caps/browse paths. Maintain provider attribution and evidence requirements.
- Apply the selected page order and section navigation, including responsive behavior and accessible disclosure controls.
Verification and completion
- Verify the same heavy and light examples on desktop and phone, in light and dark; remeasure against the selected budgets and record before/after evidence.
- Verify full-text fidelity, repeated-entry/count limits, keyboard operation, stable IDs, source links, provenance drawers, conditional sections, and GIF reduced-motion/playback behavior.
- Add meaningful component/LiveView and page-data tests for closed previews, quantity limits, expansion, and empty/sparse cases. Extend GIF hook tests if playback changes.
- Run
mix precommit, fix failures attributable to this work, and explicitly identify any independently verified environmental blocker. Run the existing GIF tests when that hook changes. - Update the parent plan with delivered behavior and any reviewed changes to its original targets. Add height attestation/health coverage as agreed in the selected design.
Out of scope
Editorial curation/ranking, choosing which definitions deserve prominence, generated summaries, new provider integrations, changes to provider/pipeline data contracts, and database/schema changes. Source-card merging across parts of speech remains deferred unless separately scoped and approved.
Checklist
- Phase 1: complete content inventory and inspect heavy/light real words
- Phase 1: three whole-page mockup alternatives, both widths and themes
- Phase 1: measurements, recommendation, and owner selection recorded here
- Phase 2: selected definition preview and metadata overflow system
- Phase 2: selected category templates, GIF behavior, page order, and navigation
- Phase 2: functional checks, height evidence, precommit, and parent-plan update
Activity
holden commentedon Sep 20, 2026
Phase 1 — what we have learned, and the direction selected
Measured on
main@6cdfe5b, 2026-09-20, Chrome, every<details>closed, at 1280 × 900 and 375 × 812. Artefacts are on the branchclaude/dictionary-page-mockup-ac2086(not yet pushed): the inventory and the comparison underdocs/discovery/, 28 browser sketches and 76 screenshots underdocs/sketches/word-page/anddocs/discovery/.Where the page stands
/define/love/define/nepotism/define/setlovereproduces #111's measurement to within a pixel. Butloveis not the worst case —/define/setis 44.6 desktop screens: nine parts of speech, five origins, and a Johnson verb card holding 39,955 characters in two entries. No rule in #111 was written against it, and any budget met onloveshould be re-measured there before it is called a budget.The five things the inventory turned up
WordPage. Glosses, chips and chains already have caps and have held. Entries, forms and etymologies have none.loveholds twelve pronunciation rows — nine IPA spellings and three recordings.WordPagekeeps three, builds the regional tags, and the component renders neither the tags nor the other nine. A silent cap is worse than no cap: the reader cannot tell that a word has one accent from a page that shows one.littlehas 66 forms. WordNet filesloveunder six synsets, each bringing a relation row and a broader chain. A rule that only shortens an item lets a generous source spend the whole page.discovery_results.match_details.lines[0].textalready carries the attested line and its number — the shelf just is not showing it.logomachyrenders a heading and No matching film for this term yet. in the position a rail would hold.Three whole-page layouts, measured on the same content
love1280love375Fully expanded, all three are today's page — 13.7–13.9 desktop screens — so nothing is lost, only folded. The nine source cards fall from 12,484 px to 2,748 px at 375 in C; that is where the height lived.
Two separable findings worth keeping whatever is built:
Selected: C, then R5
The owner selected C · the word in a rail, on the strength of its encapsulation. Five variations then held the same page five different ways, changing nothing but the enclosure:
love1280love375R5 is selected. What the measurements say about enclosure generally: it is not free (540 px of desktop between the lightest and the heaviest, all of it padding); it costs most on a phone, where a panel's gutter is spent twice (R2 adds 808 px over R1 at 375); and a background band is the only separation that costs nothing at all.
The rule that falls out of the inventory
Sorting the 41 inventory items by whether their size is knowable in advance produces the layout, rather than the other way round:
Bounded, and roughly the same on every page — these belong in the rail. Headword and pronunciation (one line), parts of speech (one line at nine of them), forms (8 + more), origin (one sentence + more), the source index (one line per source, 2–11 of them), related words (chips, capped at 12), the thing (one concept card).
Unbounded, and set by whatever the source happened to file — these belong in the stream. Source entries (64 to 32,527 characters), sense groups (1 to 27 senses), culture shelves (0 to 49 items).
So: what the page knows the size of goes in the rail; what a source decides the size of goes in the column. The rail is the part of the page that does not move, which is also what makes it worth making sticky — and what makes it safe to grow, because nothing in it can run away.
What is still wrong, and what is next
The rail is currently 18 rem against a 1280 px container, which leaves the content column around 900 px — wider than prose wants and narrower than the shelves want. The available space is not being used. Going back to the Oatmeal kit, its own idiom is not a narrow sidebar but a half-and-half label/content grid (
faqs-two-column-accordion,stats-three-column-with-description), and its disclosure pattern is a one-open-at-a-time accordion. Both are closer to what this page needs than what the sketches currently do.Next round of scenarios, against that vocabulary:
loveand two forset; every one of them being separately expandable is how a card grows without bound. One open, the rest condensed to a line.Open questions for the owner
love. R5 is 5.0 / 8.5. The definitions are no longer where the height is — in the selected direction the nine sources cost 2,748 px of a 6,463 px phone page, and the rest is the rail (522), the culture block (578), related words (600), the thing (472) and a 780 px footer. Reaching 7.0 means trimming the page's furniture, not its content. Accept the measured number, or cut the furniture?No production code has been touched.
mix precommitis green except one pre-existing environmental failure (ManifestTestcannot finddata/in a fresh worktree; with the directory symlinked it passes 11/11).holden commentedon Sep 20, 2026
What the rest of the field does, measured — and where it contradicts the plan
Follow-up to the Phase 1 comment above. Two things prompted this: the page was being designed without looking at anyone else, and the height target was being treated as self-evidently good. Neither survives contact with the evidence.
Full write-up on the branch at
docs/discovery/issue-131-how-others-do-it.md.Method. Nine reference sites measured in headless Chrome for the same word on 2026-09-20, with the same harness that measured our own pages, at 1280 × 900 and 375 × 812, nothing clicked. Honest desktop and mobile user agents, because Wikimedia serves a different page to each and three sites answer a headless UA with a challenge screen. Plus documentary research into the design teams' own published rationale and the e-lexicography literature.
Method caveats, for the record. Collins, Merriam-Webster, Britannica and Google block automated fetching to varying degrees; Google's panel and Rate Your Music are documentary-only and their figures are unverified. During research a consent banner on Cambridge was accepted before being reverted with
OneTrust.RejectAll(); every other site was reject-by-default. Wordnik is thinner than its reputation — its colophon lists six sources butsetrenders only American Heritage 5th today, so the famous five-source stack is largely gone. Don't design from the legend.1. Our page being long is not the finding
The nine run 4.3 to 24.6 desktop screens with a median near 14. Ours is 13.8 — exactly median. The two genuinely short ones are short because they show one dictionary. Merriam-Webster renders 152 senses for
setand Dictionary.com 184, both uncollapsed, on pages of 22,823 px and 25,407 px.What is ours alone is the phone ratio: 13.8 → 22.9 is 1.66, the worst measured, worse than every site that does nothing at all.
And the free advantage: the fold on every ad-supported competitor is mostly advertising. Oxford Learner's shows zero definitions above 800 px, Duden zero, Collins one, Cambridge two. Not selling ads starts us roughly 500 vertical pixels ahead.
2. Three findings that contradict this plan
(a) "Collapse everything on mobile" is wrong, and I said it before checking.
Wikimedia A/B tested precisely that and published the result: the expanded group read for 190 s against 146 s at the 90th percentile, and scrolled more sections into view than control readers ever opened. About 60% of mobile readers never expand a single collapsed section. (Research:Collapsed vs uncollapsed section view on mobile web)
Wikipedia's 24.6 → 4.3 screens is a trade, not a win: a page that fits, read by people who mostly never open it. The IDS elexiko study found the same shape in a dictionary — ratings identical whether examples were shown or hidden, but shown examples were far more likely to be read.
This also qualifies our own accordion. One source open means eight closed.
(b) Nobody collapses senses. Everybody collapses evidence.
Cambridge ships 31 accordions with exactly one open — every one wrapping examples, thesaurus, SMART Vocabulary or translations. Oxford Learner's hides Verb Forms, Extra Examples and Collocations per sense. The OED shows earliest and latest quotation behind Show more quotations. Wordnik has no show more anywhere.
The thing all eleven decline to hide is the thing our accordion hides. Not fatal — none of them places nine sources — but the burden of proof is ours.
(c) Our tier ordering is a historical-first ordering, and that is the worst-scoring pattern in the literature.
Lew, Grzelak & Leszkowicz (2013, Lexikos 23: 228–254) eye-tracked sense selection: of 50 erroneous selections, 35 — 70% — were the user taking sense 1. Only 60% of searches fixated every sense, and reading everything did not help (17% vs 23% error, p = 0.18). Users self-truncate; the page does not need to truncate for them.
McCreary (2008, EURALEX) scored comprehension out of 8: NOAD 7.04, MEDAL 5.89, Merriam-Webster Collegiate — which orders senses historically — 3.96. For aspersion, users of a historically-ordered dictionary scored below the unaided control.
We sort by tier, and the top tier is Johnson 1755 and Bierce 1911. Combined with first-sense bias, which source opens by default is a content decision with measured consequences, not a layout detail — and opening Johnson first may be actively wrong, even though it is the best writing on the page.
3. Findings that validate decisions already made
tabindex="0"and anaria-label, which is the correct manual fix. Keep it. Both instincts people reach for instead (dropping offscreen cards from the tab order,aria-hiddenon a focusable card) are WCAG violations.Bedeutungen (4), WiktionaryLanguages (41), Wikidata collapses each claim's sources as"3 references"— which is why 353 statements fit on one page. Our labels already carry their size. Never replace them with Show more.4. What it says about the selected direction
variables.less: content container 948 px (the published 960 is stale, changed under T335155), rails 196 → 248 px,scroll-margin-heading: 75px. Rails areposition: sticky; top: 24px; max-height: calc(100vh - 48px); overflow-y: auto. Below 1000 px the rail isdisplay: noneand the contents collapse inline above the article.17e siècle— by period, not publisher. For Johnson 1755 and Bierce 1911 that is friendlier than a man's name and warns the reader what kind of text they are about to read, which is a partial answer to the historical-ordering trap.set | American Dictionaryand foots it with the formal credit. Collins shows the failure mode: two of its four blocks are both headed love in American English, distinguishable only by the copyright line. For wholesale public-domain text, Wikipedia's own convention is a bottom-of-page block under a boldAttribution:line, not a per-section badge.Photos 562in the heading → six thumbs → a final tile reading+ 556. And slice the edge item — the peek affordance is the single best-corroborated decision in the survey: NN/g ranks "the illusion of continuity, created by half images" the strongest signifier and calls dots weak; eyetracking found a user "never glanced at the arrows."The humbling one. Wikimedia user-tested a full-page visual redesign on 219 participants and 89% did not notice it at all — only 24 spotted it unprompted. We spent a round comparing five enclosures. That is the evidence the enclosure is the least consequential decision on this page, and the ordering question in §2(c) is the most.
5. Wireframes for the revised direction
W4 — the first screen, 1280 × 900. Rail narrowed to 280, prose to 750, a reference source open by default rather than an 18th-century one, historical sources labelled by period.
W5 — the exclusive accordion.
<details name="sources">, the HTML exclusive-accordion attribute. No JavaScript, and opening one closes the last, so two 4,000-character entries can never both be open.W6 — a shelf, with the count in the heading and the remainder in the tile.
W7 — 375 px. Below 1000 px the rail stops being a rail, exactly as Vector 2022 does. Nothing is collapsed that is not collapsed on desktop — §2(a).
W8 — attribution, two levels. Cambridge's shape, with Wikipedia's convention for the wholesale public-domain text.
6. Revised questions for the owner
Superseding questions 1–4 in the comment above, which the research has changed or answered.
18th century/20th centuryin navigation and headings, with the full name and year in the block?Phase 1 exit needs a decision on 1–4. Nothing in this comment touches production code.
Phase 2 of #131, continued: every rail on screen, and GIFs that move
holden commentedon Sep 21, 2026
Grouping follow-up filed as #133: one row per source in the rail, Wiktionary's orphan
namerow and Wikipedia's place in the accordion, related words split by lexeme (no noun block onlove, duplicaterelated-adjid onset), and the origin block closed by default. Layout from Phase 2 stays; the changes are grouping rules inWordPage.build/2.The review round on #131: twelve findings, and their siblings
Merge pull request #132 from razrfly/claude/dictionary-page-mockup-ac…
holden commentedon Sep 21, 2026
Completed across three PRs: #132 (Phase 1 inventory and comparison, Phase 2 rail, accordion and one culture block), #137 (#133 phases 1–2: one rail row per source, the origin on screen) and #138 (#133 phases 3–4: one related-words block, Wikipedia in the thing panel). All merged to main at 71a7983.