sdtk-design-kit 0.2.1 → 0.3.1

package/src/commands/review.js

@@ -87,37 +87,6 @@ function readInputContractState(paths) {
   }
 }
 
-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 [];
@@ -129,27 +98,9 @@ function listPrototypeScreenFiles(paths) {
     .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 resolveAntiSlopLintMode(env = process.env) {
-  const value = String(env.SDTK_DESIGN_ANTI_SLOP_LINT || "warn").toLowerCase();
-  return value === "on" || value === "off" || value === "warn" ? value : "warn";
+  const value = String(env.SDTK_DESIGN_ANTI_SLOP_LINT || "on").toLowerCase();
+  return value === "off" ? "off" : "on";
 }
 
 function collectPrototypeHtmlMap({ artifactPath, artifactContent, paths }) {
@@ -157,19 +108,18 @@ function collectPrototypeHtmlMap({ artifactPath, artifactContent, paths }) {
   const add = (screenId, html) => {
     if (!map.has(screenId)) map.set(screenId, html);
   };
-  add(path.basename(artifactPath, ".html") || "artifact", artifactContent);
-  if (fs.existsSync(paths.prototypeIndexPath)) {
-    add("index", fs.readFileSync(paths.prototypeIndexPath, "utf-8"));
-  }
   for (const filePath of listPrototypeScreenFiles(paths)) {
     add(path.basename(filePath, ".html"), fs.readFileSync(filePath, "utf-8"));
   }
+  if (map.size === 0 && path.resolve(path.dirname(artifactPath)) === path.resolve(paths.prototypeScreensPath)) {
+    add(path.basename(artifactPath, ".html") || "artifact", artifactContent);
+  }
   return map;
 }
 
 function applyAntiSlopVerdict({ structuralVerdict, lintFindings, lintMode }) {
   const lintSummary = summarizeLintFindings(lintFindings);
-  const lintBlocking = lintMode === "on" && lintSummary.p0 > 0;
+  const lintBlocking = lintMode !== "off" && lintSummary.p0 > 0;
   return {
     verdict: lintBlocking ? "FAIL_WITH_RENDERER_SLOP" : structuralVerdict,
     lintSummary,
@@ -177,78 +127,112 @@ function applyAntiSlopVerdict({ structuralVerdict, lintFindings, lintMode }) {
   };
 }
 
-function evaluateHighFidelityGate({ artifactContent, statePayload, projectPath, paths }) {
-  const html = String(artifactContent || "").toLowerCase();
+function extractTagContent(html, tagName) {
+  const match = String(html || "").match(new RegExp(`<${tagName}\\b[^>]*>([\\s\\S]*?)<\\/${tagName}>`, "i"));
+  return match ? match[1] : "";
+}
+
+function stripTags(value) {
+  return String(value || "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function countTag(html, tagName) {
+  return (String(html || "").match(new RegExp(`<${tagName}\\b`, "gi")) || []).length;
+}
+
+function collectDesignTokenReferences(paths) {
+  if (!fs.existsSync(paths.designTokensPath)) return [];
+  try {
+    const payload = JSON.parse(fs.readFileSync(paths.designTokensPath, "utf-8"));
+    const values = [];
+    const visit = (value) => {
+      if (value == null) return;
+      if (typeof value === "string" || typeof value === "number") {
+        const token = String(value).trim();
+        if (token) values.push(token.toLowerCase());
+        return;
+      }
+      if (Array.isArray(value)) {
+        value.forEach(visit);
+        return;
+      }
+      if (typeof value === "object") Object.values(value).forEach(visit);
+    };
+    visit(payload);
+    return values.filter((value) => value.length >= 3);
+  } catch (_err) {
+    return [];
+  }
+}
+
+function hasDesignTokenReference(html, tokenReferences) {
+  const lower = String(html || "").toLowerCase();
+  if (/var\(--[a-z0-9-]+\)/i.test(lower)) return true;
+  return tokenReferences.some((token) => lower.includes(token));
+}
+
+function screenStructuralFindings({ screenId, html, tokenReferences }) {
+  const findings = [];
+  const lower = String(html || "").toLowerCase();
+  const title = stripTags(extractTagContent(html, "title"));
+  const body = extractTagContent(html, "body");
+  if (!lower.trimStart().startsWith("<!doctype html>")) findings.push("missing doctype");
+  if (!/<html\b/i.test(html)) findings.push("missing html element");
+  if (!/<head\b/i.test(html)) findings.push("missing head element");
+  if (!/<body\b/i.test(html)) findings.push("missing body element");
+  if (!title) findings.push("missing or empty title");
+  const h1Count = countTag(html, "h1");
+  if (h1Count !== 1) findings.push(`expected exactly one h1, found ${h1Count}`);
+  if (!stripTags(body)) findings.push("empty body");
+  if (!hasDesignTokenReference(html, tokenReferences)) findings.push("missing design token reference");
+  return {
+    screenId,
+    pass: findings.length === 0,
+    findings,
+  };
+}
+
+function evaluateHighFidelityGate({ statePayload, projectPath, paths }) {
   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 tokenReferences = collectDesignTokenReferences(paths);
   const sectionRows = [];
-  let missingCount = 0;
+  const blockers = [];
   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}`);
+    const filePath = path.join(paths.prototypeScreensPath, `${id}.html`);
+    if (!fs.existsSync(filePath)) {
+      const missing = [`missing screen file: docs/design/prototype/screens/${id}.html`];
+      blockers.push(`${title}: ${missing.join("; ")}`);
+      sectionRows.push({ title, role: id, missing, pass: false });
+      continue;
     }
-    if (missing.length > 0) missingCount += 1;
-    sectionRows.push({
-      title,
-      role,
-      missing,
-      pass: missing.length === 0,
+    const structural = screenStructuralFindings({
+      screenId: id,
+      html: fs.readFileSync(filePath, "utf-8"),
+      tokenReferences,
     });
+    if (!structural.pass) blockers.push(`${title}: ${structural.findings.join("; ")}`);
+    sectionRows.push({ title, role: id, missing: structural.findings, pass: structural.pass });
   }
 
   let verdict = "PASS_HIGH_FIDELITY_READY";
-  const blockers = [];
   if (screens.length === 0) {
-    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    verdict = "FAIL_STRUCTURE";
     blockers.push("explicit screen model is empty");
   }
   if (!hasComponentLibrary) {
-    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    verdict = "FAIL_STRUCTURE";
     blockers.push("component pattern library missing");
   }
   if (!hasTokens) {
-    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    verdict = "FAIL_STRUCTURE";
     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)");
-  }
+  if (sectionRows.some((row) => !row.pass)) verdict = "FAIL_STRUCTURE";
   return {
     verdict,
     blockers,
@@ -256,10 +240,6 @@ function evaluateHighFidelityGate({ artifactContent, statePayload, projectPath,
     sectionRows,
     hasTokens,
     hasComponentLibrary,
-    hasNav,
-    hasStateChips,
-    hasPre,
-    hasRawJsonRisk,
     projectPath,
   };
 }
@@ -272,12 +252,8 @@ function fidelityReviewContent(result) {
     `- 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-By-Screen Structural Sanity",
     "",
     "| Screen | Role | Result | Actionable notes |",
     "|---|---|---|---|",
@@ -300,41 +276,61 @@ function fidelityReviewContent(result) {
     "",
     "## Actions",
     "",
-    "- Fill missing component markers per failed screen.",
+    "- Fix failed screen HTML documents so each has doctype, html/head/body, title, one h1, non-empty body, and token references.",
     "- 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`.",
+    "- Remove anti-slop P0 findings from customer-facing prototype output.",
+    "- Re-run the design-prototype skill 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");
-  const hasOnboarding = lower.includes("section-onboarding") || lower.includes("onboarding");
-  const hasDashboard = lower.includes("section-dashboard") || lower.includes("dashboard");
-  const hasPreset = lower.includes("data-style-preset") || lower.includes("style-premium-dashboard") || lower.includes("style-minimal-saas") || lower.includes("style-bold-founder") || lower.includes("style-warm-editorial");
   const hasResponsive = lower.includes("@media") || lower.includes("viewport") || lower.includes("mobile");
-  const hasCta = includesAny(artifactContent, ["btn-primary", "Primary CTA", "Create workspace", "Add lead", "Continue", "Start"]);
-  const hasDashboardDensity = hasDashboard && includesAny(artifactContent, ["metric", "kpi", "pipeline", "status", "lead", "table", "card"]);
+  const hasCta = includesAny(artifactContent, ["btn-primary", "Primary CTA", "Create workspace", "Add lead", "Continue", "Start", "button", "href="]);
   const hasAccessibility = includesAny(artifactContent, ["accessibility", "aria-", "button", "label", "44px", "focus"]);
   const hasSpacing = includesAny(artifactContent, ["gap:", "padding:", "spacing", "density", "grid", "margin"]);
   const modeEvidence = prototypeHtml
-    ? "Prototype HTML is checked as visual direction only, not production application code."
+    ? "Prototype HTML visual polish uses standalone HTML signals; structural readiness is checked separately by the fidelity gate."
     : "Markdown artifact is checked for implementation-ready visual direction.";
 
+  const rows = [];
+  if (prototypeHtml) {
+    const hasSemanticLandmarks = includesAny(artifactContent, ["<main", "<header", "<nav", "<section", "role=", "aria-label"]);
+    const h1Count = (String(artifactContent || "").match(/<h1\b/gi) || []).length;
+    const hasSupportingHeading = /<h[2-3]\b/i.test(String(artifactContent || ""));
+    const hasHeadingOutline = h1Count === 1 && hasSupportingHeading;
+    const hasTokenUsage = /var\(--[a-z0-9-]+\)/i.test(String(artifactContent || ""));
+    const hasStubRisk = includesAny(artifactContent, ["placeholder text", "sample content", "lorem ipsum", "wireframe"]);
+    rows.push(
+      `| HTML Semantics | ${hasSemanticLandmarks ? "Pass" : "Needs attention"} | ${hasSemanticLandmarks ? "Prototype includes semantic landmarks or labelled regions." : "Add semantic landmarks such as main, nav, header, section, or labelled regions."} |`,
+      `| Heading Outline | ${hasHeadingOutline ? "Pass" : "Needs attention"} | ${hasHeadingOutline ? "Prototype has one h1 and supporting h2/h3 structure." : "Use one h1 with supporting section headings."} |`,
+      `| Responsive / Mobile Risk | ${hasResponsive ? "Pass" : "Needs attention"} | ${hasResponsive ? "Responsive viewport, media, or mobile behavior is represented." : "Add viewport or mobile breakpoint behavior before implementation."} |`,
+      `| Token Usage | ${hasTokenUsage ? "Pass" : "Needs attention"} | ${hasTokenUsage ? "Prototype references CSS custom properties for visual tokens." : "Reference design tokens via CSS custom properties in generated HTML."} |`,
+      `| CTA Clarity | ${hasCta ? "Pass" : "Needs attention"} | ${hasCta ? "A concrete action link or button is visible in the artifact." : "Add one dominant action link or button with concrete copy."} |`,
+      `| Stub / Wireframe Risk | ${!hasStubRisk ? "Pass" : "Needs attention"} | ${!hasStubRisk ? "No obvious placeholder or wireframe copy is present in the reviewed HTML." : "Replace placeholder or wireframe copy with generated product content."} |`
+    );
+  } else {
+    const hasLanding = lower.includes("landing");
+    const hasOnboarding = lower.includes("onboarding");
+    const hasDashboard = lower.includes("dashboard");
+    const hasDashboardDensity = hasDashboard && includesAny(artifactContent, ["metric", "kpi", "pipeline", "status", "lead", "table", "card"]);
+    rows.push(
+      `| Hierarchy | ${hasLanding && hasOnboarding && hasDashboard ? "Pass" : "Needs attention"} | ${hasLanding && hasOnboarding && hasDashboard ? "Landing, onboarding, and dashboard sections create a clear read order." : "Ensure the artifact clearly separates landing, onboarding, and dashboard intent."} |`,
+      `| Spacing / Density | ${hasSpacing ? "Pass" : "Needs attention"} | ${hasSpacing ? "Artifact includes grid, gap, padding, margin, or spacing guidance." : "Add spacing and density rules so the implementation does not regress into a flat wireframe."} |`,
+      `| CTA Clarity | ${hasCta ? "Pass" : "Needs attention"} | ${hasCta ? "A concrete primary action is visible in the artifact." : "Add one dominant CTA with concrete action copy."} |`,
+      `| Dashboard Information Density | ${hasDashboardDensity ? "Pass" : "Needs attention"} | ${hasDashboardDensity ? "Dashboard direction includes metrics, pipeline/status, cards, lists, or table surfaces." : "Dashboard needs enough KPI, status, list, or table detail to guide a real MVP screen."} |`,
+      `| Responsive / Mobile Risk | ${hasResponsive ? "Pass" : "Needs attention"} | ${hasResponsive ? "Responsive or mobile behavior is represented." : "Add mobile breakpoint or narrow-screen behavior before implementation."} |`,
+      `| Accessibility Baseline | ${hasAccessibility ? "Pass" : "Needs attention"} | ${hasAccessibility ? "Artifact includes accessible-control or baseline accessibility signals." : "Add labels, focus, touch-target, and color-not-alone guidance."} |`
+    );
+  }
+
   return [
     "## Visual Polish Checks",
     "",
     "| Check | Result | Evidence |",
     "|---|---|---|",
-    `| Hierarchy | ${hasLanding && hasOnboarding && hasDashboard ? "Pass" : "Needs attention"} | ${hasLanding && hasOnboarding && hasDashboard ? "Landing, onboarding, and dashboard sections create a clear read order." : "Ensure the artifact clearly separates landing, onboarding, and dashboard intent."} |`,
-    `| Spacing / Density | ${hasSpacing ? "Pass" : "Needs attention"} | ${hasSpacing ? "Artifact includes grid, gap, padding, margin, or spacing guidance." : "Add spacing and density rules so the implementation does not regress into a flat wireframe."} |`,
-    `| CTA Clarity | ${hasCta ? "Pass" : "Needs attention"} | ${hasCta ? "A concrete primary action is visible in the artifact." : "Add one dominant CTA with concrete action copy."} |`,
-    `| Dashboard Information Density | ${hasDashboardDensity ? "Pass" : "Needs attention"} | ${hasDashboardDensity ? "Dashboard direction includes metrics, pipeline/status, cards, lists, or table surfaces." : "Dashboard needs enough KPI, status, list, or table detail to guide a real MVP screen."} |`,
-    `| Responsive / Mobile Risk | ${hasResponsive ? "Pass" : "Needs attention"} | ${hasResponsive ? "Responsive or mobile behavior is represented." : "Add mobile breakpoint or narrow-screen behavior before implementation."} |`,
-    `| Accessibility Baseline | ${hasAccessibility ? "Pass" : "Needs attention"} | ${hasAccessibility ? "Artifact includes accessible-control or baseline accessibility signals." : "Add labels, focus, touch-target, and color-not-alone guidance."} |`,
-    `| Anti-Wireframe / Mockup Warning | ${prototypeHtml && hasPreset ? "Pass" : "Needs attention"} | ${prototypeHtml && hasPreset ? "Prototype includes style preset tokens/classes and should guide visual polish beyond basic wireframes." : "Do not treat the artifact as complete UI; add concrete style preset tokens/classes or visual contract details."} |`,
+    ...rows,
     "",
     `- Reviewed visual artifact: \`${artifactRelativePath}\`.`,
     `- ${modeEvidence}`,
@@ -440,13 +436,7 @@ function runDesignReview({ artifact, projectPath, force = false }) {
   let fidelityVerdict = null;
   let antiSlopLint = null;
   if (shouldRunFidelityGate) {
-    const fidelityArtifactContent = combinedPrototypeReviewContent({
-      artifactPath,
-      artifactContent,
-      paths,
-    });
     const fidelityResult = evaluateHighFidelityGate({
-      artifactContent: fidelityArtifactContent,
       statePayload,
       projectPath: resolvedProjectPath,
       paths,
@@ -500,7 +490,7 @@ function cmdReview(args) {
     console.log(`[design] Fidelity verdict: ${result.fidelityVerdict}`);
     if (result.antiSlopLint) {
       if (result.antiSlopLint.mode === "off") {
-        console.log("[design] Anti-slop lint: OFF (deprecated emergency rollback)");
+        console.log("[design] Anti-slop lint: OFF (emergency rollback)");
       } else if (result.antiSlopLint.summary.p0 > 0) {
         console.log(`[design] Anti-slop lint: ${result.antiSlopLint.summary.p0} P0 findings; see review report`);
       } else {

package/src/commands/start.js

@@ -11,7 +11,7 @@ const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths
 const { availableProfileNames } = require("../lib/design-profiles");
 const { buildInputContractState, writeInputContractState } = require("../lib/design-input-contract");
 const { writeScreenBriefArtifacts } = require("../lib/screen-briefs");
-const { writeComponentContractArtifacts } = require("../lib/component-contract");
+const { writeComponentContractArtifacts, loadBrandTokensV2, loadProjectFactsV1 } = require("../lib/component-contract");
 const { ValidationError } = require("../lib/errors");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
@@ -25,6 +25,8 @@ const START_FLAG_DEFS = {
   "design-brief": { type: "string" },
   "reference-dir": { type: "string" },
   profile: { type: "string" },
+  "brand-tokens": { type: "string" },
+  "project-facts": { type: "string" },
 };
 
 const REQUIRED_WIREFRAME_FILES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
@@ -34,12 +36,14 @@ 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>]
+  sdtk-design start --from-spec <projectPath> [--design-brief <file>] [--reference-dir <dir>] [--profile <name>] [--brand-tokens <file>] [--project-facts <file>] [--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/design/reference-export --profile b2b-commerce
+  sdtk-design start --from-spec . --profile b2b-commerce --brand-tokens ./brand-tokens.json
+  sdtk-design start --from-spec . --profile b2b-industrial-commerce --project-facts ./facts.json
 
   Style presets:
   ${availableStyleNames().join(", ")}
@@ -134,7 +138,12 @@ function runDesignStartFromSpec({
   designBrief,
   referenceDir,
   profile,
+  brandTokensPath,
+  projectFactsPath,
 }) {
+  // BK-223 + BK-229: validate explicit inputs BEFORE any artifact write (fail-closed).
+  if (brandTokensPath) loadBrandTokensV2(brandTokensPath);
+  if (projectFactsPath) loadProjectFactsV1(projectFactsPath);
   const contractState = buildInputContractState({
     fromSpecPath,
     projectPath,
@@ -147,7 +156,10 @@ function runDesignStartFromSpec({
   let componentContract = null;
   if (contractState.analysisStatus === "INPUT_CONTRACT_READY") {
     screenBriefs = writeScreenBriefArtifacts(contractState.projectPath, contractState);
-    componentContract = writeComponentContractArtifacts(contractState.projectPath, contractState);
+    componentContract = writeComponentContractArtifacts(contractState.projectPath, contractState, {
+      brandTokensPath: brandTokensPath || null,
+      projectFactsPath: projectFactsPath || null,
+    });
   }
   return {
     ...contractState,
@@ -162,7 +174,10 @@ 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);
+  const contractMode = Boolean(
+    flags["from-spec"] || flags["design-brief"] || flags["reference-dir"] ||
+    flags.profile || flags["brand-tokens"] || flags["project-facts"]
+  );
   if (contractMode) {
     const contractResult = runDesignStartFromSpec({
       fromSpecPath: flags["from-spec"],
@@ -170,6 +185,8 @@ function cmdStart(args) {
       designBrief: flags["design-brief"],
       referenceDir: flags["reference-dir"],
       profile: flags.profile,
+      brandTokensPath: flags["brand-tokens"] || null,
+      projectFactsPath: flags["project-facts"] || null,
     });
     if (contractResult.blockers.length > 0) {
       throw new ValidationError(
@@ -216,7 +233,7 @@ function cmdStart(args) {
   console.log(`[design] Style: ${result.style}`);
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
   console.log("[design] No review, handoff, URL, browser, screenshot, vision, network, .sdtk/atlas, or SDTK-WIKI output was used.");
-  console.log("[design] Next: sdtk-design prototype");
+  console.log("[design] Next: sdtk-design handoff");
   return 0;
 }
 

package/src/commands/status.js

@@ -85,13 +85,21 @@ function inspectDesignStatus(projectPath) {
   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 {
+    } else if (prototypeMissing) {
       nextCommand = "sdtk-design prototype";
+    } else if (!reviewExists) {
+      nextCommand = "sdtk-design review --artifact docs/design/prototype/index.html";
+    } else if (handoffMissing) {
+      nextCommand = "sdtk-design handoff";
+    } else {
+      nextCommand = "SDTK-CODE can consume docs/design/DESIGN_HANDOFF.md";
     }
   } else if (coreMissing.length > 0) {
     nextCommand = 'sdtk-design start --idea "<idea>"';
+  } else if (prototypeMissing && handoffMissing) {
+    nextCommand = "sdtk-design handoff";
   } else if (prototypeMissing) {
-    nextCommand = "sdtk-design prototype";
+    nextCommand = "Run sdtk-design start --from-spec with explicit design inputs before sdtk-design prototype.";
   } else if (!reviewExists) {
     nextCommand = "sdtk-design review --artifact docs/design/prototype/index.html";
   } else if (handoffMissing) {