sdtk-design-kit 0.1.0

package/src/commands/init.js

@@ -0,0 +1,166 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { ValidationError } = require("../lib/errors");
+const {
+  assertProjectLocalPath,
+  describeDesignPaths,
+  resolveProjectPath,
+} = require("../lib/design-paths");
+
+const INIT_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+  "no-state": { type: "boolean" },
+};
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function cmdInitHelp() {
+  console.log(`SDTK-DESIGN Init
+
+Usage:
+  sdtk-design init [--project-path <path>] [--force] [--no-state]
+
+Example:
+  sdtk-design init
+
+Creates:
+  docs/design/
+  docs/design/wireframes/
+  docs/design/reviews/
+  docs/design/README.md
+  .sdtk/design/manifest.json unless --no-state is used
+
+Safety:
+  Local files only.
+  Existing managed files are skipped 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 designReadmeContent() {
+  return [
+    "# SDTK-DESIGN Workspace",
+    "",
+    "This folder contains human-facing design artifacts for the local MVP workflow.",
+    "",
+    "## Expected Phase A Artifacts",
+    "",
+    "- `DESIGN_BRIEF.md`: target user, pain point, MVP promise, CTA, non-goals, success metric, assumptions, and open questions.",
+    "- `SCREEN_MAP.md`: 3 to 6 MVP screens with purpose, primary action, required data, and state handling.",
+    "- `wireframes/`: low-fidelity screen specs such as `LANDING.md`, `ONBOARDING.md`, and `DASHBOARD.md`.",
+    "- `DESIGN_SYSTEM.md`: typography, colors, spacing, components, tone, and accessibility baseline.",
+    "- `DESIGN_HANDOFF.md`: deterministic SDTK-CODE handoff with readiness verdict.",
+    "",
+    "## Recommended Next Commands",
+    "",
+    "```powershell",
+    "sdtk-design brief --idea \"<your MVP idea>\"",
+    "sdtk-design screens",
+    "sdtk-design wireframe --screen landing",
+    "sdtk-design system",
+    "sdtk-design handoff",
+    "```",
+    "",
+    "## Boundary",
+    "",
+    "SDTK-DESIGN stores human-facing artifacts under `docs/design`. Internal design state may live under `.sdtk/design`. It must not create or mutate `.sdtk/atlas`.",
+    "",
+  ].join("\n");
+}
+
+function manifestContent(projectPath) {
+  return `${JSON.stringify({
+    schema_version: 1,
+    product: "SDTK-DESIGN",
+    state: "initialized",
+    created_at: new Date().toISOString(),
+    project_path: projectPath,
+    docs_path: "docs/design",
+    managed_by: "sdtk-design",
+  }, null, 2)}\n`;
+}
+
+function ensureDirectory(dirPath, projectPath, result) {
+  assertProjectLocalPath(dirPath, projectPath, "directory");
+  if (fs.existsSync(dirPath)) {
+    if (!fs.statSync(dirPath).isDirectory()) {
+      throw new ValidationError(`Expected directory but found a file: ${dirPath}. No project files were changed.`);
+    }
+    result.skipped.push(toPosix(path.relative(projectPath, dirPath)) + "/");
+    return;
+  }
+  fs.mkdirSync(dirPath, { recursive: true });
+  result.created.push(toPosix(path.relative(projectPath, dirPath)) + "/");
+}
+
+function writeManagedFile(filePath, content, projectPath, force, result) {
+  assertProjectLocalPath(filePath, projectPath, "managed file");
+  if (fs.existsSync(filePath) && !force) {
+    result.skipped.push(toPosix(path.relative(projectPath, filePath)));
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf-8");
+  result.created.push(toPosix(path.relative(projectPath, filePath)));
+}
+
+function runDesignInit({ projectPath, force = false, state = true }) {
+  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 result = {
+    projectPath: resolvedProjectPath,
+    created: [],
+    skipped: [],
+    stateEnabled: Boolean(state),
+  };
+
+  ensureDirectory(paths.designDocsPath, resolvedProjectPath, result);
+  ensureDirectory(paths.wireframesPath, resolvedProjectPath, result);
+  ensureDirectory(paths.reviewsPath, resolvedProjectPath, result);
+  writeManagedFile(paths.designReadmePath, designReadmeContent(), resolvedProjectPath, force, result);
+
+  if (state) {
+    ensureDirectory(paths.designStatePath, resolvedProjectPath, result);
+    writeManagedFile(paths.manifestPath, manifestContent(resolvedProjectPath), resolvedProjectPath, force, result);
+  }
+
+  return result;
+}
+
+function cmdInit(args) {
+  const { flags } = parseFlags(args || [], INIT_FLAG_DEFS);
+  if (flags.help) return cmdInitHelp();
+
+  const result = runDesignInit({
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+    state: !flags["no-state"],
+  });
+
+  console.log(`[design] Initialized SDTK-DESIGN workspace: ${result.projectPath}`);
+  console.log(`[design] Created: ${result.created.length}`);
+  console.log(`[design] Skipped: ${result.skipped.length}`);
+  console.log(`[design] State: ${result.stateEnabled ? ".sdtk/design enabled" : "disabled by --no-state"}`);
+  console.log("[design] No .sdtk/atlas, SDTK-WIKI output, source files, network, or app code was modified.");
+  console.log('[design] Next: sdtk-design brief --idea "<your MVP idea>"');
+  return 0;
+}
+
+module.exports = {
+  cmdInit,
+  cmdInitHelp,
+  runDesignInit,
+};

package/src/commands/review.js

@@ -0,0 +1,176 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { describeDesignPaths, isPathInsideOrEqual, resolveProjectPath } = require("../lib/design-paths");
+const { ValidationError } = require("../lib/errors");
+
+const REVIEW_FLAG_DEFS = {
+  help: { type: "boolean" },
+  artifact: { type: "string" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+};
+
+function cmdReviewHelp() {
+  console.log(`SDTK-DESIGN Review
+
+Usage:
+  sdtk-design review --artifact docs/design/wireframes/LANDING.md [--project-path <path>] [--force]
+
+Example:
+  sdtk-design review --artifact docs/design/wireframes/LANDING.md
+
+Reads:
+  A project-local markdown design artifact.
+
+Creates:
+  docs/design/reviews/DESIGN_REVIEW_YYYYMMDD.md
+
+Safety:
+  Local markdown artifact review only.
+  Existing same-day review report is not overwritten unless --force is explicit.
+  No URL, browser, screenshot, vision, or DOM review in BK-161.
+  No .sdtk/atlas creation or mutation.
+  No SDTK-WIKI output mutation.
+  No network call, Pro entitlement, or production app code generation.`);
+  return 0;
+}
+
+function formatDateYYYYMMDD(date = new Date()) {
+  return date.toISOString().slice(0, 10).replace(/-/g, "");
+}
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function resolveArtifactPath(artifact, projectPath) {
+  const raw = String(artifact || "").trim();
+  if (!raw) {
+    throw new ValidationError('Missing required --artifact "<path>". No project files were changed.');
+  }
+  const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(projectPath, raw);
+  if (!isPathInsideOrEqual(resolved, projectPath)) {
+    throw new ValidationError(`Refusing to review artifact outside project root: ${resolved}. No project files were changed.`);
+  }
+  return resolved;
+}
+
+function hasHeading(content, heading) {
+  return content.toLowerCase().includes(heading.toLowerCase());
+}
+
+function reviewContent({ artifactRelativePath, artifactContent }) {
+  const hasPrimaryCta = hasHeading(artifactContent, "Primary CTA") || artifactContent.toLowerCase().includes("cta");
+  const hasMobile = hasHeading(artifactContent, "Mobile Notes") || artifactContent.toLowerCase().includes("mobile");
+  const hasStates = hasHeading(artifactContent, "State Handling") || ["empty", "success", "error"].every((term) => artifactContent.toLowerCase().includes(term));
+  const hasAcceptance = hasHeading(artifactContent, "Acceptance Criteria");
+
+  return [
+    "# Design Review",
+    "",
+    "## Reviewed Artifact",
+    "",
+    `- Artifact: \`${artifactRelativePath}\``,
+    "- Review mode: local markdown artifact review",
+    "- No URL, browser, screenshot, vision, or DOM review was used.",
+    "",
+    "## Findings By Severity",
+    "",
+    "| Severity | Finding | Recommended action |",
+    "|---|---|---|",
+    `| High | ${hasPrimaryCta ? "No high-severity CTA blocker found in the artifact." : "Primary CTA is missing or not explicit."} | ${hasPrimaryCta ? "Keep the CTA visually dominant during implementation." : "Add one explicit primary CTA before handoff."} |`,
+    `| Medium | ${hasMobile ? "Mobile notes are present." : "Mobile behavior is not documented."} | ${hasMobile ? "Validate mobile layout during implementation." : "Add mobile layout notes for narrow screens."} |`,
+    `| Medium | ${hasStates ? "State handling is represented." : "Empty, success, or error states are incomplete."} | ${hasStates ? "Carry the states into implementation acceptance criteria." : "Document empty, success, and error handling."} |`,
+    `| Low | ${hasAcceptance ? "Acceptance criteria are present." : "Acceptance criteria are missing."} | ${hasAcceptance ? "Use criteria as SDTK-CODE test obligations." : "Add concrete acceptance criteria before coding."} |`,
+    "",
+    "## UX Issues",
+    "",
+    "- Keep the screen focused on one job and one dominant next action.",
+    "- Avoid adding enterprise configuration or secondary flows before the MVP action works.",
+    "- Ensure empty states teach the user what to do next instead of only saying no data exists.",
+    "",
+    "## CTA / Conversion Notes",
+    "",
+    "- The Primary CTA should be visible in the first viewport and repeated only where it helps the user finish the workflow.",
+    "- CTA copy should use a concrete verb, such as Add, Continue, Save, or Review.",
+    "- Supporting copy should reduce uncertainty before asking for setup or data entry.",
+    "",
+    "## Mobile / Accessibility Notes",
+    "",
+    "- Mobile layout should stay single-column with no horizontal scrolling.",
+    "- Interactive targets should be at least 44px by 44px where practical.",
+    "- Do not rely on color alone for status; pair it with visible text.",
+    "- Preserve keyboard focus and accessible names for icon-only controls.",
+    "",
+    "## Actionable Fixes",
+    "",
+    "- Confirm the screen has one visually dominant primary CTA.",
+    "- Confirm empty, success, and error states are visible in the artifact or downstream implementation plan.",
+    "- Confirm mobile notes are present before SDTK-CODE implementation starts.",
+    "- Confirm the artifact stays within SDTK-DESIGN scope and does not imply generated production app code.",
+    "",
+    "## Boundaries",
+    "",
+    "- No Figma, Lovable, v0, or full app-builder replacement behavior is claimed.",
+    "- No network call, Pro entitlement, `.sdtk/atlas`, or SDTK-WIKI output is required.",
+    "",
+  ].join("\n");
+}
+
+function runDesignReview({ artifact, 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 artifactPath = resolveArtifactPath(artifact, resolvedProjectPath);
+  if (!fs.existsSync(artifactPath) || !fs.statSync(artifactPath).isFile()) {
+    throw new ValidationError(`--artifact is not a readable file: ${artifactPath}. No project files were changed.`);
+  }
+
+  const paths = describeDesignPaths(resolvedProjectPath);
+  const reportName = `DESIGN_REVIEW_${formatDateYYYYMMDD()}.md`;
+  const reportPath = path.join(paths.reviewsPath, reportName);
+  if (fs.existsSync(reportPath) && !force) {
+    throw new ValidationError(`docs/design/reviews/${reportName} already exists. Re-run with --force to replace this managed review report.`);
+  }
+
+  const artifactContent = fs.readFileSync(artifactPath, "utf-8");
+  const artifactRelativePath = toPosix(path.relative(resolvedProjectPath, artifactPath));
+  fs.mkdirSync(paths.reviewsPath, { recursive: true });
+  fs.writeFileSync(reportPath, reviewContent({ artifactRelativePath, artifactContent }), "utf-8");
+
+  return {
+    projectPath: resolvedProjectPath,
+    relativeReportPath: `docs/design/reviews/${reportName}`,
+    forced: Boolean(force),
+  };
+}
+
+function cmdReview(args) {
+  const { flags } = parseFlags(args || [], REVIEW_FLAG_DEFS);
+  if (flags.help) return cmdReviewHelp();
+
+  const result = runDesignReview({
+    artifact: flags.artifact,
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+  });
+
+  console.log(`[design] Wrote ${result.relativeReportPath}: ${result.projectPath}`);
+  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.");
+  return 0;
+}
+
+module.exports = {
+  cmdReview,
+  cmdReviewHelp,
+  formatDateYYYYMMDD,
+  reviewContent,
+  runDesignReview,
+};

package/src/commands/screens.js

@@ -0,0 +1,208 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
+const { ValidationError } = require("../lib/errors");
+
+const SCREENS_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+};
+
+function cmdScreensHelp() {
+  console.log(`SDTK-DESIGN Screens
+
+Usage:
+  sdtk-design screens [--project-path <path>] [--force]
+
+Example:
+  sdtk-design screens
+
+Reads:
+  docs/design/DESIGN_BRIEF.md
+
+Creates:
+  docs/design/SCREEN_MAP.md
+
+Safety:
+  Local files only.
+  Existing SCREEN_MAP.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 includesAny(text, terms) {
+  const value = text.toLowerCase();
+  return terms.some((term) => value.includes(term));
+}
+
+function extractBriefLine(briefContent, heading) {
+  const lines = briefContent.split(/\r?\n/);
+  const headingIndex = lines.findIndex((line) => line.trim().toLowerCase() === heading.toLowerCase());
+  if (headingIndex < 0) return "";
+  for (let index = headingIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (line.startsWith("## ")) return "";
+    if (line.startsWith("- ")) return line.slice(2).trim();
+    if (line) return line;
+  }
+  return "";
+}
+
+function inferScreenContext(briefContent) {
+  const isCrm = includesAny(briefContent, ["crm", "lead", "follow-up", "pipeline"]);
+  if (isCrm) {
+    return {
+      productLabel: "lightweight CRM",
+      targetUser: extractBriefLine(briefContent, "## Target User") || "Solo consultants.",
+      promise: extractBriefLine(briefContent, "## MVP Promise") || "A lightweight CRM for lead tracking, follow-ups, notes, and simple pipeline visibility.",
+      primaryRecord: "lead",
+      primaryAction: "Add first lead",
+      dashboardObject: "active leads, follow-ups, and simple pipeline status",
+      emptyObject: "leads",
+    };
+  }
+  return {
+    productLabel: "focused MVP workspace",
+    targetUser: extractBriefLine(briefContent, "## Target User") || "Solo founders.",
+    promise: extractBriefLine(briefContent, "## MVP Promise") || "A focused MVP workflow with a clear next action.",
+    primaryRecord: "record",
+    primaryAction: "Start first workflow",
+    dashboardObject: "active work and next actions",
+    emptyObject: "records",
+  };
+}
+
+function screenMapContent(briefContent) {
+  const context = inferScreenContext(briefContent);
+  const screens = [
+    {
+      id: "LANDING",
+      name: "Landing",
+      purpose: `Explain the ${context.productLabel} promise quickly and route the user into the first meaningful action.`,
+      action: context.primaryAction,
+      data: "Value proposition, primary CTA, proof points, and a short preview of the first workflow.",
+      empty: "Show concise promise copy and a single CTA when no workspace exists yet.",
+      success: "User understands the product promise and starts onboarding.",
+      error: "If onboarding cannot start, show a clear retry path and keep the CTA visible.",
+    },
+    {
+      id: "ONBOARDING",
+      name: "Onboarding",
+      purpose: `Capture only the minimum setup needed before the user can create the first ${context.primaryRecord}.`,
+      action: context.primaryAction,
+      data: "User name or workspace label, first workflow preference, and optional sample data choice.",
+      empty: "Offer one guided setup path and one option to skip non-essential fields.",
+      success: `Workspace is ready and the user can create the first ${context.primaryRecord}.`,
+      error: "Inline validation identifies the missing required field and preserves entered values.",
+    },
+    {
+      id: "DASHBOARD",
+      name: "Dashboard",
+      purpose: `Show ${context.dashboardObject} with enough context to decide the next action.`,
+      action: context.primaryAction,
+      data: "Summary counters, prioritized list, next action date, recent notes, and simple status or stage.",
+      empty: `Explain that no ${context.emptyObject} exist yet and keep the first-create CTA prominent.`,
+      success: "User can scan current work, add or update a record, and leave with a visible next action.",
+      error: "If records fail to load, show a recoverable error with retry and no destructive action.",
+    },
+  ];
+
+  const lines = [
+    "# Screen Map",
+    "",
+    "## Brief Input Summary",
+    "",
+    `- Target user: ${context.targetUser}`,
+    `- MVP promise: ${context.promise}`,
+    "",
+    "## User Journey",
+    "",
+    "1. Visitor lands on the product promise and chooses the primary CTA.",
+    "2. User completes a short setup path that avoids enterprise configuration.",
+    "3. User reaches the dashboard and performs the first repeated workflow action.",
+    "",
+    "## MVP Screens",
+    "",
+  ];
+
+  for (const screen of screens) {
+    lines.push(
+      `### ${screen.id} - ${screen.name}`,
+      "",
+      `- Purpose: ${screen.purpose}`,
+      `- Primary action: ${screen.action}`,
+      `- Data needed: ${screen.data}`,
+      `- Empty state: ${screen.empty}`,
+      `- Success state: ${screen.success}`,
+      `- Error state: ${screen.error}`,
+      ""
+    );
+  }
+
+  lines.push(
+    "## Out Of Scope For MVP Screen Map",
+    "",
+    "- Production application code, database schema, and integration implementation.",
+    "- Complex enterprise configuration, advanced analytics, and multi-team administration.",
+    "- Figma, Lovable, v0, or full app-builder replacement behavior.",
+    ""
+  );
+
+  return lines.join("\n");
+}
+
+function runDesignScreens({ 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);
+  if (!fs.existsSync(paths.designBriefPath)) {
+    throw new ValidationError("Missing docs/design/DESIGN_BRIEF.md. Run sdtk-design brief --idea \"<idea>\" first. No project files were changed.");
+  }
+  if (fs.existsSync(paths.screenMapPath) && !force) {
+    throw new ValidationError("docs/design/SCREEN_MAP.md already exists. Re-run with --force to replace this managed screen map.");
+  }
+
+  const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
+  fs.mkdirSync(path.dirname(paths.screenMapPath), { recursive: true });
+  fs.writeFileSync(paths.screenMapPath, screenMapContent(briefContent), "utf-8");
+
+  return {
+    projectPath: resolvedProjectPath,
+    screenMapPath: paths.screenMapPath,
+    relativeScreenMapPath: "docs/design/SCREEN_MAP.md",
+    forced: Boolean(force),
+  };
+}
+
+function cmdScreens(args) {
+  const { flags } = parseFlags(args || [], SCREENS_FLAG_DEFS);
+  if (flags.help) return cmdScreensHelp();
+
+  const result = runDesignScreens({
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+  });
+
+  console.log(`[design] Wrote ${result.relativeScreenMapPath}: ${result.projectPath}`);
+  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 wireframe --screen landing");
+  return 0;
+}
+
+module.exports = {
+  cmdScreens,
+  cmdScreensHelp,
+  inferScreenContext,
+  runDesignScreens,
+  screenMapContent,
+};

package/src/commands/start.js

@@ -0,0 +1,121 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { runDesignBrief } = require("./brief");
+const { runDesignScreens } = require("./screens");
+const { runDesignSystem } = require("./system");
+const { runDesignWireframe } = require("./wireframe");
+const { parseFlags } = require("../lib/args");
+const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
+const { ValidationError } = require("../lib/errors");
+
+const START_FLAG_DEFS = {
+  help: { type: "boolean" },
+  idea: { type: "string" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+};
+
+const REQUIRED_WIREFRAME_FILES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
+
+function cmdStartHelp() {
+  console.log(`SDTK-DESIGN Start
+
+Usage:
+  sdtk-design start --idea "<rough MVP idea>" [--project-path <path>] [--force]
+
+Example:
+  sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads."
+
+Runs:
+  brief -> screens -> wireframe --screen all -> system
+
+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
+
+Safety:
+  Local files only.
+  Existing managed core design outputs are not overwritten unless --force is explicit.
+  No review, handoff, URL, browser, screenshot, vision, or DOM work.
+  No .sdtk/atlas creation or mutation.
+  No SDTK-WIKI output mutation.
+  No network call, Pro entitlement, or production app code generation.`);
+  return 0;
+}
+
+function normalizeIdea(idea) {
+  return String(idea || "").replace(/\s+/g, " ").trim();
+}
+
+function coreOutputTargets(paths) {
+  return [
+    { relativePath: "docs/design/DESIGN_BRIEF.md", filePath: paths.designBriefPath },
+    { relativePath: "docs/design/SCREEN_MAP.md", filePath: paths.screenMapPath },
+    { relativePath: "docs/design/DESIGN_SYSTEM.md", filePath: paths.designSystemPath },
+    ...REQUIRED_WIREFRAME_FILES.map((fileName) => ({
+      relativePath: `docs/design/wireframes/${fileName}`,
+      filePath: path.join(paths.wireframesPath, fileName),
+    })),
+  ];
+}
+
+function runDesignStart({ idea, projectPath, force = false }) {
+  const normalizedIdea = normalizeIdea(idea);
+  if (!normalizedIdea) {
+    throw new ValidationError('Missing required --idea "<rough MVP idea>". No project files were changed.');
+  }
+
+  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 existing = coreOutputTargets(paths).filter((target) => fs.existsSync(target.filePath));
+  if (existing.length > 0 && !force) {
+    const files = existing.map((target) => target.relativePath).join(", ");
+    throw new ValidationError(`Managed core design output already exists: ${files}. Re-run with --force to replace core outputs.`);
+  }
+
+  runDesignBrief({ idea: normalizedIdea, projectPath: resolvedProjectPath, force });
+  runDesignScreens({ projectPath: resolvedProjectPath, force });
+  runDesignWireframe({ screen: "all", projectPath: resolvedProjectPath, force });
+  runDesignSystem({ projectPath: resolvedProjectPath, force });
+
+  return {
+    projectPath: resolvedProjectPath,
+    written: coreOutputTargets(paths).map((target) => target.relativePath),
+    forced: Boolean(force),
+  };
+}
+
+function cmdStart(args) {
+  const { flags } = parseFlags(args || [], START_FLAG_DEFS);
+  if (flags.help) return cmdStartHelp();
+
+  const result = runDesignStart({
+    idea: flags.idea,
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+  });
+
+  console.log(`[design] Started SDTK-DESIGN package: ${result.projectPath}`);
+  console.log(`[design] Wrote core artifacts: ${result.written.join(", ")}`);
+  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");
+  return 0;
+}
+
+module.exports = {
+  cmdStart,
+  cmdStartHelp,
+  coreOutputTargets,
+  runDesignStart,
+};