docs(statistics-deck): zero-scroll display model and the projector paradox

gabogg commented

2026-09-24 23:08:05 +00:00

Owner

Problem

The statistics deck proposed in #20 was closed because its content and layout no longer match the plan. The one argument from it that still holds, and the reason the deck needs a new design, is the projector paradox. It was buried in §1.2 of that RFC and never carried into a decision:

Meeting room projectors (70"–120") and flat panels (65"–85") are almost always driven at 1920 × 1080, so a layout that picks "scrolling vs. fits on one screen" by resolution treats a 72" projector as a laptop. Half the figures end up below the fold and the presenter scrolls in front of the room.
Resolution also gets density backwards. A 13" 1080p laptop runs at about 166 DPI, read from arm's length. A 72" 1080p projector runs at about 30 DPI, read from 3–6 m, where a dense layout is the more legible one.

The deck's audience is investors and presentations: meaningful KPIs and graphs about footfall and its trend, not operations or calibration detail.

Approach

Add docs/architecture/rfc-statistics-deck-display-model.md, a new RFC that keeps the paradox and turns it into display rules:

No scrolling on any display: 100dvh, overflow: hidden, minmax(0, Nfr) rows; graphs redraw to their box and thin out labels instead of overflowing.
One closed period per view (Complete Day / Week / Month in facility time), switched by tabs.
Layout profiles chosen by the viewer, never inferred from resolution. Room (projector / large panel: 6 KPIs, 4–5 graphs), Desk (monitor: 4 KPIs, 3 graphs), Laptop (3 KPIs, 1 graph). A profile is a different layout, not a zoom, so 3 periods × 3 profiles = nine designed views.
One 38 px top bar (tabs, profile switch, Fullscreen, back to ops), reclaiming about 90 px. Fullscreen is the primary presentation mode.
A 1080p height budget for Room (38 + 2 + 125 / 572 / 343 px), also checked at the ~960 px of a normal browser window.
Period selector in the top bar (rules from #81 in RFC §5.1); Year period out of scope.
Content direction: KPIs and graphs, no tables, using the current glossary definitions from #68–#71. A candidate KPI and graph set per period is listed for confirmation on real data.
Data-quality marker (RFC §4.1): two tiers, Estimate and Unreliable, driven by the cycle verdict, gap estimates and missing days, never a Data Trust threshold. A top-bar badge plus per-day graph marks, amber only, a numpad * detail panel, always on. Records skip Unreliable days. The occupancy confidence margin stays off the deck.
Small screens stack and scroll below 760 CSS px, the only exception to rule 1.

Not carried over from #20: the metric catalogue, the schemas, the per-period layouts, and its reading of "density" as a font scale.

The old RFC remains readable at refs/pull/20/head (482f827, docs/architecture/rfc-executive-statistics-deck.md).

Mockup

https://claude.ai/artifact/AECeXhQqEWZHEoZYNbmVuL (shared; also linked from the RFC header)

All nine views: period tabs × Room / Desk / Laptop.
Numpad shortcuts: 7 8 9 period, 4 5 6 layout, 0 fullscreen, . period picker, / help (- / + reserved for previous / next period). The ? button in the top bar (or the ? key) shows them on a numpad diagram.
Opens in a "1920×1080 fullscreen" preview that renders a real 1920-px deck scaled to fit; also a 1920×960 browser-window mode and fit-to-window.
Period button at the left of the top bar (WEEK MON 14 – SUN 20 SEP 2026 ▾, numpad .) opens a WIP placeholder picker; selection rules are in #81.
Comparisons use the previous period first (Day: vs last Wednesday) and add last year only when that data exists.
The Month view is about the month only: day by day, running total vs July, peak inside per day, average by weekday, entrance share vs July. Yearly trends are out of scope.
The figures are invented. The back-to-ops control and the data-quality marker are not in the mockup.

#81 (closed): period selection; decisions in RFC §5.1 and CONTEXT.md.
Deck routes, all merged: #82 selectable periods, #83 period summary KPIs, #84 daily totals (absorbs #87 as bucket=hour), #86 per-entrance breakdown, #88 usual-weekday baselines. They sit under a separate read-only /api/statistics/ router.
Statistics rules, merged: #103 Closed Days, #104 partial-period comparisons, #105 baseline sample rules, #106 per-day excluded/trusted and the cycle's own multiplier.
#121 viewer role, merged in #123. #107 wallboard mode (deferred).
Follow-ups from the 2026-09-26 grilling: #128 one ranked cycle verdict (offset resets are not verdicts), #129 marker inputs (records rule, per-bucket gap flag, tier counts, gap intervals), #130 calibration tools move into the configuration tab, #131 retire the routes of the dropped analytics charts (blocked until the deck ships).
#85 (closed): monthly/yearly series, dropped with yearly scope.

Design points

All settled; see RFC §5, dated per session (2026-09-24 triage, 2026-09-25 maintainer decisions and grilling, 2026-09-26 grilling). RFC §6 now lists only what is deferred.

Notes

Status: Accepted (2026-09-26).
Docs only; no code changes. Also adds glossary terms to CONTEXT.md: Complete Period, Partial Period, Weekend Share, Data-Quality Marker and Cycle Verdict. Usual Weekday Baseline and Closed Day came to master with #105 and #103. Rebased onto master on 2026-09-26; pre-commit (ruff, pytest) and scripts/check_docs.py passed.
The RFC sits in docs/architecture/ and is linked from docs/README.md (Architecture and explanation). Accepted by the maintainer on 2026-09-26.

Refs #20

🤖 Generated with Claude Code

## Problem The statistics deck proposed in #20 was closed because its content and layout no longer match the plan. The one argument from it that still holds, and the reason the deck needs a new design, is the **projector paradox**. It was buried in §1.2 of that RFC and never carried into a decision: - Meeting room projectors (70"–120") and flat panels (65"–85") are almost always driven at 1920 × 1080, so a layout that picks "scrolling vs. fits on one screen" by resolution treats a 72" projector as a laptop. Half the figures end up below the fold and the presenter scrolls in front of the room. - Resolution also gets density backwards. A 13" 1080p laptop runs at about 166 DPI, read from arm's length. A 72" 1080p projector runs at about 30 DPI, read from 3–6 m, where a dense layout is the more legible one. The deck's audience is investors and presentations: meaningful KPIs and graphs about footfall and its trend, not operations or calibration detail. ## Approach Add `docs/architecture/rfc-statistics-deck-display-model.md`, a new RFC that keeps the paradox and turns it into display rules: 1. No scrolling on any display: `100dvh`, `overflow: hidden`, `minmax(0, Nfr)` rows; graphs redraw to their box and thin out labels instead of overflowing. 2. One closed period per view (Complete Day / Week / Month in facility time), switched by tabs. 3. **Layout profiles chosen by the viewer, never inferred from resolution.** Room (projector / large panel: 6 KPIs, 4–5 graphs), Desk (monitor: 4 KPIs, 3 graphs), Laptop (3 KPIs, 1 graph). A profile is a different layout, not a zoom, so 3 periods × 3 profiles = **nine designed views**. 4. One 38 px top bar (tabs, profile switch, Fullscreen, back to ops), reclaiming about 90 px. Fullscreen is the primary presentation mode. 5. A 1080p height budget for Room (38 + 2 + 125 / 572 / 343 px), also checked at the ~960 px of a normal browser window. 6. Period selector in the top bar (rules from #81 in RFC §5.1); Year period out of scope. 7. Content direction: KPIs and graphs, no tables, using the current glossary definitions from #68–#71. A candidate KPI and graph set per period is listed for confirmation on real data. 8. **Data-quality marker** (RFC §4.1): two tiers, Estimate and Unreliable, driven by the cycle verdict, gap estimates and missing days, never a Data Trust threshold. A top-bar badge plus per-day graph marks, amber only, a numpad `*` detail panel, always on. Records skip Unreliable days. The occupancy confidence margin stays off the deck. 9. Small screens stack and scroll below 760 CSS px, the only exception to rule 1. **Not carried over from #20:** the metric catalogue, the schemas, the per-period layouts, and its reading of "density" as a font scale. The old RFC remains readable at `refs/pull/20/head` (`482f827`, `docs/architecture/rfc-executive-statistics-deck.md`). ## Mockup **https://claude.ai/artifact/AECeXhQqEWZHEoZYNbmVuL** (shared; also linked from the RFC header) - All nine views: period tabs × Room / Desk / Laptop. - Numpad shortcuts: 7 8 9 period, 4 5 6 layout, 0 fullscreen, `.` period picker, `/` help (`-` / `+` reserved for previous / next period). The `?` button in the top bar (or the `?` key) shows them on a numpad diagram. - Opens in a "1920×1080 fullscreen" preview that renders a real 1920-px deck scaled to fit; also a 1920×960 browser-window mode and fit-to-window. - Period button at the left of the top bar (`WEEK MON 14 – SUN 20 SEP 2026 ▾`, numpad `.`) opens a WIP placeholder picker; selection rules are in #81. - Comparisons use the previous period first (Day: vs last Wednesday) and add last year only when that data exists. - The Month view is about the month only: day by day, running total vs July, peak inside per day, average by weekday, entrance share vs July. Yearly trends are out of scope. - The figures are invented. The back-to-ops control and the data-quality marker are not in the mockup. ## Related issues - #81 (closed): period selection; decisions in RFC §5.1 and `CONTEXT.md`. - Deck routes, all merged: #82 selectable periods, #83 period summary KPIs, #84 daily totals (absorbs #87 as `bucket=hour`), #86 per-entrance breakdown, #88 usual-weekday baselines. They sit under a separate read-only `/api/statistics/` router. - Statistics rules, merged: #103 Closed Days, #104 partial-period comparisons, #105 baseline sample rules, #106 per-day `excluded`/`trusted` and the cycle's own multiplier. - #121 viewer role, merged in #123. #107 wallboard mode (deferred). - Follow-ups from the 2026-09-26 grilling: #128 one ranked cycle verdict (offset resets are not verdicts), #129 marker inputs (records rule, per-bucket gap flag, tier counts, gap intervals), #130 calibration tools move into the configuration tab, #131 retire the routes of the dropped analytics charts (blocked until the deck ships). - #85 (closed): monthly/yearly series, dropped with yearly scope. ## Design points All settled; see RFC §5, dated per session (2026-09-24 triage, 2026-09-25 maintainer decisions and grilling, 2026-09-26 grilling). RFC §6 now lists only what is deferred. ## Notes - **Status: Accepted (2026-09-26).** - Docs only; no code changes. Also adds glossary terms to `CONTEXT.md`: Complete Period, Partial Period, Weekend Share, Data-Quality Marker and Cycle Verdict. Usual Weekday Baseline and Closed Day came to master with #105 and #103. Rebased onto master on 2026-09-26; pre-commit (ruff, pytest) and `scripts/check_docs.py` passed. - The RFC sits in `docs/architecture/` and is linked from `docs/README.md` (Architecture and explanation). Accepted by the maintainer on 2026-09-26. Refs #20 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gabogg added 1 commit

2026-09-24 23:08:06 +00:00

docs(statistics-deck): RFC for the zero-scroll display model

CI / lint-and-test (pull_request) Successful in 1m23s

Details

03f85bc875

Recover the projector paradox from the closed PR #20 RFC and turn it
into display rules for a redesigned statistics deck: no scrolling on
any display, one closed period per view, a viewer-chosen density scale
decoupled from resolution, a single 38 px top bar, and a 1080p height
budget. The per-period content is left open for a separate design pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

#	Decision
Small screens	Stack and scroll below 760 CSS px; the no-scroll rule applies from the Laptop profile up.
Verdict (#128)	One ranked cycle verdict (retroactive audit, then the nocturnal audit as set by the admin trust toggle, then the automatic verdict) decides `excluded` and `trusted` for the marker, the baseline and `excluded_days`. `MANUAL_ADMIN` and `MANUAL_OVERRIDE` offset resets are not verdicts.
Confidence margin	Not on the deck; it stays in the admin calibration tools.
Marker tiers	Estimate: gap estimated or unverified. Unreliable: excluded or missing.
Placement	Period badge in the top bar plus marks on per-day graphs; no per-KPI marks.
Figures	Totals and averages include marked days; records skip Unreliable days.
`min_data_trust`	Ignored by the marker.
Look	Amber only, no hazard red. Estimate: dashed outline and `◇`. Unreliable: grey hatching and `◆`.
Per profile	Room and Desk: full text. Laptop: glyphs and counts.
Day view	Hatch the buckets that overlap a gap; grey out an Unreliable day's graphs.
Detail	Numpad `*` or a click on the badge opens plain-language lines per day; no internal codes.
Hiding	Not possible; the marker is always on.

Rows
Columns

docs(statistics-deck): zero-scroll display model and the projector paradox #80

Problem

Approach

Mockup

Related issues

Design points

Notes

New requirements from the maintainer (2026-09-25), to fold into the RFC

Decisions on the new requirements (maintainer, 2026-09-25)

Decision: the analytics tab's operational charts (maintainer, 2026-09-25)

Open design points settled (grilling, 2026-09-26)