Skip to content

Word page height and shelf templates: fold the prose, one template per content type, the world above the fold — measured on /define/love, phased #111

Open

Description

@holden

Active implementation follow-up

#131 is the dedicated implementation issue. The owner has selected a mockup-first process: Phase 1 inventories the whole current page, compares three layouts using a content-heavy and a lighter real word, and records an owner-selected design; Phase 2 implements that design, beginning with definition cards. This supersedes the implementation-first handoff and phase ordering below. Pronunciations, forms, etymologies, all definitions, cultural shelves, and conditional sections are part of the inventory and compact-presentation system. This issue remains the broader rationale and baseline; its original wireframes and limits are inputs to the mockup comparison, with any selected changes recorded in #131.

Purpose

/define/love is 13.8 screens tall on a desktop and 22.9 screens on a phone, and the first picture on it arrives at screen 10 (desktop) and screen 18 (phone). Nothing on it is wrong; everything on it is unfolded. This issue measures where the height goes, decides what the page's first screen owes a reader, gives the content types that still need one their own card, and sequences the work so each phase lands on its own.

Refreshed 2026-09-20 against main @ 6cdfe5b, after #109, #116 and #126 landed. Three of the original premises were done by that work and are struck below; the numbers were re-measured; the GIFs shelf's redesign (three versions, owner picks) is folded into Phase 2, where L4 and L6 already put it. Design lineage is #66 (the descent through the tiers) and #67 (the evidence wall); both stay open as direction, nothing here is blocked on them, and this issue is the plan for the page they describe.

Handoff prompts, one line each: "Do Phase 1 of this issue", "Do Phase 2 of this issue", "Do Phase 3 of this issue".

Implementation clarification — compact presentation before curation

Updated after the owner's discussion on 2026-09-20. This remains the overall page plan. Start with the closed state of the historical definition cards, then extend the same approach to the rest of the page. Definitions are the first implementation slice, not the full scope of the space problem.

A shared system for variable-length content

Every section needs a deliberate compact default and a way to access its remaining content. Apply this to prose definitions, lists of senses, pronunciations and their variants, forms, etymologies, related-word lists, and cultural shelves. Content should not consume unbounded vertical space simply because a source returns more of it.

The shared rules are:

  • Bound both length and quantity. Shortening each item is insufficient when a card contains many items. Set an overall closed-state budget for a card or section as well as an appropriate preview length or visible-item count.
  • Keep short content whole. Expand only when necessary, with a clear label indicating what remains. Preserve the original text, attribution, source links, and access to the complete content.
  • Use content-appropriate presentation. Consistent disclosure and framing do not mean identical cards: definitions use text previews, pronunciation variants use a compact visible selection with access to the rest, films use posters, quotations lead with the matched line, and GIFs need motion controls. Provider-specific requirements fit within the content type's presentation.
  • Choose and verify limits with real examples at both widths. Pronunciations, forms, and other metadata need their own measured limits; the six-line prose preview is not a universal rule. Existing behavior that keeps all forms or pronunciations visible is not an exemption from the overall compact-default requirement.

Immediate slice: compact historical definition cards

Begin Phase 1 with Johnson and Bierce using the shared source-card behavior, rather than author-specific truncation rules. A short Bierce entry stays whole; a long Bierce or Johnson entry gets a bounded excerpt and an explicit expansion to the intact original. Where a card contains multiple entries, the whole card must remain bounded rather than granting every entry a separate full preview allowance.

Validate short Bierce, long Bierce, long Johnson, and a card containing multiple entries on desktop and phone. Preserve the existing source order, source links, drawer access, and stable identifiers. This slice does not merge cards across parts of speech or change the underlying content.

Judge this first slice by the compact cards and faithful expansion. Record its effect on page height, but do not require it alone to meet the whole-page height target. Continue Phase 1 with origin and other headword overflow, including pronunciation and form lists, then carry the same rules through the remaining definition types and sections. Separate follow-up slices can use this issue as their governing plan.

Presentation now; editorial selection later

Sources currently appear because matching content is available, not because their entries have been individually curated. The immediate work changes how much is exposed by default, not which definitions are judged valuable or worth highlighting. Retain current source order and use a deterministic preview of the original content; do not generate rewritten summaries or introduce editorial ranking in this work.

Future curation may choose which definitions are highlighted and place others behind a secondary disclosure or view. The compact presentation should support that later selection without requiring curation to exist first. Editorial selection, ranking, and its data model are outside this issue.

How this qualifies the existing plan

  • The first implementation slice is the historical definition cards above. The rest of Phase 1 remains follow-on work, with headword overflow broadened beyond etymology alone.
  • L1's final ≤ 4 desktop / ≤ 7 phone screens is the overall plan's final target. Phase 1's ≤ 6 / ≤ 10 is its intermediate target after the broader Phase 1 work, not a gate for the first card-only slice. The statement that the final budget gates every phase is superseded by these staged targets.
  • L2's initial six-line preview is a starting point to verify, not permission for repeated entries or groups to grow a card indefinitely. Full expanded text is intentionally uncapped; any cap assertion concerns the closed preview, not the complete original.
  • L3's statement that forms and pronunciations stay means the information remains available. Their default visible length and count must also be bounded when they overflow.
  • The category-specific shelf work, GIF design choice, page-order decision, and jump bar remain later work under this plan.

Schema impact

0 new tables, 0 changes to existing tables, all phases. This is lib/devils_dictionary_web/, assets/js/ and the ContentTypes data table; WordPage.build/2 may gain a cap, never a column. No provider file.

Where it stands — measured 2026-09-20 on main @ 6cdfe5b, /define/love

Chrome, document.documentElement.scrollHeight and getBoundingClientRect() per section, every <details> closed (the reader's default), on the owner's dev server at the merged main.

Section (#id) 1280 × 900 px screens 375 × 812 px screens what it is
headword 633 0.7 1,069 1.3 lemma, 5 parts of speech, forms, two etymologies of ~700 chars
card-johnson-noun 3,816 4.2 5,532 6.8 one prose entry, 4,746 chars, uncapped
card-johnson-verb 1,148 1.3 1,632 2.0 one prose entry, 1,385 chars
card-bierce 212 0.2 472 0.6 the page's reason to exist
card-wordnet-noun + -verb 1,212 1.3 1,924 2.4 11 synsets, relation rows, chips capped at 12
card-wiktionary-* (3) 732 0.8 1,148 1.4 glosses capped at 3, folded
card-wikipedia 544 0.6 1,776 2.2 2,566 chars of summary prose
in-culture — four shelves 1,378 1.5 1,518 1.9 Films 360 · Artworks 376 · Texts 228 · Images 372 (demoted last on this page: search-only, #126 D1)
giphy-* 328 0.4 332 0.4 its own chrome beneath the block; a row of stills, nothing moves
related-* 312 0.3 600 0.7
thing 341 0.4 429 0.5 a picture of love (Romeo and Juliet), below the fold by 13 screens
page 12,382 13.8 18,562 22.9 first image at 9,005 px / screen 10 (desktop), 14,317 px / screen 18 (phone)
scroll map, 1280×900, one █ ≈ 0.25 screen

headword         ███
johnson noun     █████████████████
johnson verb     █████
bierce           █
wordnet          █████
wiktionary ×3    ███
wikipedia        ██
culture block    ██████      ← four shelves, one section, since #109/#116/#126
gifs             █           ← second chrome
related          █
thing            ██

Against the 2026-09-18 measurement: the page lost 1.2 screens on phone and 0.1 on desktop, all of it from #artwork-candidates leaving the page (#109 K2) — the culture block gained three shelves in the same span. The definitions did not move. Johnson + Wikipedia are still 6.1 of 13.8 screens on desktop and 11 of 22.9 on phone.

The findings, in the order they cost

  1. Prose entries are uncapped. Word.source_card/1 renders entry.body_html whole. Glosses have a cap, chips have a cap, prose has none. Johnson's noun entry is 4.2 screens by itself; the full text already has two homes (the ⓘ drawer and /sources/johnson), so the card is a third copy.
  2. The headword block is a page. Two etymologies at ~700 characters put the first definition below the fold on a phone. Origin is a fact about the word, not the definition of it.
  3. The visual reason to be on the page arrives at screen 10 on desktop and screen 18 on a phone. The culture block now carries four shelves and 40-odd images, and every one of them is under nine screens of prose.
  4. Two chromes for one kind of thing. The four pipeline shelves share one chrome (Shelf appearance: one chrome per shelf, one-line credits, and what a search-only shelf is allowed to be #126: one heading, a byline of names, one About, one Load more per shelf). The GIPHY shelf is still its own component with its own heading, status and button, 400 px below them, and its GIFs never move: a row of stills is a broken GIF shelf.
  5. No way to jump. 16 sections, no in-page navigation, no way to reach Related words without passing Johnson.
  6. Nothing measures it. U4 attests 375 px width; no row attests height. This is why the page drifted from the Design: Definition page — three-tier definitions + community evidence wall (wireframes, UI, UX) #66 wireframe (one screen, three tiers, one evidence row) to 14 screens without anyone deciding to.

Struck since 2026-09-18, done elsewhere: #artwork-candidates left the page (#109 K2) · one shelf chrome with Load more appending into the row (#126 D3, D5's first half) · the ContentTypes table carries attribution and evidence (#116) · text cards have no image slot and a wider column (#109 3b) · credits are one line, linked, unclamped (#126 D2/D3) · a search-only shelf demotes to last with one page (#126 D1).

Decisions (defaults; change them here, not in a chat)

The GIFs shelf, three ways (Phase 2's first half)

What the GIFs shelf is and what may not change: browser-only, its own component and hook, nothing ever written to the database or browser storage (K10), the Powered by GIPHY mark visible in every version, media never rehosted, the search G-rated, the hook's URL guards, three-page cap, ten-second timeout and reduced-motion handling all kept. The key allows 100 requests an hour for everyone; every page view spends one.

  • A. Same chrome as every other shelf. Heading, byline naming GIPHY beside its mark, one Matches for love · About these results explaining these are search results, one Load more, cards at the shared column width and type scale, Play as an overlay on the still rather than a text button.
  • B. Motion on intent. Stills by default; a GIF plays while hovered or focused on a pointer device and on tap on touch, pauses when the pointer leaves, never plays under prefers-reduced-motion. Frames use the GIF's own aspect at a fixed height rather than a square crop.
  • C. Compact strip. Smaller tiles, more per row, no visible titles (GIF titles are tag soup); title and link reachable through the About disclosure and the tile's aria-label; one Play-all control for the strip.

Produced as static HTML under docs/sketches/gifs-shelf/ loading the app's built stylesheet, screenshots at 1280 and 375 in light and dark under docs/discovery/, and a comment on this issue with the trade-offs, the measurements (tile size, rows per card at 375, GIFs in the first viewport, how the shelf reads with and without motion) and a recommendation. The owner names a version on this issue before it is built. L4's :motion default (plays in view) is version B's behaviour; A and C are chrome and density choices that can combine with it.

Wireframes

W1 — Target, 1280 × 900, the first screen

┌────────────────────────────────────────────────────────────────────────────────┐
│ wordhoard                                                                  ☾   │
│ Definitions · In the world · Related · The thing                 ← L8 jump bar │
├────────────────────────────────────────────────────────────────────────────────┤
│                                                                                │
│  love   /lʌv/                               noun · noun · verb · name · name   │
│  forms  loue · loved · loves · loving · luv                                    │
│  origin From Middle English love, from Old English lufu …  ▸ more     ← L3     │
│  Defined here by 6 sources                                                     │
│                                                                                │
│  ┃ 👑 Samuel Johnson · 1755 · noun                                    ↗ ⓘ     │
│  ┃ LOVE. n. s. [from the verb.] 1. The passion between the sexes.              │
│  ┃ Hairbreadth 'scapes i' th' imminent deadly breach … ── six lines ──         │
│  ┃ ▸ Read Johnson's full entry · 4,700 characters                     ← L2     │
│                                                                                │
│  ┃ 👑 Ambrose Bierce · 1906                                            ↗ ⓘ     │
│  ┃ A temporary insanity curable by marriage …                                  │
│                                                                                │
│  OUT IN THE WORLD                                                     ← L6/L7  │
│  Films                                        CineGraph · keywords: TMDb       │
│  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌──                   │
│  │2:3 │ │    │ │    │ │    │ │    │ │    │ │    │ │    │ │   → scrolls, L5     │
│  └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └──                   │
│  title · 2026   …                                                              │
└────────────────────────────────────────────────────────────────────────────────┘
   screen 2 ↓  Artworks (square) · GIFs (moving) · Texts (quote) ·
              📚 WordNet, Wiktionary, Wikipedia — folded · Related words · The thing

W2 — A folded entry card (L2), closed and open

┃ 👑 Samuel Johnson · 1755 · noun                              ↗ ⓘ
┃ LOVE. n. s. [from the verb.]
┃ 1. The passion between the sexes.
┃    Hairbreadth 'scapes i' th' imminent deadly breach …
┃ 2. Kindness; good-will; friendship.
┃    God brought Moses into the love of …                       ← line-clamp: 6
┃ ▸ Read Johnson's full entry · 4,700 characters

                    ── opened (a <details>, URL unchanged) ──

┃ 👑 Samuel Johnson · 1755 · noun                              ↗ ⓘ
┃ … the whole entry, as today …
┃ ▾ Fold Johnson's entry

W3 — Shelf templates by content type (L4)

Films · CineGraph                          Artworks · The Met · Wikidata
┌──────┐ ┌──────┐ ┌──────┐                 ┌────────┐ ┌────────┐ ┌────────┐
│      │ │      │ │      │  2:3 poster     │        │ │        │ │        │  1:1
│      │ │      │ │      │                 │        │ │        │ │        │
└──────┘ └──────┘ └──────┘                 └────────┘ └────────┘ └────────┘
The Inviting          Honeymoon             Cupid and Psyche       Antiochus and…
2026 · Film           2027 · Film           Gérard · 1798          Ingres · 1840
▸ Matches for "love" · About these results  ▸ Why these · 4 depict Q316 "love"  ← once

GIFs · Powered by GIPHY                     Texts · PoetryDB
┌────────┐ ┌────────┐ ┌────────┐            ┌──────────────────┐ ┌──────────────────┐
│ ▶ plays│ │ ▶ plays│ │ ▶ plays│  1:1,      │ "Love is not love │ │ "How do I love   │
│ in view│ │ in view│ │ in view│  moving    │  which alters…"   │ │  thee? Let me…"  │
└────────┘ └────────┘ └────────┘            │ Sonnet 116        │ │ Sonnet 43        │
Happy In Love GIF     Kiss You Love GIF     │ Shakespeare       │ │ E. B. Browning   │
(reduced motion: still, with Play)          └──────────────────┘ └──────────────────┘
                                            no image slot; the line is the picture

W4 — 375 × 812, first two screens

┌───────────────────────┐   ┌───────────────────────┐
│ wordhoard          ☾  │   │ 👑 Bierce · 1906   ↗ ⓘ│
│ Definitions · World · │   │ A temporary insanity  │
│ Related · Thing       │   │ curable by marriage.  │
├───────────────────────┤   │                       │
│ love  /lʌv/           │   │ OUT IN THE WORLD      │
│ noun · verb · name    │   │ Films                 │
│ forms loved · loves … │   │ ┌───┐ ┌───┐ ┌───┐ ┌─  │
│ origin From Middle …▸ │   │ │   │ │   │ │   │ │   │
│ 6 sources             │   │ └───┘ └───┘ └───┘ └─  │
│                       │   │ Artworks              │
│ 👑 Johnson · 1755 ↗ ⓘ │   │ ┌───┐ ┌───┐ ┌───┐ ┌─  │
│ LOVE. n. s. 1. The    │   │ │   │ │   │ │   │ │   │
│ passion between the   │   │ └───┘ └───┘ └───┘ └─  │
│ sexes. Hairbreadth…   │   │ GIFs                  │
│ ▸ Read the full entry │   │ ┌───┐ ┌───┐ ┌───┐ ┌─  │
└───────────────────────┘   └───────────────────────┘
        screen 1                    screen 2

Phase 1 — Fold the long things (one session; start here)

No shelf, no provider, no order change. word.ex, word_page.ex, one CSS rule, tests.

  1. L2: @entry_cap in WordPage (characters, so a test can assert it without a browser); Word.source_card/1 clamps the entry with line-clamp-6 and renders Read {author}'s full entry · N characters as a <details> when the body exceeds the cap. Wikipedia's card takes the same fold.
  2. L3: etymology folds to its first clause with origin ▸; the #etymology-N ids and the drawer are unchanged.
  3. L1: the height test — WordPage asserts every card's unfolded text is under the cap; a dated 1280 × 900 and 375 × 812 attestation of /define/love under docs/mobile/ with the numbers in this issue's table as the before.
  4. Nothing else moves.

Exit: precommit green apart from the environmental manifest test; /define/love ≤ 6 screens at 1280 × 900 (from 13.8) and ≤ 10 at 375 (from 22.9); Johnson's noun card under 0.5 screens closed and identical to today opened; every #card-*, #etymology-*, ⓘ and ↗ id unchanged so no existing test moves; the first image on the page under screen 5 on desktop.

Why first: it is 40% of the page in one component, it has no dependency on anything, and every later phase should be judged against a page that is already short.

Phase 2 — The culture block: one chrome, and the GIFs that move (one session, in two halves; owner picks between halves)

First half, no production code: the three GIFs sketches above, screenshots, the comment, the recommendation. Stop and wait for the pick.

Second half, after the pick:

  1. L4: ContentTypes gains card; Culture dispatches on it; the :text row's :quote card puts the matched line first.
  2. L4 gif, in the picked version: giphy_shelf.mjs gains the IntersectionObserver (or the pointer/touch intent of version B), prefers-reduced-motion keeps today's behaviour exactly, every existing guard stays, node --test assets/js/giphy_shelf.test.mjs green and extended.
  3. L6: one Out in the world block; GiphyShelf.section/1 renders inside it with the shared heading, byline, About and Load more styles, keeping its hook and phx-update="ignore".
  4. L5's second half: the row cap at 24 and the browse link after it.

Exit: five shelves, one header, one chrome; a GIF moves as the picked version says and not otherwise; a reduced-motion browser sees stills and Play; the block is under 2 screens with every shelf present; no component under discovery/providers/; conformance green including the multi-source and fold checks, whose ids may not move.

Phase 3 — Order and the jump bar (half a session; owner confirms L7 first)

  1. L7: the culture block moves between the aristocracy cards and the institutional cards. One :for moves in word_live.ex render/1; WordPage already sorts cards by tier so the split is Enum.split_while(&(&1.tier == :aristocracy)).
  2. L8: the jump bar, rendered from the sections present; scroll-margin-top on each target.
  3. Re-attest L1: the two dated screenshots redone; the budget (≤ 4 / ≤ 7) is now the number to hit, and the Health.Score row lands.

Exit: the first screen at both widths shows the headword, Johnson folded, Bierce whole and the first shelf row (W1, W4); the budget holds; U4's twelve screenshots are unaffected.

Checklist

Activity

  1. holden commented on Sep 20, 2026

    @holden
    MemberAuthor

    Refreshed 2026-09-20 against main @ 6cdfe5b, after #109, #116 and #126.

    Re-measured /define/love: 13.8 screens at 1280 × 900, 22.9 at 375 × 812, first image at screen 10 and screen 18. Since the 09-18 measurement the page lost only what #artwork-candidates took with it; the definitions did not move, and Johnson + Wikipedia are still 6.1 of 13.8 desktop screens.

    Struck as done elsewhere: candidates leaving the page, one shelf chrome with Load more into the row, the table's attribution and evidence columns, the text card's slot and column, one-line linked credits, the demoted search-only shelf. Kept: L1 budget, L2 fold, L3 origin, L7 order, L8 jump bar, and L4/L6 reduced to what remains — the card variant, the quote-first text card, GIFs that move, and the GIPHY shelf inside the culture block.

    New: the GIFs shelf's redesign is Phase 2's first half — three sketched versions, screenshots, a recommendation, and the owner's pick before anything is built. Phase 1 is unchanged and is still where to start.

  2. holden commented on Sep 27, 2026

    @holden
    MemberAuthor

    Page-height cost of #212 Build 2 (PR #223: "Why this example is here" on the exemplar card, and a line on the person page).

    Measured the way this issue measures: document.documentElement.scrollHeight and getBoundingClientRect(), with every <details> closed.

    Viewport Page, before → after Screens #examples, before → after Per card, closed Per card, opened
    1280 × 900 3,284 → 3,340 px 3.65 → 3.71 581 → 637 px +28 px +240 / +192 px more
    375 × 812 5,063 → 5,159 px 6.24 → 6.35 961 → 1,057 px +48 px (a 44 px tap target) +712 / +544 px more

    The person page's cited as panel gains one line per published selection:

    • +24 px at 1280 (page 1,854 → 1,878 px);
    • +56 px at 375 (page 2,332 → 2,388 px).

    Closed, the disclosure costs one line per exemplar card and nothing else. Opened, its six rows stack on a phone, so the open cost is concentrated at 375.

    Almost no live page draws an exemplar card yet. The dev database has 5 current illustrates claims (2026-09-27).

    Captures and method are in docs/design/issue-212/ on #223's branch.

  3. holden commented on Oct 7, 2026

    @holden
    MemberAuthor

    Page-height cost of #212 Build 3 (PR #235: an exemplar in the curated opening). Measured as this issue measures: document.documentElement.scrollHeight, with every <details> closed.

    The opening renders only behind the development gate (?opening=fixture), so no public page pays for it. Behind the gate, /on/coward, which has one exemplar shown and two withheld, measures:

    Viewport Page without the fixture → with it #opening closed → open
    1280 × 900 3,181 → 3,460 px (+279) 263 → 875 px
    375 × 812 4,848 → 5,279 px (+431) 399 → 1,573 px

    Light and dark measure the same. On a phone, the opening's "Why this…" summaries are now 44 px tap targets (min-h-11 sm:min-h-0; they were 28 px). Captures and method: docs/design/issue-212/README.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions