sdtk-design-kit 0.1.0 → 0.1.1

package/README.md

@@ -8,12 +8,13 @@ It is not a Figma clone, Lovable clone, v0 clone, full app builder, or productio
 
 ## Beginner Flow
 
-Use this five-command flow for a clean project:
+Use this optimized flow for a clean project:
 
 ```powershell
 sdtk-design init
-sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads, follow-ups, notes, and simple revenue pipeline without using a complex enterprise CRM."
-sdtk-design review --artifact docs/design/wireframes/LANDING.md
+sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads, follow-ups, notes, and simple revenue pipeline without using a complex enterprise CRM." --style premium-dashboard
+sdtk-design prototype
+sdtk-design review --artifact docs/design/prototype/index.html
 sdtk-design handoff
 sdtk-design status
 ```
@@ -22,7 +23,8 @@ What each command does:
 
 - `init`: creates the local design workspace.
 - `start`: creates the design brief, screen map, required wireframes, and design system.
-- `review`: reviews a local markdown design artifact.
+- `prototype`: creates a static visual preview from the generated design artifacts.
+- `review`: reviews a local markdown or static HTML design artifact with visual polish checks.
 - `handoff`: converts the generated design package into SDTK-CODE handoff guidance.
 - `status`: reports complete artifacts, missing artifacts, and the next recommended command.
 
@@ -32,13 +34,15 @@ What each command does:
 sdtk-design --help
 sdtk-design --version
 sdtk-design init [--project-path <path>] [--force] [--no-state]
-sdtk-design start --idea "<idea>" [--project-path <path>] [--force]
+sdtk-design start --idea "<idea>" [--style <preset>] [--project-path <path>] [--force]
 sdtk-design brief --idea "<idea>" [--project-path <path>] [--force]
 sdtk-design screens [--project-path <path>] [--force]
 sdtk-design wireframe --screen landing [--project-path <path>] [--force]
 sdtk-design wireframe --screen all [--project-path <path>] [--force]
-sdtk-design system [--project-path <path>] [--force]
+sdtk-design system [--style <preset>] [--project-path <path>] [--force]
+sdtk-design prototype [--style <preset>] [--project-path <path>] [--force]
 sdtk-design review --artifact docs/design/wireframes/LANDING.md [--project-path <path>] [--force]
+sdtk-design review --artifact docs/design/prototype/index.html [--project-path <path>] [--force]
 sdtk-design handoff [--project-path <path>] [--force]
 sdtk-design status [--project-path <path>]
 ```
@@ -54,6 +58,8 @@ docs/design/
   SCREEN_MAP.md
   DESIGN_SYSTEM.md
   DESIGN_HANDOFF.md
+  prototype/
+    index.html
   wireframes/
     LANDING.md
     ONBOARDING.md
@@ -64,6 +70,17 @@ docs/design/
 
 Internal state may live under `.sdtk/design/`. SDTK-DESIGN must not create or mutate `.sdtk/atlas`.
 
+## Visual Style Presets
+
+`start` and `system` accept `--style <preset>`. If omitted, SDTK-DESIGN uses `minimal-saas`.
+
+Available presets:
+
+- `minimal-saas`: clean solo-founder SaaS default.
+- `premium-dashboard`: dashboard-first MVP with stronger metrics, cards, and status surfaces.
+- `bold-founder`: high-contrast launch style for marketing-heavy MVPs.
+- `warm-editorial`: softer consultant/service-product style.
+
 ## Command Details
 
 ### `init`
@@ -82,9 +99,27 @@ brief -> screens -> wireframe --screen all -> system
 
 This is the beginner facade for the core design package. It does not run review or handoff. Existing managed core outputs are not overwritten unless `--force` is explicit.
 
+Use `--style premium-dashboard` for dashboard-led MVPs such as ClientPulse.
+
+### `prototype`
+
+Creates a static visual preview at `docs/design/prototype/index.html`.
+
+```powershell
+sdtk-design prototype --style premium-dashboard
+```
+
+The prototype includes landing, onboarding, and dashboard sections with responsive CSS, selected visual preset tokens, and domain copy derived from the generated design artifacts. It is not production app code and does not create files outside `docs/design/prototype`.
+
 ### `review`
 
-Reviews a local markdown artifact, for example:
+Reviews a local markdown or static HTML artifact. For the optimized workflow, review the generated prototype:
+
+```powershell
+sdtk-design review --artifact docs/design/prototype/index.html
+```
+
+Markdown artifact review remains supported:
 
 ```powershell
 sdtk-design review --artifact docs/design/wireframes/LANDING.md
@@ -92,18 +127,20 @@ sdtk-design review --artifact docs/design/wireframes/LANDING.md
 
 The review report is written to `docs/design/reviews/DESIGN_REVIEW_YYYYMMDD.md`.
 
-Current review support is local markdown artifact review only. No URL, browser, screenshot, vision, or DOM review is implemented in Foundation Beta.
+Current review support is local artifact review only. The report includes visual polish checks for hierarchy, spacing/density, CTA clarity, dashboard information density, responsive/mobile risk, accessibility baseline, and anti-wireframe/mockup risk. No URL, browser, screenshot, vision, or DOM review is implemented in Foundation Beta.
 
 ### `handoff`
 
 Reads the generated brief, screen map, required wireframes, and design system, then writes `docs/design/DESIGN_HANDOFF.md`.
 
-The handoff is planning input for SDTK-CODE. It includes screen-to-component mapping, screen-to-user-story mapping, design decisions, implementation notes, acceptance criteria, and a readiness verdict. It does not generate production app code.
+The handoff is planning input for SDTK-CODE. It includes screen-to-component mapping, screen-to-user-story mapping, design decisions, implementation notes, suggested data model, domain/status taxonomy, interaction flow, persistence guidance, visual implementation contract, prototype reference, SDTK-CODE build notes, acceptance criteria, and a readiness verdict. Domain-specific examples are derived from the generated artifacts rather than fixed to one demo product. It does not generate production app code.
 
 ### `status`
 
 Read-only command. It reports complete artifacts, missing artifacts, and the next recommended command.
 
+The optimized readiness path expects `docs/design/prototype/index.html` before prototype review and handoff.
+
 ## Non-Goals And Deferred Features
 
 Foundation Beta does not provide:

package/package.json

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

package/src/commands/handoff.js

@@ -4,6 +4,7 @@ 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 = {
@@ -56,7 +57,13 @@ function requiredArtifacts(paths) {
   ];
 }
 
-function handoffContent() {
+function handoffContent({ hasPrototype = false, 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];
+
   return [
     "# Design Handoff",
     "",
@@ -73,6 +80,7 @@ function handoffContent() {
     "- `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",
     "",
@@ -80,15 +88,15 @@ function handoffContent() {
     "|---|---|---|",
     "| 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, lead list, status pill, quick-add action, empty-state panel, recoverable error alert |",
+    `| 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 a solo consultant, I want to understand the lightweight CRM 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 lead without enterprise configuration. | Required fields are clear, validation is inline, and entered values are preserved on error. |",
-    "| Dashboard | As a solo consultant, I want to see active leads and follow-ups so I can choose my next action. | Leads, next actions, notes, and simple pipeline status are scannable with empty and error states. |",
+    `| 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",
     "",
@@ -105,18 +113,79 @@ function handoffContent() {
     "- 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}`,
+    "- 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 work, next action, simple pipeline status, empty state, and recoverable error state.",
+    `- 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.",
-    "- Enterprise CRM automation, complex analytics, billing, or multi-team administration.",
+    `- ${profile.nonGoals}`,
     "- Package publish or deployment.",
     "",
   ].join("\n");
@@ -138,8 +207,14 @@ function runDesignHandoff({ projectPath, force = false }) {
     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 });
+
   fs.mkdirSync(path.dirname(paths.designHandoffPath), { recursive: true });
-  fs.writeFileSync(paths.designHandoffPath, handoffContent(), "utf-8");
+  fs.writeFileSync(paths.designHandoffPath, handoffContent({ hasPrototype: fs.existsSync(paths.prototypeIndexPath), profile }), "utf-8");
 
   return {
     projectPath: resolvedProjectPath,

package/src/commands/help.js

@@ -7,21 +7,27 @@ Usage:
   sdtk-design --help
   sdtk-design --version
   sdtk-design init
-  sdtk-design start --idea "<idea>"
+  sdtk-design start --idea "<idea>" --style premium-dashboard
   sdtk-design brief --idea "<idea>"
   sdtk-design screens
   sdtk-design wireframe --screen landing
-  sdtk-design system
-  sdtk-design review --artifact docs/design/wireframes/LANDING.md
+  sdtk-design system --style minimal-saas
+  sdtk-design prototype --style premium-dashboard
+  sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
   sdtk-design status
 
 Examples:
-  sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads."
-  sdtk-design review --artifact docs/design/wireframes/LANDING.md
+  sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads." --style premium-dashboard
+  sdtk-design prototype --style premium-dashboard
+  sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
   sdtk-design status
 
+Visual style presets:
+  minimal-saas, premium-dashboard, bold-founder, warm-editorial
+  Default: minimal-saas
+
 Foundation Beta purpose:
   SDTK-DESIGN is a local-first MVP design planner and reviewer for solo founders.
   It turns a rough MVP idea into reviewable design artifacts and a deterministic SDTK-CODE handoff.
@@ -33,6 +39,7 @@ Required human-facing output:
   docs/design/wireframes/LANDING.md
   docs/design/wireframes/ONBOARDING.md
   docs/design/wireframes/DASHBOARD.md
+  docs/design/prototype/index.html
   docs/design/reviews/DESIGN_REVIEW_YYYYMMDD.md
   docs/design/DESIGN_HANDOFF.md
 
@@ -43,8 +50,9 @@ Command status:
   screens               Available.
   wireframe             Available.
   system                Available.
+  prototype             Available static HTML/CSS preview.
   handoff               Available.
-  review                Available for local markdown artifacts.
+  review                Available for local markdown and static HTML artifacts.
   start                 Available beginner facade.
   status                Available.