sdtk-design-kit 0.1.1 → 0.2.0

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.");

package/src/commands/start.js

@@ -8,6 +8,10 @@ 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 { writeScreenBriefArtifacts } = require("../lib/screen-briefs");
+const { writeComponentContractArtifacts } = require("../lib/component-contract");
 const { ValidationError } = require("../lib/errors");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
@@ -17,6 +21,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 +34,45 @@ 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/design/reference-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
+    docs/design/screens/*_DESIGN_BRIEF.md (when INPUT_CONTRACT_READY)
+    .sdtk/design/screen-briefs/*.json (managed sidecars for deterministic renderer intake)
+    docs/design/COMPONENT_PATTERN_LIBRARY.md (when INPUT_CONTRACT_READY)
+    docs/design/DESIGN_TOKENS.json (when INPUT_CONTRACT_READY)
 
 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 +128,82 @@ 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);
+  let screenBriefs = null;
+  let componentContract = null;
+  if (contractState.analysisStatus === "INPUT_CONTRACT_READY") {
+    screenBriefs = writeScreenBriefArtifacts(contractState.projectPath, contractState);
+    componentContract = writeComponentContractArtifacts(contractState.projectPath, contractState);
+  }
+  return {
+    ...contractState,
+    statePath,
+    stateRelativePath: ".sdtk/design/START_INPUT_STATE.json",
+    screenBriefs,
+    componentContract,
+  };
+}
+
 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}`);
+    if (contractResult.screenBriefs) {
+      console.log(`[design] Wrote per-screen briefs: ${contractResult.screenBriefs.generatedCount} artifact(s)`);
+    }
+    if (contractResult.componentContract) {
+      console.log(
+        `[design] Wrote component/token contract: ${contractResult.componentContract.componentLibraryRelativePath}, ${contractResult.componentContract.designTokensRelativePath}`
+      );
+    }
+    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 +224,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/component-contract.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const fs = require("fs");
+const { describeDesignPaths } = require("./design-paths");
+const { ValidationError } = require("./errors");
+
+const ECOMMERCE_PATTERNS = [
+  "Header and navigation shell",
+  "Category filter sidebar",
+  "Product card grid",
+  "Product detail spec table and gallery area",
+  "Search result list and no-result state",
+  "Cart table and quantity controls",
+  "Checkout stepper and summary card",
+  "Order history list or table",
+  "Order status timeline and detail summary",
+  "Account sidebar and view or edit form",
+  "Configurator wizard shell",
+  "Preview panel",
+  "BOM and material table",
+  "Exclude and recalculate action",
+];
+
+const BASELINE_PATTERNS = [
+  "Header and navigation shell",
+  "Primary content section",
+  "Secondary support panel",
+  "Summary card",
+  "State badge and status chip",
+  "Primary and secondary action row",
+];
+
+function contractTokens(profile, statePayload) {
+  const mappedRefs =
+    statePayload &&
+    statePayload.referenceMap &&
+    typeof statePayload.referenceMap.mappedCount === "number"
+      ? statePayload.referenceMap.mappedCount
+      : 0;
+  return {
+    schema: "sdtk.design.tokens.v1",
+    profile: profile || "generic",
+    color: {
+      surface: "#FFFFFF",
+      surfaceAlt: "#F7F8FA",
+      textPrimary: "#111827",
+      textMuted: "#64748B",
+      border: "#D8E0EA",
+      accentPrimary: profile === "b2b-commerce" ? "#0F766E" : "#2563EB",
+      accentSecondary: profile === "b2b-commerce" ? "#2563EB" : "#0F8A5F",
+    },
+    typography: {
+      fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
+      headingWeight: 800,
+      bodyWeight: 400,
+      uiWeight: 700,
+      letterSpacing: 0,
+    },
+    spacing: {
+      xs: 4,
+      sm: 8,
+      md: 12,
+      lg: 16,
+      xl: 24,
+      sectionGap: 32,
+    },
+    radius: {
+      card: 8,
+      control: 8,
+      chip: 999,
+    },
+    metadata: {
+      generatedFrom: "START_INPUT_STATE",
+      explicitScreenCount: statePayload.screenModel.totalScreens,
+      mappedReferenceCount: mappedRefs,
+    },
+  };
+}
+
+function markdownLibrary(profile, statePayload) {
+  const mappedRefs =
+    statePayload &&
+    statePayload.referenceMap &&
+    typeof statePayload.referenceMap.mappedCount === "number"
+      ? statePayload.referenceMap.mappedCount
+      : 0;
+  const patterns = profile === "b2b-commerce" ? ECOMMERCE_PATTERNS : BASELINE_PATTERNS;
+  return `# Component Pattern Library
+
+## Contract Meta
+- Profile: ${profile || "generic"}
+- Source: .sdtk/design/START_INPUT_STATE.json
+- Explicit screens: ${statePayload.screenModel.totalScreens}
+- Mapped references: ${mappedRefs}
+
+## Core Pattern Set
+${patterns.map((item) => `- ${item}`).join("\n")}
+
+## Usage Rules
+- Keep component usage screen-role driven from explicit screen model.
+- Reuse token contract from docs/design/DESIGN_TOKENS.json.
+- Keep customer specifics project-local; runtime library stays profile-generic.
+
+## Accessibility Baseline
+- Interactive controls should preserve clear focus styling.
+- Keep readable contrast and deterministic heading hierarchy.
+- Keep touch targets at least 44px where practical in prototype guidance.
+`;
+}
+
+function writeComponentContractArtifacts(projectPath, inputContractState) {
+  const paths = describeDesignPaths(projectPath);
+  if (
+    !inputContractState ||
+    inputContractState.analysisStatus !== "INPUT_CONTRACT_READY" ||
+    !inputContractState.screenModel ||
+    !Array.isArray(inputContractState.screenModel.screens) ||
+    inputContractState.screenModel.screens.length === 0
+  ) {
+    throw new ValidationError(
+      "Component and token contract generation requires INPUT_CONTRACT_READY with explicit screens."
+    );
+  }
+  const profile = inputContractState.profileSelection || null;
+  const tokensPayload = contractTokens(profile, inputContractState);
+  const libraryMarkdown = markdownLibrary(profile, inputContractState);
+
+  fs.writeFileSync(paths.componentPatternLibraryPath, `${libraryMarkdown}\n`, "utf-8");
+  fs.writeFileSync(paths.designTokensPath, `${JSON.stringify(tokensPayload, null, 2)}\n`, "utf-8");
+
+  return {
+    componentLibraryRelativePath: "docs/design/COMPONENT_PATTERN_LIBRARY.md",
+    designTokensRelativePath: "docs/design/DESIGN_TOKENS.json",
+    profile: profile || "generic",
+    patternCount: profile === "b2b-commerce" ? ECOMMERCE_PATTERNS.length : BASELINE_PATTERNS.length,
+  };
+}
+
+module.exports = {
+  writeComponentContractArtifacts,
+};
+