sdtk-design-kit 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-design-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local-first MVP design planner and reviewer for SDTK workspaces.",
   "bin": {
     "sdtk-design": "bin/sdtk-design.js"

package/src/commands/help.js

@@ -8,6 +8,7 @@ Usage:
   sdtk-design --version
   sdtk-design init
   sdtk-design start --idea "<idea>" --style premium-dashboard
+  sdtk-design start --from-spec . --reference-dir ./docs/ui/claude-design-export --profile b2b-commerce
   sdtk-design brief --idea "<idea>"
   sdtk-design screens
   sdtk-design wireframe --screen landing
@@ -19,6 +20,7 @@ Usage:
 
 Examples:
   sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads." --style premium-dashboard
+  sdtk-design start --from-spec . --reference-dir ./docs/ui/claude-design-export --profile b2b-commerce
   sdtk-design prototype --style premium-dashboard
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
@@ -31,6 +33,7 @@ Visual style presets:
 Foundation Beta purpose:
   SDTK-DESIGN is a local-first MVP design planner and reviewer for solo founders.
   It turns a rough MVP idea into reviewable design artifacts and a deterministic SDTK-CODE handoff.
+  For SPEC-driven flows, it consumes explicit design artifacts via start --from-spec; it does not parse raw requirement prose.
 
 Required human-facing output:
   docs/design/DESIGN_BRIEF.md

package/src/commands/prototype.js

@@ -67,6 +67,17 @@ const THEME_TOKENS = {
   },
 };
 
+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 cmdPrototypeHelp() {
   console.log(`SDTK-DESIGN Prototype
 
@@ -87,6 +98,7 @@ Reads:
   docs/design/wireframes/LANDING.md
   docs/design/wireframes/ONBOARDING.md
   docs/design/wireframes/DASHBOARD.md
+  .sdtk/design/START_INPUT_STATE.json (optional; enables explicit multi-screen rendering when ready)
 
 Creates:
   docs/design/prototype/index.html
@@ -275,6 +287,127 @@ function prototypeContent({ style, briefContent, screenMapContent, designSystemC
 `;
 }
 
+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 renderPrimitiveChips(primitiveNames) {
+  if (!Array.isArray(primitiveNames) || primitiveNames.length === 0) return "";
+  return `<div class="chip-row">${primitiveNames.map((item) => `<span class="chip">${escapeHtml(item)}</span>`).join("")}</div>`;
+}
+
+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>`;
+}
+
+function multiScreenPrototypeContent({ style, statePayload }) {
+  const styleName = resolveStyleName(style);
+  const tokens = THEME_TOKENS[styleName];
+  const screens = statePayload.screenModel.screens;
+  const profileSelection = statePayload.profileSelection || null;
+  const profilePrimitives = statePayload.profilePrimitives || null;
+  const mappedRefs = statePayload.referenceMap && typeof statePayload.referenceMap.mappedCount === "number" ? statePayload.referenceMap.mappedCount : 0;
+
+  const sections = screens
+    .map((screen) => {
+      const screenRole = normalizeScreenRole(screen);
+      const primitiveHints =
+        profilePrimitives &&
+        profilePrimitives.screenRoleHints &&
+        Array.isArray(profilePrimitives.screenRoleHints[screenRole])
+          ? profilePrimitives.screenRoleHints[screenRole]
+          : [];
+      const majorSections = Array.isArray(screen.majorSections) && screen.majorSections.length > 0 ? screen.majorSections : ["Primary content", "Supporting panel"];
+      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>` : ""}
+            ${screen.purpose ? `<p class="support">${escapeHtml(screen.purpose)}</p>` : ""}
+          </div>
+          ${renderPrimitiveChips(primitiveHints)}
+          ${renderStateChips(screen.requiredStates)}
+          <div class="screen-grid">
+            <article class="panel">
+              <h3>Main layout</h3>
+              <ul>${majorSections.slice(0, 5).map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>
+            </article>
+            <article class="panel">
+              <h3>Primary action</h3>
+              <p>${escapeHtml(screen.primaryAction || "Primary CTA from explicit input")}</p>
+              <div class="button-row"><a class="btn btn-primary" href="#screen-${escapeHtml(screen.screenId)}">Trigger CTA</a></div>
+            </article>
+          </div>
+        </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 Multi-Screen Prototype</title>
+  <style>
+    :root { --bg:${tokens.bg}; --surface:${tokens.surface}; --text:${tokens.text}; --muted:${tokens.muted}; --primary:${tokens.primary}; --accent:${tokens.accent}; --border:${tokens.border}; --shadow:${tokens.shadow}; }
+    * { 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(1200px, calc(100vw - 24px)); margin:0 auto; padding:24px 0 44px; }
+    .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,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)); }
+    .screen-grid { display:grid; grid-template-columns:1.2fr 1fr; gap:12px; }
+    .panel { border:1px solid var(--border); border-radius:8px; padding:14px; }
+    .panel ul { margin:0; padding-left:18px; }
+    .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; }
+    .btn-primary { background:var(--primary); color:#fff; }
+    @media (max-width: 820px) { .screen-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 multi-screen 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 runDesignPrototype({ projectPath, force = false, style }) {
   const explicitStyleName = typeof style === "string" && style.trim() ? resolveStyleName(style) : null;
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
@@ -283,7 +416,15 @@ function runDesignPrototype({ projectPath, force = false, style }) {
   }
 
   const paths = describeDesignPaths(resolvedProjectPath);
-  const missing = requiredArtifactTargets(paths).filter((target) => !fs.existsSync(target.filePath));
+  const inputContractState = readInputContractState(paths);
+  const canUseMultiScreen =
+    inputContractState &&
+    inputContractState.mode === "from-spec" &&
+    inputContractState.analysisStatus === "INPUT_CONTRACT_READY" &&
+    inputContractState.screenModel &&
+    Array.isArray(inputContractState.screenModel.screens) &&
+    inputContractState.screenModel.screens.length > 0;
+  const missing = canUseMultiScreen ? [] : requiredArtifactTargets(paths).filter((target) => !fs.existsSync(target.filePath));
   if (missing.length > 0) {
     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.`);
@@ -292,26 +433,33 @@ function runDesignPrototype({ projectPath, force = false, style }) {
     throw new ValidationError("docs/design/prototype/index.html already exists. Re-run with --force to replace this managed prototype.");
   }
 
-  const designSystemContent = fs.readFileSync(paths.designSystemPath, "utf-8");
-  const styleName = explicitStyleName || inferStyleFromDesignSystem(designSystemContent);
-  const wireframeContents = REQUIRED_ARTIFACTS
-    .filter(([relativePath]) => relativePath.startsWith("docs/design/wireframes/"))
-    .map(([, key]) => {
-      const filePath =
-        key === "landingWireframePath"
-          ? wireframePath(paths, "LANDING.md")
-          : key === "onboardingWireframePath"
-            ? wireframePath(paths, "ONBOARDING.md")
-            : wireframePath(paths, "DASHBOARD.md");
-      return fs.readFileSync(filePath, "utf-8");
-    });
-  const content = prototypeContent({
-    style: styleName,
-    briefContent: fs.readFileSync(paths.designBriefPath, "utf-8"),
-    screenMapContent: fs.readFileSync(paths.screenMapPath, "utf-8"),
-    designSystemContent,
-    wireframeContents,
-  });
+  const designSystemContent = fs.existsSync(paths.designSystemPath) ? fs.readFileSync(paths.designSystemPath, "utf-8") : "";
+  const styleName = explicitStyleName || (designSystemContent ? inferStyleFromDesignSystem(designSystemContent) : DEFAULT_STYLE);
+  const wireframeContents = canUseMultiScreen
+    ? []
+    : REQUIRED_ARTIFACTS
+        .filter(([relativePath]) => relativePath.startsWith("docs/design/wireframes/"))
+        .map(([, key]) => {
+          const filePath =
+            key === "landingWireframePath"
+              ? wireframePath(paths, "LANDING.md")
+              : key === "onboardingWireframePath"
+                ? wireframePath(paths, "ONBOARDING.md")
+                : wireframePath(paths, "DASHBOARD.md");
+          return fs.readFileSync(filePath, "utf-8");
+        });
+  const content = canUseMultiScreen
+    ? multiScreenPrototypeContent({
+        style: styleName,
+        statePayload: inputContractState,
+      })
+    : 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");
@@ -321,6 +469,8 @@ function runDesignPrototype({ projectPath, force = false, style }) {
     relativePrototypePath: "docs/design/prototype/index.html",
     forced: Boolean(force),
     style: styleName,
+    mode: canUseMultiScreen ? "multi-screen" : "simple",
+    screenCount: canUseMultiScreen ? inputContractState.screenModel.screens.length : 3,
   };
 }
 
@@ -336,6 +486,7 @@ 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] 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/start.js

@@ -8,6 +8,8 @@ const { runDesignSystem } = require("./system");
 const { runDesignWireframe } = require("./wireframe");
 const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
+const { availableProfileNames } = require("../lib/design-profiles");
+const { buildInputContractState, writeInputContractState } = require("../lib/design-input-contract");
 const { ValidationError } = require("../lib/errors");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
@@ -17,6 +19,10 @@ const START_FLAG_DEFS = {
   "project-path": { type: "string" },
   force: { type: "boolean" },
   style: { type: "string" },
+  "from-spec": { type: "string" },
+  "design-brief": { type: "string" },
+  "reference-dir": { type: "string" },
+  profile: { type: "string" },
 };
 
 const REQUIRED_WIREFRAME_FILES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
@@ -26,29 +32,41 @@ function cmdStartHelp() {
 
 Usage:
   sdtk-design start --idea "<rough MVP idea>" [--style <preset>] [--project-path <path>] [--force]
+  sdtk-design start --from-spec <projectPath> [--design-brief <file>] [--reference-dir <dir>] [--profile <name>] [--project-path <path>]
 
 Example:
   sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads."
   sdtk-design start --idea "ClientPulse for consultants" --style premium-dashboard
+  sdtk-design start --from-spec . --reference-dir ./docs/ui/claude-design-export --profile b2b-commerce
 
-Style presets:
+  Style presets:
   ${availableStyleNames().join(", ")}
   Default: ${DEFAULT_STYLE}
 
+  Design profiles (optional in from-spec mode):
+  ${availableProfileNames().join(", ")}
+
 Runs:
-  brief -> screens -> wireframe --screen all -> system
+  idea mode:
+    brief -> screens -> wireframe --screen all -> system
+  from-spec mode:
+    explicit SPEC/design artifact intake -> contract state write
 
 Creates:
-  docs/design/DESIGN_BRIEF.md
-  docs/design/SCREEN_MAP.md
-  docs/design/wireframes/LANDING.md
-  docs/design/wireframes/ONBOARDING.md
-  docs/design/wireframes/DASHBOARD.md
-  docs/design/DESIGN_SYSTEM.md
+  idea mode:
+    docs/design/DESIGN_BRIEF.md
+    docs/design/SCREEN_MAP.md
+    docs/design/wireframes/LANDING.md
+    docs/design/wireframes/ONBOARDING.md
+    docs/design/wireframes/DASHBOARD.md
+    docs/design/DESIGN_SYSTEM.md
+  from-spec mode:
+    .sdtk/design/START_INPUT_STATE.json
 
 Safety:
   Local files only.
   Existing managed core design outputs are not overwritten unless --force is explicit.
+  --from-spec consumes explicit artifacts; no raw requirement semantic parsing.
   No review, handoff, URL, browser, screenshot, vision, or DOM work.
   No .sdtk/atlas creation or mutation.
   No SDTK-WIKI output mutation.
@@ -104,10 +122,66 @@ function runDesignStart({ idea, projectPath, force = false, style = DEFAULT_STYL
   };
 }
 
+function runDesignStartFromSpec({
+  fromSpecPath,
+  projectPath,
+  designBrief,
+  referenceDir,
+  profile,
+}) {
+  const contractState = buildInputContractState({
+    fromSpecPath,
+    projectPath,
+    designBriefPath: designBrief,
+    referenceDir,
+    profile,
+  });
+  const statePath = writeInputContractState(contractState.projectPath, contractState);
+  return {
+    ...contractState,
+    statePath,
+    stateRelativePath: ".sdtk/design/START_INPUT_STATE.json",
+  };
+}
+
 function cmdStart(args) {
   const { flags } = parseFlags(args || [], START_FLAG_DEFS);
   if (flags.help) return cmdStartHelp();
 
+  const contractMode = Boolean(flags["from-spec"] || flags["design-brief"] || flags["reference-dir"] || flags.profile);
+  if (contractMode) {
+    const contractResult = runDesignStartFromSpec({
+      fromSpecPath: flags["from-spec"],
+      projectPath: flags["project-path"],
+      designBrief: flags["design-brief"],
+      referenceDir: flags["reference-dir"],
+      profile: flags.profile,
+    });
+    if (contractResult.blockers.length > 0) {
+      throw new ValidationError(
+        `SDTK-DESIGN input contract blocked: ${contractResult.blockers.join(", ")}. Review ${contractResult.stateRelativePath}.`
+      );
+    }
+    console.log(`[design] Started SDTK-DESIGN package: ${contractResult.projectPath}`);
+    console.log(`[design] Mode: from-spec`);
+    console.log(`[design] Wrote ${contractResult.stateRelativePath}`);
+    console.log(`[design] Screen model: ${contractResult.screenModel.totalScreens} explicit screen(s), readiness=${contractResult.screenModel.readiness}`);
+    if (contractResult.referenceDirectory && contractResult.referenceDirectory.provided) {
+      console.log(
+        `[design] Reference map: ${contractResult.referenceMap.mappedCount}/${contractResult.referenceMap.totalFiles} mapped (${contractResult.referenceMap.unmappedCount} unmapped)`
+      );
+    }
+    console.log(
+      `[design] Inputs: ${Object.entries(contractResult.artifacts)
+        .filter(([, artifact]) => artifact.found)
+        .map(([name, artifact]) => `${name}=${artifact.relativeToSpecRoot}`)
+        .join(", ")}`
+    );
+    console.log("[design] No raw requirement semantic parsing, .sdtk/atlas, SDTK-WIKI output, or network activity was used.");
+    console.log("[design] Next: sdtk-design prototype");
+    return 0;
+  }
+
   const result = runDesignStart({
     idea: flags.idea,
     projectPath: flags["project-path"],
@@ -128,5 +202,6 @@ module.exports = {
   cmdStart,
   cmdStartHelp,
   coreOutputTargets,
+  runDesignStartFromSpec,
   runDesignStart,
 };

package/src/commands/status.js

@@ -53,6 +53,17 @@ function hasReview(paths) {
   return fs.readdirSync(paths.reviewsPath).some((name) => /^DESIGN_REVIEW_\d{8}\.md$/.test(name));
 }
 
+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 inspectDesignStatus(projectPath) {
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
   if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
@@ -65,12 +76,19 @@ function inspectDesignStatus(projectPath) {
     exists: fs.existsSync(artifact.filePath),
   }));
   const reviewExists = hasReview(paths);
+  const inputContractState = readInputContractState(paths);
   const coreMissing = artifacts.filter((artifact) => artifact.phase === "core" && !artifact.exists);
   const prototypeMissing = artifacts.find((artifact) => artifact.phase === "prototype" && !artifact.exists);
   const handoffMissing = artifacts.find((artifact) => artifact.phase === "handoff" && !artifact.exists);
 
   let nextCommand = "SDTK-CODE can consume docs/design/DESIGN_HANDOFF.md";
-  if (coreMissing.length > 0) {
+  if (inputContractState && inputContractState.mode === "from-spec") {
+    if (Array.isArray(inputContractState.blockers) && inputContractState.blockers.length > 0) {
+      nextCommand = "Provide missing explicit SPEC/design artifacts and re-run sdtk-design start --from-spec.";
+    } else {
+      nextCommand = "sdtk-design prototype";
+    }
+  } else if (coreMissing.length > 0) {
     nextCommand = 'sdtk-design start --idea "<idea>"';
   } else if (prototypeMissing) {
     nextCommand = "sdtk-design prototype";
@@ -83,6 +101,7 @@ function inspectDesignStatus(projectPath) {
   return {
     projectPath: resolvedProjectPath,
     artifacts,
+    inputContractState,
     reviewExists,
     nextCommand,
   };
@@ -122,6 +141,23 @@ function cmdStatus(args) {
     }
   }
   console.log("");
+  console.log("Input contract:");
+  if (!status.inputContractState) {
+    console.log("  - not found");
+  } else {
+    console.log(`  - mode: ${status.inputContractState.mode}`);
+    console.log(`  - status: ${status.inputContractState.analysisStatus}`);
+    if (status.inputContractState.screenModel && typeof status.inputContractState.screenModel.totalScreens === "number") {
+      console.log(`  - explicit screens: ${status.inputContractState.screenModel.totalScreens}`);
+      console.log(`  - readiness: ${status.inputContractState.screenModel.readiness}`);
+    }
+    if (status.inputContractState.profileSelection) {
+      console.log(`  - profile: ${status.inputContractState.profileSelection}`);
+    }
+    const blockers = Array.isArray(status.inputContractState.blockers) ? status.inputContractState.blockers : [];
+    console.log(`  - blockers: ${blockers.length > 0 ? blockers.join(", ") : "none"}`);
+  }
+  console.log("");
   console.log(`Next recommended command: ${status.nextCommand}`);
   console.log("No .sdtk/atlas, SDTK-WIKI output, network, or app code was modified.");
   return 0;

package/src/lib/design-input-contract.js

@@ -0,0 +1,423 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { describeDesignPaths, resolveProjectPath } = require("./design-paths");
+const { resolveProfile } = require("./design-profiles");
+const { ValidationError } = require("./errors");
+
+function toPosixRelative(basePath, targetPath) {
+  return path.relative(basePath, targetPath).split(path.sep).join("/");
+}
+
+function findArtifactByPattern(rootPath, relativeDir, pattern) {
+  const absoluteDir = path.join(rootPath, relativeDir);
+  if (!fs.existsSync(absoluteDir) || !fs.statSync(absoluteDir).isDirectory()) {
+    return null;
+  }
+  const entries = fs
+    .readdirSync(absoluteDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && pattern.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  if (entries.length === 0) {
+    return null;
+  }
+  const fileName = entries[0];
+  const absolutePath = path.join(absoluteDir, fileName);
+  return {
+    relativePath: `${relativeDir.replace(/\\/g, "/")}/${fileName}`,
+    absolutePath,
+  };
+}
+
+function resolveReferenceDirectory(value, projectPath) {
+  if (!value) {
+    return { provided: false, status: "NOT_PROVIDED", absolutePath: null };
+  }
+  const absolutePath = path.resolve(projectPath, value);
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isDirectory()) {
+    throw new ValidationError(`--reference-dir is not a valid directory: ${absolutePath}. No project files were changed.`);
+  }
+  return {
+    provided: true,
+    status: "READY_READ_ONLY",
+    absolutePath,
+  };
+}
+
+function listFilesRecursive(rootDirectory) {
+  const results = [];
+  const stack = [rootDirectory];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(absolutePath);
+        continue;
+      }
+      if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  results.sort();
+  return results;
+}
+
+function tokenSet(value) {
+  return new Set(
+    String(value || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, " ")
+      .split(" ")
+      .map((token) => token.trim())
+      .filter(Boolean)
+  );
+}
+
+function readHtmlHints(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const titleMatch = raw.match(/<title[^>]*>(.*?)<\/title>/i);
+    const headingMatch = raw.match(/<h[1-2][^>]*>(.*?)<\/h[1-2]>/i);
+    return {
+      title: titleMatch ? titleMatch[1].replace(/<[^>]+>/g, " ").trim() : "",
+      heading: headingMatch ? headingMatch[1].replace(/<[^>]+>/g, " ").trim() : "",
+    };
+  } catch (_err) {
+    return { title: "", heading: "" };
+  }
+}
+
+function confidenceFromScore(score) {
+  if (score >= 4) return "high";
+  if (score >= 2) return "medium";
+  if (score >= 1) return "low";
+  return "low";
+}
+
+function mapReferenceFiles({ referenceDir, screens }) {
+  const files = listFilesRecursive(referenceDir);
+  const entries = [];
+  const screenTargets = Array.isArray(screens) ? screens : [];
+  const supportedExtensions = new Set([".html", ".htm", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"]);
+  for (const absolutePath of files) {
+    const relativePath = toPosixRelative(referenceDir, absolutePath);
+    const extension = path.extname(absolutePath).toLowerCase();
+    if (!supportedExtensions.has(extension)) {
+      entries.push({
+        sourceFileRelativePath: relativePath,
+        fileType: extension || "unknown",
+        mappedScreenId: null,
+        mappedScreenTitle: null,
+        confidence: "low",
+        evidenceNotes: ["unsupported file type"],
+        status: "unmapped",
+      });
+      continue;
+    }
+
+    const baseTokens = tokenSet(path.basename(absolutePath, extension));
+    const htmlHints = extension === ".html" || extension === ".htm" ? readHtmlHints(absolutePath) : { title: "", heading: "" };
+    const titleTokens = tokenSet(htmlHints.title);
+    const headingTokens = tokenSet(htmlHints.heading);
+
+    let bestMatch = null;
+    for (const screen of screenTargets) {
+      const screenTokens = tokenSet(`${screen.screenId} ${screen.title}`);
+      let score = 0;
+      const evidence = [];
+      for (const token of screenTokens) {
+        if (baseTokens.has(token)) {
+          score += 2;
+          evidence.push(`filename token match: ${token}`);
+        }
+        if (titleTokens.has(token)) {
+          score += 1;
+          evidence.push(`title token match: ${token}`);
+        }
+        if (headingTokens.has(token)) {
+          score += 1;
+          evidence.push(`heading token match: ${token}`);
+        }
+      }
+      if (!bestMatch || score > bestMatch.score) {
+        bestMatch = { score, screen, evidence };
+      }
+    }
+
+    if (!bestMatch || bestMatch.score <= 0) {
+      entries.push({
+        sourceFileRelativePath: relativePath,
+        fileType: extension,
+        mappedScreenId: null,
+        mappedScreenTitle: null,
+        confidence: "low",
+        evidenceNotes: ["no deterministic filename/title/heading match"],
+        status: "unmapped",
+      });
+      continue;
+    }
+
+    entries.push({
+      sourceFileRelativePath: relativePath,
+      fileType: extension,
+      mappedScreenId: bestMatch.screen.screenId,
+      mappedScreenTitle: bestMatch.screen.title,
+      confidence: confidenceFromScore(bestMatch.score),
+      evidenceNotes: bestMatch.evidence,
+      status: "mapped",
+    });
+  }
+
+  return {
+    totalFiles: entries.length,
+    mappedCount: entries.filter((entry) => entry.status === "mapped").length,
+    unmappedCount: entries.filter((entry) => entry.status !== "mapped").length,
+    entries,
+  };
+}
+
+function writeInputContractState(projectPath, statePayload) {
+  const paths = describeDesignPaths(projectPath);
+  fs.mkdirSync(paths.designStatePath, { recursive: true });
+  fs.writeFileSync(paths.designStartInputStatePath, `${JSON.stringify(statePayload, null, 2)}\n`, "utf-8");
+  return paths.designStartInputStatePath;
+}
+
+function toScreenId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function normalizedScreenRecord(raw, sourceArtifact, fallbackTitle) {
+  const title = String(
+    (raw && (raw.title || raw.name || raw.screen || raw.label || raw.id)) || fallbackTitle || ""
+  ).trim();
+  if (!title) {
+    return null;
+  }
+  const screenId = toScreenId((raw && (raw.id || raw.slug)) || title);
+  const route = raw && typeof raw.route === "string" ? raw.route.trim() : "";
+  const purpose = raw && typeof raw.purpose === "string" ? raw.purpose.trim() : "";
+  const primaryAction = raw && typeof raw.primaryAction === "string" ? raw.primaryAction.trim() : "";
+  const majorSections = Array.isArray(raw && raw.majorSections)
+    ? raw.majorSections.map((value) => String(value).trim()).filter(Boolean)
+    : [];
+  const requiredStates = Array.isArray(raw && raw.requiredStates)
+    ? raw.requiredStates.map((value) => String(value).trim()).filter(Boolean)
+    : [];
+  const populatedCount = [route, purpose, primaryAction].filter(Boolean).length + (majorSections.length > 0 ? 1 : 0) + (requiredStates.length > 0 ? 1 : 0);
+  const confidence = populatedCount >= 3 ? "high" : populatedCount >= 1 ? "medium" : "low";
+  return {
+    screenId,
+    title,
+    route: route || null,
+    purpose: purpose || null,
+    primaryAction: primaryAction || null,
+    majorSections,
+    requiredStates,
+    sourceArtifact,
+    sourceStatus: "explicit",
+    confidence,
+  };
+}
+
+function extractScreensFromHandoffJson(handoffPath, relativePath) {
+  const raw = fs.readFileSync(handoffPath, "utf-8");
+  let payload = null;
+  try {
+    payload = JSON.parse(raw);
+  } catch (_err) {
+    return [];
+  }
+  const candidateArrays = [
+    payload && payload.screens,
+    payload && payload.screenInventory,
+    payload && payload.screen_inventory,
+    payload && payload.screenList,
+    payload && payload.screen_list,
+  ].filter(Array.isArray);
+  const screens = [];
+  for (const candidateArray of candidateArrays) {
+    for (const item of candidateArray) {
+      const record =
+        typeof item === "string"
+          ? normalizedScreenRecord({ title: item }, relativePath, item)
+          : normalizedScreenRecord(item || {}, relativePath, "");
+      if (record) {
+        screens.push(record);
+      }
+    }
+  }
+  return screens;
+}
+
+function extractScreensFromInventoryMarkdown(inventoryPath, relativePath) {
+  const lines = fs.readFileSync(inventoryPath, "utf-8").split(/\r?\n/);
+  const screens = [];
+  for (const line of lines) {
+    const headingMatch = line.match(/^###\s+(.+?)\s*$/);
+    if (headingMatch) {
+      const record = normalizedScreenRecord({ title: headingMatch[1] }, relativePath, headingMatch[1]);
+      if (record) screens.push(record);
+      continue;
+    }
+    const listMatch = line.match(/^\s*-\s+(.+?)\s*$/);
+    if (listMatch) {
+      const candidate = listMatch[1].replace(/`/g, "").trim();
+      if (!candidate || candidate.includes(":")) {
+        continue;
+      }
+      const record = normalizedScreenRecord({ title: candidate }, relativePath, candidate);
+      if (record) screens.push(record);
+    }
+  }
+  return screens;
+}
+
+function dedupeScreens(screens) {
+  const byId = new Map();
+  for (const screen of screens) {
+    if (!screen || !screen.screenId) {
+      continue;
+    }
+    if (!byId.has(screen.screenId)) {
+      byId.set(screen.screenId, screen);
+      continue;
+    }
+    const existing = byId.get(screen.screenId);
+    const existingScore = (existing.route ? 1 : 0) + (existing.purpose ? 1 : 0) + (existing.primaryAction ? 1 : 0) + existing.majorSections.length + existing.requiredStates.length;
+    const newScore = (screen.route ? 1 : 0) + (screen.purpose ? 1 : 0) + (screen.primaryAction ? 1 : 0) + screen.majorSections.length + screen.requiredStates.length;
+    if (newScore > existingScore) {
+      byId.set(screen.screenId, screen);
+    }
+  }
+  return Array.from(byId.values());
+}
+
+function buildInputContractState({
+  fromSpecPath,
+  projectPath,
+  designBriefPath,
+  referenceDir,
+  profile,
+}) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  const resolvedSpecPath = resolveProjectPath(fromSpecPath || resolvedProjectPath);
+  if (!fs.existsSync(resolvedSpecPath) || !fs.statSync(resolvedSpecPath).isDirectory()) {
+    throw new ValidationError(`--from-spec is not a valid directory: ${resolvedSpecPath}. No project files were changed.`);
+  }
+
+  const selectedProfile = resolveProfile(profile);
+
+  const artifactRules = [
+    { key: "designHandoff", relativeDir: "docs/design", pattern: /^SPEC_TO_DESIGN_HANDOFF_.*\.json$/i, blocker: "NEEDS_DESIGN_HANDOFF" },
+    { key: "screenInventory", relativeDir: "docs/design", pattern: /^SCREEN_INVENTORY_.*\.md$/i, blocker: null },
+    { key: "userFlows", relativeDir: "docs/design", pattern: /^USER_FLOWS_.*\.md$/i, blocker: "NEEDS_USER_FLOWS" },
+    { key: "domainModel", relativeDir: "docs/specs", pattern: /^DOMAIN_MODEL_.*\.md$/i, blocker: "NEEDS_DOMAIN_MODEL" },
+    { key: "archDesign", relativeDir: "docs/architecture", pattern: /^ARCH_DESIGN_.*\.md$/i, blocker: null },
+    { key: "baSpec", relativeDir: "docs/specs", pattern: /^BA_SPEC_.*\.md$/i, blocker: null },
+  ];
+
+  const artifacts = {};
+  for (const rule of artifactRules) {
+    artifacts[rule.key] = findArtifactByPattern(resolvedSpecPath, rule.relativeDir, rule.pattern);
+  }
+
+  let explicitDesignBrief = null;
+  if (designBriefPath) {
+    const absoluteDesignBrief = path.resolve(resolvedProjectPath, designBriefPath);
+    if (!fs.existsSync(absoluteDesignBrief) || !fs.statSync(absoluteDesignBrief).isFile()) {
+      throw new ValidationError(`--design-brief is not a valid file: ${absoluteDesignBrief}. No project files were changed.`);
+    }
+    explicitDesignBrief = {
+      absolutePath: absoluteDesignBrief,
+      relativeToProject: toPosixRelative(resolvedProjectPath, absoluteDesignBrief),
+    };
+  }
+
+  const reference = resolveReferenceDirectory(referenceDir, resolvedProjectPath);
+  const parsedScreens = [];
+  if (artifacts.designHandoff) {
+    parsedScreens.push(
+      ...extractScreensFromHandoffJson(artifacts.designHandoff.absolutePath, artifacts.designHandoff.relativePath)
+    );
+  }
+  if (artifacts.screenInventory) {
+    parsedScreens.push(
+      ...extractScreensFromInventoryMarkdown(artifacts.screenInventory.absolutePath, artifacts.screenInventory.relativePath)
+    );
+  }
+  const screens = dedupeScreens(parsedScreens);
+
+  const blockers = artifactRules.filter((rule) => rule.blocker && !artifacts[rule.key]).map((rule) => rule.blocker);
+  if (screens.length === 0) {
+    blockers.push("NEEDS_SCREEN_INVENTORY");
+  }
+  const analysisStatus = blockers.length === 0 ? "INPUT_CONTRACT_READY" : "INPUT_CONTRACT_BLOCKED";
+
+  const artifactSummary = {};
+  for (const rule of artifactRules) {
+    const value = artifacts[rule.key];
+    artifactSummary[rule.key] = value
+      ? {
+          found: true,
+          relativeToSpecRoot: value.relativePath,
+          absolutePath: value.absolutePath,
+        }
+      : {
+          found: false,
+          relativeToSpecRoot: null,
+          absolutePath: null,
+        };
+  }
+
+  return {
+    schema: "sdtk.design.input-contract.v1",
+    mode: "from-spec",
+    projectPath: resolvedProjectPath,
+    fromSpecPath: resolvedSpecPath,
+    profileSelection: selectedProfile ? selectedProfile.name : null,
+    profilePrimitives: selectedProfile
+      ? {
+          name: selectedProfile.name,
+          summary: selectedProfile.summary,
+          primitives: selectedProfile.primitives,
+          screenRoleHints: selectedProfile.screenRoleHints,
+        }
+      : null,
+    explicitDesignBrief,
+    referenceDirectory: {
+      provided: reference.provided,
+      status: reference.status,
+      absolutePath: reference.absolutePath,
+    },
+    referenceMap: reference.provided
+      ? mapReferenceFiles({ referenceDir: reference.absolutePath, screens })
+      : { totalFiles: 0, mappedCount: 0, unmappedCount: 0, entries: [] },
+    artifacts: artifactSummary,
+    screenModel: {
+      totalScreens: screens.length,
+      missingMetadataCount: screens.filter((screen) => !screen.route || !screen.purpose || !screen.primaryAction).length,
+      legacyFallbackUsed: false,
+      readiness: screens.length > 0 ? "MULTI_SCREEN_READY" : "NEEDS_EXPLICIT_SCREEN_INPUT",
+      screens,
+    },
+    blockers,
+    analysisStatus,
+    nextRecommendedCommand:
+      blockers.length > 0 ? "Provide missing explicit SPEC/design artifacts and re-run sdtk-design start --from-spec." : "sdtk-design prototype",
+  };
+}
+
+module.exports = {
+  buildInputContractState,
+  writeInputContractState,
+};

package/src/lib/design-paths.js

@@ -14,6 +14,7 @@ const DESIGN_SYSTEM_RELATIVE = path.join("docs", "design", "DESIGN_SYSTEM.md");
 const DESIGN_HANDOFF_RELATIVE = path.join("docs", "design", "DESIGN_HANDOFF.md");
 const DESIGN_STATE_RELATIVE = path.join(".sdtk", "design");
 const DESIGN_MANIFEST_RELATIVE = path.join(".sdtk", "design", "manifest.json");
+const DESIGN_START_INPUT_STATE_RELATIVE = path.join(".sdtk", "design", "START_INPUT_STATE.json");
 
 function resolveProjectPath(projectPath) {
   return path.resolve(projectPath || process.cwd());
@@ -55,6 +56,7 @@ function describeDesignPaths(projectPath) {
     designHandoffPath: path.join(root, DESIGN_HANDOFF_RELATIVE),
     designStatePath: path.join(root, DESIGN_STATE_RELATIVE),
     manifestPath: path.join(root, DESIGN_MANIFEST_RELATIVE),
+    designStartInputStatePath: path.join(root, DESIGN_START_INPUT_STATE_RELATIVE),
   };
 }
 
@@ -68,6 +70,7 @@ module.exports = {
   DESIGN_README_RELATIVE,
   DESIGN_REVIEWS_RELATIVE,
   DESIGN_SCREEN_MAP_RELATIVE,
+  DESIGN_START_INPUT_STATE_RELATIVE,
   DESIGN_STATE_RELATIVE,
   DESIGN_SYSTEM_RELATIVE,
   DESIGN_WIREFRAMES_RELATIVE,

package/src/lib/design-profiles.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const { ValidationError } = require("./errors");
+
+const DESIGN_PROFILES = {
+  "b2b-commerce": {
+    name: "b2b-commerce",
+    summary: "Reusable B2B commerce primitives for multi-screen product catalogs and purchasing workflows.",
+    primitives: [
+      "catalog grid",
+      "filter sidebar",
+      "product card",
+      "pdp gallery/spec/cta",
+      "search results/no-result",
+      "cart line items/summary",
+      "checkout steps",
+      "order history/detail",
+      "account shell",
+      "configurator wizard",
+      "bom/material table",
+    ],
+    screenRoleHints: {
+      home: ["catalog grid", "product card", "sticky purchase/cta"],
+      category: ["filter sidebar", "catalog grid", "product card"],
+      "product-detail": ["pdp gallery/spec/cta", "sticky purchase/cta"],
+      search: ["search results/no-result", "product card", "filter sidebar"],
+      cart: ["cart line items/summary", "sticky purchase/cta"],
+      checkout: ["checkout steps", "cart line items/summary", "sticky purchase/cta"],
+      "order-history": ["order history/detail"],
+      "order-detail": ["order history/detail"],
+      "account-info": ["account shell"],
+      "mode-b-configurator": ["configurator wizard", "bom/material table", "sticky purchase/cta"],
+    },
+  },
+};
+
+function availableProfileNames() {
+  return Object.keys(DESIGN_PROFILES);
+}
+
+function resolveProfile(profileName) {
+  if (!profileName) {
+    return null;
+  }
+  const normalized = String(profileName).trim().toLowerCase();
+  if (DESIGN_PROFILES[normalized]) {
+    return DESIGN_PROFILES[normalized];
+  }
+  throw new ValidationError(
+    `Unsupported --profile "${profileName}". Supported profiles: ${availableProfileNames().join(", ")}. No project files were changed.`
+  );
+}
+
+module.exports = {
+  DESIGN_PROFILES,
+  availableProfileNames,
+  resolveProfile,
+};