sdtk-design-kit 0.3.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 `sdtk-design-kit` is the public CLI package for SDTK-DESIGN.
 
-Package version in this source snapshot: `0.3.1`
+Package version in this source snapshot: `0.4.0`
 CLI command: `sdtk-design`
 
 SDTK-DESIGN is a local-first MVP design planner and reviewer. It turns either a rough MVP idea or explicit SDTK-SPEC design artifacts into reviewable design docs, a static prototype, visual review evidence, and an SDTK-CODE handoff.
@@ -60,20 +60,33 @@ sdtk-design screens
 sdtk-design wireframe --screen landing
 sdtk-design system --style minimal-saas
 sdtk-design prototype
+sdtk-design preview
+sdtk-design styles
 sdtk-design review --artifact docs/design/prototype/index.html
 sdtk-design handoff
 sdtk-design status
 ```
 
+`preview` starts a local Preview Studio (browser): it renders the prototype screens, lets you click/shift-click elements to annotate them with a note, and (via the **Tokens** panel) live-preview design-token tweaks on the `:root` CSS variables a screen declares. On "Send to agent" it shows a confirm summary, writes `docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md` (schema `sdtk.design.feedback.v1`), then a copy-ready instruction to apply it. Run the `design-prototype` skill afterward to apply that scoped feedback. The studio serves the prototype read-only, writes only under `docs/design/feedback/`, and never runs the agent itself.
+
+`styles` opens the same studio focused on the **Style Gallery** — a visual menu of the category-oriented style presets (swatches + type sample + summary). Click a card to copy its `start --style <preset>` command. It needs no prototype (pick a style before generating) and is choose-only: it copies a command, it writes nothing.
+
 Visual style presets:
 
 ```text
-minimal-saas
-premium-dashboard
-bold-founder
-warm-editorial
+minimal-saas        SaaS & Productivity
+premium-dashboard   Dashboard & Data
+bold-founder        Marketing & Launch
+warm-editorial      Editorial & Content
+ecommerce-retail    E-Commerce & Retail
+fintech-trust       Fintech & Data
+editorial-content   Editorial & Content
 ```
 
+Presets are category-oriented: pick the one closest to the product you are
+designing (for example `ecommerce-retail` for a storefront). They are
+unbranded SDTK-original style directions, not copies of any third-party brand.
+
 ## Outputs
 
 Human-facing artifacts are written under `docs/design/`, including:
@@ -85,6 +98,7 @@ DESIGN_SYSTEM.md
 DESIGN_HANDOFF.md
 prototype/index.html
 reviews/DESIGN_REVIEW_YYYYMMDD.md
+feedback/DESIGN_FEEDBACK_YYYYMMDDThhmmss.md
 wireframes/
 ```
 

package/package.json

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

package/skills/design-prototype/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: design-prototype
 description: Generate high-fidelity standalone HTML prototypes from an SDTK-DESIGN generation manifest, design system, design tokens, and per-screen briefs.
+sdtk:
+  preview:
+    entry: sdtk-design preview
+  parameters:
+    - { name: --accent, type: color }
+    - { name: --primary, type: color }
+    - { name: --surface, type: color }
+    - { name: --text, type: color }
+    - { name: --radius-card, type: spacing, min: 0, max: 24 }
+    - { name: --space-section, type: spacing, min: 8, max: 96 }
+  capabilities_required: [surgical_edit]
 ---
 
 # Design Prototype
@@ -265,6 +276,17 @@ For each screen with multiple `<nav>` elements, verify before output:
 
 If any check fails, fix the CSS before emitting the HTML file.
 
+## Consume design feedback (BK-275)
+
+Use this when the user asks you to apply Preview Studio feedback (the `sdtk-design preview` annotate→send loop).
+
+1. Read the **newest** `docs/design/feedback/DESIGN_FEEDBACK_*.md` (sort by filename timestamp; the name is `DESIGN_FEEDBACK_<YYYYMMDDThhmmss>.md`). Its front-matter is `schema: sdtk.design.feedback.v1`.
+2. Parse the `<attached-preview-comments>` block. Each numbered entry names a `targetKind` (`element`, `pod`, or `token`), and — for element/pod — a `screen` (with its `file:` path), a `selector`, a `stable-id`, a `position`, and a `comment`. Pod entries list `member.N` sub-targets. **Token entries** instead name a `token` (a CSS custom property such as `--accent`), an `oldValue`, a `newValue`, a `scope: global`, and a `comment`.
+3. **Hard scope — obey it literally.** For `element`/`pod` marks, change ONLY the elements named by selector / stable-id / position, in ONLY the named screen file(s) under `docs/design/prototype/screens/`. Do NOT modify sibling screens, parent layout, global CSS, `DESIGN_SYSTEM.md`, or `DESIGN_TOKENS.json` — even if you notice issues there. Surface any out-of-scope observation as a short note in your reply instead of editing it. If a request cannot be satisfied without touching outside the scope, ask the user first.
+   - **`token` marks are the one deliberate exception** to "do not touch tokens": apply the named `token` change globally to its source of truth — update the value in `docs/design/DESIGN_TOKENS.json` if the token maps to a token field there, and/or the `:root { --token: … }` declaration shared by the screens. Change ONLY the named token(s) to the given `newValue`; do not retune other tokens, palettes, or unmarked screens. If a token has no clear source of truth, ask before editing.
+4. When you (re)write a screen, **stamp `data-sdtk-id="<stable id>"` on the stable structural elements you touch** (headers, cards, sections, nav, primary CTAs). This is best-effort and never required, but it lets future Preview Studio marks re-anchor by id instead of by DOM-path.
+5. After editing, keep each screen a complete standalone `<!doctype html>` document under ~1000 lines, exactly as elsewhere in this skill. Do not delete the feedback file.
+
 ## Boundaries
 
 - Brand, palette, typography, spacing, mood, and component direction come only from `docs/design/DESIGN_SYSTEM.md` and `docs/design/DESIGN_TOKENS.json`.

package/src/commands/help.js

@@ -14,6 +14,8 @@ Usage:
   sdtk-design wireframe --screen landing
   sdtk-design system --style minimal-saas
   sdtk-design prototype
+  sdtk-design preview
+  sdtk-design styles
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
   sdtk-design status
@@ -57,6 +59,8 @@ Command status:
   wireframe             Available.
   system                Available.
   prototype             Available SPEC-driven prototype manifest launcher.
+  preview               Available local Preview Studio (render screens + element-level annotate to feedback).
+  styles                Available visual Style Gallery (browse + copy a "start --style" command).
   handoff               Available.
   review                Available for local markdown and static HTML artifacts.
   start                 Available beginner facade.

package/src/commands/init.js

@@ -7,41 +7,67 @@ const { ValidationError } = require("../lib/errors");
 const {
   assertProjectLocalPath,
   describeDesignPaths,
+  isPathInsideOrEqual,
   resolveProjectPath,
 } = require("../lib/design-paths");
+const {
+  VALID_RUNTIMES,
+  VALID_SCOPES,
+  defaultScope,
+  resolveSkillsDir,
+} = require("../lib/runtime-skills");
 
 const INIT_FLAG_DEFS = {
   help: { type: "boolean" },
   "project-path": { type: "string" },
   force: { type: "boolean" },
   "no-state": { type: "boolean" },
+  runtime: { type: "string" },
+  "runtime-scope": { type: "string" },
+  global: { type: "boolean" },
 };
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 const DESIGN_PROTOTYPE_SKILL_SOURCE = path.join(PACKAGE_ROOT, "skills", "design-prototype");
-const DESIGN_PROTOTYPE_SKILL_TARGETS = [
-  path.join(".claude", "skills", "design-prototype"),
-  path.join(".agents", "skills", "design-prototype"),
-];
 
 function toPosix(value) {
   return String(value || "").replace(/\\/g, "/");
 }
 
+// Report a target either project-relative (when inside the project) or as an
+// absolute posix path (e.g. for user/global skills under the home directory).
+function reportPath(targetPath, projectPath) {
+  if (isPathInsideOrEqual(targetPath, projectPath)) {
+    return toPosix(path.relative(projectPath, targetPath));
+  }
+  return toPosix(targetPath);
+}
+
 function cmdInitHelp() {
   console.log(`SDTK-DESIGN Init
 
 Usage:
-  sdtk-design init [--project-path <path>] [--force] [--no-state]
+  sdtk-design init [--runtime <claude|codex>] [--runtime-scope <project|user>]
+                   [--global] [--project-path <path>] [--force] [--no-state]
 
 Example:
   sdtk-design init
+  sdtk-design init --runtime codex
+  sdtk-design init --runtime claude --global
+
+Runtime:
+  --runtime claude            Install the design-prototype skill under .claude/skills (default).
+  --runtime codex             Install it under .codex/skills (launch Codex with CODEX_HOME).
+  --runtime-scope project     Project-local skills dir (default for claude).
+  --runtime-scope user        User/global skills dir (default for codex).
+  --global                    Shorthand for --runtime-scope user (~/.claude or ~/.codex).
 
 Creates:
   docs/design/
   docs/design/wireframes/
   docs/design/reviews/
   docs/design/README.md
+  <runtime skills dir>/design-prototype/   (e.g. .claude/skills or .codex/skills)
   .sdtk/design/manifest.json unless --no-state is used
 
 Safety:
@@ -139,41 +165,70 @@ function listSkillFiles(sourceDir) {
   return results.sort();
 }
 
-function installDesignPrototypeSkill(projectPath, force, result) {
+// Install the bundled design-prototype skill into a single runtime skills dir
+// (.claude/skills or .codex/skills, per the resolved runtime/scope). For a
+// project-local target the path is guarded inside the project root; for a
+// user/global target (home directory) traversal is guarded against the skills
+// target dir instead, since the destination is intentionally outside the project.
+function installDesignPrototypeSkill(skillsDir, projectPath, force, result) {
   if (!fs.existsSync(DESIGN_PROTOTYPE_SKILL_SOURCE) || !fs.statSync(DESIGN_PROTOTYPE_SKILL_SOURCE).isDirectory()) {
     throw new ValidationError(`Bundled design-prototype skill is missing: ${DESIGN_PROTOTYPE_SKILL_SOURCE}. No project files were changed.`);
   }
 
-  for (const relativeTargetDir of DESIGN_PROTOTYPE_SKILL_TARGETS) {
-    const targetDir = path.join(projectPath, relativeTargetDir);
+  const targetDir = path.join(skillsDir, "design-prototype");
+  if (isPathInsideOrEqual(targetDir, projectPath)) {
     assertProjectLocalPath(targetDir, projectPath, "skill directory");
-    fs.mkdirSync(targetDir, { recursive: true });
-    result.created.push(toPosix(relativeTargetDir) + "/");
-
-    for (const sourceFile of listSkillFiles(DESIGN_PROTOTYPE_SKILL_SOURCE)) {
-      const relativeFile = path.relative(DESIGN_PROTOTYPE_SKILL_SOURCE, sourceFile);
-      const targetFile = path.join(targetDir, relativeFile);
-      assertProjectLocalPath(targetFile, projectPath, "skill file");
-      if (fs.existsSync(targetFile) && !force) {
-        result.skipped.push(toPosix(path.relative(projectPath, targetFile)));
-        continue;
-      }
-      fs.mkdirSync(path.dirname(targetFile), { recursive: true });
-      fs.copyFileSync(sourceFile, targetFile);
-      result.created.push(toPosix(path.relative(projectPath, targetFile)));
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  result.created.push(reportPath(targetDir, projectPath) + "/");
+
+  for (const sourceFile of listSkillFiles(DESIGN_PROTOTYPE_SKILL_SOURCE)) {
+    const relativeFile = path.relative(DESIGN_PROTOTYPE_SKILL_SOURCE, sourceFile);
+    const targetFile = path.join(targetDir, relativeFile);
+    if (!isPathInsideOrEqual(targetFile, targetDir)) {
+      throw new ValidationError(`Refusing to write skill file outside its target directory: ${targetFile}`);
+    }
+    if (fs.existsSync(targetFile) && !force) {
+      result.skipped.push(reportPath(targetFile, projectPath));
+      continue;
     }
+    fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+    fs.copyFileSync(sourceFile, targetFile);
+    result.created.push(reportPath(targetFile, projectPath));
+  }
+}
+
+function resolveRuntimeAndScope({ runtime, runtimeScope, global: globalFlag }) {
+  const resolvedRuntime = runtime || "claude";
+  if (!VALID_RUNTIMES.includes(resolvedRuntime)) {
+    throw new ValidationError(`--runtime must be one of: ${VALID_RUNTIMES.join(", ")}. Got: ${resolvedRuntime}.`);
+  }
+  const resolvedScope = globalFlag ? "user" : (runtimeScope || defaultScope(resolvedRuntime));
+  if (!VALID_SCOPES.includes(resolvedScope)) {
+    throw new ValidationError(`--runtime-scope must be one of: ${VALID_SCOPES.join(", ")}. Got: ${resolvedScope}.`);
   }
+  return { runtime: resolvedRuntime, scope: resolvedScope };
 }
 
-function runDesignInit({ projectPath, force = false, state = true }) {
+function runDesignInit({ projectPath, force = false, state = true, runtime, runtimeScope, global: globalFlag }) {
   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 { runtime: resolvedRuntime, scope: resolvedScope } = resolveRuntimeAndScope({
+    runtime,
+    runtimeScope,
+    global: globalFlag,
+  });
+  const skillsDir = resolveSkillsDir(resolvedRuntime, resolvedScope, resolvedProjectPath);
+
   const paths = describeDesignPaths(resolvedProjectPath);
   const result = {
     projectPath: resolvedProjectPath,
+    runtime: resolvedRuntime,
+    scope: resolvedScope,
+    skillsDir,
     created: [],
     skipped: [],
     stateEnabled: Boolean(state),
@@ -183,7 +238,7 @@ function runDesignInit({ projectPath, force = false, state = true }) {
   ensureDirectory(paths.wireframesPath, resolvedProjectPath, result);
   ensureDirectory(paths.reviewsPath, resolvedProjectPath, result);
   writeManagedFile(paths.designReadmePath, designReadmeContent(), resolvedProjectPath, force, result);
-  installDesignPrototypeSkill(resolvedProjectPath, force, result);
+  installDesignPrototypeSkill(skillsDir, resolvedProjectPath, force, result);
 
   if (state) {
     ensureDirectory(paths.designStatePath, resolvedProjectPath, result);
@@ -201,9 +256,14 @@ function cmdInit(args) {
     projectPath: flags["project-path"],
     force: Boolean(flags.force),
     state: !flags["no-state"],
+    runtime: flags.runtime,
+    runtimeScope: flags["runtime-scope"],
+    global: Boolean(flags.global),
   });
 
   console.log(`[design] Initialized SDTK-DESIGN workspace: ${result.projectPath}`);
+  console.log(`[design] Runtime: ${result.runtime} (scope: ${result.scope})`);
+  console.log(`[design] Skill:   ${path.join(result.skillsDir, "design-prototype")}`);
   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"}`);

package/src/commands/preview.js

@@ -0,0 +1,195 @@
+"use strict";
+
+// BK-275 — `sdtk-design preview`: serve the Preview Studio (rendered prototype
+// screens + element-level annotate→feedback loop) from a local server. Reuses
+// the sdtk-wiki viewer rail pattern; writes nothing except via the studio's
+// /api/feedback endpoint (which lands in docs/design/feedback/).
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const { parseFlags } = require("../lib/args");
+const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
+const { ValidationError } = require("../lib/errors");
+const { DEFAULT_STYLE, styleCatalog } = require("../lib/style-presets");
+const {
+  startDesignServer,
+  findFreePort,
+  waitForServer,
+} = require("../lib/design-server");
+
+const PREVIEW_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  port: { type: "string" },
+  "no-open": { type: "boolean" },
+};
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3210;
+const STUDIO_BOOTSTRAP_MARKER = "/*__SDTK_STUDIO_BOOTSTRAP__*/";
+
+function cmdPreviewHelp() {
+  console.log(`SDTK-DESIGN Preview Studio
+
+Usage:
+  sdtk-design preview [--project-path <path>] [--port <n>] [--no-open]
+
+Example:
+  sdtk-design preview
+  sdtk-design preview --port 3210 --no-open
+
+Reads:
+  docs/design/prototype/.manifest.json (run sdtk-design prototype first)
+  docs/design/prototype/screens/*.html (skill-owned screen HTML)
+
+In the studio:
+  Annotate — click/shift-click elements to mark them with a note.
+  Tokens — live-preview design-token tweaks on the :root CSS variables a screen
+    declares (no file is written); "Add changes to queue" turns them into marks.
+  Send to agent — shows a confirm summary, writes the feedback file, then a
+    copy-ready instruction to apply it (the studio never runs the agent itself).
+
+Creates (only via the in-browser "Send to agent" action):
+  docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md (schema sdtk.design.feedback.v1)
+
+Safety:
+  Local server on 127.0.0.1 only; no external network.
+  Serves the prototype directory read-only; writes only under docs/design/feedback.
+  Never shells out to an agent; token live-preview is in-browser only (no file write).
+  Does not generate or modify screen HTML, the design system, tokens, .sdtk/atlas, or SDTK-WIKI output.
+  In WSL2/Docker, use --no-open and tunnel the printed URL (e.g. cloudflared).`);
+  return 0;
+}
+
+function loadStudioHtml(manifest) {
+  const assetPath = path.join(__dirname, "..", "..", "assets", "design-studio.html");
+  const template = fs.readFileSync(assetPath, "utf-8");
+  // Escape "<" so a screen title containing "</script>" (or "<!--") cannot break
+  // out of the inline <script> the bootstrap is injected into.
+  const json = JSON.stringify({
+    schema: "sdtk.design.feedback.v1",
+    manifest: { screens: (manifest.screens || []).map((s) => ({ screenId: s.screenId, title: s.title || s.screenId, role: s.role || "" })) },
+  }).replace(/</g, "\\u003c");
+  const bootstrap = `window.__SDTK_STUDIO__ = ${json};`;
+  // Use a function replacer so "$" sequences in the JSON are inserted literally
+  // (String.replace honors $& / $` / $' patterns in a string replacement).
+  if (template.includes(STUDIO_BOOTSTRAP_MARKER)) {
+    return template.replace(STUDIO_BOOTSTRAP_MARKER, () => bootstrap);
+  }
+  // Defensive: if the marker is missing, inject before </head> so the studio still boots.
+  return template.replace("</head>", () => `<script>${bootstrap}</script>\n</head>`);
+}
+
+function tryOpenBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch (_) {
+    // Best-effort only; non-fatal (WSL2/Docker has no browser — use the printed URL).
+  }
+}
+
+async function runDesignPreview({ projectPath, port, noOpen = 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 server started.`);
+  }
+  const paths = describeDesignPaths(resolvedProjectPath);
+  if (!fs.existsSync(paths.prototypeManifestPath)) {
+    throw new ValidationError(
+      "Missing docs/design/prototype/.manifest.json. Run sdtk-design prototype first. No server started."
+    );
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(paths.prototypeManifestPath, "utf-8"));
+  } catch (err) {
+    throw new ValidationError(`Could not read prototype manifest: ${err.message}. No server started.`);
+  }
+  const screenCount = Array.isArray(manifest.screens) ? manifest.screens.length : 0;
+
+  const studioHtml = loadStudioHtml(manifest);
+
+  let chosenPort = DEFAULT_PORT;
+  if (port !== undefined && port !== "") {
+    const parsed = Number.parseInt(port, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new ValidationError(`Invalid --port: ${port}. No server started.`);
+    }
+    chosenPort = parsed;
+  } else {
+    chosenPort = await findFreePort(DEFAULT_HOST, DEFAULT_PORT);
+  }
+
+  // The studio reads the design-prototype skill's optional `sdtk:` front-matter
+  // (preview parameters) to filter which token sliders to show. Best-effort:
+  // the kit-bundled SKILL.md if present, else the endpoint returns {}.
+  const skillMetaPath = path.join(
+    __dirname, "..", "..", "skills", "design-prototype", "SKILL.md"
+  );
+
+  const { server, url } = await startDesignServer({
+    host: DEFAULT_HOST,
+    port: chosenPort,
+    projectPath: resolvedProjectPath,
+    studioHtml,
+    skillMetaPath: fs.existsSync(skillMetaPath) ? skillMetaPath : undefined,
+    styles: styleCatalog(),
+    defaultStyle: DEFAULT_STYLE,
+  });
+  await waitForServer(DEFAULT_HOST, chosenPort);
+
+  return { server, url, screenCount, projectPath: resolvedProjectPath, noOpen };
+}
+
+async function cmdPreview(args) {
+  const { flags, positionals } = parseFlags(args || [], PREVIEW_FLAG_DEFS);
+  if (flags.help) return cmdPreviewHelp();
+  if (positionals.length > 0) {
+    throw new ValidationError(
+      `Unsupported preview argument: ${positionals.join(" ")}. Use sdtk-design preview [--project-path <path>] [--port <n>] [--no-open]. No server started.`
+    );
+  }
+
+  const result = await runDesignPreview({
+    projectPath: flags["project-path"],
+    port: flags.port,
+    noOpen: Boolean(flags["no-open"]),
+  });
+
+  console.log(`[design] Preview Studio: ${result.url}`);
+  console.log(`[design] Serving ${result.screenCount} screen(s) from docs/design/prototype/`);
+  console.log("[design] Annotate elements, then \"Send to agent\" writes docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md");
+  console.log("[design] Then run the design-prototype skill to apply the scoped feedback.");
+  if (result.noOpen) {
+    console.log("[design] --no-open: not launching a browser. Open the URL above (tunnel it on WSL2/Docker).");
+  } else {
+    tryOpenBrowser(result.url);
+  }
+  console.log("[design] Press Ctrl+C to stop the preview server.");
+
+  return new Promise((resolve) => {
+    const shutdown = () => {
+      try { result.server.close(); } catch (_) {}
+      resolve(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+}
+
+module.exports = {
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  STUDIO_BOOTSTRAP_MARKER,
+  cmdPreview,
+  cmdPreviewHelp,
+  loadStudioHtml,
+  runDesignPreview,
+  tryOpenBrowser,
+};

package/src/commands/styles.js

@@ -0,0 +1,140 @@
+"use strict";
+
+// BK-277 P-B — `sdtk-design styles`: open the Preview Studio focused on the
+// visual Style Gallery so the user can browse style directions and copy the
+// `start --style <preset>` command BEFORE generating. Unlike `preview`, it does
+// NOT require a prototype manifest (you pick a style first). Read-only / choose-
+// only: it never generates or mutates anything — the gallery just copies a
+// command to the clipboard.
+
+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 { DEFAULT_STYLE, styleCatalog } = require("../lib/style-presets");
+const { startDesignServer, findFreePort, waitForServer } = require("../lib/design-server");
+const { DEFAULT_HOST, DEFAULT_PORT, loadStudioHtml, tryOpenBrowser } = require("./preview");
+
+const STYLES_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  port: { type: "string" },
+  "no-open": { type: "boolean" },
+};
+
+function cmdStylesHelp() {
+  console.log(`SDTK-DESIGN Style Gallery
+
+Usage:
+  sdtk-design styles [--project-path <path>] [--port <n>] [--no-open]
+
+Example:
+  sdtk-design styles
+  sdtk-design styles --no-open
+
+What it does:
+  Opens the Preview Studio focused on the visual Style Gallery. Browse the
+  category-oriented style presets (e.g. ecommerce-retail) as cards — swatches,
+  a type sample, and a summary — and click one to copy its
+  "sdtk-design start --idea ... --style <preset>" command. Does NOT require a
+  prototype; pick a style before you generate.
+
+Reads:
+  Nothing required. If docs/design/prototype/.manifest.json exists, its screens
+  are also previewable; otherwise only the gallery is shown.
+
+Creates:
+  Nothing. The gallery is choose-only — it copies a command, it does not write.
+
+Safety:
+  Local server on 127.0.0.1 only; no external network. Never shells out.
+  In WSL2/Docker, use --no-open and tunnel the printed URL (e.g. cloudflared).`);
+  return 0;
+}
+
+async function runDesignStyles({ projectPath, port, noOpen = 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 server started.`);
+  }
+  const paths = describeDesignPaths(resolvedProjectPath);
+
+  // The gallery works without a prototype; load screens only if a manifest exists.
+  let manifest = { screens: [] };
+  if (fs.existsSync(paths.prototypeManifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(paths.prototypeManifestPath, "utf-8"));
+    } catch (_) {
+      manifest = { screens: [] }; // a malformed manifest must not block the gallery
+    }
+  }
+  const studioHtml = loadStudioHtml(manifest);
+
+  let chosenPort = DEFAULT_PORT;
+  if (port !== undefined && port !== "") {
+    const parsed = Number.parseInt(port, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new ValidationError(`Invalid --port: ${port}. No server started.`);
+    }
+    chosenPort = parsed;
+  } else {
+    chosenPort = await findFreePort(DEFAULT_HOST, DEFAULT_PORT);
+  }
+
+  const skillMetaPath = path.join(__dirname, "..", "..", "skills", "design-prototype", "SKILL.md");
+
+  const { server, url } = await startDesignServer({
+    host: DEFAULT_HOST,
+    port: chosenPort,
+    projectPath: resolvedProjectPath,
+    studioHtml,
+    skillMetaPath: fs.existsSync(skillMetaPath) ? skillMetaPath : undefined,
+    styles: styleCatalog(),
+    defaultStyle: DEFAULT_STYLE,
+  });
+  await waitForServer(DEFAULT_HOST, chosenPort);
+
+  const galleryUrl = `${url}#styles`;
+  return { server, url: galleryUrl, styleCount: styleCatalog().length, projectPath: resolvedProjectPath, noOpen };
+}
+
+async function cmdStyles(args) {
+  const { flags, positionals } = parseFlags(args || [], STYLES_FLAG_DEFS);
+  if (flags.help) return cmdStylesHelp();
+  if (positionals.length > 0) {
+    throw new ValidationError(
+      `Unsupported styles argument: ${positionals.join(" ")}. Use sdtk-design styles [--project-path <path>] [--port <n>] [--no-open]. No server started.`
+    );
+  }
+
+  const result = await runDesignStyles({
+    projectPath: flags["project-path"],
+    port: flags.port,
+    noOpen: Boolean(flags["no-open"]),
+  });
+
+  console.log(`[design] Style Gallery: ${result.url}`);
+  console.log(`[design] ${result.styleCount} style preset(s). Click a card to copy its start command.`);
+  if (result.noOpen) {
+    console.log("[design] --no-open: not launching a browser. Open the URL above (tunnel it on WSL2/Docker).");
+  } else {
+    tryOpenBrowser(result.url);
+  }
+  console.log("[design] Press Ctrl+C to stop the server.");
+
+  return new Promise((resolve) => {
+    const shutdown = () => {
+      try { result.server.close(); } catch (_) {}
+      resolve(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+}
+
+module.exports = {
+  cmdStyles,
+  cmdStylesHelp,
+  runDesignStyles,
+};

package/src/commands/system.js

@@ -118,6 +118,9 @@ function systemContent(briefContent, screenMapContent, style) {
     "- Avoid nested cards and decorative gradient backgrounds.",
     `- Preset density rule: ${preset.density}`,
     "",
+    ...(preset.elevation
+      ? ["## Depth & Elevation", "", `- ${preset.elevation}`, ""]
+      : []),
     "## Table / Dashboard Density",
     "",
     `- ${preset.dashboard}`,
@@ -134,6 +137,9 @@ function systemContent(briefContent, screenMapContent, style) {
     "",
     ...linesForBullets(preset.components),
     "",
+    ...(preset.dosAndDonts && preset.dosAndDonts.length
+      ? ["## Do's and Don'ts", "", ...linesForBullets(preset.dosAndDonts), ""]
+      : []),
     "## Mobile Layout Rules",
     "",
     `- ${preset.mobile}`,