Wireframes System

Status: Active

One config-driven wireframe per app section — real brand tokens, static-rendered (no CDN), deployed under /wireframes on the Cockpit. This is the design surface for aligning layout, hierarchy, and flow before app code. It is deliberately separate from the interactive ui_kits/mobile click-through kit.

The one rule: wireframes are grounded in the real code

The real components under packages/… are the single source of truth for what a screen is. Everything else — screen-blueprint.md, the kit *Screen.jsx mocks, these wireframes — is a subordinate representation that must track the code.

A wireframe built from a doc or a mock instead of the code caused a real drift incident: the Home wireframe was drawn as a "10-card feed" (a superseded design the screen-blueprint still described) when the app actually ships a 오늘/이번 주/이번 달 temporal briefing. The tripwire below exists so that can't happen silently again.

Build a section wireframe by READING the real components it mirrors — trace what the route actually renders (e.g. home-feed-screen.tsx → its views → SessionCard), not the obvious-named doc. See research-methodology.

The drift tripwire

Every section in scripts/build-wireframes.mjs declares the real files it reflects:

{ key: 'home', file: 'wireframes/home.jsx', component: 'HomeWireframe',
  groundedIn: [
    'packages/features/home/src/home-feed-screen.tsx',
    'packages/app/src/presentation/components/sessions/session-card.tsx',
    // …
  ] }

On every build (yarn docs:wireframes, and docs:site:build inside docs:check):

• Hard-fail if a cited source no longer exists (moved/renamed ⇒ the grounding is broken). This fails the pre-push + CI gate.
• Warn if a cited source's content changed since the wireframe was last grounded — a prompt to re-verify the wireframe still reflects it.

The committed baseline of source hashes is .grounding.json. After re-verifying a wireframe against changed code, accept the new baseline:

REGROUND=1 yarn docs:wireframes

Adding or updating a section wireframe

1. Read the real code the section renders (route → screen → components). Note the actual structure, section names, card anatomy, and states.
2. Write/edit wireframes/<section>.jsx — one config object → components, reusing the shared ui_kits/mobile/Primitives.jsx + colors_and_type.css tokens. Export the component on window.
3. Add/update the section entry in scripts/build-wireframes.mjs, including groundedIn (the files you just read).
4. yarn docs:wireframes → verify the render + the grounding manifest. Deploy with the Cockpit (yarn docs:site:build → wrangler pages deploy).

Sections

Section	File	Status
Home · 홈	home.jsx	Faithful to home-feed-screen.tsx
Clubs · 클럽	../ui_kits/mobile/ClubSurfaces.jsx	To relocate into wireframes/
Sessions · 경기	—	Planned
Records · 기록	—	Planned
Profile · 프로필	—	Planned