diff --git a/.impeccable/surfaces/cool.md b/.impeccable/surfaces/cool.md new file mode 100644 index 0000000..13ec5e5 --- /dev/null +++ b/.impeccable/surfaces/cool.md @@ -0,0 +1,42 @@ +--- +version: 1 +slug: "cool" +primary_target: "cool" +related_targets: ["/cool/stage", "/cool/city", "/plan"] +--- + +# Surface brief — Cool City decision demo + +## Scope + +Primary: `/cool` (public, person-first route decision). Related: `/cool/stage` (projector keynote), `/cool/city` (cooling-gap module), `/plan` (retail module, linked only). + +## Audience and job + +Ruth, 78, lives alone — a composite, not a real person. She needs bread from Marktplatz on a hot day. The phone answers which way now; the stage tells the room the same story. The audience votes; the model recommends **Accessible for Ruth**. + +## Success + +- `/cool` is minimal: Ruth card, time slider, three route cards with shade and direct-sun minutes, vote buttons. No map dashboard, sensor table, weather card or methodology paragraphs. +- `/cool?vote=1` is only the question and three buttons. No map, no PII. +- `/cool/stage` is a keynote: Ruth card → Cool places → Data honesty → Find routes → 10:00→16:00 → Start vote → Lock vote → City view → Retail module → close. Quiet presenter controls, exact labels. +- The key insight is visible: the shaded route is 732 m / 9.8 min, 50.0% shade but 4.9 direct-sun min versus the shortest 359 m / 4.8 min, 43.8% shade, 2.7 min, with a 15% ramp. The accessible route is 438 m / 5.8 min, 43.8% shade, 3.3 min, no ramp, water and benches. +- Real route/city JSON only; missing values are hidden or TBD. + +## Constraints + +Real data: `public/cool-city/route.json` (normalised from `shade.json`, `routes.geojson`, `places.json`) and `public/cool-city/city-gap.json`. No retail numbers on Cool City. Onyx stays, themed with the system UI stack. Shared time/phase state is in-memory Nitro; vote per round. No PII. Keep SSR, accessibility, reduced motion, build/tests. + +## Direction contract + +THESIS: A live demo, not a dashboard. One decision: which way should Ruth go now? Apple-like clarity — less information, more confidence — with the map as stage content and a minimal phone flow. + +OWN-WORLD: Warm off-white `#F6F3EE`, near-black `#121212`, heat `#E4572E`, shade/water `#2F6FED`, system UI stack, tabular numerals, 28 px translucent surfaces, soft shadows, generous 8-point space, subtle state motion. Stage inverts to `#0B1114` with bright heat and shade. + +STORY: Ruth card. The city has cool places but no route. Three routes; at 10:00 the shortest is fine; at 16:00 shade % and direct-sun minutes disagree. The shaded route takes twice as long for 4.9 sun minutes; the shortest has a 15% ramp; the accessible route is one minute longer with no ramp, water and benches. The room votes; the model recommends **Accessible for Ruth**. Close: "The pulse is not the people. But the city still has to protect them." + +FIRST VIEWPORT: `/cool` — Ruth card, time slider, route cards with accessible first. `/cool/stage` — Ruth card first; then the dark route board at `Find routes`, with the exact labels and presenter strip. + +FORM: Pinned by `COOL_CITY_DESIGN.md` and `presentation/cool-city-demo-script.md`; no roll. `seed: none (pinned)` — "The frontend is a live demo, not a dashboard. Less information, more confidence. ... Apple-like clarity, not an Apple skin. ... full-bleed map ... floating bottom sheet ... one typeface, one accent, subtle motion, immaculate finish." + +FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, DESIGN.md, and every shipping raster carrying its provenance. diff --git a/PRODUCT.md b/PRODUCT.md index 7aa9b7c..0b6da25 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -8,57 +8,62 @@ web ## Users -The primary user is the duty manager of an inner-city Heilbronn retailer who has to decide the next staff schedule. The secondary audience is a hackathon judging room: a presenter on a projector, judges and audience on their own phones, and a presenter operating a control page. +**Primary public user:** Ruth, 78, lives alone in Heilbronn. She is a clearly labelled composite persona, not a real person: the stand-in for an older resident who needs bread, a bench, water and shade on a hot day. The product must work on her phone, one-handed, in bright light. + +**Secondary audiences:** the hackathon room watching a projector; a city climate-adaptation team looking for where shade, water and benches are missing; the retailer who pays for the staffing module. ## Product Purpose -PulseCast turns inner-city footfall into a transparent staffing plan for the coming store week. It exists so a manager can answer one question — who works when, and what does that week cost? — with the forecast, assumptions, uncertainty and trade-offs visible rather than hidden. +Cool City is Heilbronn's public heat-safe route. It tells a person how to reach the places they need — cooler, quieter, step-free — at a given hour, and shows the city where shade, water and benches are missing. The retail staffing plan remains a separate commercial module, not the hero. ## Positioning -Measured footfall becomes a modelled forecast, the forecast becomes a shift board, and the same decision is broadcast to the room. The product shows the cost against a flat schedule and names the overstaffed hours it buys. A neighbouring dashboard could copy the chart; it cannot copy the honest chain from sensor to shift to phone. +The city publishes almost 60 cool places on a map and an address list. It does not turn them into a time-aware, person-level route. Cool City connects the public cool-place map, modelled shade, OSM access features and the existing footfall/weather stack into three route choices a person can act on: shortest, shaded, accessible. It shows the room's vote next to the model's recommendation. A private dashboard cannot truthfully copy the public framing or the person-level route. ## Operating Context -- Heilbronn inner-city store, Europe/Berlin, store hours 10:00–20:00. -- Eight fixed sensors in a roughly 580 m pedestrian cluster; 15-minute cadence. -- Shift blocks of 2–5 hours; default 4 hours; 25 visitors per staff-hour; ×1.15 safety factor; €16/hour labour assumption. -- No POS, sales, queue, payroll or labour-cost feed. Cost is an assumption, clearly labelled. -- The plan heuristic is decision support, not an optimizer. Coverage is at or above requirement by construction because each block is sized to its peak; overstaffed hours are the visible trade-off. -- The demo uses the live Go API. `/control` broadcasts a scenario over SSE; `/stage` and `/live` follow it with a 5-second polling fallback. -- The live plan window currently returned by the API is 14–20 Nov 2026, not next Monday's week. The UI must label the real window and never say "next week" while the data says otherwise. +- Heilbronn inner city. Origin Stadtgalerie, destination Marktplatz. Verify route geometry and place names against OSM and the final route bundle before the demo. +- Three options: shortest; shaded via the Deutschhof passage / Kiliansplatz; accessible with water, benches and step-free access. +- Time stops: 10:00, 12:00, 14:00, 16:00. The recommendation may change with the sun. +- Shade is modelled from solar position and building/tree geometry, not measured. Never claim a temperature difference. +- Sensors are eight inner-city PAX counters: a relative device index, not people. No city-wide heatmap claim. +- Public vote: one vote per random session ID in localStorage; aggregate tally only; no PII, no accounts, no location upload. +- The route/shade bundle lives in `cool-city-data/route/`; the cooling-gap bundle in `cool-city-data/city/`. Final JSON is copied to `public/cool-city/`. If a bundle is missing, label TBD and do not invent values. +- Do not generalise the commissioned FITNAH PET range to every inner-city street. ## Capabilities and Constraints -- Nuxt 4 SSR with Onyx as the component system. Routes: `/`, `/forecast`, `/plan`, `/simulate`, `/about`, `/stage`, `/live`, `/control`. -- `/plan` reads Go `/api/staffing` through Nitro. Local assumption edits are an explicitly labelled preview; they do not change the API plan. -- `/stage` and `/live` follow the live scenario and must show connection state honestly (Live, Polling, Offline) and a last-updated time. -- No new backend behavior, no new dependencies, no fabricated numbers. Read plan values from the API. -- Preserve SSR, keyboard access, contrast, reduced motion, responsive behaviour and the existing build and tests. -- The plan window on 14 Nov 2026 is 14–20 Nov. The paper brief's 5 staff / 210 staff-hours / €3,360 is stale and not reproducible; the reproducible sunny baseline is 5 peak, 172 staff-hours, €2,752 vs €5,600 flat. +- Nuxt 4 SSR + Onyx + MapLibre available. Routes: `/cool`, `/cool/stage`, `/cool/city`, plus the existing retail routes. +- `/cool` is mobile-first and must also read clearly on a projector. `/cool/stage` is a dark, full-bleed projection surface. +- `/cool/city` ranks eight sensor catchments with a relative cooling-gap index and shows the weights and assumptions. No measured temperature map. +- Vote backend: in-memory Nitro route, aggregate counts, one vote per random session ID, stage polls every 2 s. No database, no Go change. +- Keep `/plan`, `/forecast`, `/simulate`, `/about` working. The retail module is linked, not merged into the Cool City hero. +- Preserve SSR, keyboard access, contrast, reduced motion, responsive behaviour, build and tests. ## Brand Commitments -- Name: PulseCast. -- Voice: direct, quiet confidence; honest about what is measured, modelled and assumed. "Staff the pulse, not the noise." -- The visual world is pinned as a **shift board**: paper/ink ground, signal orange for the peak, heavy timetable rules, tabular numerals and physical time blocks. `/stage` inverts to a dark board. -- Onyx remains the component system; default Onyx visuals must not ship. +- Name: **Cool City** (public product). Built on the PulseCast stack; the retail plan remains PulseCast's staffing module. +- Visual world pinned by `COOL_CITY_DESIGN.md`: **a live demo, not a dashboard**. Apple-like clarity: warm off-white ground, near-black ink, heat orange, shade/water blue, one system typeface, generous space, 28 px translucent surfaces and soft shadows, subtle motion. `/cool` is a minimal phone/desktop card flow; `/cool/stage` is a full-bleed dark route board with huge type and quiet presenter controls. The retail module keeps the shift-board identity. +- Voice: public, direct, protective, not promotional. Never present Ruth as a real person without consent. ## Evidence on Hand -- Live Go API at `https://api-pulse.noelsabia.dev` and checked-in mock JSON. -- Baseline screenshots and audit in `/tmp/opencode/audit` (session artefact). -- Tests in `test/` including a captured Go staffing fixture. -- No customer testimonials, no POS data, no city-wide heatmap claim. Do not invent them. +- `COOL_CITY.md` product brief and `Paper/research/cool-city-sources.md` source-checked claims. +- RKI estimate: ~16,000 heat-related deaths in Germany in 2026 through KW37 (95% PI 14,400–17,600). Say estimated, not a count; not Heilbronn. +- FITNAH-3D commissioned model: citywide PET 16.1–44.5 °C; unshaded sealed street space can exceed 41 °C PET. Do not generalise. +- City: almost 60 cool places; map + address list, not a routing or time-aware service. 2021 climate-adaptation concept adopted 2023 with 31 measures; 2025 spatial concept; 2023 heat-health action package. Do not say no heat action plan. +- City tree cadastre Jan 2026 (dl-de/by-2.0); OSM (ODbL); Open-Meteo (CC BY 4.0); population by planning district aggregate. +- The route/shade and city bundles are pending. Use a clearly labelled TBD placeholder; no fake numbers. ## Product Principles -1. Answer first. The peak shift, staff count, cost and coverage are the first reading order on every decision surface. -2. Show the chain. Measured, modelled and assumed are visibly different things. -3. One plan, every surface. The stage, the phone and the plan are the same numbers, propagated live. -4. Keep the trade-off visible. Overstaffed hours and uncertainty are part of the answer, not a footnote. -5. Earn the projector and the phone. Ten-metre legibility and one-thumb clarity are design constraints, not afterthoughts. +1. Public first. The hero is a person trying to reach a place safely, not a retailer's dashboard. +2. The hour matters. A route is not cool in the abstract; it is cool at 14:00 or 16:00. +3. Modelled is not measured. Shade coverage and direct-sun minutes are model outputs; say so. +4. The room is part of the product. The vote is aggregate, anonymous and shown next to the model. +5. The city only sees what the person reveals. The cooling-gap module is a relative planning aid, not a temperature map. +6. Keep the retail proof separate. The staffing module is the commercial layer, not the public story. ## Accessibility & Inclusion -WCAG 2.2 AA. Keyboard access for all controls and scrollable data; visible focus; 4.5:1 body text and 3:1 large text; no colour-only meaning; reduced-motion alternatives; touch targets at least 44×44 px where practical; stage text legible from 10 m. +WCAG 2.2 AA. Keyboard and visible focus for the time control, route cards and vote; 4.5:1 body text and 3:1 large text; no colour-only meaning; reduced-motion alternatives; 44 px touch targets; stage text legible at 10 m; phone-first reading order with no horizontal page scroll. diff --git a/README.md b/README.md index 0a4e3e9..6b91238 100644 --- a/README.md +++ b/README.md @@ -167,6 +167,9 @@ deployed path are the real API. | Route | Purpose | | --- | --- | +| `/cool` | **Cool City public hero.** Ruth card, time, three real route options, vote buttons; `/cool?vote=1` is the minimal audience vote page | +| `/cool/stage` | **Cool City projector.** Ruth card, cool places, data honesty, route board with exact labels, live vote, city view, retail link | +| `/cool/city` | Cooling-gap module: eight ranked catchments, one-line reasons, top block and “What would help” | | `/` | Landing: the live shift board, peak shift, cost vs flat, coverage and the measured/modelled/assumed chain | | `/forecast` | 7-day daily forecast, uncertainty band, weather strip | | `/plan` | **Hero.** Peak decision, weekly shift board, coverage, cost vs flat, settings, hourly detail | @@ -179,6 +182,20 @@ deployed path are the real API. The layout targets **390 px** (single column, mobile Onyx nav, day cards) and **1440 px** (Onyx horizontal nav, two-column plan with tables). +### Cool City demo data and state + +- `/cool` reads `public/cool-city/route.json`, normalised from + `cool-city-data/route/shade.json`, `routes.geojson` and `places.json`. + `/cool/city` reads `public/cool-city/city-gap.json`. +- Vote and demo state are in-memory Nitro routes: `GET/POST /api/cool/state`, + `GET/POST /api/cool/vote`, `POST /api/cool/reset`. `round` is + `preselection` or `final`; votes never mix. The stage and phones poll every + 2 seconds. No database and no PII. +- Stage labels: `Cool places`, `Data honesty`, `Find routes`, `Shortest`, + `Shaded`, `Accessible`, `Start vote`, `Lock vote`, `City view`, + `Retail module`, `Reset round`. The model recommendation is + **“Accessible for Ruth”**. + ## Plan logic `shared/staffing.ts` is the single implementation of the contract heuristic: diff --git a/app/app.vue b/app/app.vue index 817438d..e362870 100644 --- a/app/app.vue +++ b/app/app.vue @@ -14,7 +14,14 @@ const usingMock = computed(() => { return value === true || value === '1' || value === 'true' }) -const isPresentation = computed(() => route.path === '/stage' || route.path === '/live') +const isCool = computed(() => route.path.startsWith('/cool')) +const isDarkPresentation = computed( + () => route.path === '/stage' || route.path === '/live' || route.path === '/cool/stage', +) +const isStandalone = computed(() => isCool.value || isDarkPresentation.value) +const bodyClass = computed(() => + isDarkPresentation.value ? 'pc-presentation' : isCool.value ? 'pc-cool-presentation' : '', +) const navigation = [ { to: '/', label: 'Now', icon: iconHome }, @@ -30,7 +37,7 @@ const activeLabel = computed( ) useHead(() => ({ - bodyAttrs: { class: isPresentation.value ? 'pc-presentation' : '' }, + bodyAttrs: { class: bodyClass.value }, })) // Onyx renders its overflow navigation as a `menubar` whose direct child is a @@ -51,7 +58,7 @@ onBeforeUnmount(() => navRoleObserver?.disconnect())