sdtk-design-kit 0.1.2 → 0.2.1

package/package.json

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

package/src/commands/handoff.js

@@ -1,248 +1,402 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
 const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
-const { inferDomainProfile } = require("../lib/domain-profile");
-const { ValidationError } = require("../lib/errors");
-
-const HANDOFF_FLAG_DEFS = {
-  help: { type: "boolean" },
-  "project-path": { type: "string" },
-  force: { type: "boolean" },
-};
-
-const REQUIRED_WIREFRAMES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
-
-function cmdHandoffHelp() {
-  console.log(`SDTK-DESIGN Handoff
-
-Usage:
-  sdtk-design handoff [--project-path <path>] [--force]
+const { inferDomainProfile } = require("../lib/domain-profile");
+const { ValidationError } = require("../lib/errors");
+
+const HANDOFF_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+};
+
+const REQUIRED_WIREFRAMES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
+
+function cmdHandoffHelp() {
+  console.log(`SDTK-DESIGN Handoff
+
+Usage:
+  sdtk-design handoff [--project-path <path>] [--force]
+
+Example:
+  sdtk-design handoff
+
+Reads:
+  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
+
+Creates:
+  docs/design/DESIGN_HANDOFF.md
+
+Safety:
+  Local files only.
+  Existing DESIGN_HANDOFF.md is not overwritten unless --force is explicit.
+  No .sdtk/atlas creation or mutation.
+  No SDTK-WIKI output mutation.
+  No network call, Pro entitlement, or production app code generation.`);
+  return 0;
+}
+
+function requiredArtifacts(paths) {
+  return [
+    { label: "Design brief", relativePath: "docs/design/DESIGN_BRIEF.md", filePath: paths.designBriefPath },
+    { label: "Screen map", relativePath: "docs/design/SCREEN_MAP.md", filePath: paths.screenMapPath },
+    { label: "Design system", relativePath: "docs/design/DESIGN_SYSTEM.md", filePath: paths.designSystemPath },
+    ...REQUIRED_WIREFRAMES.map((fileName) => ({
+      label: `${fileName.replace(".md", "")} wireframe`,
+      relativePath: `docs/design/wireframes/${fileName}`,
+      filePath: path.join(paths.wireframesPath, fileName),
+    })),
+  ];
+}
 
-Example:
-  sdtk-design handoff
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (_err) {
+    return null;
+  }
+}
 
-Reads:
-  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
+function readInputContractState(paths) {
+  if (!fs.existsSync(paths.designStartInputStatePath) || !fs.statSync(paths.designStartInputStatePath).isFile()) {
+    return null;
+  }
+  return readJsonSafe(paths.designStartInputStatePath);
+}
 
-Creates:
-  docs/design/DESIGN_HANDOFF.md
+function listScreenBriefArtifacts(paths) {
+  if (!fs.existsSync(paths.screensPath) || !fs.statSync(paths.screensPath).isDirectory()) {
+    return [];
+  }
+  return fs
+    .readdirSync(paths.screensPath)
+    .filter((name) => name.endsWith("_DESIGN_BRIEF.md"))
+    .sort()
+    .map((name) => `docs/design/screens/${name}`);
+}
 
-Safety:
-  Local files only.
-  Existing DESIGN_HANDOFF.md is not overwritten unless --force is explicit.
-  No .sdtk/atlas creation or mutation.
-  No SDTK-WIKI output mutation.
-  No network call, Pro entitlement, or production app code generation.`);
-  return 0;
+function listPrototypeArtifacts(paths) {
+  const refs = [];
+  if (fs.existsSync(paths.prototypeIndexPath)) {
+    refs.push("docs/design/prototype/index.html");
+  }
+  if (fs.existsSync(paths.prototypeScreensPath) && fs.statSync(paths.prototypeScreensPath).isDirectory()) {
+    refs.push(
+      ...fs
+        .readdirSync(paths.prototypeScreensPath)
+        .filter((name) => name.toLowerCase().endsWith(".html"))
+        .sort()
+        .map((name) => `docs/design/prototype/screens/${name}`)
+    );
+  }
+  return refs;
 }
 
-function requiredArtifacts(paths) {
-  return [
-    { label: "Design brief", relativePath: "docs/design/DESIGN_BRIEF.md", filePath: paths.designBriefPath },
-    { label: "Screen map", relativePath: "docs/design/SCREEN_MAP.md", filePath: paths.screenMapPath },
-    { label: "Design system", relativePath: "docs/design/DESIGN_SYSTEM.md", filePath: paths.designSystemPath },
-    ...REQUIRED_WIREFRAMES.map((fileName) => ({
-      label: `${fileName.replace(".md", "")} wireframe`,
-      relativePath: `docs/design/wireframes/${fileName}`,
-      filePath: path.join(paths.wireframesPath, fileName),
-    })),
-  ];
+function requiredComponentsForRole(role) {
+  const map = {
+    home: ["hero section", "category or featured component", "primary CTA"],
+    category: ["filter sidebar", "product card grid"],
+    "product-detail": ["spec table or gallery area", "quantity or add-to-cart control"],
+    search: ["search toolbar", "result list and no-result state"],
+    cart: ["cart line table", "summary or checkout CTA"],
+    checkout: ["checkout stepper", "form plus summary"],
+    "order-history": ["order list or table"],
+    "order-detail": ["status timeline", "detail summary card"],
+    "account-info": ["account sidebar", "view or edit form"],
+    "mode-b-configurator": ["wizard shell", "preview panel", "BOM table", "exclude/recalculate", "add-to-cart CTA"],
+  };
+  return map[role] || ["screen-specific component set from design brief"];
 }
 
-function handoffContent({ hasPrototype = false, profile = inferDomainProfile() } = {}) {
+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 handoffContent({ hasPrototype = false, prototypeRefs = [], profile = inferDomainProfile() } = {}) {
   const prototypeReference = hasPrototype
     ? "`docs/design/prototype/index.html` is available as the static visual preview reference."
     : "Run `sdtk-design prototype` to create `docs/design/prototype/index.html` before implementation if visual preview evidence is needed.";
-  const setupKey = profile.storageKeys[0];
-  const itemKey = profile.storageKeys[1];
+  const setupKey = profile.storageKeys[0];
+  const itemKey = profile.storageKeys[1];
+
+  return [
+    "# Design Handoff",
+    "",
+    "## Readiness Verdict",
+    "",
+    "- Verdict: READY_FOR_SDTK_CODE",
+    "- Rationale: Required Phase A design artifacts exist and provide enough screen, component, state, and design-system context for implementation planning.",
+    "",
+    "## Source Artifacts",
+    "",
+    "- `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`",
+    hasPrototype ? "- `docs/design/prototype/index.html`" : "- `docs/design/prototype/index.html` (optional, not present at handoff time)",
+    "",
+    "## Screen-To-Component Mapping",
+    "",
+    "| Screen | Design artifact | Component direction |",
+    "|---|---|---|",
+    "| Landing | `docs/design/wireframes/LANDING.md` | Header, hero copy, primary CTA, workflow preview, benefit bullets |",
+    "| Onboarding | `docs/design/wireframes/ONBOARDING.md` | Progress indicator, setup form, segmented sample-data control, inline validation, continue CTA |",
+    `| Dashboard | \`docs/design/wireframes/DASHBOARD.md\` | Summary counters, ${profile.collectionSurface}, status treatment, quick-add action, empty-state panel, recoverable error alert |`,
+    "",
+    "## Screen-To-User-Story Mapping",
+    "",
+    "| Screen | User story | Acceptance signal |",
+    "|---|---|---|",
+    `| Landing | As ${profile.targetUser}, I want to understand the ${profile.productName} promise so I can decide whether to start. | Primary CTA is visible and routes to onboarding. |`,
+    `| Onboarding | As a new user, I want a short setup path so I can create my first ${profile.itemSingular} without heavy configuration. | Required fields are clear, validation is inline, and entered values are preserved on error. |`,
+    `| Dashboard | As ${profile.targetUser}, I want to see active ${profile.itemPlural} and next actions so I can choose what to do next. | ${profile.itemPlural.charAt(0).toUpperCase() + profile.itemPlural.slice(1)}, next actions, context, and status are scannable with empty and error states. |`,
+    "",
+    "## Design Decisions",
+    "",
+    "- Keep the MVP to three core screens: Landing, Onboarding, and Dashboard.",
+    "- Optimize for repeated action and scan speed over decorative presentation.",
+    "- Use a restrained operational design system with stable controls, clear form states, and accessible status language.",
+    "- Preserve `docs/design` as the human-facing design output boundary.",
+    "",
+    "## Implementation Notes For SDTK-CODE",
+    "",
+    "- Treat the markdown artifacts as planning input, not generated production code.",
+    "- Implement screens in this order: Landing, Onboarding, Dashboard.",
+    "- Keep user data capture minimal until the first useful workflow is complete.",
+    "- Preserve empty, success, and error states from the screen map and wireframes.",
+    "- Apply typography, color, spacing, button, card, form, tone, and accessibility rules from `DESIGN_SYSTEM.md`.",
+    "",
+    "## Suggested Data Model",
+    "",
+    "Workspace fields:",
+    "",
+    "- `id`: local identifier.",
+    `- \`name\`: ${profile.setupLabel.toLowerCase()} name.`,
+    "- `createdAt`: ISO timestamp.",
+    "",
+    `${profile.modelName} fields:`,
+    "",
+    "- `id`: local identifier.",
+    `- \`name\`: ${profile.itemSingular} name or label.`,
+    "- `status`: workflow status.",
+    "- `nextAction`: next action or due context.",
+    "- `note`: latest context note or summary.",
+    "- `createdAt`: ISO timestamp.",
+    "- `updatedAt`: ISO timestamp.",
+    "",
+    "## Domain Vocabulary / Status Taxonomy",
+    "",
+    `- ${profile.itemLabel}: the primary record the MVP helps the user create and track.`,
+    "- Next action: the next planned step needed to keep the workflow moving.",
+    "- Note: short context needed before the next action.",
+    `- ${profile.collectionSurface.charAt(0).toUpperCase() + profile.collectionSurface.slice(1)}: the grouped view for active ${profile.itemPlural}.`,
+    `- Status taxonomy: ${profile.statusTaxonomy.join(", ")}.`,
+    "",
+    "## Interaction Flow",
+    "",
+    "1. Landing -> user chooses the primary CTA.",
+    `2. Onboarding -> user enters ${profile.setupLabel.toLowerCase()} name and continues.`,
+    `3. Dashboard -> user sees empty state, ${profile.itemSingular} form, and status counters.`,
+    `4. ${profile.itemAction} -> validate required fields, append ${profile.itemSingular}, update list/counts, and show the saved note/next action.`,
+    `5. Refresh -> restore ${profile.setupLabel.toLowerCase()} and ${profile.itemPlural} from local persistence before rendering dashboard state.`,
+    "",
+    "## Persistence Guidance",
+    "",
+    "- For a frontend-only MVP, use browser `localStorage` or equivalent local persistence.",
+    `- Suggested keys: \`${setupKey}\` and \`${itemKey}\`.`,
+    "- Store arrays/objects as JSON and tolerate parse failures by falling back to empty state.",
+    "- Do not introduce backend, API, auth, database, or network persistence unless a later SDTK-CODE task explicitly adds it.",
+    "",
+    "## Visual Implementation Contract",
+    "",
+    "- Implement the selected visual preset from `DESIGN_SYSTEM.md` before adding extra decoration.",
+    `- Preserve landing hero hierarchy, onboarding form clarity, dashboard metric density, ${profile.collectionSurface}, status treatment, and empty state.`,
+    "- Keep responsive behavior explicit: grids collapse at mobile width and controls remain at least 44px tall.",
+    "- Pair every status color with text; do not rely on color alone.",
+    "- Avoid shipping a gray wireframe look when the prototype/design system provides finished tokens.",
+    "",
+    "## Prototype Reference",
+    "",
+    `- ${prototypeReference}`,
+    ...(prototypeRefs.length > 0 ? prototypeRefs.map((ref) => `- \`${ref}\``) : []),
+    "- Treat the prototype as visual direction only, not production application code.",
+    "",
+    "## SDTK-CODE Build Notes",
+    "",
+    "- A static frontend implementation may use `app/index.html`, `app/styles.css`, and `app/app.js` when no framework is required.",
+    "- Keep runtime dependencies optional; this handoff does not require a framework, server, or package install.",
+    `- Add verification for local rendering, ${profile.itemAction.toLowerCase()} behavior, persistence after refresh, and mobile-width layout.`,
+    "- SDTK-CODE owns implementation planning, code changes, tests, and ship readiness.",
+    "",
+    "## Acceptance Criteria",
+    "",
+    "- Landing renders the product promise, workflow preview, and a single dominant primary CTA.",
+    "- Onboarding captures only required setup data and keeps validation inline.",
+    `- Dashboard shows active ${profile.itemPlural}, next action, status, empty state, and recoverable error state.`,
+    "- Components follow the design system tokens and accessibility baseline.",
+    "- No production app code, network integration, Pro entitlement, `.sdtk/atlas`, or SDTK-WIKI mutation is implied by this handoff.",
+    "",
+    "## Non-Goals",
+    "",
+    "- Figma, Lovable, v0, or full app-builder replacement behavior.",
+    `- ${profile.nonGoals}`,
+    "- Package publish or deployment.",
+    "",
+  ].join("\n");
+}
+
+function highFidelityHandoffAppendix({ paths, statePayload, hasPrototype }) {
+  const briefRefs = listScreenBriefArtifacts(paths);
+  const prototypeRefs = listPrototypeArtifacts(paths);
+  const hasComponentLibrary = fs.existsSync(paths.componentPatternLibraryPath);
+  const hasDesignTokens = fs.existsSync(paths.designTokensPath);
+  const prototypeRef = hasPrototype
+    ? "docs/design/prototype/index.html"
+    : "docs/design/prototype/index.html (generate with sdtk-design prototype)";
+  const screens = statePayload && statePayload.screenModel && Array.isArray(statePayload.screenModel.screens) ? statePayload.screenModel.screens : [];
+  const rows = screens.map((screen) => {
+    const role = normalizeScreenRole(screen);
+    const reqs = requiredComponentsForRole(role).join("; ");
+    const brief = briefRefs.find((ref) => ref.toLowerCase().includes(`${String(screen.screenId || "").toLowerCase()}_design_brief.md`)) || "missing brief ref";
+    return `| ${screen.title} | ${screen.route || "(unspecified route)"} | ${brief} | ${reqs} |`;
+  });
 
   return [
-    "# Design Handoff",
-    "",
-    "## Readiness Verdict",
-    "",
-    "- Verdict: READY_FOR_SDTK_CODE",
-    "- Rationale: Required Phase A design artifacts exist and provide enough screen, component, state, and design-system context for implementation planning.",
-    "",
-    "## Source Artifacts",
-    "",
-    "- `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`",
-    hasPrototype ? "- `docs/design/prototype/index.html`" : "- `docs/design/prototype/index.html` (optional, not present at handoff time)",
-    "",
-    "## Screen-To-Component Mapping",
+    "## High-Fidelity UI Contract",
     "",
-    "| Screen | Design artifact | Component direction |",
-    "|---|---|---|",
-    "| Landing | `docs/design/wireframes/LANDING.md` | Header, hero copy, primary CTA, workflow preview, benefit bullets |",
-    "| Onboarding | `docs/design/wireframes/ONBOARDING.md` | Progress indicator, setup form, segmented sample-data control, inline validation, continue CTA |",
-    `| Dashboard | \`docs/design/wireframes/DASHBOARD.md\` | Summary counters, ${profile.collectionSurface}, status treatment, quick-add action, empty-state panel, recoverable error alert |`,
+    `- Input contract state: ${statePayload && statePayload.analysisStatus ? statePayload.analysisStatus : "not available"}`,
+    `- Component pattern library: ${hasComponentLibrary ? "`docs/design/COMPONENT_PATTERN_LIBRARY.md`" : "missing"}`,
+    `- Design tokens: ${hasDesignTokens ? "`docs/design/DESIGN_TOKENS.json`" : "missing"}`,
+    `- Prototype reference: \`${prototypeRef}\``,
+    `- Screen brief count: ${briefRefs.length}`,
     "",
-    "## Screen-To-User-Story Mapping",
+    "### Prototype Pages",
     "",
-    "| Screen | User story | Acceptance signal |",
-    "|---|---|---|",
-    `| Landing | As ${profile.targetUser}, I want to understand the ${profile.productName} promise so I can decide whether to start. | Primary CTA is visible and routes to onboarding. |`,
-    `| Onboarding | As a new user, I want a short setup path so I can create my first ${profile.itemSingular} without heavy configuration. | Required fields are clear, validation is inline, and entered values are preserved on error. |`,
-    `| Dashboard | As ${profile.targetUser}, I want to see active ${profile.itemPlural} and next actions so I can choose what to do next. | ${profile.itemPlural.charAt(0).toUpperCase() + profile.itemPlural.slice(1)}, next actions, context, and status are scannable with empty and error states. |`,
+    ...(prototypeRefs.length > 0 ? prototypeRefs.map((ref) => `- \`${ref}\``) : ["- none"]),
     "",
-    "## Design Decisions",
+    "### Screen Brief Links",
     "",
-    "- Keep the MVP to three core screens: Landing, Onboarding, and Dashboard.",
-    "- Optimize for repeated action and scan speed over decorative presentation.",
-    "- Use a restrained operational design system with stable controls, clear form states, and accessible status language.",
-    "- Preserve `docs/design` as the human-facing design output boundary.",
+    ...(briefRefs.length > 0 ? briefRefs.map((ref) => `- \`${ref}\``) : ["- none"]),
     "",
-    "## Implementation Notes For SDTK-CODE",
+    "### Required UI Components Per Screen",
     "",
-    "- Treat the markdown artifacts as planning input, not generated production code.",
-    "- Implement screens in this order: Landing, Onboarding, Dashboard.",
-    "- Keep user data capture minimal until the first useful workflow is complete.",
-    "- Preserve empty, success, and error states from the screen map and wireframes.",
-    "- Apply typography, color, spacing, button, card, form, tone, and accessibility rules from `DESIGN_SYSTEM.md`.",
+    "| Screen | Route | Brief | Required components |",
+    "|---|---|---|---|",
+    ...(rows.length > 0 ? rows : ["| none | none | none | none |"]),
     "",
-    "## Suggested Data Model",
+    "### No-Debug-UI Acceptance Rules",
     "",
-    "Workspace fields:",
+    "- Customer-facing UI must not expose raw JSON dumps, `<pre>` debug panels, stack traces, or schema payloads.",
+    "- Prototype and implementation should keep structured components as the default surface for state and errors.",
+    "- Debug data can exist only behind developer-only diagnostics not visible in customer-facing routes.",
     "",
-    "- `id`: local identifier.",
-    `- \`name\`: ${profile.setupLabel.toLowerCase()} name.`,
-    "- `createdAt`: ISO timestamp.",
+    "### Route-Level Visual Acceptance Checks",
     "",
-    `${profile.modelName} fields:`,
+    "- Every screen route must map to a corresponding screen brief and required component set.",
+    "- Navigation links between covered screens must remain visible and deterministic.",
+    "- Required states (empty, success, error, and screen-specific states) must be rendered without raw debug fallback.",
     "",
-    "- `id`: local identifier.",
-    `- \`name\`: ${profile.itemSingular} name or label.`,
-    "- `status`: workflow status.",
-    "- `nextAction`: next action or due context.",
-    "- `note`: latest context note or summary.",
-    "- `createdAt`: ISO timestamp.",
-    "- `updatedAt`: ISO timestamp.",
+    "### SDTK-CODE Preservation Notes",
     "",
-    "## Domain Vocabulary / Status Taxonomy",
-    "",
-    `- ${profile.itemLabel}: the primary record the MVP helps the user create and track.`,
-    "- Next action: the next planned step needed to keep the workflow moving.",
-    "- Note: short context needed before the next action.",
-    `- ${profile.collectionSurface.charAt(0).toUpperCase() + profile.collectionSurface.slice(1)}: the grouped view for active ${profile.itemPlural}.`,
-    `- Status taxonomy: ${profile.statusTaxonomy.join(", ")}.`,
-    "",
-    "## Interaction Flow",
-    "",
-    "1. Landing -> user chooses the primary CTA.",
-    `2. Onboarding -> user enters ${profile.setupLabel.toLowerCase()} name and continues.`,
-    `3. Dashboard -> user sees empty state, ${profile.itemSingular} form, and status counters.`,
-    `4. ${profile.itemAction} -> validate required fields, append ${profile.itemSingular}, update list/counts, and show the saved note/next action.`,
-    `5. Refresh -> restore ${profile.setupLabel.toLowerCase()} and ${profile.itemPlural} from local persistence before rendering dashboard state.`,
-    "",
-    "## Persistence Guidance",
-    "",
-    "- For a frontend-only MVP, use browser `localStorage` or equivalent local persistence.",
-    `- Suggested keys: \`${setupKey}\` and \`${itemKey}\`.`,
-    "- Store arrays/objects as JSON and tolerate parse failures by falling back to empty state.",
-    "- Do not introduce backend, API, auth, database, or network persistence unless a later SDTK-CODE task explicitly adds it.",
-    "",
-    "## Visual Implementation Contract",
-    "",
-    "- Implement the selected visual preset from `DESIGN_SYSTEM.md` before adding extra decoration.",
-    `- Preserve landing hero hierarchy, onboarding form clarity, dashboard metric density, ${profile.collectionSurface}, status treatment, and empty state.`,
-    "- Keep responsive behavior explicit: grids collapse at mobile width and controls remain at least 44px tall.",
-    "- Pair every status color with text; do not rely on color alone.",
-    "- Avoid shipping a gray wireframe look when the prototype/design system provides finished tokens.",
-    "",
-    "## Prototype Reference",
-    "",
-    `- ${prototypeReference}`,
-    "- Treat the prototype as visual direction only, not production application code.",
-    "",
-    "## SDTK-CODE Build Notes",
-    "",
-    "- A static frontend implementation may use `app/index.html`, `app/styles.css`, and `app/app.js` when no framework is required.",
-    "- Keep runtime dependencies optional; this handoff does not require a framework, server, or package install.",
-    `- Add verification for local rendering, ${profile.itemAction.toLowerCase()} behavior, persistence after refresh, and mobile-width layout.`,
-    "- SDTK-CODE owns implementation planning, code changes, tests, and ship readiness.",
-    "",
-    "## Acceptance Criteria",
-    "",
-    "- Landing renders the product promise, workflow preview, and a single dominant primary CTA.",
-    "- Onboarding captures only required setup data and keeps validation inline.",
-    `- Dashboard shows active ${profile.itemPlural}, next action, status, empty state, and recoverable error state.`,
-    "- Components follow the design system tokens and accessibility baseline.",
-    "- No production app code, network integration, Pro entitlement, `.sdtk/atlas`, or SDTK-WIKI mutation is implied by this handoff.",
-    "",
-    "## Non-Goals",
-    "",
-    "- Figma, Lovable, v0, or full app-builder replacement behavior.",
-    `- ${profile.nonGoals}`,
-    "- Package publish or deployment.",
+    "- Preserve token contract (`DESIGN_TOKENS.json`) and component pattern references during implementation.",
+    "- Do not replace required UI components with generic placeholder panels when high-fidelity contract artifacts exist.",
+    "- Keep no-debug-UI rules as QA-checked acceptance gates for customer-facing screens.",
     "",
   ].join("\n");
 }
-
+
 function runDesignHandoff({ projectPath, force = false }) {
-  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
-  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
-    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No project files were changed.`);
-  }
-
-  const paths = describeDesignPaths(resolvedProjectPath);
-  const missing = requiredArtifacts(paths).filter((artifact) => !fs.existsSync(artifact.filePath));
-  if (missing.length > 0) {
-    const missingList = missing.map((artifact) => artifact.relativePath).join(", ");
-    throw new ValidationError(`Missing required design artifacts: ${missingList}. Run the previous SDTK-DESIGN commands first. No project files were changed.`);
-  }
-  if (fs.existsSync(paths.designHandoffPath) && !force) {
-    throw new ValidationError("docs/design/DESIGN_HANDOFF.md already exists. Re-run with --force to replace this managed handoff.");
-  }
-
-  const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
-  const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
-  const designSystemContent = fs.readFileSync(paths.designSystemPath, "utf-8");
-  const wireframeContents = REQUIRED_WIREFRAMES.map((fileName) => fs.readFileSync(path.join(paths.wireframesPath, fileName), "utf-8"));
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No project files were changed.`);
+  }
+
+  const paths = describeDesignPaths(resolvedProjectPath);
+  const missing = requiredArtifacts(paths).filter((artifact) => !fs.existsSync(artifact.filePath));
+  if (missing.length > 0) {
+    const missingList = missing.map((artifact) => artifact.relativePath).join(", ");
+    throw new ValidationError(`Missing required design artifacts: ${missingList}. Run the previous SDTK-DESIGN commands first. No project files were changed.`);
+  }
+  if (fs.existsSync(paths.designHandoffPath) && !force) {
+    throw new ValidationError("docs/design/DESIGN_HANDOFF.md already exists. Re-run with --force to replace this managed handoff.");
+  }
+
+  const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
+  const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
+  const designSystemContent = fs.readFileSync(paths.designSystemPath, "utf-8");
+  const wireframeContents = REQUIRED_WIREFRAMES.map((fileName) => fs.readFileSync(path.join(paths.wireframesPath, fileName), "utf-8"));
   const profile = inferDomainProfile({ briefContent, screenMapContent, designSystemContent, wireframeContents });
+  const statePayload = readInputContractState(paths);
+  const highFidelityReady =
+    statePayload &&
+    statePayload.mode === "from-spec" &&
+    statePayload.analysisStatus === "INPUT_CONTRACT_READY" &&
+    fs.existsSync(paths.componentPatternLibraryPath) &&
+    fs.existsSync(paths.designTokensPath) &&
+    listScreenBriefArtifacts(paths).length > 0;
 
   fs.mkdirSync(path.dirname(paths.designHandoffPath), { recursive: true });
-  fs.writeFileSync(paths.designHandoffPath, handoffContent({ hasPrototype: fs.existsSync(paths.prototypeIndexPath), profile }), "utf-8");
+  const prototypeRefs = listPrototypeArtifacts(paths);
+  const base = handoffContent({ hasPrototype: fs.existsSync(paths.prototypeIndexPath), prototypeRefs, profile });
+  const appendix = highFidelityReady
+    ? highFidelityHandoffAppendix({
+        paths,
+        statePayload,
+        hasPrototype: fs.existsSync(paths.prototypeIndexPath),
+      })
+    : "## High-Fidelity UI Contract\n\n- Not activated for this project state. Simple MVP handoff remains valid.\n";
+  fs.writeFileSync(paths.designHandoffPath, `${base}\n${appendix}\n`, "utf-8");
 
   return {
     projectPath: resolvedProjectPath,
     relativeDesignHandoffPath: "docs/design/DESIGN_HANDOFF.md",
+    highFidelityReady,
     forced: Boolean(force),
   };
 }
-
-function cmdHandoff(args) {
-  const { flags } = parseFlags(args || [], HANDOFF_FLAG_DEFS);
-  if (flags.help) return cmdHandoffHelp();
-
-  const result = runDesignHandoff({
-    projectPath: flags["project-path"],
-    force: Boolean(flags.force),
-  });
-
+
+function cmdHandoff(args) {
+  const { flags } = parseFlags(args || [], HANDOFF_FLAG_DEFS);
+  if (flags.help) return cmdHandoffHelp();
+
+  const result = runDesignHandoff({
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+  });
+
   console.log(`[design] Wrote ${result.relativeDesignHandoffPath}: ${result.projectPath}`);
   console.log(`[design] Verdict: READY_FOR_SDTK_CODE`);
+  console.log(`[design] High-fidelity contract: ${result.highFidelityReady ? "enabled" : "not enabled"}`);
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
-  console.log("[design] No .sdtk/atlas, SDTK-WIKI output, source files, network, or app code was modified.");
-  return 0;
-}
-
-module.exports = {
-  cmdHandoff,
-  cmdHandoffHelp,
-  handoffContent,
-  requiredArtifacts,
-  runDesignHandoff,
-};
+  console.log("[design] No .sdtk/atlas, SDTK-WIKI output, source files, network, or app code was modified.");
+  return 0;
+}
+
+module.exports = {
+  cmdHandoff,
+  cmdHandoffHelp,
+  handoffContent,
+  requiredArtifacts,
+  runDesignHandoff,
+};

package/src/commands/help.js

@@ -8,7 +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 start --from-spec . --reference-dir ./docs/design/reference-export --profile b2b-commerce
   sdtk-design brief --idea "<idea>"
   sdtk-design screens
   sdtk-design wireframe --screen landing
@@ -20,7 +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 start --from-spec . --reference-dir ./docs/design/reference-export --profile b2b-commerce
   sdtk-design prototype --style premium-dashboard
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff