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)
Before fanning out, factor the reusable pieces so 22 screens stay consistent and DRY (one implementation per pattern — the app's own rule):
- Shared atoms → extract Home's reusable primitives (
Phone,Zone, wireframeCard/Badge/Pressable-row/SectionHead, faces + capacity ring) intowireframes/_kit.jsx, loaded before every screen (likePrimitives.jsxis today). - Shared domain cards → the cards reused across screens (
SessionCard,ClubCard, member row…) become shared wireframe components — drawn once, reused everywhere they appear, mirroring the app's single-source components. - Shared Foundations → the design-system reference part (spacing grid, palette, type scale, primitives) becomes 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.
Result: each new screen is a thin config (its states + its parts).
The per-screen loop (repeatable unit)
- Research (agent · sonnet) — trace route → screen → components; extract the structure, sections, states, data hooks. Report files:lines.
- Re-ground the spec (agent · sonnet) — rewrite that screen's
screen-blueprintsection from code (fixing stale paths + descriptions); recordgroundedIn. - Design spec (agent · sonnet) — extract per-part design usage (Primitives / Spacing / Typography / Color / Sizes) grounded in the components (the Home pattern).
- 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 intobuild-wireframes.mjs. - Verify (main) — build (tripwire) +
yarn check+ deploy. - 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) |
| A1 | Clubs · 클럽 | clubs/src/club-list-screen, clubs-discover-screen, join-club-screen (research ready) |
| A2 | 경기 · Activity | activity/src/activity-screen, activity-pickups-screen |
| A3 | Records · 기록 | records/src/records-screen, record-detail-screen, records-history-screen |
| A4 | Profile · 프로필 | profile/src/profile-screen, public-profile-screen |
Phase B — Club detail & management
| # | Section | Grounds in |
|---|---|---|
| B1 | Club Dashboard | clubs/src/club-detail-screen |
| B2 | Club Management | club-members, club-dues, club-attendance, club-settings, club-analytics, club-challenges, join-review-detail, partner-suggester |
| B3 | Club Board | club-board-screen, post-detail-screen, post-create-screen |
| B4 | Club Sessions & Venues | club-sessions-screen, club-venues-screen, sessions/src/venue-detail-screen |
Phase C — Session & match flows
| # | Section | Grounds in |
|---|---|---|
| C1 | Session Detail | sessions/src/session-detail-screen, public-pickup-preview-screen |
| C2 | Create / Edit Session | create-session-screen, edit-session-screen |
| C3 | Live & Scoring | spectator-scorecard-screen, match-board-screen, tournament-board-screen, match-rules-screen |
| C4 | Host Ops | pickup-host-dashboard-screen, participants-screen, session-payments-screen, session-attendance-screen |
Phase D — Records depth & ranking
| # | Section | Grounds in |
|---|---|---|
| D1 | Leaderboards & Ranking | records/src/records-leaderboard-screen, ranking.tsx, lb/[clubId] |
| D2 | Analysis & H2H | records/src/head-to-head-screen, records analysis views |
Phase E — Profile depth, settings & social
| # | Section | Grounds in |
|---|---|---|
| E1 | Settings hub | profile/src/settings-screen + settings-privacy, settings-consent-management, settings-blocked-users, settings-signal-preferences, change-password, delete-account, edit-profile-screen |
| E2 | Social & activity | friends-screen, add-friend-screen, achievements-gallery-screen, practice-log-screen |
| E3 | Messaging | messaging/src/dm-inbox-screen, dm-thread-screen, dm-create-group-screen, dm-add-members-screen |
Phase F — Onboarding, discovery & long tail
| # | Section | Grounds in |
|---|---|---|
| F1 | Onboarding / Auth | onboarding/src/onboarding-wizard-screen |
| F2 | Create Club | clubs/src/create-club-screen |
| F3 | Venues & Courts directory | sessions/src/courts-directory-screen, directory-venue-detail-screen |
| F4 | Notifications & announcements | home/src/notification-center-screen, profile/src/announcements-screen |
| F5 | Legal & misc | profile/src/terms-screen, contact-screen, consent-history-screen; weather insight |
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.