sdtk-design-kit 0.1.2 → 0.2.0

package/src/commands/prototype.js

@@ -6,6 +6,7 @@ const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
 const { inferDomainProfile } = require("../lib/domain-profile");
 const { ValidationError } = require("../lib/errors");
+const { renderMultiPagePrototype, screenFileName } = require("../lib/prototype-renderer");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
 const PROTOTYPE_FLAG_DEFS = {
@@ -101,16 +102,38 @@ Reads:
   .sdtk/design/START_INPUT_STATE.json (optional; enables explicit multi-screen rendering when ready)
 
 Creates:
-  docs/design/prototype/index.html
+  legacy/simple mode:
+    docs/design/prototype/index.html
+  from-spec multi-page mode:
+    docs/design/prototype/index.html
+    docs/design/prototype/screens/*.html
+    docs/design/prototype/assets/prototype.css
+    docs/design/prototype/assets/prototype.js
 
 Safety:
   Local files only.
   Existing prototype index is not overwritten unless --force is explicit.
   No production app code outside docs/design/prototype.
-  No JavaScript runtime, server, network call, .sdtk/atlas, or SDTK-WIKI output mutation.`);
+  No JavaScript app runtime, server, network call, .sdtk/atlas, or SDTK-WIKI output mutation.`);
   return 0;
 }
 
+function resolvePrototypeMode(canUseMultiScreen) {
+  if (!canUseMultiScreen) {
+    return "single";
+  }
+  const raw = String(process.env.SDTK_DESIGN_PROTOTYPE_MODE || "").trim().toLowerCase();
+  if (!raw) {
+    return "multi";
+  }
+  if (raw === "single" || raw === "multi") {
+    return raw;
+  }
+  throw new ValidationError(
+    `Unsupported SDTK_DESIGN_PROTOTYPE_MODE "${process.env.SDTK_DESIGN_PROTOTYPE_MODE}". Use "single" or "multi". No project files were changed.`
+  );
+}
+
 function wireframePath(paths, fileName) {
   return path.join(paths.wireframesPath, fileName);
 }
@@ -309,7 +332,192 @@ function renderPrimitiveChips(primitiveNames) {
 
 function renderStateChips(requiredStates) {
   if (!Array.isArray(requiredStates) || requiredStates.length === 0) return "";
-  return `<div class="chip-row">${requiredStates.slice(0, 3).map((item) => `<span class="chip chip-state">${escapeHtml(item)}</span>`).join("")}</div>`;
+  return `<div class="chip-row">${requiredStates
+    .slice(0, 3)
+    .map((item) => `<span class="chip" data-chip-type="state">${escapeHtml(item)}</span>`)
+    .join("")}</div>`;
+}
+
+function screenBriefPath(paths, screenId) {
+  return path.join(paths.screensPath, `${screenId}_DESIGN_BRIEF.md`);
+}
+
+function screenBriefSidecarPath(paths, screenId) {
+  return path.join(paths.designScreenBriefsStatePath, `${screenId}.json`);
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function loadHighFidelityContracts(paths, statePayload) {
+  const warnings = [];
+  if (!fs.existsSync(paths.componentPatternLibraryPath)) {
+    warnings.push("missing docs/design/COMPONENT_PATTERN_LIBRARY.md");
+  }
+  if (!fs.existsSync(paths.designTokensPath)) {
+    warnings.push("missing docs/design/DESIGN_TOKENS.json");
+  }
+  const missingBriefs = [];
+  const screenContracts = new Map();
+  for (const screen of statePayload.screenModel.screens) {
+    const briefPath = screenBriefPath(paths, screen.screenId);
+    if (!fs.existsSync(briefPath)) {
+      missingBriefs.push(screen.screenId);
+      continue;
+    }
+    const sidecarPath = screenBriefSidecarPath(paths, screen.screenId);
+    screenContracts.set(screen.screenId, {
+      briefPath,
+      briefContent: fs.readFileSync(briefPath, "utf-8"),
+      sidecar: fs.existsSync(sidecarPath) ? readJsonSafe(sidecarPath) : null,
+    });
+  }
+  if (missingBriefs.length > 0) {
+    warnings.push(`missing per-screen briefs for: ${missingBriefs.join(", ")}`);
+  }
+  if (warnings.length > 0) {
+    return { ready: false, warnings, screenContracts: new Map(), tokens: null };
+  }
+  const tokens = readJsonSafe(paths.designTokensPath);
+  if (!tokens || typeof tokens !== "object") {
+    return { ready: false, warnings: ["invalid docs/design/DESIGN_TOKENS.json"], screenContracts: new Map(), tokens: null };
+  }
+  return { ready: true, warnings: [], screenContracts, tokens };
+}
+
+function managedPrototypeTargets(paths, statePayload, mode) {
+  const targets = [{ relativePath: "docs/design/prototype/index.html", filePath: paths.prototypeIndexPath }];
+  if (
+    mode === "multi" &&
+    statePayload &&
+    statePayload.screenModel &&
+    Array.isArray(statePayload.screenModel.screens)
+  ) {
+    targets.push(
+      { relativePath: "docs/design/prototype/assets/prototype.css", filePath: paths.prototypeCssPath },
+      { relativePath: "docs/design/prototype/assets/prototype.js", filePath: paths.prototypeJsPath },
+      ...statePayload.screenModel.screens.map((screen) => ({
+        relativePath: `docs/design/prototype/screens/${screenFileName(screen)}`,
+        filePath: path.join(paths.prototypeScreensPath, screenFileName(screen)),
+      }))
+    );
+  }
+  return targets;
+}
+
+function tokenOrDefault(tokens, keyPath, fallback) {
+  const value = keyPath.reduce((obj, key) => (obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined), tokens);
+  return value == null ? fallback : value;
+}
+
+function renderHighFidelityScreen(screenRole, title) {
+  switch (screenRole) {
+    case "home":
+      return `
+      <section class="hf-hero panel"><h3>${escapeHtml(title)} hero</h3><p>Category-first commerce landing with featured products and guided CTA.</p><div class="button-row"><a class="btn btn-primary" href="#">Start purchase</a><a class="btn btn-secondary" href="#">Open configurator</a></div></section>
+      <section class="hf-feature-grid"><article class="panel">Category range</article><article class="panel">Featured products</article><article class="panel">Configurator quick start</article></section>`;
+    case "category":
+      return `<section class="hf-split"><aside class="panel">Filter sidebar</aside><div class="panel"><h3>Product grid</h3><div class="hf-card-grid"><article class="product-card">Card A</article><article class="product-card">Card B</article><article class="product-card">Card C</article></div></div></section>`;
+    case "product-detail":
+      return `<section class="hf-split"><div class="panel"><h3>Gallery and spec area</h3><table class="spec-table"><tr><th>Spec</th><th>Value</th></tr><tr><td>Voltage</td><td>High pressure</td></tr></table></div><aside class="panel"><h3>Price and quantity</h3><div class="qty-stepper"><button>-</button><span>1</span><button>+</button></div><a class="btn btn-primary" href="#">Add to cart</a></aside></section>`;
+    case "search":
+      return `<section class="panel"><h3>Search and result state</h3><div class="search-toolbar"><input aria-label="Search query" placeholder="Search product"><button class="btn btn-primary">Search</button></div><div class="hf-list"><article class="result-row">Result item</article><article class="result-row no-result">No-result state</article></div></section>`;
+    case "cart":
+      return `<section class="hf-split"><div class="panel"><h3>Cart table</h3><table class="cart-table"><tr><th>Item</th><th>Qty</th><th>Total</th></tr><tr><td>Product</td><td><div class="qty-stepper"><button>-</button><span>2</span><button>+</button></div></td><td>100000</td></tr></table></div><aside class="panel"><h3>Summary</h3><p>Subtotal, tax, total</p><a class="btn btn-primary" href="#">Checkout</a></aside></section>`;
+    case "checkout":
+      return `<section class="panel"><ol class="checkout-stepper"><li>Information</li><li>Confirmation</li><li>Complete</li></ol><div class="hf-split"><div class="panel"><h3>Checkout form</h3><div class="field-row">Recipient / Address / Phone</div></div><aside class="panel"><h3>Summary card</h3><a class="btn btn-primary" href="#">Place order</a></aside></div></section>`;
+    case "order-history":
+      return `<section class="panel"><h3>Order history list</h3><div class="hf-list"><article class="result-row">Order #001 / paid</article><article class="result-row">Order #002 / shipping</article></div></section>`;
+    case "order-detail":
+      return `<section class="hf-split"><div class="panel"><h3>Order timeline</h3><ul class="timeline"><li>Placed</li><li>Paid</li><li>Shipping</li></ul></div><aside class="panel"><h3>Detail summary</h3><p>Delivery and payment snapshot</p></aside></section>`;
+    case "account-info":
+      return `<section class="hf-split"><aside class="panel">Account sidebar</aside><div class="panel"><h3>View or edit form</h3><div class="field-row">Company / Contact / Email / Phone</div><a class="btn btn-primary" href="#">Save profile</a></div></section>`;
+    case "mode-b-configurator":
+      return `<section class="panel"><h3>Configurator wizard</h3><ol class="checkout-stepper"><li>Project</li><li>Assembly</li><li>Construction</li><li>Review</li></ol><div class="hf-split"><div class="panel"><h4>Preview panel</h4><p>Derived material preview</p></div><div class="panel"><h4>BOM table</h4><table class="cart-table"><tr><th>Material</th><th>Qty</th><th>Action</th></tr><tr><td>Cable</td><td>4</td><td><button>Exclude</button></td></tr></table><div class="button-row"><a class="btn btn-secondary" href="#">Recalculate</a><a class="btn btn-primary" href="#">Add BOM to cart</a></div></div></div></section>`;
+    default:
+      return `<section class="panel"><h3>Screen contract section</h3><p>Render screen-specific layout from brief + component contract.</p></section>`;
+  }
+}
+
+function highFidelityMultiScreenPrototypeContent({ style, statePayload, contractBundle }) {
+  const styleName = resolveStyleName(style);
+  const tokens = contractBundle.tokens || {};
+  const screens = statePayload.screenModel.screens;
+  const profileSelection = statePayload.profileSelection || null;
+  const mappedRefs = statePayload.referenceMap && typeof statePayload.referenceMap.mappedCount === "number" ? statePayload.referenceMap.mappedCount : 0;
+  const sections = screens
+    .map((screen) => {
+      const screenRole = normalizeScreenRole(screen);
+      const contract = contractBundle.screenContracts.get(screen.screenId);
+      const sidecar = contract && contract.sidecar ? contract.sidecar : null;
+      const stateChips = renderStateChips(sidecar && Array.isArray(sidecar.required_states) ? sidecar.required_states : screen.requiredStates);
+      return `
+      <section class="prototype-section screen-${escapeHtml(screen.screenId)}" id="screen-${escapeHtml(screen.screenId)}" aria-labelledby="title-${escapeHtml(screen.screenId)}">
+        <div class="section-inner">
+          <div class="section-header">
+            <p class="eyebrow">${escapeHtml(screenRole.replace(/-/g, " "))}</p>
+            <h2 id="title-${escapeHtml(screen.screenId)}">${escapeHtml(screen.title)}</h2>
+            ${screen.route ? `<p class="support">Route: <code>${escapeHtml(screen.route)}</code></p>` : ""}
+            <p class="support">Source brief: <code>${escapeHtml(path.basename(contract.briefPath))}</code></p>
+          </div>
+          ${stateChips}
+          ${renderHighFidelityScreen(screenRole, screen.title)}
+        </div>
+      </section>`;
+    })
+    .join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SDTK-DESIGN High-Fidelity Prototype</title>
+  <style>
+    :root { --bg:${tokenOrDefault(tokens, ["color", "surfaceAlt"], "#F5F7FB")}; --surface:${tokenOrDefault(tokens, ["color", "surface"], "#FFFFFF")}; --text:${tokenOrDefault(tokens, ["color", "textPrimary"], "#111827")}; --muted:${tokenOrDefault(tokens, ["color", "textMuted"], "#64748B")}; --primary:${tokenOrDefault(tokens, ["color", "accentPrimary"], "#0F766E")}; --accent:${tokenOrDefault(tokens, ["color", "accentSecondary"], "#2563EB")}; --border:${tokenOrDefault(tokens, ["color", "border"], "#D8E0EA")}; --shadow:0 18px 40px rgba(15,23,42,0.10); }
+    * { box-sizing:border-box; } body { margin:0; background:var(--bg); color:var(--text); font:15px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+    .shell { width:min(1240px, calc(100vw - 24px)); margin:0 auto; padding:24px 0 48px; }
+    .topbar { position:sticky; top:0; z-index:4; background:color-mix(in srgb, var(--bg) 92%, var(--surface)); border:1px solid var(--border); border-radius:8px; box-shadow:var(--shadow); padding:14px; margin-bottom:18px; }
+    .topline { display:flex; gap:10px; align-items:center; justify-content:space-between; flex-wrap:wrap; }
+    .meta { color:var(--muted); font-size:12px; font-weight:700; }
+    .nav { display:flex; gap:8px; overflow:auto; margin-top:10px; padding-bottom:4px; } .nav a { text-decoration:none; border:1px solid var(--border); border-radius:999px; padding:6px 10px; white-space:nowrap; color:var(--text); background:var(--surface); font-size:12px; font-weight:700; }
+    .prototype-section { background:var(--surface); border:1px solid var(--border); border-radius:8px; box-shadow:var(--shadow); margin:14px 0; } .section-inner { padding:20px; }
+    .eyebrow { margin:0 0 6px; color:var(--primary); font-size:12px; font-weight:800; text-transform:uppercase; } h2,h3,h4,p { margin-top:0; } h2 { margin-bottom:8px; font-size:28px; } .support { color:var(--muted); margin-bottom:10px; }
+    .chip-row { display:flex; gap:8px; flex-wrap:wrap; margin:10px 0 12px; } .chip { border:1px solid var(--border); border-radius:999px; padding:4px 10px; font-size:12px; background:color-mix(in srgb, var(--surface) 92%, var(--bg)); } .chip-state { color:var(--primary); border-color:color-mix(in srgb, var(--primary) 35%, var(--border)); }
+    .panel { border:1px solid var(--border); border-radius:8px; padding:14px; background:color-mix(in srgb, var(--surface) 95%, var(--bg)); }
+    .hf-split { display:grid; grid-template-columns:minmax(220px,0.35fr) minmax(0,1fr); gap:12px; }
+    .hf-feature-grid, .hf-card-grid { display:grid; gap:12px; grid-template-columns:repeat(3, minmax(0, 1fr)); }
+    .product-card, .result-row { border:1px solid var(--border); border-radius:8px; padding:10px; background:var(--surface); }
+    .search-toolbar { display:flex; gap:8px; flex-wrap:wrap; margin-bottom:10px; } input { min-height:40px; border:1px solid var(--border); border-radius:8px; padding:0 12px; min-width:220px; }
+    .button-row { display:flex; flex-wrap:wrap; gap:10px; margin-top:10px; } .btn { display:inline-flex; min-height:40px; align-items:center; justify-content:center; border-radius:8px; padding:0 14px; text-decoration:none; font-weight:800; border:1px solid transparent; } .btn-primary { background:var(--primary); color:#fff; } .btn-secondary { border-color:var(--border); color:var(--text); background:transparent; }
+    .spec-table, .cart-table { width:100%; border-collapse:collapse; font-size:13px; } .spec-table th, .spec-table td, .cart-table th, .cart-table td { border-bottom:1px solid var(--border); text-align:left; padding:8px 6px; }
+    .qty-stepper { display:inline-flex; align-items:center; gap:8px; border:1px solid var(--border); border-radius:8px; padding:4px 8px; }
+    .checkout-stepper { display:flex; gap:10px; list-style:none; padding:0; margin:0 0 12px; } .checkout-stepper li { border:1px solid var(--border); border-radius:999px; padding:4px 10px; font-size:12px; font-weight:700; }
+    .timeline { margin:0; padding-left:16px; } .field-row { border:1px dashed var(--border); border-radius:8px; padding:10px; color:var(--muted); }
+    @media (max-width: 920px) { .hf-split,.hf-feature-grid,.hf-card-grid { grid-template-columns:1fr; } h2 { font-size:24px; } }
+  </style>
+</head>
+<body>
+  <main class="shell style-${styleName}" data-style-preset="${styleName}">
+    <header class="topbar">
+      <div class="topline">
+        <strong>SDTK-DESIGN high-fidelity prototype</strong>
+        <span class="meta">screens=${screens.length} | profile=${escapeHtml(profileSelection || "none")} | mapped references=${mappedRefs}</span>
+      </div>
+      <nav class="nav" aria-label="Screen navigation">
+        ${screens.map((screen) => `<a href="#screen-${escapeHtml(screen.screenId)}">${escapeHtml(screen.title)}</a>`).join("")}
+      </nav>
+    </header>
+    ${sections}
+  </main>
+</body>
+</html>
+`;
 }
 
 function multiScreenPrototypeContent({ style, statePayload }) {
@@ -429,8 +637,16 @@ function runDesignPrototype({ projectPath, force = false, style }) {
     const list = missing.map((target) => target.relativePath).join(", ");
     throw new ValidationError(`Missing required design artifacts: ${list}. Run sdtk-design start --idea "<idea>" first. No project files were changed.`);
   }
-  if (fs.existsSync(paths.prototypeIndexPath) && !force) {
-    throw new ValidationError("docs/design/prototype/index.html already exists. Re-run with --force to replace this managed prototype.");
+  const prototypeMode = resolvePrototypeMode(canUseMultiScreen);
+  const existingManagedPrototype = managedPrototypeTargets(paths, inputContractState, prototypeMode).filter((target) =>
+    fs.existsSync(target.filePath)
+  );
+  if (existingManagedPrototype.length > 0 && !force) {
+    throw new ValidationError(
+      `docs/design/prototype/index.html already exists. Managed prototype output already exists: ${existingManagedPrototype
+        .map((target) => target.relativePath)
+        .join(", ")}. Re-run with --force to replace managed prototype outputs.`
+    );
   }
 
   const designSystemContent = fs.existsSync(paths.designSystemPath) ? fs.readFileSync(paths.designSystemPath, "utf-8") : "";
@@ -448,29 +664,61 @@ function runDesignPrototype({ projectPath, force = false, style }) {
                 : wireframePath(paths, "DASHBOARD.md");
           return fs.readFileSync(filePath, "utf-8");
         });
-  const content = canUseMultiScreen
-    ? multiScreenPrototypeContent({
+  let renderResult = null;
+  let content = null;
+  let bundle = null;
+  if (canUseMultiScreen) {
+    bundle = loadHighFidelityContracts(paths, inputContractState);
+    if (prototypeMode === "multi" && bundle.ready) {
+      renderResult = renderMultiPagePrototype({
+        paths,
+        statePayload: inputContractState,
+        contractBundle: bundle,
+        styleName,
+      });
+    } else if (bundle.ready) {
+      content = highFidelityMultiScreenPrototypeContent({
         style: styleName,
         statePayload: inputContractState,
-      })
-    : prototypeContent({
+        contractBundle: bundle,
+      });
+    } else {
+      content = multiScreenPrototypeContent({
         style: styleName,
-        briefContent: fs.readFileSync(paths.designBriefPath, "utf-8"),
-        screenMapContent: fs.readFileSync(paths.screenMapPath, "utf-8"),
-        designSystemContent,
-        wireframeContents,
+        statePayload: inputContractState,
       });
+    }
+  } else {
+    content = prototypeContent({
+      style: styleName,
+      briefContent: fs.readFileSync(paths.designBriefPath, "utf-8"),
+      screenMapContent: fs.readFileSync(paths.screenMapPath, "utf-8"),
+      designSystemContent,
+      wireframeContents,
+    });
+  }
 
-  fs.mkdirSync(path.dirname(paths.prototypeIndexPath), { recursive: true });
-  fs.writeFileSync(paths.prototypeIndexPath, content, "utf-8");
+  if (!renderResult) {
+    fs.mkdirSync(path.dirname(paths.prototypeIndexPath), { recursive: true });
+    fs.writeFileSync(paths.prototypeIndexPath, content, "utf-8");
+  }
 
   return {
     projectPath: resolvedProjectPath,
     relativePrototypePath: "docs/design/prototype/index.html",
     forced: Boolean(force),
     style: styleName,
-    mode: canUseMultiScreen ? "multi-screen" : "simple",
+    mode: renderResult
+      ? renderResult.mode
+      : canUseMultiScreen
+        ? bundle && bundle.ready
+          ? "high-fidelity-single-file"
+          : "multi-screen"
+        : "simple",
     screenCount: canUseMultiScreen ? inputContractState.screenModel.screens.length : 3,
+    warnings: canUseMultiScreen && bundle ? bundle.warnings : [],
+    generatedPages: renderResult ? renderResult.screenPages : [],
+    densityReport: renderResult ? renderResult.densityReport : null,
   };
 }
 
@@ -486,7 +734,18 @@ function cmdPrototype(args) {
 
   console.log(`[design] Wrote ${result.relativePrototypePath}: ${result.projectPath}`);
   console.log(`[design] Style: ${result.style}`);
-  console.log(`[design] Mode: ${result.mode} (${result.screenCount} screen section(s))`);
+  console.log(`[design] Mode: ${result.mode} (${result.screenCount} screen(s))`);
+  if (result.densityReport) {
+    console.log(
+      `[design] Density: ${result.densityReport.pass ? "PASS" : "FAIL"} total=${result.densityReport.totalBytes}/${result.densityReport.minTotalBytes} bytes`
+    );
+    for (const page of result.densityReport.pages) {
+      console.log(`[design] Density page: ${page.screenId} ${page.byteLength}/${page.minBytes} bytes ${page.pass ? "PASS" : "FAIL"}`);
+    }
+  }
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    console.log(`[design] Contract fallback: ${result.warnings.join("; ")}`);
+  }
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
   console.log("[design] Prototype mode: static HTML/CSS preview only.");
   console.log("[design] No app code outside docs/design/prototype, server, network, .sdtk/atlas, or SDTK-WIKI output was modified.");

package/src/commands/review.js

@@ -75,6 +75,197 @@ function includesAny(content, terms) {
   return terms.some((term) => lower.includes(term.toLowerCase()));
 }
 
+function readInputContractState(paths) {
+  if (!fs.existsSync(paths.designStartInputStatePath) || !fs.statSync(paths.designStartInputStatePath).isFile()) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(paths.designStartInputStatePath, "utf-8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function normalizeScreenRole(screen) {
+  const token = `${screen.screenId || ""} ${screen.title || ""}`.toLowerCase();
+  if (token.includes("home")) return "home";
+  if (token.includes("category")) return "category";
+  if (token.includes("product-detail") || token.includes("product detail") || token.includes("pdp")) return "product-detail";
+  if (token.includes("search")) return "search";
+  if (token.includes("cart")) return "cart";
+  if (token.includes("checkout")) return "checkout";
+  if (token.includes("order-history") || token.includes("order history")) return "order-history";
+  if (token.includes("order-detail") || token.includes("order detail")) return "order-detail";
+  if (token.includes("account")) return "account-info";
+  if (token.includes("configurator") || token.includes("mode-b")) return "mode-b-configurator";
+  return screen.screenId || "screen";
+}
+
+function requiredRoleMarkers(role) {
+  const map = {
+    home: ["hero", "featured products", "configurator"],
+    category: ["filter sidebar", "product grid"],
+    "product-detail": ["spec-table", "add to cart"],
+    search: ["search-toolbar", "no-result"],
+    cart: ["cart-table", "checkout"],
+    checkout: ["checkout-stepper", "summary card"],
+    "order-history": ["order history list"],
+    "order-detail": ["timeline", "detail summary"],
+    "account-info": ["account sidebar", "view or edit form"],
+    "mode-b-configurator": ["configurator wizard", "preview panel", "bom table", "recalculate", "add bom to cart"],
+  };
+  return map[role] || [];
+}
+
+function listPrototypeScreenFiles(paths) {
+  if (!fs.existsSync(paths.prototypeScreensPath) || !fs.statSync(paths.prototypeScreensPath).isDirectory()) {
+    return [];
+  }
+  return fs
+    .readdirSync(paths.prototypeScreensPath)
+    .filter((name) => name.toLowerCase().endsWith(".html"))
+    .sort()
+    .map((name) => path.join(paths.prototypeScreensPath, name));
+}
+
+function combinedPrototypeReviewContent({ artifactPath, artifactContent, paths }) {
+  const screenFiles = listPrototypeScreenFiles(paths);
+  if (screenFiles.length === 0) {
+    return artifactContent;
+  }
+  const parts = [artifactContent];
+  if (path.resolve(artifactPath) !== path.resolve(paths.prototypeIndexPath) && fs.existsSync(paths.prototypeIndexPath)) {
+    parts.push(fs.readFileSync(paths.prototypeIndexPath, "utf-8"));
+  }
+  for (const filePath of screenFiles) {
+    if (path.resolve(filePath) === path.resolve(artifactPath)) {
+      continue;
+    }
+    parts.push(fs.readFileSync(filePath, "utf-8"));
+  }
+  return parts.join("\n");
+}
+
+function evaluateHighFidelityGate({ artifactContent, statePayload, projectPath, paths }) {
+  const html = String(artifactContent || "").toLowerCase();
+  const screens = statePayload.screenModel.screens || [];
+  const profile = statePayload.profileSelection || "none";
+  const hasTokens = fs.existsSync(paths.designTokensPath);
+  const hasComponentLibrary = fs.existsSync(paths.componentPatternLibraryPath);
+  const hasPre = html.includes("<pre");
+  const hasRawJsonRisk = html.includes("json.stringify") || html.includes("raw json") || html.includes("{\"") || html.includes("not_found");
+  const hasNav = html.includes('aria-label="screen navigation"') || html.includes("screen navigation");
+  const hasStateChips = html.includes('data-chip-type="state"') || html.includes("chip");
+  const sectionRows = [];
+  let missingCount = 0;
+  for (const screen of screens) {
+    const id = String(screen.screenId || "");
+    const title = String(screen.title || id);
+    const role = normalizeScreenRole(screen);
+    const idMarker = `id="screen-${id}"`;
+    const navMarkers = [`href="#screen-${id}"`, `href="screens/${id}.html"`, `href="${id}.html"`];
+    const roleMarkers = requiredRoleMarkers(role);
+    const missing = [];
+    if (!html.includes(idMarker.toLowerCase())) missing.push("missing screen section id");
+    if (!navMarkers.some((marker) => html.includes(marker.toLowerCase()))) missing.push("missing navigation link");
+    for (const marker of roleMarkers) {
+      if (!html.includes(marker)) missing.push(`missing component marker: ${marker}`);
+    }
+    if (missing.length > 0) missingCount += 1;
+    sectionRows.push({
+      title,
+      role,
+      missing,
+      pass: missing.length === 0,
+    });
+  }
+
+  let verdict = "PASS_HIGH_FIDELITY_READY";
+  const blockers = [];
+  if (screens.length === 0) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("explicit screen model is empty");
+  }
+  if (!hasComponentLibrary) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("component pattern library missing");
+  }
+  if (!hasTokens) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("design tokens missing");
+  }
+  if (!hasNav) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("inter-screen navigation contract missing");
+  }
+  if (!hasStateChips) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("state chip coverage missing");
+  }
+  if (missingCount > 0) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push(`${missingCount} screen(s) missing required component markers`);
+  }
+  if (hasPre || hasRawJsonRisk) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("debug/raw JSON UI risk detected");
+  }
+  if (profile === "b2b-commerce" && !html.includes("configurator wizard")) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("configurator completeness missing");
+  }
+  if (html.includes("main layout</h3>") && html.includes("primary action</h3>")) {
+    verdict = "FAIL_HIGH_FIDELITY_NOT_READY";
+    blockers.push("generic scaffold markers detected (Main layout / Primary action)");
+  }
+  return {
+    verdict,
+    blockers,
+    profile,
+    sectionRows,
+    hasTokens,
+    hasComponentLibrary,
+    hasNav,
+    hasStateChips,
+    hasPre,
+    hasRawJsonRisk,
+    projectPath,
+  };
+}
+
+function fidelityReviewContent(result) {
+  return [
+    "# Design Fidelity Review",
+    "",
+    `- Verdict: ${result.verdict}`,
+    `- Profile: ${result.profile}`,
+    `- Component library: ${result.hasComponentLibrary ? "present" : "missing"}`,
+    `- Design tokens: ${result.hasTokens ? "present" : "missing"}`,
+    `- Navigation contract: ${result.hasNav ? "present" : "missing"}`,
+    `- State coverage markers: ${result.hasStateChips ? "present" : "missing"}`,
+    `- Raw <pre> debug risk: ${result.hasPre ? "detected" : "not detected"}`,
+    `- Raw JSON debug risk: ${result.hasRawJsonRisk ? "detected" : "not detected"}`,
+    "",
+    "## Screen-By-Screen Coverage",
+    "",
+    "| Screen | Role | Result | Actionable notes |",
+    "|---|---|---|---|",
+    ...result.sectionRows.map((row) => `| ${row.title} | ${row.role} | ${row.pass ? "PASS" : "FAIL"} | ${row.pass ? "coverage complete" : row.missing.join("; ")} |`),
+    "",
+    "## Gate Findings",
+    "",
+    ...(result.blockers.length > 0 ? result.blockers.map((item) => `- ${item}`) : ["- No blocking fidelity gaps found."]),
+    "",
+    "## Actions",
+    "",
+    "- Fill missing component markers per failed screen.",
+    "- Ensure design tokens and component pattern library are generated before review.",
+    "- Remove raw debug UI surfaces (`<pre>` and JSON dumps) from customer-facing prototype output.",
+    "- Re-run `sdtk-design prototype` and `sdtk-design review --artifact docs/design/prototype/index.html`.",
+    "",
+  ].join("\n");
+}
+
 function visualPolishChecks({ artifactRelativePath, artifactContent, prototypeHtml }) {
   const lower = String(artifactContent || "").toLowerCase();
   const hasLanding = lower.includes("section-landing") || lower.includes("landing");
@@ -191,12 +382,47 @@ function runDesignReview({ artifact, projectPath, force = false }) {
 
   const artifactContent = fs.readFileSync(artifactPath, "utf-8");
   const artifactRelativePath = toPosix(path.relative(resolvedProjectPath, artifactPath));
+  const statePayload = readInputContractState(paths);
+  const shouldRunFidelityGate =
+    isPrototypeHtmlArtifact(artifactRelativePath, artifactContent) &&
+    statePayload &&
+    statePayload.mode === "from-spec" &&
+    statePayload.analysisStatus === "INPUT_CONTRACT_READY" &&
+    statePayload.screenModel &&
+    Array.isArray(statePayload.screenModel.screens) &&
+    statePayload.screenModel.screens.length >= 4;
   fs.mkdirSync(paths.reviewsPath, { recursive: true });
   fs.writeFileSync(reportPath, reviewContent({ artifactRelativePath, artifactContent }), "utf-8");
 
+  let fidelityReportRelativePath = null;
+  let fidelityVerdict = null;
+  if (shouldRunFidelityGate) {
+    const fidelityArtifactContent = combinedPrototypeReviewContent({
+      artifactPath,
+      artifactContent,
+      paths,
+    });
+    const fidelityResult = evaluateHighFidelityGate({
+      artifactContent: fidelityArtifactContent,
+      statePayload,
+      projectPath: resolvedProjectPath,
+      paths,
+    });
+    const fidelityName = `DESIGN_FIDELITY_REVIEW_${formatDateYYYYMMDD()}.md`;
+    const fidelityPath = path.join(paths.reviewsPath, fidelityName);
+    if (fs.existsSync(fidelityPath) && !force) {
+      throw new ValidationError(`docs/design/reviews/${fidelityName} already exists. Re-run with --force to replace this managed fidelity review report.`);
+    }
+    fs.writeFileSync(fidelityPath, fidelityReviewContent(fidelityResult), "utf-8");
+    fidelityReportRelativePath = `docs/design/reviews/${fidelityName}`;
+    fidelityVerdict = fidelityResult.verdict;
+  }
+
   return {
     projectPath: resolvedProjectPath,
     relativeReportPath: `docs/design/reviews/${reportName}`,
+    fidelityReportRelativePath,
+    fidelityVerdict,
     forced: Boolean(force),
   };
 }
@@ -212,6 +438,10 @@ function cmdReview(args) {
   });
 
   console.log(`[design] Wrote ${result.relativeReportPath}: ${result.projectPath}`);
+  if (result.fidelityReportRelativePath) {
+    console.log(`[design] Wrote ${result.fidelityReportRelativePath}: ${result.projectPath}`);
+    console.log(`[design] Fidelity verdict: ${result.fidelityVerdict}`);
+  }
   console.log(`[design] Review mode: local artifact`);
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
   console.log("[design] No URL, browser, screenshot, vision, network, .sdtk/atlas, or SDTK-WIKI output was used.");