sdtk-design-kit 0.1.0 → 0.1.2

package/src/commands/start.js

@@ -8,13 +8,21 @@ 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");
 
 const START_FLAG_DEFS = {
   help: { type: "boolean" },
   idea: { type: "string" },
   "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"];
@@ -23,25 +31,42 @@ function cmdStartHelp() {
   console.log(`SDTK-DESIGN Start
 
 Usage:
-  sdtk-design start --idea "<rough MVP idea>" [--project-path <path>] [--force]
+  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:
+  ${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.
@@ -65,11 +90,12 @@ function coreOutputTargets(paths) {
   ];
 }
 
-function runDesignStart({ idea, projectPath, force = false }) {
+function runDesignStart({ idea, projectPath, force = false, style = DEFAULT_STYLE }) {
   const normalizedIdea = normalizeIdea(idea);
   if (!normalizedIdea) {
     throw new ValidationError('Missing required --idea "<rough MVP idea>". No project files were changed.');
   }
+  const styleName = resolveStyleName(style);
 
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
   if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
@@ -86,12 +112,35 @@ function runDesignStart({ idea, projectPath, force = false }) {
   runDesignBrief({ idea: normalizedIdea, projectPath: resolvedProjectPath, force });
   runDesignScreens({ projectPath: resolvedProjectPath, force });
   runDesignWireframe({ screen: "all", projectPath: resolvedProjectPath, force });
-  runDesignSystem({ projectPath: resolvedProjectPath, force });
+  runDesignSystem({ projectPath: resolvedProjectPath, force, style: styleName });
 
   return {
     projectPath: resolvedProjectPath,
     written: coreOutputTargets(paths).map((target) => target.relativePath),
     forced: Boolean(force),
+    style: styleName,
+  };
+}
+
+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",
   };
 }
 
@@ -99,17 +148,53 @@ 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"],
     force: Boolean(flags.force),
+    style: flags.style,
   });
 
   console.log(`[design] Started SDTK-DESIGN package: ${result.projectPath}`);
   console.log(`[design] Wrote core artifacts: ${result.written.join(", ")}`);
+  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 review --artifact docs/design/wireframes/LANDING.md");
+  console.log("[design] Next: sdtk-design prototype");
   return 0;
 }
 
@@ -117,5 +202,6 @@ module.exports = {
   cmdStart,
   cmdStartHelp,
   coreOutputTargets,
+  runDesignStartFromSpec,
   runDesignStart,
 };

package/src/commands/status.js

@@ -41,6 +41,7 @@ function artifactPlan(paths) {
     { label: "Onboarding wireframe", relativePath: "docs/design/wireframes/ONBOARDING.md", filePath: path.join(paths.wireframesPath, "ONBOARDING.md"), phase: "core" },
     { label: "Dashboard wireframe", relativePath: "docs/design/wireframes/DASHBOARD.md", filePath: path.join(paths.wireframesPath, "DASHBOARD.md"), phase: "core" },
     { label: "Design system", relativePath: "docs/design/DESIGN_SYSTEM.md", filePath: paths.designSystemPath, phase: "core" },
+    { label: "Prototype preview", relativePath: "docs/design/prototype/index.html", filePath: paths.prototypeIndexPath, phase: "prototype" },
     { label: "Design handoff", relativePath: "docs/design/DESIGN_HANDOFF.md", filePath: paths.designHandoffPath, phase: "handoff" },
   ];
 }
@@ -52,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()) {
@@ -64,14 +76,24 @@ 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";
   } else if (!reviewExists) {
-    nextCommand = "sdtk-design review --artifact docs/design/wireframes/LANDING.md";
+    nextCommand = "sdtk-design review --artifact docs/design/prototype/index.html";
   } else if (handoffMissing) {
     nextCommand = "sdtk-design handoff";
   }
@@ -79,6 +101,7 @@ function inspectDesignStatus(projectPath) {
   return {
     projectPath: resolvedProjectPath,
     artifacts,
+    inputContractState,
     reviewExists,
     nextCommand,
   };
@@ -118,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/commands/system.js

@@ -5,21 +5,28 @@ const path = require("path");
 const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
 const { ValidationError } = require("../lib/errors");
+const { DEFAULT_STYLE, availableStyleNames, getStylePreset, resolveStyleName } = require("../lib/style-presets");
 
 const SYSTEM_FLAG_DEFS = {
   help: { type: "boolean" },
   "project-path": { type: "string" },
   force: { type: "boolean" },
+  style: { type: "string" },
 };
 
 function cmdSystemHelp() {
   console.log(`SDTK-DESIGN System
 
 Usage:
-  sdtk-design system [--project-path <path>] [--force]
+  sdtk-design system [--style <preset>] [--project-path <path>] [--force]
 
-Example:
+Examples:
   sdtk-design system
+  sdtk-design system --style premium-dashboard
+
+Style presets:
+  ${availableStyleNames().join(", ")}
+  Default: ${DEFAULT_STYLE}
 
 Reads:
   docs/design/DESIGN_BRIEF.md
@@ -42,7 +49,12 @@ function includesAny(text, terms) {
   return terms.some((term) => value.includes(term));
 }
 
-function systemContent(briefContent, screenMapContent) {
+function linesForBullets(items) {
+  return items.map((item) => `- ${item}`);
+}
+
+function systemContent(briefContent, screenMapContent, style = DEFAULT_STYLE) {
+  const preset = getStylePreset(style);
   const source = `${briefContent}\n${screenMapContent}`;
   const isCrm = includesAny(source, ["crm", "lead", "follow-up", "pipeline"]);
   const primaryAction = isCrm ? "Add first lead" : "Start first workflow";
@@ -57,26 +69,24 @@ function systemContent(briefContent, screenMapContent) {
     "- Favor clarity, scannability, and obvious next actions over decorative marketing composition.",
     `- Primary repeated action: ${primaryAction}.`,
     "",
+    "## Visual Preset",
+    "",
+    `- Preset: ${resolveStyleName(style)} (${preset.label}).`,
+    `- Direction: ${preset.summary}`,
+    "- Presets are compact SDTK-DESIGN guidance adapted from reference patterns, not imported runtime code.",
+    "",
     "## Typography",
     "",
-    "- Font stack: system UI, Segoe UI, Roboto, Helvetica, Arial, sans-serif.",
-    "- Page title: 28px, 36px line-height, semibold.",
-    "- Section heading: 18px, 26px line-height, semibold.",
-    "- Body text: 15px, 22px line-height, regular.",
-    "- Label text: 13px, 18px line-height, medium.",
+    ...linesForBullets(preset.typography),
     "- Do not scale font size with viewport width; keep letter spacing at 0.",
     "",
     "## Color Tokens",
     "",
-    "- `color-bg`: #F7F8FA for the application background.",
-    "- `color-surface`: #FFFFFF for panels, forms, and lists.",
-    "- `color-text`: #1F2933 for primary text.",
-    "- `color-muted`: #667085 for secondary text.",
-    "- `color-primary`: #2563EB for the main CTA and selected states.",
-    "- `color-success`: #0F8A5F for confirmed progress.",
-    "- `color-warning`: #B7791F for attention without blocking.",
-    "- `color-danger`: #B42318 for destructive or failed states.",
-    "- `color-border`: #D9DEE7 for quiet dividers and input borders.",
+    ...linesForBullets(preset.colors),
+    "",
+    "## Surface / Background Strategy",
+    "",
+    `- ${preset.surface}`,
     "",
     "## Spacing",
     "",
@@ -94,6 +104,7 @@ function systemContent(briefContent, screenMapContent) {
     "- Icon buttons: square 36px control with tooltip when the icon is not self-evident.",
     "- Disabled state: 45% opacity with no hover elevation.",
     "- CTA copy should use verbs tied to the workflow, such as Add, Save, Continue, or Review.",
+    `- Preset CTA treatment: ${preset.cta}`,
     "",
     "## Card Style",
     "",
@@ -102,6 +113,11 @@ function systemContent(briefContent, screenMapContent) {
     "- Border: 1px solid `color-border`; avoid heavy shadows.",
     "- Card content order: status, title, next action, supporting metadata.",
     "- Avoid nested cards and decorative gradient backgrounds.",
+    `- Preset density rule: ${preset.density}`,
+    "",
+    "## Table / Dashboard Density",
+    "",
+    `- ${preset.dashboard}`,
     "",
     "## Form Style",
     "",
@@ -111,6 +127,15 @@ function systemContent(briefContent, screenMapContent) {
     "- Prefer segmented controls or toggles for short option sets.",
     "- Forms should ask for the minimum needed before the first useful action.",
     "",
+    "## Component Recipe Hints",
+    "",
+    ...linesForBullets(preset.components),
+    "",
+    "## Mobile Layout Rules",
+    "",
+    `- ${preset.mobile}`,
+    "- Keep text within parent containers at mobile widths and avoid viewport-scaled type.",
+    "",
     "## Tone",
     "",
     `- Use practical language around ${toneObject}; avoid enterprise jargon.`,
@@ -120,6 +145,7 @@ function systemContent(briefContent, screenMapContent) {
     "",
     "## Accessibility Baseline",
     "",
+    `- Preset accessibility emphasis: ${preset.accessibility}`,
     "- Maintain visible keyboard focus for all interactive controls.",
     "- Use 4.5:1 contrast for body text and 3:1 for large text and essential UI boundaries.",
     "- Do not rely on color alone for status; pair status color with text or icon labels.",
@@ -136,7 +162,8 @@ function systemContent(briefContent, screenMapContent) {
   ].join("\n");
 }
 
-function runDesignSystem({ projectPath, force = false }) {
+function runDesignSystem({ projectPath, force = false, style = DEFAULT_STYLE }) {
+  const styleName = resolveStyleName(style);
   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.`);
@@ -156,12 +183,13 @@ function runDesignSystem({ projectPath, force = false }) {
   const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
   const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
   fs.mkdirSync(path.dirname(paths.designSystemPath), { recursive: true });
-  fs.writeFileSync(paths.designSystemPath, systemContent(briefContent, screenMapContent), "utf-8");
+  fs.writeFileSync(paths.designSystemPath, systemContent(briefContent, screenMapContent, styleName), "utf-8");
 
   return {
     projectPath: resolvedProjectPath,
     relativeDesignSystemPath: "docs/design/DESIGN_SYSTEM.md",
     forced: Boolean(force),
+    style: styleName,
   };
 }
 
@@ -172,9 +200,11 @@ function cmdSystem(args) {
   const result = runDesignSystem({
     projectPath: flags["project-path"],
     force: Boolean(flags.force),
+    style: flags.style,
   });
 
   console.log(`[design] Wrote ${result.relativeDesignSystemPath}: ${result.projectPath}`);
+  console.log(`[design] Style: ${result.style}`);
   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.");
   console.log("[design] Next: sdtk-design handoff");

package/src/index.js

@@ -4,6 +4,7 @@ const { cmdBrief } = require("./commands/brief");
 const { cmdHandoff } = require("./commands/handoff");
 const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
+const { cmdPrototype } = require("./commands/prototype");
 const { cmdReview } = require("./commands/review");
 const { cmdScreens } = require("./commands/screens");
 const { cmdStart } = require("./commands/start");
@@ -66,6 +67,9 @@ async function run(argv) {
   if (command === "review") {
     return cmdReview(args);
   }
+  if (command === "prototype") {
+    return cmdPrototype(args);
+  }
   if (command === "start") {
     return cmdStart(args);
   }