Karvey Mockup

Karvey Mockup — Navigable HTML Prototype

Purpose

Generate a navigable HTML file with 3–4 levels of depth before defining the graphic design. The engineer navigates the mockup in the browser, gives feedback, and it's iterated until approval. Crucially, the mockup is then validated against the requirements (Step 5B) to surface spec-gaps while they are still cheap to fix — before design, architecture and impl. Only afterward does it advance to graphic design and architecture.

Why deeper (3–4 levels): the goal of the mockup is to make the product real enough that spec mistakes become visible now, not during testing. A shallow mockup (just shells and lists) hides the decisions that actually break specs — wizards, confirmations, error/empty states, edge flows. Go to a 4th level whenever a flow has a multi-step action, a destructive confirmation, or a non-trivial state machine.

Target agnosticism

The mockup adapts to the target declared in docs/spec/project.json (the targets field) — see karvey/rules/targets.md. Don't assume web by default:

• web → navigable HTML (App Shell + views + overlays, as described below)
• mobile (ios/android) → screen flow (a sequence of screens with transitions, not a desktop sidebar)
• cli → command transcript (example terminal input/output)
• api/backend → request/response examples (sample payloads per endpoint)

The levels, rules, and HTML structure in the following sections apply to the web target. For other targets, generate the target's equivalent artifact and likewise save it under docs/spec/changes/{change-id}/ (adjusting the extension where appropriate, e.g. mockup.md for a CLI transcript or API examples). The rest of the flow (iteration, approval, knowledge sync) is identical.

Generation modes

• Normal mode (default): a single mockup proposal, iterated with the user until approval (Steps 1 to 6).
• Shotgun mode (opt-in): generate N variants of the mockup at once (default 3) with distinct design approaches, and offer a comparison board so the user can pick one or combine elements from several. Activated with the --shotgun flag (3 variants) or --variants N (N variants). Inspired by /design-shotgun. See Step 3B.

If the user doesn't pass a flag, always use normal mode.

Navigation levels

• Level 1 — App Shell: Main navigation (sidebar/topbar with the product's sections)
• Level 2 — Section: Views of each section (lists, forms, dashboards)
• Level 3 — Detail: Detail views (modals, side panels, sub-views, wizards)
• Level 4 — Sub-flow / state (when warranted): the steps and states inside a Level 3 action — wizard step 2/3, destructive confirmation, error/empty/loading states of that flow, success state. Add it whenever a flow has a multi-step action, a confirmation, or a non-trivial state machine. This is where spec-gaps usually hide, so don't skip it for those flows.

Execution steps

Step 1 — Load context

Read:

• docs/spec/changes/{change-id}/spec.json
• docs/spec/changes/{change-id}/requirements.md
• docs/spec/changes/{change-id}/proposal.md

Verify that approvals.requirements.approved = true. If not, stop and ask to approve requirements first.

Check whether a UI applies: Read spec.json → the layers field. If it only includes [DB] and/or [Backend] without [Frontend], ask the user: "This change doesn't seem to have a user interface. Does it need a visual mockup or do we go straight to architecture?" If it doesn't need one, skip to karvey-architecture.

Detect iteration: if docs/spec/changes/{change-id}/mockup.html exists, increment the iteration number.

Step 2 — Map screens from requirements

Build the screen map by reading the requirements:

Level 1 (Navigation):
  - {Section A} → requirements {N.N, N.N}
  - {Section B} → requirements {N.N, N.N}

Level 2 (Views per section):
  Section A:
    - List View: {what it shows}
    - Form View: {what it captures}
  Section B:
    - Dashboard View: {what it shows}

Level 3 (Details):
  - Confirmation modal
  - Detail panel
  - Step-by-step wizard

Step 3 — Generate mockup.html

Generate a single self-contained HTML file:

HTML structure:

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <title>MOCKUP — {change-id} — Iteration {N}</title>
  <!-- Tailwind CDN — for prototyping only, does not imply its use in the real project -->
  <script src="https://cdn.tailwindcss.com"></script>
  <style>/* additional styles */</style>
</head>
<body>
  <!-- Mockup banner, always visible -->
  <!-- App Shell with Level 1 navigation -->
  <!-- Level 2 views container (changes with navigation) -->
  <!-- Level 3 overlays (modals, panels) -->
  <!-- Navigation JavaScript -->
</body>
</html>

Set lang on <html> to the project's language (per spec.json language).

Construction rules:

1. Persistent banner at the top: 🔧 MOCKUP — {change-id} — Iteration {N} — {date}
2. Level 1 navigation: sidebar or topbar with placeholder icons (gray circles) and section names
3. Level 2 views: represent each screen as a view with:
   • The screen title
   • A table/list with real columns (real labels, example data coherent with the domain)
   • Buttons with real labels ("Transfer call", "Confirm", not "Button 1")
   • Forms with real fields and correct types
   • Loading states represented with gray skeletons
4. Level 3: modals and panels implemented as overlays shown/hidden with pure JS
5. Navigation JS: showView(viewId), showModal(modalId), closeModal(modalId) — no external dependencies
6. Neutral palette: grays only. The real project's color and design system will come in karvey-design-graphic.
7. Basic responsive: work at a minimum width of 1280px+
8. Example data: use fictitious but domain-coherent data (tenant names, real call types, etc.)

Forbidden elements in the mockup:

• Lorem ipsum (use real domain text)
• "Button 1", "Section A" (use real labels)
• External images (use divs with bg-gray-300)
• Heavy JS frameworks (only Tailwind CDN and native JS)

Step 3B — Shotgun mode (only if --shotgun or --variants N)

Replaces Step 3/4 when shotgun mode is active. Instead of a single mockup, generate N variants (default 3) that explore distinct design approaches over the same screen map from Step 2 (same screens, real data, and labels — the approach varies, not the scope). Examples of variation axes: information density (compact vs. spacious), navigation pattern (sidebar vs. topbar vs. tabs), visual hierarchy, the main task's flow.

1. Load taste preferences (if they exist): read docs/spec/changes/{change-id}/taste.md and/or docs/spec/taste.md. Apply those preferences to all variants so as not to repeat already-discarded approaches.
2. Generate N variants, each self-contained and following all the "Construction rules" from Step 3 (neutral palette, real data, native JS, banner, etc.):

   docs/spec/changes/{change-id}/mockup-variant-1.html
   docs/spec/changes/{change-id}/mockup-variant-2.html
   docs/spec/changes/{change-id}/mockup-variant-N.html
   

   Each variant's banner includes its approach: 🔧 MOCKUP — {change-id} — Variant {k}/{N}: {approach} — {date}.
3. Generate a comparison board docs/spec/changes/{change-id}/mockup-board.html: a self-contained page that shows the N variants side by side in <iframe>s (or cards with a screenshot/link to each file), each with its approach name and a 1-line summary of how it differs. The board lets you open each variant full size.
4. Update spec.json (see Step 4) with approvals.mockup.variants: N in addition to the normal fields.

Choice and taste: offer the user to open the board (open docs/spec/changes/{change-id}/mockup-board.html) and ask them to choose a variant or indicate what to combine ("the navigation from #1 with the tables from #3"). On receiving the choice:

• Consolidate the chosen variant (or the combination) as mockup.html, which becomes the working mockup for the normal iteration cycle (Step 6).
• Remember the taste: append to docs/spec/changes/{change-id}/taste.md which approach/elements they preferred and which they discarded, in short bullets, to guide future iterations and future shotgun runs for this change.

Step 4 — Write the file

docs/spec/changes/{change-id}/mockup.html

Update spec.json:

• phase: "mockup-generated"
• approvals.mockup.generated: true
• updated_at: {timestamp}

Step 4B — Update the knowledge graph

Sync knowledge per karvey/rules/knowledge-sync.md (Obsidian if available; at minimum /graphify docs/spec/ --update) to reflect the mockup.html created or modified. If docs/spec/graphify-out/ doesn't exist, invoke /graphify docs/spec/ without --update.

Step 4C — Spec↔mockup validation (catch spec-gaps early)

Before presenting, walk the mockup against requirements.md — one pass to confirm the mockup actually realizes every requirement, and to find what the requirements forgot. This is the cheapest place in the whole pipeline to fix a spec.

For each requirement, check:

• Is there a screen/state in the mockup that satisfies it? (requirement → no screen = a gap in the mockup, or a requirement that's vaguer than it looked)
• Does the mockup imply a behavior/state/field that no requirement covers? (screen → no requirement = a likely spec-gap: the requirement is incomplete)
• Are the Level-4 states (errors, confirmations, empty, multi-step) actually specified, or did the mockup just invent them?

Record each mismatch. Then route per karvey/rules/iteration-loop.md:

• If requirements is still in this change's scope and not yet locked downstream, the cheapest path is to fix the requirement now: note it and update requirements.md + spec-delta.md directly (you're still pre-design), keeping PRD traceability.
• If the gap is bigger or contested, append it to docs/spec/changes/{change-id}/findings.md as a spec-gap and run /karvey-iterate {change-id} to route it formally.

Document the validation outcome briefly in the presentation (Step 5): "Spec↔mockup: N requirements covered, M gaps found and fixed/routed."

Step 5 — Present to the user

Shotgun mode: present the comparison board instead of a single file (open docs/spec/changes/{change-id}/mockup-board.html), list the N variants with their approach, and ask the user to choose one or indicate what to combine. After the choice, continue with the normal iteration cycle (Step 6) on the consolidated mockup.html.

Normal mode:

🖥️ Mockup generated — Iteration {N}

File: docs/spec/changes/{change-id}/mockup.html
Open with: open docs/spec/changes/{change-id}/mockup.html

Screens included ({N} total):
  Level 1 — Navigation:
    - {section 1}
    - {section 2}
  Level 2 — Views:
    - {section 1}: {view A}, {view B}
    - {section 2}: {view C}
  Level 3 — Details:
    - {modal/panel 1}
    - {modal/panel 2}

What feedback do you have? Describe the changes and I'll generate Iteration {N+1}.
Or type "approved" to advance to graphic design.

Step 6 — Iteration cycle

If the user gives feedback:

1. Read the feedback in detail
2. Identify which screens/components to change
3. Edit mockup.html applying the changes
4. Increment the iteration number in the banner
5. Sync knowledge per karvey/rules/knowledge-sync.md (Obsidian if available; at minimum /graphify docs/spec/ --update)
6. Return to Step 5

If the user approves:

• Update spec.json: approvals.mockup.approved: true
• Output:

✅ Mockup approved — Iteration {N}

Next step:
/karvey-design-graphic {change-id}

Safety

• Verify that requirements are approved before generating
• If the mockup has >20 screens, ask whether to split it into modules
• In shotgun mode, if --variants N requests more than 5 variants, ask first (cost/noise); each variant and the board must open without errors in a modern browser
• The HTML file must open without errors in a modern browser (Chrome/Safari/Firefox)
• Don't use document.write or eval in the generated JS

Advance to the next phase

When you finish this phase and have the corresponding approval, actively ask the user: "Shall we advance to the Graphic Design phase now?"

• If they confirm → run /karvey-design-graphic {change-id}.
• If they prefer to review or adjust first → wait. Advancing is always with the user's OK (a gate of the method).
• If you resume in another session, /karvey {change-id} indicates which phase you're on and which one comes next.

Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md. Karvey = Afán, an ona/selknam word.