sdtk-design-kit 0.1.0 → 0.1.1

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);
   }

package/src/lib/design-paths.js

@@ -5,6 +5,8 @@ const path = require("path");
 const DESIGN_DOCS_RELATIVE = path.join("docs", "design");
 const DESIGN_WIREFRAMES_RELATIVE = path.join("docs", "design", "wireframes");
 const DESIGN_REVIEWS_RELATIVE = path.join("docs", "design", "reviews");
+const DESIGN_PROTOTYPE_RELATIVE = path.join("docs", "design", "prototype");
+const DESIGN_PROTOTYPE_INDEX_RELATIVE = path.join("docs", "design", "prototype", "index.html");
 const DESIGN_README_RELATIVE = path.join("docs", "design", "README.md");
 const DESIGN_BRIEF_RELATIVE = path.join("docs", "design", "DESIGN_BRIEF.md");
 const DESIGN_SCREEN_MAP_RELATIVE = path.join("docs", "design", "SCREEN_MAP.md");
@@ -44,6 +46,8 @@ function describeDesignPaths(projectPath) {
     designDocsPath: path.join(root, DESIGN_DOCS_RELATIVE),
     wireframesPath: path.join(root, DESIGN_WIREFRAMES_RELATIVE),
     reviewsPath: path.join(root, DESIGN_REVIEWS_RELATIVE),
+    prototypePath: path.join(root, DESIGN_PROTOTYPE_RELATIVE),
+    prototypeIndexPath: path.join(root, DESIGN_PROTOTYPE_INDEX_RELATIVE),
     designReadmePath: path.join(root, DESIGN_README_RELATIVE),
     designBriefPath: path.join(root, DESIGN_BRIEF_RELATIVE),
     screenMapPath: path.join(root, DESIGN_SCREEN_MAP_RELATIVE),
@@ -59,6 +63,8 @@ module.exports = {
   DESIGN_DOCS_RELATIVE,
   DESIGN_HANDOFF_RELATIVE,
   DESIGN_MANIFEST_RELATIVE,
+  DESIGN_PROTOTYPE_INDEX_RELATIVE,
+  DESIGN_PROTOTYPE_RELATIVE,
   DESIGN_README_RELATIVE,
   DESIGN_REVIEWS_RELATIVE,
   DESIGN_SCREEN_MAP_RELATIVE,

package/src/lib/domain-profile.js

@@ -0,0 +1,108 @@
+"use strict";
+
+function normalizeText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function extractSourceIdea(briefContent) {
+  const match = String(briefContent || "").match(/## Source Idea\s+([\s\S]*?)(?:\n## |\s*$)/i);
+  return normalizeText(match ? match[1] : "");
+}
+
+function extractProductName(sourceIdea, crmLike) {
+  const clean = normalizeText(sourceIdea);
+  const namedBuild = clean.match(/\bbuild\s+([A-Z][A-Za-z0-9-]{2,40})(?:,|\s+for|\s+to|\s+that|\s+-)/);
+  if (namedBuild) return namedBuild[1];
+  return crmLike ? "Client Workspace" : "MVP Workspace";
+}
+
+function slugify(value) {
+  const slug = normalizeText(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "mvp-workspace";
+}
+
+function inferDomainProfile({ briefContent = "", screenMapContent = "", designSystemContent = "", wireframeContents = [] } = {}) {
+  const sourceIdea = extractSourceIdea(briefContent);
+  const combined = normalizeText([sourceIdea, briefContent, screenMapContent, designSystemContent, ...wireframeContents].join(" "));
+  const domainSource = normalizeText([sourceIdea, briefContent].join(" "));
+  const lower = domainSource.toLowerCase();
+  const crmLike = /\b(crm|lead|leads|pipeline|follow-up|follow up|consultant|client conversation|opportunity)\b/.test(lower);
+  const productName = extractProductName(sourceIdea || combined, crmLike);
+  const slug = slugify(productName);
+
+  if (crmLike) {
+    return {
+      kind: "crm",
+      productName,
+      slug,
+      targetUser: "the primary user",
+      promise: "Track leads, notes, follow-ups, and simple pipeline status without enterprise CRM weight.",
+      setupLabel: "Workspace",
+      setupNameLabel: "Workspace name",
+      setupNameValue: `${productName} Consulting`,
+      primaryAction: "Create workspace",
+      secondaryAction: "Preview dashboard",
+      itemSingular: "lead",
+      itemPlural: "leads",
+      itemLabel: "Lead",
+      itemNameLabel: "Name",
+      itemNameValue: "Avery Lee",
+      itemContextLabel: "Next follow-up",
+      itemContextValue: "2026-05-27",
+      itemAction: "Add lead",
+      saveAction: "Save lead",
+      collectionSurface: "lead list",
+      dashboardTitle: "Pipeline dashboard with next actions visible.",
+      emptyState: "Empty state: when no leads exist, keep the first-create CTA prominent.",
+      statusTaxonomy: ["New", "Contacted", "Proposal", "Won", "Lost"],
+      statusExample: "Proposal",
+      metricLabels: ["Active leads", "Due follow-ups", "Proposal value", "Won this month"],
+      metricValues: ["12", "4", "$18k", "3"],
+      modelName: "Lead",
+      storageKeys: [`${slug}.workspace`, `${slug}.leads`],
+      nonGoals: "Enterprise CRM automation, complex analytics, billing, or multi-team administration.",
+    };
+  }
+
+  return {
+    kind: "generic",
+    productName,
+    slug,
+    targetUser: "the primary user",
+    promise: "Turn the core MVP workflow into a clear launch, setup, and dashboard experience.",
+    setupLabel: "Workspace",
+    setupNameLabel: "Workspace name",
+    setupNameValue: `${productName} Team`,
+    primaryAction: "Start setup",
+    secondaryAction: "Preview dashboard",
+    itemSingular: "work item",
+    itemPlural: "work items",
+    itemLabel: "Work item",
+    itemNameLabel: "Item name",
+    itemNameValue: "First workflow",
+    itemContextLabel: "Next action",
+    itemContextValue: "Review progress",
+    itemAction: "Add item",
+    saveAction: "Save item",
+    collectionSurface: "work queue",
+    dashboardTitle: "Dashboard with current work and next actions visible.",
+    emptyState: "Empty state: when no work items exist, keep the first-create CTA prominent.",
+    statusTaxonomy: ["New", "In Progress", "Review", "Done"],
+    statusExample: "In Progress",
+    metricLabels: ["Active items", "Due actions", "In review", "Completed"],
+    metricValues: ["8", "3", "2", "5"],
+    modelName: "WorkItem",
+    storageKeys: [`${slug}.workspace`, `${slug}.items`],
+    nonGoals: "Enterprise workflow automation, advanced analytics, billing, or multi-role administration.",
+  };
+}
+
+module.exports = {
+  extractSourceIdea,
+  inferDomainProfile,
+  normalizeText,
+  slugify,
+};

package/src/lib/style-presets.js

@@ -0,0 +1,150 @@
+"use strict";
+
+const { ValidationError } = require("./errors");
+
+const DEFAULT_STYLE = "minimal-saas";
+
+const STYLE_PRESETS = {
+  "minimal-saas": {
+    label: "Minimal SaaS",
+    summary: "Clean solo-founder SaaS default with practical hierarchy, quiet surfaces, and low-decoration components.",
+    typography: [
+      "Use system UI, Segoe UI, Roboto, Helvetica, Arial, sans-serif.",
+      "Use a clear 32/24/18/15/13px hierarchy for page, section, card, body, and label text.",
+      "Keep letter spacing at 0 except optional uppercase micro-labels at 0.04em.",
+    ],
+    colors: [
+      "`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, `color-warning`: #B7791F, `color-danger`: #B42318.",
+      "`color-border`: #D9DEE7 for quiet dividers and input borders.",
+    ],
+    surface: "Use white cards on a soft gray page. Prefer borders over shadows and keep radius at 8px or less.",
+    density: "Use medium density: 16px form/list gaps, 24px section gaps, and compact repeated cards.",
+    cta: "One filled primary CTA per screen; secondary actions should be outlined or text-only.",
+    dashboard: "Use 3-4 summary cards, a simple list/table, status pills with text, and an obvious empty state.",
+    mobile: "Collapse grids to one column under 760px and keep controls at least 44px tall.",
+    accessibility: "Prioritize contrast, visible focus, labeled inputs, and text labels for status.",
+    components: [
+      "Metric card: label, value, short delta.",
+      "Lead card/table row: status, name, next action, note metadata.",
+      "Form row: label, input, helper or inline error.",
+    ],
+  },
+  "premium-dashboard": {
+    label: "Premium Dashboard",
+    summary: "Dashboard-first MVP style with stronger density, metrics, cards, tables, and command surfaces.",
+    typography: [
+      "Use Inter-like system sans with tabular numerals for metrics.",
+      "Use a 34/24/18/14/12px hierarchy with heavier labels and compact metadata.",
+      "Reserve monospace only for technical IDs, timestamps, or compact metric labels.",
+    ],
+    colors: [
+      "`color-bg`: #0B1020 for a deep operational shell or #F5F7FB for light dashboards.",
+      "`color-surface`: #FFFFFF for light cards or #111827 for dark panels.",
+      "`color-text`: #111827 on light surfaces and #F8FAFC on dark surfaces.",
+      "`color-muted`: #64748B for secondary text.",
+      "`color-primary`: #0F766E for primary actions and active states.",
+      "`color-accent`: #2563EB for one chart or selected metric highlight.",
+      "`color-border`: #D8E0EA for light mode or rgba(255,255,255,0.10) for dark panels.",
+    ],
+    surface: "Use a structured dashboard shell with cards, tables, and status surfaces. Shadows can be slightly stronger but must stay functional.",
+    density: "Use higher density: 12px row gaps, 14-16px card padding, aligned KPI tracks, and scannable table rows.",
+    cta: "Primary CTA should be compact and task-oriented, such as Add lead or Review pipeline.",
+    dashboard: "Lead with 4 KPI cards, then a pipeline/list region. Keep status, follow-up, and note snippets visible without opening details.",
+    mobile: "Stack metric cards into two columns then one column; avoid horizontal scrolling for core lead data.",
+    accessibility: "Status color must always pair with text. Keep focus rings visible on dense controls.",
+    components: [
+      "KPI card: label, value, trend, comparison.",
+      "Pipeline panel: status pill, count, next action.",
+      "Command surface: compact primary action plus one secondary filter/control.",
+    ],
+  },
+  "bold-founder": {
+    label: "Bold Founder",
+    summary: "High-contrast launch style for marketing-heavy MVPs with decisive type and CTA hierarchy.",
+    typography: [
+      "Use a heavy display face fallback stack: Impact, Arial Black, Inter, system-ui.",
+      "Use a 56/36/24/16/13px hierarchy and keep body copy short.",
+      "Use uppercase labels sparingly for proof points and section markers.",
+    ],
+    colors: [
+      "`color-bg`: #111111 for dark launch sections or #FFF7ED for high-contrast light sections.",
+      "`color-surface`: #FFFFFF or #18181B for framed proof blocks.",
+      "`color-text`: #FAFAFA on dark and #111827 on light.",
+      "`color-muted`: #A1A1AA for secondary text.",
+      "`color-primary`: #F97316 for the main CTA.",
+      "`color-accent`: #22C55E for one success/proof highlight.",
+      "`color-border`: #27272A or #111827 for strong edges.",
+    ],
+    surface: "Use bold framed sections, hard borders, and clear contrast. Avoid decorative clutter.",
+    density: "Use lower density in hero areas, then compact proof cards and feature rows.",
+    cta: "CTA should be visually dominant, direct, and above the fold.",
+    dashboard: "If a dashboard is needed, use bold stat cards and clear status blocks rather than subtle utility chrome.",
+    mobile: "Reduce hero type, keep CTA full-width, and stack proof points in a single column.",
+    accessibility: "High contrast is required; do not use accent-only meaning.",
+    components: [
+      "Hero lockup: large headline, short proof line, primary CTA.",
+      "Proof card: metric, label, customer-facing implication.",
+      "Status badge: strong text label plus color.",
+    ],
+  },
+  "warm-editorial": {
+    label: "Warm Editorial",
+    summary: "Softer consultant/service-product style with restrained serif-led hierarchy and warm surfaces.",
+    typography: [
+      "Use Georgia, Charter, or Times New Roman for display; use system sans for UI labels and forms.",
+      "Use a 44/30/22/16/13px hierarchy with generous line-height for reading.",
+      "Use serif display for promise, stats, and narrative sections; keep forms sans and literal.",
+    ],
+    colors: [
+      "`color-bg`: #FAF7F2 warm off-white.",
+      "`color-surface`: #FFFFFF for elevated content.",
+      "`color-text`: #1C1A17 near-black.",
+      "`color-muted`: #8A817A for metadata and secondary copy.",
+      "`color-primary`: #C0512F terracotta for primary CTA.",
+      "`color-accent`: #2F5B4F forest for tags and section dividers.",
+      "`color-border`: rgba(47,91,79,0.16) for restrained structure.",
+    ],
+    surface: "Use warm paper backgrounds, restrained cards, and minimal shadows.",
+    density: "Use generous spacing for landing and onboarding, then moderate density for dashboard cards.",
+    cta: "Primary CTA uses terracotta fill; secondary actions stay outlined.",
+    dashboard: "Use readable cards and notes-first presentation for relationship-led work, not heavy analytics chrome.",
+    mobile: "Keep reading width narrow, stack cards, and reduce vertical spacing by about one third.",
+    accessibility: "Warm palettes still need contrast checks; avoid low-contrast tan-on-cream labels.",
+    components: [
+      "Editorial hero: serif headline, concise support copy, terracotta CTA.",
+      "Relationship card: lead, latest note, next follow-up.",
+      "Tag row: forest-accent labels with readable text.",
+    ],
+  },
+};
+
+function availableStyleNames() {
+  return Object.keys(STYLE_PRESETS);
+}
+
+function resolveStyleName(style) {
+  const normalized = String(style || DEFAULT_STYLE).trim().toLowerCase();
+  if (STYLE_PRESETS[normalized]) {
+    return normalized;
+  }
+  throw new ValidationError(
+    `Unsupported --style "${style}". Supported styles: ${availableStyleNames().join(", ")}. No project files were changed.`
+  );
+}
+
+function getStylePreset(style) {
+  return STYLE_PRESETS[resolveStyleName(style)];
+}
+
+module.exports = {
+  DEFAULT_STYLE,
+  STYLE_PRESETS,
+  availableStyleNames,
+  getStylePreset,
+  resolveStyleName,
+};