Hero Board UX Plan — 2026-07-20

Operational usability + visualization improvements for /admin/board (web/src/pages/admin/AdminBoardPage.tsx, 3,172 lines). Read-only analysis; every idea below is grounded in the actual code and notes whether it reuses data the board already fetches or needs new API work.

✅ APPROVED — Justin, 2026-07-20: "I love the plan, I want to do all of it," plus two design directives that govern every phase

1. "Actions" dropdown per sticky (space preservation). Anything that CHANGES an event consolidates into a single Actions button on the card with a dropdown to pick what you're editing (prize, sponsor, beneficiary, image, draw config, …) — replacing the row of 5+ ghost buttons. "Show QR code" joins the dropdown too (Justin, 2026-07-20 follow-up) — opening the QR in a modal/popover instead of rendering an 88px block on every card, which alone reclaims most of the card height. Use this consolidation pattern anywhere we need to preserve space on the board. Justin on the split of edit-vs-view items: "I'll trust what you go with — lean toward the most useful and the cleanest approach." Quality bar, verbatim: "Don't half ass anything here, let's get this thing looking beautiful."
2. The sticky IS the editing surface (feel). Justin wants to feel like he's editing EVERYTHING right on the sticky and to move back and forth fluidly between sticky and edit mode. Concretely: the sticky ↔ full-edit round-trip must stay instant and lossless (the Close-to-focus loop from op-admin-edit-flow — sticky → full edit → Close → board scrolled + pulsing that same sticky — is the backbone; deep-link ?focus= preserved), tight edits happen from the card via the Actions dropdown without losing board context, and compact cards must never make an edit feel farther away than it is today.

Rollout consequence: all three phases are greenlit; the Actions dropdown moves UP into the Phase 1/compact-card work rather than waiting for Phase 2. Ops queue AFTER op-admin-edit-flow-2026-07-20 + op-admin-notes-panel-2026-07-20 (same files).

(a) The board today — 1-paragraph summary

The board is a 3-column pipeline (Inquiry → Event → Closeout, ?archived=1 adds Archive) that classifies parties + inquiries by classifyToColumn (web/src/lib/lifecycles.ts), fetched in full via queryPipelineEntities (web/src/api/admin.ts:1181 — /admin/query/party + /admin/query/inquiry, limit 200, complete entities incl. tags, details, connectors, _caps). It does a LOT well: drag-and-drop transitions with optimistic update + revert, per-card quick actions (+Prize/+Sponsor/Beneficiary/Image/Preview), herodraw Run Draw + Winners/Top-raisers steppers persisted on details.settings, completeness checklist dots, closeout checklists backed by note-tasks, QR codes, ?focus=<id> gold-pulse deep links with copy-link buttons, and sidebar Tasks/Lessons-Learned views. The pain points visible in the code: money is invisible — party.tags.total_raised is already in memory on every card but never rendered; cards are enormous (QR at 88px, 5+ ghost buttons, steppers, email, UUID-prefix owner, checklist — so 4 live events + inquiries means heavy scrolling and no at-a-glance scan); no summary strip (you can't see total live $, closing-soon, or draw-pending without opening things); no dates/countdown despite tags.end_time / details.settings.draw_date being fetched; no category theming despite $accentHeropicks/$accentHerodraw/$accentHerofund tokens existing (web/src/tamagui.config.ts:264-266); duplicate cards for the same event (converted inquiry + active party both land in Event column — the ?focus comment at line ~1824 admits this confuses even the team); plus several dead/rough affordances (pipeline-mode checkboxes select things but the bulk bar only renders when !pipelineMode at line ~2922; Reassign asks for a raw user UUID; owner renders as assigned_to.slice(0,8)…; the Image checklist reads details.banner_url top-level while real branding lives at details.branding.banner_url).

(b) Ranked idea list

Legend: S ≈ hours (one dev-mission slice), M ≈ a day-ish, L ≈ multi-day / needs API design. "Cheap" = uses data queryPipelineEntities already returns; "API" = needs new/changed backend.

1. Money on every party card + board summary strip — S, cheap ⭐ highest impact

• WHAT: Render $ raised big and bold (Cinzel, Victory Gold or category accent) on every party card, and add a summary strip above the columns: Total live $ (sum of tags.total_raised for status='active'), Active events, Pending inquiries (inquiry-column count), Closing soon (count with end/draw date within 7d), Draws pending (herodraw + past close + no draw run).
• WHY: This is the #1 operational question ("how are the live fundraisers doing?") and the data is already on the client — party.tags.total_raised is an atomically-maintained counter (sdk/api/parties.js:406-426, incremented on every donation) that the board fetches and silently drops. Zero extra requests.
• HOW: BoardCard (AdminBoardPage.tsx ~line 819) + a new BoardSummaryStrip component in web/src/components/admin/. ⚠️ total_raised is cents (donations tag_amount is cents; there's a known cents-display bug precedent at PartyDetailPage.tsx:2478) — format with /100 and a shared formatCurrency (copy from AdminEventMetricsPage.tsx:28).

2. Days-to-close / countdown chip — S, cheap

• WHAT: A "Closes in 3d" / "Closed 2d ago" chip on party cards, red/amber when ≤3d or overdue-but-still-active.
• WHY: "What needs action next" is currently invisible; Merrill's close date drove a whole week of ops and nothing on the board showed it.
• HOW: The card already computes closeIso (draw_date ‖ details.end_date ‖ tags.end_date, line ~705) and isDone — but only for herodraw and only to gate Top Raisers. Generalize to all parties (tags.end_time is on every party per AdminParty interface, admin.ts:222) and render it. Feeds the "Closing soon" summary tile and attention badges (#3).

3. Attention/health badges + attention-first sort within columns — S/M, mostly cheap

• WHAT: Colored badges at the TOP of cards for states needing action: ⚠ Draw pending (herodraw + isDone + no completed draw), ⏰ Closing soon, 🐌 Stalled Nd (staleDays already computed, line ~692, currently buried as gray microtext), 🖼 No image, 💳 No processor, 🎯 No challenge (see note). Sort cards within each column: attention-flagged first, then by $ raised desc, replacing pure -created_at.
• WHY: Turns the board from "inventory" into "worklist". The completeness checklist (lines 999-1040) already derives Image/Beneficiary/Prize/Sponsor/Processor but renders as passive same-size dots at the card bottom — missing items don't pop.
• HOW: Derive in BoardCard / a deriveAttention(entity) helper next to classifyToColumn in lifecycles.ts; sort in entitiesByColumn memo (line ~1909). "No challenge" needs challenge presence — one batched /admin/query/challenge?limit=200 at board load, group client-side by connectors.party (memory rule: "every fundraising Party needs ≥1 Challenge or donate/predict UI is dead" — this badge catches exactly that failure). "Draw pending" can start as isDone && no drawWinners rendered; exact truth needs a draw-record lookup (Phase 3).
• Bundled fix: the Image check reads det.banner_url/hero_url/logo_url top-level (line 1003) but branding is persisted at details.branding.banner_url (see PartyDetailPage.tsx:1086, InlineBrandingEditor → /api/parties/:id/branding/:asset). Check both paths — today the dot is likely a false "missing" for parties.

4. Category theming — HeroPicks teal / HeroDraw gold / HeroFund deep teal — S, cheap

• WHAT: 4px left accent border + small category chip (HeroDraw etc.) on each party card, and tint the summary tiles the same way.
• WHY: "Which kind of fundraiser is this?" at a glance, using the brand language donors already see. The tokens exist and are themed ($accentHeropicks #0F6A6F, $accentHerodraw #F2B705, $accentHerofund #0A4F53 — tamagui.config.ts:163-168) and the board already imports classifyFundraiser (fundraiser-taxonomy.ts) for the herodraw gate.
• HOW: classifyFundraiser(entity) in BoardCard; labels/taglines come from TAXONOMY (single source of truth per its header comment). Caveat: without round data the classifier can't split heropicks from herofund (hasPredictions defaults false) — ship herodraw-vs-rest first; correct heropicks with a batched /admin/query/round?limit=200 (or challenge-based proxy) in Phase 2.

5. Compact cards by default + expand for the command center — M, cheap ⭐ biggest visual win

• WHAT: Default card = title, $ raised, status pill, countdown chip, category accent, attention badges (~5 dense rows). Everything else — QR (88px!), contact email, 5 quick-action buttons, Team/Cap/Winners/Raisers steppers, checklist detail — moves behind a per-card expand (the isExpanded / onToggleExpand plumbing already exists for task expansion, lines 1277-1321) or lives on the full edit page (the in-flight op makes party stickies open full-edit directly, so per-card button farms matter less now).
• WHY: Card height is the root cause of "hard to see operationally" — with QR + buttons + steppers a single card can exceed a laptop viewport row; three live events fill the whole Event column. Compact cards make the pipeline shape visible again.
• HOW: Restructure BoardCard into CompactBody + ExpandedBody; persist preference in localStorage + ?dense=1 URL param (pattern: existing archived/test params). No API.

6. Merge/dedupe the converted-inquiry + party twin cards — S/M, cheap

• WHAT: When a converted inquiry's connectors.converted_party points at a party that's also on the board, hide the inquiry card and show a small "from inquiry ↗" chip on the party card (linking to /admin/board/inquiry/:id).
• WHY: The code itself documents the confusion (focus-link comment: the party card "is otherwise easy to confuse with the converted inquiry card for the same event"). Two stickies per event doubles Event-column noise and invites edits on the wrong one.
• HOW: In entitiesByColumn memo: build a set of party ids, filter inquiries whose connectors.converted_party is present (the QR block already reads that connector, line ~972). Keep a "show origin inquiries" escape hatch under the existing toggle row.

7. Ops table view toggle ("Board / Table") — M, cheap

• WHAT: A second rendering of the same fetched data as a dense sortable table: Name · Category · Status · $ raised · Closes · Assignee · Attention · quick actions. One row per entity; click → focus/edit.
• WHY: Kanban answers "where is it in the pipeline"; a table answers "sort all events by money / by closing date" — the daily ops scan. Precedent already in-repo: StatusBoardPage.tsx (sortable AdminTable over manageQuery) and AdminTable/AdminTableRow components — this is assembly, not invention.
• HOW: ?view=table alongside existing view values; reuse AdminTable (web/src/components/admin/AdminTable.tsx), share the derive helpers from #1-#3. Also the natural home for CSV export later.

8. Pipeline-mode filters + working bulk bar — S, cheap

• WHAT: (a) Category filter chips (HeroPicks/HeroDraw/HeroFund/All) + "Mine" assignee toggle in pipeline mode; (b) either render the bulk bar in pipeline mode or remove the dead checkboxes.
• WHY: Search (line ~1895) only matches org/name/contact; the assigneeFilter/priorityFilter params are parsed but only applied in sidebar mode (the filtered memo returns [] in pipelineMode, line 1858). And the selection checkboxes on every pipeline card do nothing — the bulk bar requires !pipelineMode (line 2922). Dead affordances erode trust in the tool.
• HOW: Extend filteredPipelineEntities memo; for the bulk bar reuse getPipelineTransitions intersection across selected entities.

9. Reassign & owner display humanized — S, small reuse

• WHAT: Reassign modal becomes a team-member dropdown (name/email) instead of "Enter user UUID" (line 3118); card owner shows initials/name instead of assigned_to.slice(0,8)… (line 690). Show created_by too (standing feedback: "Board cards need created_by").
• WHY: Nobody knows teammates' UUIDs; the current modal is effectively admin-only-with-a-cheat-sheet.
• HOW: fetchAdminSalesUsers already exists (admin.ts:506); fetch once at board load, build id → {name, email} map, feed both the modal (as HeroSelect) and an AvatarCell-style chip (web/src/components/admin/AvatarCell.tsx exists). Also fixes the odd double-call in handleConfirmReassign (it currently calls updateEntityStatus pointlessly before the real PUT, line ~2241).

10. Mobile: default-open Event section + summary strip — S, cheap

• WHAT: On mobile, auto-expand the Event accordion (all sections start collapsed — expandedColumns initialized empty, line 1596) and show the #1 summary strip (tiles wrap 2-up).
• WHY: Justin runs ops from a phone; today mobile lands on three closed headers and zero information. One useState(new Set(['event'])) change plus the strip = usable phone dashboard.
• HOW: AdminBoardPage mobile branch (lines ~2805-2847). Compact cards (#5) matter doubly here.

11. Compliance visibility — S (manual) → M/L (automated)

• WHAT: Add "Compliance" to the completeness checklist / attention badges. Start manual: a details.compliance_checked_at flag set from the edit page or a card action; warn (non-blocking) on drag/Move to active when absent. Later: an API endpoint running the same checks as scripts/compliance-check.mjs so the badge is automatic.
• WHY: The restricted-jurisdiction rule is account-survival (Stripe froze the account once) and the pre-launch check is CLI-only — invisible exactly where activation happens (board drag to Event column → status='active', pipelineColumnToStatus line 468).
• HOW: Manual phase is pure client + one details field (no schema change — D1 column cap respected). Automated phase = new compute route reusing the script's logic.

12. Freshness: last-refreshed stamp + auto-refresh — S, cheap

• WHAT: "Updated 2m ago" next to the refresh button; optional 60s polling while tab visible (document.visibilityState).
• WHY: During a live draw/close window the team refreshes obsessively; totals silently go stale otherwise.
• HOW: Timestamp state in fetchEntities; setInterval + visibility listener. Note fetchEntities fans out closeout-task queries per completed party (line 1741) — keep the poll to pipeline queries only.

13. Keyboard/speed affordances — S, cheap (nice-to-have)

• WHAT: / focuses search; Esc clears; n opens the search field pre-scoped. Card hover shows the focus-link icon persistently (it's already tiny at 13px).
• WHY: Daily-driver tool; cheap delight.
• HOW: useEffect keydown listener on the page; skip when a modal/input is focused.

14. Bigger bets (Phase 3 seeds)

• Per-party 7-day sparkline + velocity on expanded cards ("$450 this week ▲"): needs a batched board-metrics endpoint — GET /api/admin/parties/:id/metrics exists (AdminEventMetricsPage/mdt-01) but is per-party; N calls per board load is too many. New /admin/board/metrics-summary (window rollups per active party, reusing PartyMetricsWindowRollups from web/src/api/analytics.ts). L, API.
• Goal progress bars: goal_amount exists on teams (parties.ts:263-265), not parties — needs a party-level goal decision (a details.goal_amount field) before it can render. M, needs product decision.
• Board activity feed: ActivityFeed component exists (AdminDashboard uses it) — a collapsible right rail on the board answering "what changed since yesterday". M.
• True draw-record status: replace the heuristic "draw pending" with a fetchDrawResults-backed check + link to the verified record (e.g. Merrill 864c4bdb). M, cheap-ish (endpoint exists, admin.ts:443).

(c) Phased rollout (each phase = one op-planner mission scope)

Phase 1 — "Board at a glance" (high impact, low effort; all client-side, one mission)

Scope for op-planner: AdminBoardPage information density + summary layer; no new API endpoints; no entity-schema changes.

1. Summary strip (total live $, active events, pending inquiries, closing soon, draws pending) — idea #1.
2. $ raised (cents→USD) prominent on party cards — #1.
3. Countdown/closes chip on all party cards (generalize existing closeIso) — #2.
4. Attention badges from already-fetched fields (closing-soon, stalled, no-image, no-processor) + attention-first, then $-desc sort within columns — #3 (defer no-challenge/draw-record to Phase 2/3).
5. Category accent border + chip via classifyFundraiser + existing accent tokens (herodraw vs rest) — #4.
6. Fix Image-checklist path (details.branding.*) — #3 bundled fix.
7. Mobile: Event accordion open by default + summary strip — #10.
8. Last-refreshed stamp — #12 (skip polling if time-boxed). Test surface: chromium render of /admin/board (desktop + 390px), assert strip totals equal sum of card amounts, badge presence on a seeded closing-soon/stale party, accent colors per category. (Board ops must follow the op-video standard.)

Phase 2 — "Work the board" (medium)

Scope: interaction correctness + findability; ≤1 extra batched query per load; still no schema changes.

1. Compact card default + expand toggle (?dense=1, localStorage) — #5.
2. Dedupe converted-inquiry/party twins with "from inquiry" chip + escape hatch — #6.
3. Pipeline filters (category chips, Mine) + fix-or-remove pipeline bulk selection — #8.
4. Reassign dropdown + owner/created_by names via fetchAdminSalesUsers map + AvatarCell — #9.
5. Batched challenge query → "No challenge" badge; batched round query → correct heropicks classification — #3/#4 completions.
6. Manual compliance flag in checklist + non-blocking warn on activate — #11 phase A.
7. Keyboard: / search focus — #13.

Phase 3 — "Ops cockpit" (bigger bets)

Scope: new API surface; product decisions from (d) resolved first.

1. Table/ops view toggle reusing AdminTable + shared derive helpers, sortable by $, close date, attention — #7 (can be pulled into Phase 2 if it's hot).
2. /admin/board/metrics-summary endpoint + 7-day velocity/sparkline on expanded cards + real draws-pending from draw records — #14.
3. Automated compliance-check endpoint + automatic badge — #11 phase B.
4. Party-level goal + progress bars (pending decision) — #14.
5. Board activity feed rail — #14.
6. Auto-refresh polling with visibility gating — #12 completion.

Explicit non-goals

• No changes to lifecycle/transition semantics (lifecycles.ts mirrors SDK — server is source of truth).
• No new tag_*/connector_* columns (D1 100-column cap); any new field (compliance flag, party goal) goes in details.
• Don't rebuild the sidebar Tasks/Lessons-Learned views; they inherit compact cards for free via BoardCard.

(d) Open questions for Justin / Ryan

1. Compact-by-default or dense-by-default? Phase 2 makes compact the default with expand — OK, or should the current "everything visible" card stay default with compact as the toggle?
2. QR codes: at-a-glance on every card (current), or fine behind expand/edit page? They're the single biggest card-height cost.
3. Converted-inquiry cards: safe to auto-hide when the linked party is on the board, or does anyone still work the inquiry sticky post-conversion?
4. Party-level fundraising goal: do we want details.goal_amount on parties (enables progress bars + "% to goal" in the summary strip)? Today goals only exist per-team.
5. Compliance: is a manual "compliance checked" checkbox acceptable as step 1, or hold for the automated endpoint? Should activation be blocked (not just warned) without it?
6. Team Availability panel (lines 228-409, collapsible, scope still pending per its own banner): keep on the board, move to dashboard, or drop?
7. "Closing soon" threshold: 7 days? 3? Configurable?
8. Summary-strip money: live (active) only, or include closeout-column totals in a second figure (e.g. "collected this month")?
9. Table view priority: pull #7 into Phase 2 if it's the daily driver Ryan wants — is a sortable table more valuable than the compact-kanban work?