Hugging Face's logo

Spaces:
lablab-ai-amd-developer-hackathon
/
riprap-nyc
Running

App Files Community
riprap-nyc / docs /design_handoff /README.md
seriffic's picture
seriffic
docs: replace handoff bundle with v0.4.5 spec
79cf005
preview code
|
raw
history blame contribute delete
22.2 kB

Handoff: Riprap Findings Region

Current target version: v0.4.5 (polish on v0.4.4 — now applied in Riprap Stone-Grouped UI v0.4.5.html). See V0.4.5_SPEC.md for the nine deltas. This README is the v0.4.4 specification and remains the reference for everything not changing in v0.4.5.

Read order for the implementer:

  1. CLAUDE_CODE_PROMPT.md — paste into Claude Code
  2. V0.4.5_SPEC.md — the nine fixes (now realized in v0.4.5.html)
  3. README.md (this file) — v0.4.4 reference
  4. design_files/ — prototypes (both v0.4.4 and v0.4.5 HTMLs are present)

Overview

Riprap is a citation-grounded Flood Exposure Briefing tool for New York City. A user enters an address, neighborhood, or proposed development; Riprap returns a written briefing where every numeric claim links to its primary public-record source (FEMA, USGS, NYC DOITT, FloodNet, NYC OpenData, etc.).

This handoff covers the Findings region — the structured-data sibling of the briefing prose. It groups model outputs into five named "Stones" (cognitive roles), each rendered as a card stack with explicit epistemic tiering, smart provenance traces, and cross-linking to the map.

The target codebase is SvelteKit (Svelte 5 with runes). The files in design_files/ are React-based prototypes — design references, not production code. Recreate them as Svelte components.

About the Design Files

The files in design_files/ are design references created in HTML + React — high-fidelity prototypes showing the intended look and behavior. They are not production code to copy directly.

Your task is to recreate these designs in the existing Svelte codebase, using its established patterns (Svelte 5 runes, scoped styles, the project's existing route structure and data layer). Lift visual values, copy, and interaction logic from the references; do not transpile JSX to Svelte.

File pairing (each prototype area has one or two source files):

  • Riprap Stone-Grouped UI v0.4.4.html — main prototype, the v0.4.4 Findings region in context
  • findings.jsx — Findings region: stones, cards, run-health, grammar reference (the centerpiece of this handoff)
  • briefing.jsx — long-form briefing prose with inline citations
  • map.jsx — mini-map with FEMA AE / HWM / FloodNet / 311 / address layers and link highlighting
  • trace.jsx, stones-trace.jsx, stone-evidence.jsx — provenance trace variants
  • shell.jsx — app header, footer, cold-start state
  • glyphs.jsx — four tier glyphs as inline SVG
  • tokens.css — design tokens (colors, type, spacing). Port verbatim.
  • styles.css — component CSS. Reference only; rewrite as scoped Svelte styles.
  • tweaks-panel.jsx, design-canvas.jsx, landing-variants.* — prototype-time tooling. Ignore.

Fidelity

High-fidelity (hifi). Pixel-perfect mockups with final colors, typography, spacing, glyphs, and interactions. Recreate the UI pixel-perfectly using the codebase's existing libraries and patterns. The tier color values, the IBM Plex font stack, the 4/8/12/16/24/32/48/64/96 spacing scale, and the four-tier glyph system are all final.

The Findings region in particular has been through several iterations (v0.4.0 → v0.4.4) and is settled. Don't redesign card layouts; port them as-is.

Screens / Views

The product is a single-page app with two states: cold-start (no query) and briefing (query active).

1. Cold-start

Empty state with the wordmark, a deck explaining what Riprap is, a query input, three sample-query buttons, and a "How Riprap is built" trust band. See shell.jsx → <ColdStart>.

  • Layout: centered single column, max-width ~720px, paper background (--paper)
  • Wordmark: riprap lowercase, IBM Plex Mono 14px / 600, with a 0.85em accent bar ▌ prefix
  • Deck: serif paragraph, 18px, line-height 1.55, ink-secondary
  • Query input: full width, 1px ink border, mono placeholder, 16px
  • Submit: ink fill, paper text, mono caps, 13px
  • Sample queries: three buttons in a column, each shows mode (caps mono) / query (sans 16px) / sub (mono 12px tertiary)
  • Trust band: section-label heading, italic-serif "Cornerstone remembers. Keystone tallies. Touchstone watches. Lodestone projects. Capstone writes it all down with citations." then a bullet list

2. Briefing (active query)

Three-region layout, vertical stack:

  1. App header (sticky top): wordmark · context · query pill · methodology / export PDF / live status
  2. Briefing prose region: long-form text with inline [N] citations, three side-by-side panes (excerpt · evidence cards · mini map)
  3. Findings region: the v0.4.4 Stone-grouped card stack (this handoff's focus)
  4. Footer: tier legend + build line

The Findings region is the substantial new surface. Everything below documents it.

Findings Region (v0.4.4) — detailed spec

Composition 

<FindingsRegion>
  <RunHealthStrip />               ← 1 row, top, summarizes all 25 model calls
  <StoneRegion stone="cornerstone" />
  <StoneRegion stone="keystone" />
  <StoneRegion stone="touchstone" />
  <StoneRegion stone="lodestone" />
  <StoneRegion stone="capstone" />
  <CardGrammarReference />         ← optional, on by default; one stub per variant
</FindingsRegion>

Stones

Five fixed roles, in order:

key name role tag
cornerstone Cornerstone the hazard reader what NYC's ground remembers
keystone Keystone the asset register what's exposed
touchstone Touchstone the present-tense witness what's happening now
lodestone Lodestone the future-pointer what's coming
capstone Capstone the writer what we say, with citations

Each <StoneRegion> has:

  • Header: Stone name (IBM Plex Serif 26px italic for the name, sans for the role) · role tagline · <StoneTally> chip showing N/M cards fired · provenance toggle button
  • Provenance trace: smart-default expansion (see below). Renders specialist tree with status pips.
  • Card grid: 12-column grid, each card spans 4 cols by default (3 per row); register/timeseries/raster cards may span 6.

Card data schema 

type Card = {
  stone: "cornerstone" | "keystone" | "touchstone" | "lodestone" | "capstone";
  tier: "empirical" | "modeled" | "proxy" | "synthetic";
  variant: CardVariant;       // see below
  source: string;             // short label, e.g. "FEMA"
  agency: string;             // long form, e.g. "FEMA preliminary FIRM, panel 36047C..."
  vintage: string;            // e.g. "2024-Q3" or "2007–present"
  title: string;              // card title
  // variant-specific fields:
  headline?: string; subhead?: string;
  columns?: string[]; rows?: (string | number)[][];
  scalars?: { label: string; value: string; unit?: string }[];
  spark?: number[]; histogram?: number[];
  timeseries?: { hours: number[]; values: number[]; threshold?: number };
  forecast?: { years: number[]; p10: number[]; p50: number[]; p90: number[] };
  raster?: "stormwater" | "fema-ae" | "hwm" | "floodnet-density" | ...;
  register?: { tag: string; label: string; sourceId: string; detail: string }[];
  comparison?: { left: ScalarSet; right: ScalarSet; delta: string };
  meta?: Record<string, string>;
  // citation fan-out:
  cites?: { id: string; label: string; href?: string }[];
  // map link:
  mapLayer?: "fema-ae" | "hwm" | "floodnet" | "nycha" | "address" | ...;
};

See findings.jsx lines 12–230 for the canonical CARDS table populated for the Red Hook query.

Card grammar (12 variants)

Every card uses the same chrome — title row (sans 14/600), source · agency · vintage row (mono 11/tertiary), a body block, and a footer with the tier badge (3-letter caps mono) and a "cite" button. The body block is one of:

variant shape use
headline one big number/label, scenario-tagged subhead single-fact cards: "Zone AE"
tabular small N×3 table, mono observation lists: HWM marks
scalars 2–3 labeled scalars in a row "1.2 m · 0.18 mi · 2012"
spark 60×24 inline sparkline, no axes trend at a glance
histogram 8–12 bar histogram, mono labels distributions
timeseries 240×84 line chart with threshold rule hourly water level, 311 calls
forecast 240×88 fan chart (p10/p50/p90) 2050/2080 SLR, surge
raster 240×120 stylized raster thumbnail FEMA AE polygon, stormwater extent, HWM contour
raster-pred same shape with dashed top-rule (synthetic tier) TerraMind 2050 prediction
register 3-col dense list (tag · label · sourceId), detail in title= tooltip NYCHA buildings, schools
comparison side-by-side scalar columns with delta FEMA-AE vs Prithvi-2050
meta definition list of run metadata model id, prompt hash, latency

Synthetic tier cards (TerraMind predictions, prior-only Lodestone outputs) get a dashed top-rule (1px dashed --tier-synthetic-line) to telegraph "no observed data here." Comparison cards always render synthetic.

The <CardGrammarReference> region renders one stub per variant in findings.jsx lines 529–581 — a visual catalog the design team uses to spot-check fidelity. Keep it, gate it on showGrammar prop (default true in dev, false in prod).

Tier system

Four epistemic tiers, encoded redundantly:

tier color glyph badge meaning
empirical #0B5394 (8.59:1) filled square EMP observed, ground-truth
modeled #2A6FA8 (5.41:1) open square MOD computed from observations
proxy #6B6B6B (5.74:1) dotted ring PRX indirect signal, e.g. 311 calls
synthetic #2A6FA8 + dashed hatched square SYN model prior, no observation

Glyphs are inline SVG, 12×12, black-stroke. See glyphs.jsx for the four shapes.

Accessibility: tier is always encoded by color + glyph + label, never color alone. Modeled and synthetic share a hue; the dashed top-rule and glyph carry the difference.

Provenance trace

Every Stone has a tree of specialists ("CORN-001: pull FEMA NFHL → CORN-002: parse panel index → ..."). Each specialist has a status: ok / warn / error / silent.

Smart-default rule (provenanceMode = "smart"):

  • All-ok Stone → collapsed by default, single-line summary "12/12 specialists fired clean"
  • Any warn or error → expanded, full tree visible
  • All silent → collapsed, single-line "no firings (section omitted from briefing)"

provenanceMode = "expanded" forces all expanded; "collapsed" forces all collapsed (warn/error still get a count chip).

The trace UI: indented tree, mono ids, status pip (●/▲/■/○) in tier-color or warn/error colors. Specialist names italic-serif. Hovering a specialist row dims the rest. See trace.jsx for the leaf and stones-trace.jsx for the per-Stone composition.

Run-health strip

Single row above the Stones, full-width. Shows:

  • Total specialists fired / total specialists registered (e.g. 83/100)
  • Per-tier breakdown as four chips: EMP 41 · MOD 28 · PRX 12 · SYN 2
  • Total runtime (e.g. 3.4s)
  • Cache-hit ratio (e.g. 92%)

Mono throughout. Background --paper-deep, 1px ink-soft top + bottom rule.

Hover linking

Every card with a mapLayer is hoverable. On hover (or focus), the card's key becomes the page-level linkedKey. The briefing's map frame reads linkedKey and:

  • Adds is-link-{layer} class to its root, which lights up that layer (see map.jsx for the CSS rules)
  • Renders a small label badge bottom-right: "linked: {layer}"

The same applies in reverse: hovering a layer in the map sets linkedKey to the corresponding card key, which gets a 2px accent outline.

In Svelte: lift linkedKey to +page.svelte as let linkedKey = $state(null), pass it down both branches, and have the cards / layers update it on pointerenter / focus / pointerleave / blur.

Density

density: "compact" | "comfortable" (default comfortable).

  • Comfortable: 16px card padding, 14px line-height multiplier 1.4
  • Compact: 10px card padding, 12px line-height multiplier 1.25, register-card row height 18px (vs 24px)

Pass through to all card bodies; only register/tabular/meta visibly change.

Interactions & Behavior

  • Card hover: 200ms background-color transition to --paper-deep, 2px accent outline if linked
  • Cite button: opens a small popover with the full citation list (cites[]), each row a link to the source PDF/page
  • Provenance toggle: button with aria-expanded, animates the tree open/closed via details/summary or scoped max-height transition (≤200ms)
  • Map layer hover: sets linkedKey, 100ms layer fill opacity transition
  • Reduced motion: all transitions become 0.01ms via the global rule in tokens.css. Don't add motion on top.
  • Keyboard: every card is tabindex=0 with aria-label="{tier} card · {title} · {source}". Cite button is real <button>. Provenance toggle is real <button>.
  • Loading: cards show a 1px ink-soft skeleton (no spinner); replace with content when the specialist returns
  • Error / silent: cards with status error render a 1-line "specialist failed: {reason}" in tier-error color and stay; cards with status silent are omitted entirely (silence over confabulation — design tenet)

State Management

Svelte 5 runes; lift to +page.svelte:

<script>
  let query = $state(null);
  let density = $state("comfortable");
  let provenanceMode = $state("smart");
  let showComparison = $state(false);
  let showGrammar = $state(false);   // dev-only toggle
  let linkedKey = $state(null);

  // Data: load once per query, hydrate from server
  let cardsByStone = $derived(loadCards(query));
  let runHealth = $derived(summarize(cardsByStone));
</script>

Children take props via $props(). No Svelte stores unless cross-route.

Data fetching: assume the existing codebase has a +page.server.ts load function that runs the 25 specialists and returns the Card[] payload. This handoff doesn't change the data layer; it changes the rendering.

Design Tokens

Port tokens.css verbatim. Key values:

Tier colors (all WCAG AA on white):

  • --tier-empirical: #0B5394 (8.59:1)
  • --tier-modeled: #2A6FA8 (5.41:1)
  • --tier-proxy: #6B6B6B (5.74:1)
  • --tier-synthetic: #2A6FA8 (pattern-differentiated)

Neutrals:

  • --paper: #FAFAF7 (warm near-white, USGS-report register)
  • --paper-deep: #F2F2EE
  • --ink: #1A1A1A · --ink-secondary: #4A4A4A · --ink-tertiary: #6B6B6B
  • --rule: #1A1A1A · --rule-soft: #C9C9C5

Accent:

  • --accent: #B8620A (for text, AA)
  • --accent-graphical: #D17C00 (for shapes/lines, ≥3:1)

Type:

  • --font-sans: "IBM Plex Sans" (UI, body)
  • --font-serif: "IBM Plex Serif" (Stone names, hero italic emphasis, oversized stone numerals)
  • --font-mono: "IBM Plex Mono" (labels, source ids, badges, table cells)

All three are SIL OFL / Apache; self-host or load from Google Fonts. No system fallbacks for branding — always specify the Plex stack, fall through only on load failure.

Spacing (--s-1 through --s-9): 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 px. Use these tokens; don't hand-roll values.

Type scale (suggested, not enforced):

  • 11px mono labels (section-label)
  • 12–13px mono row text
  • 14px sans card titles (600)
  • 16px sans body
  • 18px sans deck text
  • 26px serif italic Stone names
  • 36–52px serif headlines (italic for emphasis)

Radius: 0 throughout (this is a civic-tech-clean, USGS-report register; no rounded corners except 1px on focus rings).

Shadows: none. Differentiation by 1px rules and --paper-deep fills only.

Assets

  • Fonts: IBM Plex Sans / Serif / Mono. Self-host woff2 or Google Fonts.
  • Wordmark: text + accent bar ▌ prefix, no logo file
  • Tier glyphs: inline SVG, see glyphs.jsx
  • Map raster thumbnails: hand-drawn SVG approximations using each layer's conventional palette. See findings.jsx → RasterThumb. Replace with real raster previews if/when MapLibre tile snapshots are wired up.
  • Real map: the production map should use MapLibre GL with a custom style.json that respects the tier palette. Style fragments are sketched in shell.jsx comments.
  • No icon library. No Lucide, no Heroicons. SVG glyphs for tiers, mono characters (⌕, ↗, ▌) for chrome.
  • No emoji.

Files in this bundle 

design_handoff_riprap_findings/
├── CLAUDE_CODE_PROMPT.md        ← paste this into Claude Code first
├── README.md                     ← you are here
└── design_files/
    ├── Riprap Stone-Grouped UI v0.4.4.html   ← main prototype, open in browser
    ├── Riprap Landing.html
    ├── Riprap Landing Variants.html
    ├── tokens.css                ← port verbatim
    ├── styles.css                ← reference only
    ├── findings.jsx              ← Findings region (this handoff's centerpiece)
    ├── briefing.jsx              ← long-form prose
    ├── evidence.jsx              ← evidence card stack used in briefing
    ├── map.jsx                   ← mini-map with link highlighting
    ├── trace.jsx
    ├── stones-trace.jsx
    ├── stone-evidence.jsx
    ├── shell.jsx                 ← header, footer, cold-start
    ├── glyphs.jsx                ← four tier glyphs
    ├── tweaks-panel.jsx          ← prototype tooling, ignore
    ├── design-canvas.jsx         ← prototype tooling, ignore
    ├── landing-variants.css      ← marketing-page exploration, ignore unless asked
    └── landing-variants.jsx      ← marketing-page exploration, ignore unless asked

Scope

In scope for this handoff:

  • The Findings region (5 Stones, 12 card variants, run-health strip, smart provenance, hover linking, card grammar reference)
  • Briefing prose and map, to the extent they connect to Findings via linkedKey
  • The marketing landing page (see §"Landing page" below)
  • v0.4.5 deltas in V0.4.5_SPEC.md

Out of scope: the methodology PDF, the export-PDF flow.

Landing page

The landing page is the public-facing entry point at / (separate from the app's cold-start state at /app). Two design files in design_files/:

  • Riprap Landing.html — final shipping landing page
  • Riprap Landing Variants.html — three exploratory variants on a design canvas (kept for reference; do not port)

Landing structure (port Riprap Landing.html)

Four-section vertical scroll, max-width 1200px, paper background:

  1. Hero

    • Wordmark top-left (with ▌ accent prefix)
    • Headline (52px serif, italic emphasis on any place, line-broken into two lines)
    • Deck (18px sans, max 70ch, ink-secondary)
    • Big query box: "Try:" label + cycling example queries on a fixed dotted-underline rail (rail width pinned, ellipsis fallback for overflow)
    • Submit button (ink fill, paper text, mono caps)

  2. "What you'll get back" preview — 3-pane grid (1.4fr / 1fr / 1fr), bottoms equalized:

    • Excerpt pane: serif briefing snippet with inline [N] citation pins; compact source list at bottom (tier-coded)
    • Evidence cards pane: 2x2 grid of compact evidence cards, each with tier-coded left rule (2px), claim, source
    • Map pane: mini SVG map (240x200, 8px paper-grain grid texture) with FEMA-AE polygon fill, HWM contour, FloodNet sensor pin, 311 cluster, address pin, and a compact tier-legend overlay bottom-edge

  3. Five Stones strip — explanation grid: 5 columns (repeat(5, 1fr)), one cell per Stone:

    • Oversized italic-serif numerals 01..05 top-right of each cell (in --rule-soft, decorative)
    • Stone name (serif 22px / 500)
    • Role tagline (sans 13px / ink-secondary)
    • Italic-serif tag ("what NYC's ground remembers" etc.)
    • Dashed rule + mono source list at bottom

  4. Footer — earns its keep:

    • Tier legend (4 swatches: empirical / modeled / proxy / synthetic)
    • Build line (mono, ink-tertiary)

Landing — what's settled (don't redesign)

  • The hero dropped the redundant "Riprap" eyebrow; the wordmark already says it. Headline carries the lede.
  • Cycling examples ride a single fixed dotted underline (no jump on length change). Pin the rail width; ellipsis-truncate overflow.
  • Pane heights are equalized via a flex-1 spacer in the cards pane and flex: 1 on the map pane.
  • Map texture is a subtle 8px paper-grain grid behind the colored layers — gives it a map register, not a diagram register.
  • Stones strip uses oversized italic numerals as a typographic register (decorative, in soft-rule color).
  • Italic serif is intentional: hero emphasis + Stone tags + Stone numerals. Reads as a deliberate third voice.

Landing — em-dashes

All user-facing em-dashes have been purged from Riprap Landing.html, landing-variants.css, and landing-variants.jsx. Replacement convention: , (comma-space) for em-dashes used as parenthetical breaks. Maintain this convention when porting copy. Em-dashes in source-code comments (non-rendered) are fine.

Landing — out of scope variants

Riprap Landing Variants.html contains three earlier explorations on a design canvas: v1 (minimal pushed harder), v2 (example gallery), v3 (methodology-forward). Kept for reference only; do not port. The shipping landing page is Riprap Landing.html (a refinement of v1).

Open questions for the design team

These are deliberately not resolved in the prototype; raise them with the designer before locking implementation:

  1. Should register cards paginate when N > 20, or stay scrollable in a fixed-height card?
  2. The comparison card is currently always synthetic (FEMA-AE vs Prithvi-2050). Will there be empirical-vs-empirical comparisons (e.g. FEMA-AE vs HWM observed)?
  3. Run-health cache-hit ratio — is this surfaced to end users, or is it dev-mode only?
  4. Provenance trace expansion: should expanded state survive across query changes, or reset?