design-interactive-preview

Design Interactive Preview — Interactive Visual Comparison

Entry/Exit

Entry: 02-design.md Contains 2+ Design Alternatives, and artifact_type is software(has UI),visual or deck
Exit: The user has made a selection,02-design.md has been refined into the selected direction,design-selection.json has been written to
Points to: After the selection is complete, return to design-workflow-design Step 5 for final approval
Preload: CANON.md + scripts/design-preview.mjs + references/design-best-practices.md + references/design-inspiration-catalog.md + project root DESIGN.md(if it exists)
Output path: After the selection is complete, return to design-workflow-design Step 5 → after final approval, enter build-content-writing or build-content-layout

When not to use

artifact_type is document / article(text artifact, low value for visual comparison)
software Pure backend, pure script, pure migration, pure CI
02-design.md Only one design direction (no alternatives)
Node.js is unavailable and MCP browser tools are also unavailable (degrade to CLI text comparison)

Iron Law

Applicable artifact_type and comparison dimensions

artifact_type	Round 1 dimensions	Round 2+ dimensions
`software` + UI	Overall layout + interaction pattern	Layout refinement / color scheme / fonts / component style / state flow
`visual`	Composition + color direction	Color palette / hierarchy / whitespace / visual elements
`deck`	Narrative structure + page rhythm	Single-page typography / visual style / chart approach

Process

Step 1: Read alternatives and plan comparison rounds

Read 02-design.md in ## Design Alternatives section:

Confirm there are 2-3 alternatives
Determine the comparison dimensions and rounds based on artifact_type Determine comparison dimensions and rounds
Determine which dimensions are worth comparing over multiple rounds and which can be settled together in the first round

Step 2: Generate this round's comparison HTML

Generate design-comparison.html to the feature directory. Page requirements:

Structure:

┌─────────────────────────────────────────┐
│  Round Indicator: Step 1 of N           │
│  Dimension: [当前对比维度标签]            │
├───────────┬───────────┬─────────────────┤
│ Alt A     │ Alt B     │ Alt C (可选)     │
│ ┌───────┐ │ ┌───────┐ │ ┌─────────────┐ │
│ │视觉示意│ │ │视觉示意│ │ │视觉示意     │ │
│ └───────┘ │ └───────┘ │ └─────────────┘ │
│ 名称      │ 名称      │ 名称            │
│ 核心差异   │ 核心差异   │ 核心差异        │
│ 设计要点   │ 设计要点   │ 设计要点        │
│ 优势      │ 优势      │ 优势            │
│ 劣势      │ 劣势      │ 劣势            │
│ [Select]  │ [Select]  │ [Select]        │
├───────────┴───────────┴─────────────────┤
│ Already decided: [Round 1 → Alt X]      │
└─────────────────────────────────────────┘

Technical requirements:

All CSS/JS inline, zero external dependencies
CSS Grid or Flexbox side-by-side layout
System font stack (-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif）
Responsive: 2-3 columns on desktop, stacked on mobile
Works in both dark and light mode (respect prefers-color-scheme）

Interaction logic (inline JS):

Click the "Select" button → POST /api/selection send { round, dimension, selected, alternatives }
On success: the selected card is highlighted (border turns blue), the other cards fade out (opacity: 0.5)
Display "✓ You selected: [Name]" at the top of the page
The selected summary bar updates

Visual representation (CSS/SVG):

software + UI: Use CSS Grid/Flexbox to simulate a wireframe (header/nav/main/sidebar/footer areas represented by color blocks)
visual: Use inline SVG or CSS gradients to represent composition and color direction
deck: Use a sequence of thumbnail cards to represent page rhythm

Step 3: Start the local HTTP server

node scripts/design-preview.mjs <feature-dir> &

Capture DESIGN_PREVIEW_PORT=<port> output to get the port number
If startup fails, use the fallback path

Step 4: Open the browser

Priority:

open http://localhost:<port> （macOS）
MCP browser tool navigate_page
Manually tell the user the URL

Step 5: Wait for the user to choose

Two modes (can be used together):

A. File polling mode:

Read every 5 seconds design-selection.json
The file exists and contains selected field → selection complete

B. CLI confirmation mode:

Tell the user "the comparison page has been opened in the browser, please make a selection and come back to confirm"
The user replies with the selection result in the CLI

Step 6: Process the selection result

Read design-selection.json(if it exists)
If there is a next round of comparison → update the HTML → POST /api/next-round → go back to Step 2
If there is no next round or the user says "this is the one" → proceed to Step 7

Step 7: Refine `02-design.md`

Promote the design decisions of the selected alternative to the main design content
Move unselected options into ### Alternatives Considered, with the reasons for the selection
In ### Selection Record , record each round's selection
Ensure the evidence chain is complete—all design decisions of the selected option can still be traced back to the Adopt list

Step 8: Shut down the service

kill <server-pid>

or pkill -f design-preview.mjs

Fallback path

Environment	Fallback
Node.js unavailable	Use the MCP browser tool to open directly `file://` URL，`evaluate_script` Read `window.__selection`
MCP browser unavailable (Codex CLI)	CLI text comparison:`AskUserQuestion` + `preview` field to render an ASCII comparison
Both unavailable	Plain text `AskUserQuestion` item-by-item comparison

When degraded, in 02-design.md Selection Record, note:

- Preview mode: degraded (CLI text comparison)
- Reason: Node.js unavailable / browser unavailable

Adopt / Reject

The generation of the visual comparison page follows references/design-best-practices.md 's 4+1 layer source model:

Adopt: CSS Grid side-by-side layout — Source Layer: Enterprise Product Patterns; Reason: side-by-side comparison is the standard interaction pattern of mature product design tools (Figma, InVision, etc.)
Adopt: System font stack — Source Layer: Official Systems / Platform Rules; Reason: does not depend on external fonts, maintaining the zero external dependency constraint
Adopt: Multiple rounds of layer-by-layer narrowing — Source Layer: Methods / Theory / Style Schools; Reason: incremental decision-making (progressive commitment) reduces cognitive load
Reject: External CSS frameworks (Tailwind/Bootstrap) — Source Layer: Enterprise Product Patterns; Reason: the project has a zero-dependency constraint, and the comparison page should not introduce npm dependencies
Reject: Comparing all dimensions at once on a single page — Source Layer: Anti-patterns; Reason: 2-3 directions × 3-4 dimensions = 6-12 cards, exceeding the user's cognitive bandwidth

Local Project Truth

The project is a zero-dependency Markdown/JSON/Shell framework—the HTML/CSS/JS of the comparison page must all be inline, without introducing npm packages
scripts/design-preview.mjs is the only JS file in the project, using Node.js built-in modules—the comparison page should maintain an equivalent level of simplicity
The Iron Law of the design phase stipulates that designs without approval cannot enter /plan—the selection of the visual comparison must be written back to 02-design.md, and cannot replace the approval process
artifact_type determines the comparison dimensions—document/article is not applicable to visual comparison, which has already been made clear in "When not to use"

Common claims

Claim	Reality	Consequences
"Selecting it in the browser counts as approval"	Wrong. Visual comparison is only directional selection; Phase 5 still needs to confirm evidence quality and completeness.	Skipping evidence checks → selecting a visually appealing but evidence-poor direction → rework during implementation
"No need for multiple rounds, one round is enough"	Fine. The user can say "this one" at any round to skip subsequent comparisons.	No consequence (this is the correct flexible choice)
"The HTML is too bare and ugly"	The purpose of the comparison page is to let the user distinguish directional differences, not to produce the final UI. Wireframe level is enough.	Over-polishing the comparison page → delays decision by 2-3 hours; the comparison page is not the final artifact
"Just viewing it in the terminal is fine"	For text artifacts, yes. For UI/visual/deck, visual comparison is an order of magnitude more efficient than text descriptions.	Describing directional differences in text → user misunderstands → picks the wrong direction → redesign after implementation takes 5x as long

Red Flags — STOP

User selects an option in the browser but design-selection.json is not written
The design decision of the selected option cannot be traced to any evidence in the Adopt list
HTML generation fails or the browser cannot open, and the fallback path is also unavailable
The port cannot be obtained after the service starts
Multi-round comparison falls into a loop (more than 5 rounds)

Validation failure handling

Validation item	Failure manifestation	Handling method
HTTP service fails to start	The port cannot be obtained or the service cannot start	Use the fallback path: MCP browser opens the file:// URL or CLI text comparison
HTML generation fails	design-comparison.html is not generated or renders incorrectly	Fall back to CLI text comparison; note the reason for the fallback in the Selection Record
design-selection.json is not written	The file is not updated after the user selects	Check whether the POST route works properly; fall back to CLI confirmation mode
Evidence chain broken	The design decision of the selected option cannot be traced to the Adopt list	Go back to design-workflow-design to supplement evidence; do not approve an evidence-free direction
Multi-round comparison exceeds 5 rounds	Comparison falls into a loop	Force stop; take the current best direction as the selected option and record the reason for stopping

Good and bad examples

Good: multi-round narrowing + evidence write-back + fallback recording

Round 1: 整体布局对比 → 用户选 Alt B (侧栏布局)
Round 2: 侧栏布局配色对比 → 用户选 "就这个了" (深色主题)
02-design.md 更新: Alt B 提升为主设计，Alt A 移入 Alternatives Considered
Selection Record: 每轮选择 + 降级模式（如有）

Bad: selection without write-back + no evidence tracking

用户在浏览器选了 Alt B → design-selection.json 未写入
02-design.md 未更新 → 选定方案无证据链
直接进入 build → 没有经过 design-workflow-design 批准

Output template

交互式视觉对比完成：

对比轮次: [N] 轮
选择结果:
  Round 1: [维度] → 选中 [Alt X]
  Round 2: [维度] → 选中 [Alt Y] / 用户说"就这个了"

02-design.md 更新:
  - 选定方向已提升为主设计: [是/否]
  - 未选方案已移入 Alternatives Considered: [是/否]
  - Selection Record 已写入: [是/否]
  - 证据链完整（每决策 → Adopt 来源）: [是/否]

降级信息:
  - Preview mode: [full / degraded]
  - 降级原因: [无 / Node.js unavailable / browser unavailable]

服务状态: 已关闭

Validation checklist

HTTP service has started and returned a port number
design-comparison.html has been generated
The page renders correctly in the browser (2-3 columns side by side)
The Select button is clickable and triggers a POST request
design-selection.json is written after selection
The Agent successfully reads the selection result
02-design.md has been refined into the selected direction
Unselected options have been moved to Alternatives Considered
The service has been shut down