Wireframe + Spec Buildout — every screen, grounded in code

Status: Accepted

Bring every app screen into one interactive UI/UX kit — a code-grounded, inspectable wireframe with a full design spec, held honest by the drift tripwire. Generalizes the Home kit (/wireframes/home) to the whole app, and re-grounds the app-wide doc drift the Home incident exposed.

Non-negotiable: every wireframe/spec is built by READING the real screen + components (route → screen → components), never a doc or the kit mock. Each screen declares groundedIn: [real files]; the build hard-fails if a cited source moved and warns if it changed.

The locked template — the interactive kit

Each screen renders (via build-wireframes.mjs) as a full-viewport 3-pane inspector with three modes, grounded in Storybook / Figma Dev Mode / Zeroheight:

• Overview (default) — the whole wireframe; pick a state from the left rail.
• Compare — check 2–4 states → rendered side by side.
• Inspect — click a part → it highlights on the phone + its structured spec opens.

Specs are structured property lists, never prose. Each part carries Structure (components / data / behavior) + Design (Primitives / Spacing $tokens / Typography roles / Color hex / Sizes) + a one-line Rationale. Every screen opens with a shared Foundations reference (the design system itself).

Scope — the real inventory

~70 feature screens (packages/features/*/src/*-screen.tsx) behind ~80 routes (apps/mobile/app/**), grouped into 22 sections across 6 phases by user priority. Rich surfaces get full kits; form/legal screens bundle as row/variant specimens.

Phase 0 — Shared wireframe kit (infra, one-time) — ✅ DELIVERED

Before fanning out, factor the reusable pieces so 22 screens stay consistent and DRY (one implementation per pattern — the app's own rule). Shipped in wireframes/_kit.jsx, reviewable at /wireframes/components:

• Shared tokens → WF object carries the REAL running theme values (classic-grass light), extracted file:line from source. Two drifts the extraction caught and the kit now encodes correctly: $textTertiary = #607565 (tokens.ts's #738C78 is dead) and $warning = #946200 (not tokens.ts's #B45309) — the theme object is what renders, not the same-named tokens.ts entry.
• Shared atoms → WFPhone · WFZone · WFCard · WFBadge · WFChip · WFDivider · WFDot/WFPulseDot · WFSectionHead · WFShell · WFPill · WFScrubber · WFAvatarBubble · WFFaces · WFCapacityRing · WFProgressBar · WFEmptyState · WFDateTile · WFBottomCta · WFStatTile · WFTierRangeBadge · WFTrustTierBadge.
• Shared domain cards → WFSessionCard (location-first) · WFClubCard (v3, the isMember projection in one component) · WFVenueHero · WFSessionCompactRow · WFMemberRow · WFRecapDonut — drawn once, reused everywhere they appear, mirroring the app's single-source components.
• Shared Foundations → WF_FOUNDATIONS (spacing grid, palette, type scale, primitives + domain cards) — a const prepended to every screen's anatomy.
• The interactive-kit chrome (modes · nav · spec panel · JS · CSS) already lives in build-wireframes.mjs — shared.
• A Components showcase section (components.jsx → /wireframes/components) renders every WF* specimen for review, grounded in packages/ui + the theme (tripwire-protected).

Result: each new screen is a thin config (its states + its parts).

The per-screen loop (repeatable unit)

1. Research (agent · sonnet) — trace route → screen → components; extract the structure, sections, states, data hooks. Report files:lines.
2. Re-ground the spec (agent · sonnet) — rewrite that screen's screen-blueprint section from code (fixing stale paths + descriptions); record groundedIn.
3. Design spec (agent · sonnet) — extract per-part design usage (Primitives / Spacing / Typography / Color / Sizes) grounded in the components (the Home pattern).
4. Author (main · opus) — build the screen's states (reusing the shared kit) + the Meta (states + anatomy [{label, state, zone, spec, design, rationale}]) + groundedIn; wire the section into build-wireframes.mjs.
5. Verify (main) — build (tripwire) + yarn check + deploy.
6. Review (owner) — per screen.

Steps 1–3 run as parallel agents (≤3); step 4 is main-thread design judgment. Spec + wireframe cite the same groundedIn, so the tripwire protects both.

Sections & phases

Phase A — Core tabs (the daily surfaces)

#	Section	Grounds in
✓	Home · 홈	home/src/home-feed-screen.tsx (done — the template)
✓	Clubs · 클럽	clubs/src/club-list-screen, clubs-discover-screen, join-club-screen (done — 6 states)
✓	경기 · Activity	activity/src/activity-screen, activity-pickups-screen (done — 4-tab hub, 6 states)
✓	Records · 기록	records/src/records-screen, record-detail-screen, records-history-screen (done — dashboard + drill + history)
✓	Profile · 프로필	profile/src/profile-screen, public-profile-screen (done — 4 states; Phase A complete)

Phase B — Club detail & management

#	Section	Grounds in
✓	Club Dashboard	clubs/src/club-detail-screen (done — 5 states: 홈/소식/기록/관리 + 비회원)
✓	Club Management	club-members, club-dues, club-attendance, club-settings, club-analytics, club-challenges, join-review-detail, partner-suggester
✓	Club Board	club-board-screen, post-detail-screen, post-create-screen
✓	Club Sessions & Venues	club-sessions-screen, club-venues-screen, sessions/src/venue-detail-screen

Phase C — Session & match flows

#	Section	Grounds in
✓	Session Detail	sessions/src/session-detail-screen, public-pickup-preview-screen
✓	Create / Edit Session	create-session-screen, edit-session-screen
✓	Live & Scoring	spectator-scorecard-screen, match-board-screen, tournament-board-screen, match-rules-screen
✓	Host Ops	pickup-host-dashboard-screen, participants-screen, session-payments-screen, session-attendance-screen

Phase D — Records depth & ranking

#	Section	Grounds in
✓	Leaderboards & Ranking	records-leaderboard-screen + leaderboard-{club,region}-tab, leaderboard-podium, leaderboard-row (done — 6 states: 클럽/지역/전국 + 내 순위 + 로딩 + 없음; ranking.tsx/lb/[clubId] are legacy redirects, not screens)
✓	Analysis & H2H	head-to-head-screen (route records/analysis/rivals.tsx), status-badges dot mode (done — 4 states: 전적/없음/로딩/오류)

Phase E — Profile depth, settings & social

#	Section	Grounds in
✓	Settings hub	settings-screen + edit-profile, signal-preferences, settings-privacy, consent-management, delete-account (done — 6 states: header-less menu + 5 sub-screens; sectionX i18n dead, +WFSwitch/WFSelectChip)
✓	Social & activity	friends-screen, add-friend-screen, achievements-gallery-screen (74 not 55), practice-log-screen (done — 4 states; grouped-not-tabbed friends, search state machine, tiered achievement tiles)
✓	Messaging	dm-inbox-screen, dm-thread-screen, dm-create-group-screen, shared/friend-picker-row, use-dm (done — 4 states; focus-gated 5s refetch not Realtime; +WFChatBubble/WFComposeBar/WFPickerRow)

Phase F — Onboarding, discovery & long tail

#	Section	Grounds in
✓	Onboarding / Auth	login-screen (email-only, OAuth unreachable), onboarding-wizard-screen, onboarding-value-props, consent-matrix (done — 5 states; blueprint's Kakao chooser is stale, no 본인인증/region)
✓	Create Club	create-club-screen (7-step wizard), wizard-shell, wizard-review-row (done — 4 states; wizard chrome PROMOTED to _kit.jsx, shared w/ create-session; banner/logo/tier/join-policy)
✓	Venues & Courts directory	courts-directory-screen, directory-venue-detail-screen, venue-confidence, venue-correction-modal (done — 3 states; +WFTrustRing/WFConfidenceBars/WFSourceChips; per-fact provenance)
✓	Notifications & announcements	notification-center-screen, shared/notification-row-shell (done — 3 states; count-chip filters + 할일/새/이전 bands)
✓	Legal & misc	content-page, terms-screen, announcements-screen (done — 4 states; shared ContentPage + numbered sections + announcement cards)

Delegation & cadence

• Agents (sonnet, ≤3 parallel) do steps 1–3 (research + re-ground spec + design spec) per screen. Main (opus) authors the wireframe + assembles the kit + reviews.
• Review cadence: per screen (owner directive — codebase integrity over speed). Home + the kit template validated the loop end to end.

Spec documentation

screen-blueprint.md is re-grounded per screen as it's wireframed (this closes the ~24 stale sections the audit flagged); each screen's kit + blueprint section cite the same groundedIn. The dead-and-stale register tracks the residue — code cleanup is deferred until the app work is done (owner directive).

Estimate

21 screens remaining × (2–3 parallel agents + author + verify + per-screen review), across 6 phases, after Phase 0 (the shared kit). Each screen ships and is reviewed before the next.