sdtk-design-kit 0.2.0 → 0.2.1

package/package.json

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

package/src/commands/prototype.js

@@ -736,11 +736,25 @@ function cmdPrototype(args) {
   console.log(`[design] Style: ${result.style}`);
   console.log(`[design] Mode: ${result.mode} (${result.screenCount} screen(s))`);
   if (result.densityReport) {
-    console.log(
-      `[design] Density: ${result.densityReport.pass ? "PASS" : "FAIL"} total=${result.densityReport.totalBytes}/${result.densityReport.minTotalBytes} bytes`
-    );
-    for (const page of result.densityReport.pages) {
-      console.log(`[design] Density page: ${page.screenId} ${page.byteLength}/${page.minBytes} bytes ${page.pass ? "PASS" : "FAIL"}`);
+    if (result.densityReport.mode === "bytes") {
+      console.log("[design] Density mode: bytes (deprecated rollback; report shape only, no filler emission)");
+      console.log(
+        `[design] Density: ${result.densityReport.pass ? "PASS" : "FAIL"} total=${result.densityReport.totalBytes}/${result.densityReport.minTotalBytes} bytes`
+      );
+      for (const page of result.densityReport.pages) {
+        console.log(`[design] Density page: ${page.screenId} ${page.byteLength}/${page.minBytes} bytes ${page.pass ? "PASS" : "FAIL"}`);
+      }
+    } else {
+      const aggregate = result.densityReport.aggregate || {};
+      console.log(
+        `[design] Density: ${result.densityReport.pass ? "PASS" : "FAIL"} mode=semantic sections=${aggregate.sectionCount || 0} components=${aggregate.componentCount || 0} dataSlots=${aggregate.dataSlotCount || 0} states=${aggregate.stateCount || 0}`
+      );
+      for (const page of result.densityReport.pages) {
+        const missing = Array.isArray(page.findings) && page.findings.length > 0 ? ` (${page.findings.join("; ")})` : "";
+        console.log(
+          `[design] Density page: ${page.screenId} sections=${page.sectionCount} components=${page.componentCount} dataSlots=${page.dataSlotCount} states=${page.stateCount} ${page.pass ? "PASS" : "FAIL"}${missing}`
+        );
+      }
     }
   }
   if (Array.isArray(result.warnings) && result.warnings.length > 0) {
@@ -750,7 +764,7 @@ function cmdPrototype(args) {
   console.log("[design] Prototype mode: static HTML/CSS preview only.");
   console.log("[design] No app code outside docs/design/prototype, server, network, .sdtk/atlas, or SDTK-WIKI output was modified.");
   console.log("[design] Next: sdtk-design review --artifact docs/design/prototype/index.html");
-  return 0;
+  return result.densityReport && result.densityReport.mode !== "bytes" && !result.densityReport.pass ? 1 : 0;
 }
 
 module.exports = {

package/src/commands/review.js

@@ -3,6 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 const { parseFlags } = require("../lib/args");
+const { lintArtifactTree, summarizeLintFindings } = require("../lib/anti-slop-lint");
 const { describeDesignPaths, isPathInsideOrEqual, resolveProjectPath } = require("../lib/design-paths");
 const { ValidationError } = require("../lib/errors");
 
@@ -146,6 +147,36 @@ function combinedPrototypeReviewContent({ artifactPath, artifactContent, paths }
   return parts.join("\n");
 }
 
+function resolveAntiSlopLintMode(env = process.env) {
+  const value = String(env.SDTK_DESIGN_ANTI_SLOP_LINT || "warn").toLowerCase();
+  return value === "on" || value === "off" || value === "warn" ? value : "warn";
+}
+
+function collectPrototypeHtmlMap({ artifactPath, artifactContent, paths }) {
+  const map = new Map();
+  const add = (screenId, html) => {
+    if (!map.has(screenId)) map.set(screenId, html);
+  };
+  add(path.basename(artifactPath, ".html") || "artifact", artifactContent);
+  if (fs.existsSync(paths.prototypeIndexPath)) {
+    add("index", fs.readFileSync(paths.prototypeIndexPath, "utf-8"));
+  }
+  for (const filePath of listPrototypeScreenFiles(paths)) {
+    add(path.basename(filePath, ".html"), fs.readFileSync(filePath, "utf-8"));
+  }
+  return map;
+}
+
+function applyAntiSlopVerdict({ structuralVerdict, lintFindings, lintMode }) {
+  const lintSummary = summarizeLintFindings(lintFindings);
+  const lintBlocking = lintMode === "on" && lintSummary.p0 > 0;
+  return {
+    verdict: lintBlocking ? "FAIL_WITH_RENDERER_SLOP" : structuralVerdict,
+    lintSummary,
+    lintBlocking,
+  };
+}
+
 function evaluateHighFidelityGate({ artifactContent, statePayload, projectPath, paths }) {
   const html = String(artifactContent || "").toLowerCase();
   const screens = statePayload.screenModel.screens || [];
@@ -256,6 +287,17 @@ function fidelityReviewContent(result) {
     "",
     ...(result.blockers.length > 0 ? result.blockers.map((item) => `- ${item}`) : ["- No blocking fidelity gaps found."]),
     "",
+    "## Anti-Slop Lint Findings",
+    "",
+    `- Mode: ${result.lintMode || "warn"}`,
+    `- Summary: P0=${result.lintSummary ? result.lintSummary.p0 : 0}, P1=${result.lintSummary ? result.lintSummary.p1 : 0}, P2=${result.lintSummary ? result.lintSummary.p2 : 0}`,
+    "",
+    "| Severity | ID | Screen | Message | Fix | Snippet |",
+    "|---|---|---|---|---|---|",
+    ...(Array.isArray(result.lintFindings) && result.lintFindings.length > 0
+      ? result.lintFindings.map((item) => `| ${item.severity} | ${item.id} | ${item.screenId || "artifact"} | ${item.message} | ${item.fix} | ${String(item.snippet || "").replace(/\|/g, "/")} |`)
+      : ["| - | - | - | No lint findings. | - | - |"]),
+    "",
     "## Actions",
     "",
     "- Fill missing component markers per failed screen.",
@@ -396,6 +438,7 @@ function runDesignReview({ artifact, projectPath, force = false }) {
 
   let fidelityReportRelativePath = null;
   let fidelityVerdict = null;
+  let antiSlopLint = null;
   if (shouldRunFidelityGate) {
     const fidelityArtifactContent = combinedPrototypeReviewContent({
       artifactPath,
@@ -408,6 +451,19 @@ function runDesignReview({ artifact, projectPath, force = false }) {
       projectPath: resolvedProjectPath,
       paths,
     });
+    const lintMode = resolveAntiSlopLintMode();
+    const lintFindings = lintMode === "off" ? [] : lintArtifactTree(collectPrototypeHtmlMap({ artifactPath, artifactContent, paths }));
+    const lintVerdict = applyAntiSlopVerdict({
+      structuralVerdict: fidelityResult.verdict,
+      lintFindings,
+      lintMode,
+    });
+    fidelityResult.verdict = lintVerdict.verdict;
+    fidelityResult.lintMode = lintMode;
+    fidelityResult.lintFindings = lintFindings;
+    fidelityResult.lintSummary = lintVerdict.lintSummary;
+    fidelityResult.lintBlocking = lintVerdict.lintBlocking;
+    antiSlopLint = { mode: lintMode, findings: lintFindings, summary: lintVerdict.lintSummary, blocking: lintVerdict.lintBlocking };
     const fidelityName = `DESIGN_FIDELITY_REVIEW_${formatDateYYYYMMDD()}.md`;
     const fidelityPath = path.join(paths.reviewsPath, fidelityName);
     if (fs.existsSync(fidelityPath) && !force) {
@@ -423,6 +479,7 @@ function runDesignReview({ artifact, projectPath, force = false }) {
     relativeReportPath: `docs/design/reviews/${reportName}`,
     fidelityReportRelativePath,
     fidelityVerdict,
+    antiSlopLint,
     forced: Boolean(force),
   };
 }
@@ -441,17 +498,27 @@ function cmdReview(args) {
   if (result.fidelityReportRelativePath) {
     console.log(`[design] Wrote ${result.fidelityReportRelativePath}: ${result.projectPath}`);
     console.log(`[design] Fidelity verdict: ${result.fidelityVerdict}`);
+    if (result.antiSlopLint) {
+      if (result.antiSlopLint.mode === "off") {
+        console.log("[design] Anti-slop lint: OFF (deprecated emergency rollback)");
+      } else if (result.antiSlopLint.summary.p0 > 0) {
+        console.log(`[design] Anti-slop lint: ${result.antiSlopLint.summary.p0} P0 findings; see review report`);
+      } else {
+        console.log(`[design] Anti-slop lint: PASS (P1=${result.antiSlopLint.summary.p1}, P2=${result.antiSlopLint.summary.p2})`);
+      }
+    }
   }
   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;
+  return result.antiSlopLint && result.antiSlopLint.blocking ? 1 : 0;
 }
 
 module.exports = {
   cmdReview,
   cmdReviewHelp,
   formatDateYYYYMMDD,
+  resolveAntiSlopLintMode,
   isPrototypeHtmlArtifact,
   reviewContent,
   runDesignReview,

package/src/lib/anti-slop-lint.js

@@ -0,0 +1,210 @@
+"use strict";
+
+function stripHtmlComments(html) {
+  return String(html || "").replace(/<!--[\s\S]*?-->/g, "");
+}
+
+function stripTags(html) {
+  return String(html || "")
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function snippet(value, index = 0, length = 100) {
+  const text = stripTags(value);
+  if (text) return text.slice(0, length);
+  return String(value || "").slice(Math.max(0, index - 30), index + length).replace(/\s+/g, " ").trim();
+}
+
+function finding(severity, id, message, fix, text, screenId) {
+  return { severity, id, message, fix, snippet: snippet(text), ...(screenId ? { screenId } : {}) };
+}
+
+function addRegexFindings(findings, clean, regex, severity, id, message, fix, screenId) {
+  let match;
+  const pattern = new RegExp(regex.source, regex.flags.includes("g") ? regex.flags : `${regex.flags}g`);
+  while ((match = pattern.exec(clean))) {
+    findings.push(finding(severity, id, message, fix, match[0], screenId));
+  }
+}
+
+function articleTexts(clean) {
+  const result = [];
+  const regex = /<article\b[^>]*>([\s\S]*?)<\/article>/gi;
+  let match;
+  while ((match = regex.exec(clean))) {
+    const text = stripTags(match[1]).toLowerCase();
+    if (text) result.push(text);
+  }
+  return result;
+}
+
+function articleBodyTexts(clean) {
+  const result = [];
+  const regex = /<article\b[^>]*>([\s\S]*?)<\/article>/gi;
+  let match;
+  while ((match = regex.exec(clean))) {
+    const bodyOnly = match[1].replace(/<h[1-6]\b[\s\S]*?<\/h[1-6]>/i, "");
+    const text = stripTags(bodyOnly).toLowerCase().replace(/\s+/g, " ").trim();
+    if (text.length >= 20) result.push(text);
+  }
+  return result;
+}
+
+function lintArtifactHtml(html, options = {}) {
+  const screenId = options.screenId;
+  const clean = stripHtmlComments(html);
+  const findings = [];
+
+  addRegexFindings(
+    findings,
+    clean,
+    /\b(line\s*item|product\s*card|material|result\s*item|feature)\s+(one|two|three|[1-9]|\d+)\b|\blorem\s+ipsum\b|\bdolor\s+sit\s+amet\b|\bsample\s+content\b|\bplaceholder\s+text\b/i,
+    "P0",
+    "filler-copy",
+    "Auto-numbered filler copy detected.",
+    "Replace auto-numbered filler with brief-derived data_slot placeholders or grey blocks.",
+    screenId
+  );
+  addRegexFindings(
+    findings,
+    clean,
+    /#[ ]*(6366f1|4f46e5|4338ca|3730a3|8b5cf6|7c3aed|a855f7)\b/i,
+    "P0",
+    "ai-default-indigo",
+    "AI-default indigo/purple hex detected.",
+    "Replace with var(--primary), var(--accent), or an explicit brand token override.",
+    screenId
+  );
+  addRegexFindings(
+    findings,
+    clean,
+    /<h[1-6]\b[^>]*>[^<]*✨[^<]*<\/h[1-6]>|<button\b[^>]*>[^<]*✨[^<]*<\/button>|<a\b[^>]*class="[^"]*\bbtn\b[^"]*"[^>]*>[^<]*✨[^<]*<\/a>/i,
+    "P0",
+    "slop-emoji",
+    "Decorative emoji used in heading, button, CTA, or icon surface.",
+    "Use a 1.6-1.8px stroke monoline SVG with currentColor, or remove the icon.",
+    screenId
+  );
+  addRegexFindings(
+    findings,
+    clean,
+    /<(h[1-6]|button|a\b[^>]*class="[^"]*\bbtn\b[^"]*"|[^>]*class="[^"]*\bicon\b[^"]*")[^>]*>[\s\S]*?(✨|笨ｨ|噫|識|笞｡|櫨|庁)[\s\S]*?<\/\1>/i,
+    "P0",
+    "slop-emoji",
+    "Decorative emoji used in heading, button, CTA, or icon surface.",
+    "Use a 1.6-1.8px stroke monoline SVG with currentColor, or remove the icon.",
+    screenId
+  );
+  addRegexFindings(
+    findings,
+    clean,
+    /\b\d+x\s+(faster|better|easier)\b|\b99\.\d+%\s+uptime\b|\bzero[- ]downtime\b|\b3x\s+more\s+(productive|efficient)\b/i,
+    "P0",
+    "invented-metric",
+    "Unsourced marketing metric detected.",
+    "Pull the metric from a real source or remove the claim.",
+    screenId
+  );
+  addRegexFindings(
+    findings,
+    clean,
+    /class="[^"]*\bdensity-evidence\b[^"]*"/i,
+    "P0",
+    "density-evidence-residue",
+    "Legacy density-evidence filler residue detected.",
+    "Remove filler section emitters from the renderer.",
+    screenId
+  );
+
+  const counts = new Map();
+  for (const text of articleTexts(clean)) counts.set(text, (counts.get(text) || 0) + 1);
+  const fullDuplicates = new Set();
+  for (const [text, count] of counts.entries()) {
+    if (count >= 3) {
+      fullDuplicates.add(text);
+      findings.push(finding("P0", "duplicate-article-text", "Three or more article nodes share identical text.", "Replace duplicated articles with brief-derived data or a single labelled state card.", text, screenId));
+    }
+  }
+  if (fullDuplicates.size === 0) {
+    const bodyCounts = new Map();
+    for (const text of articleBodyTexts(clean)) bodyCounts.set(text, (bodyCounts.get(text) || 0) + 1);
+    for (const [text, count] of bodyCounts.entries()) {
+      if (count >= 3) {
+        findings.push(finding("P1", "near-duplicate-article-body", "Three or more article elements share identical body text while headings differ.", "Pull each article body from a distinct data_slot purpose or remove the repeated paragraph.", text, screenId));
+      }
+    }
+  }
+
+  const accentCount = (clean.match(/var\(--(accent|primary)\)/gi) || []).length;
+  if (accentCount >= 6) {
+    findings.push(finding("P1", "accent-overuse", "Primary/accent token is overused in one page.", "Reduce accent use to primary actions and key state markers.", `accent count ${accentCount}`, screenId));
+  }
+  const withoutRoot = clean.replace(/:root\s*\{[\s\S]*?\}/gi, "");
+  const rawHexCount = (withoutRoot.match(/#[0-9a-fA-F]{3,8}\b/g) || []).length;
+  if (rawHexCount > 12) {
+    findings.push(finding("P1", "raw-hex-outside-root", "Too many raw hex values outside :root.", "Move colors into design tokens or CSS variables.", `raw hex count ${rawHexCount}`, screenId));
+  }
+  if (options.tokens && options.tokens.typography && /serif/i.test(String(options.tokens.typography.displayFamily || ""))) {
+    addRegexFindings(
+      findings,
+      clean,
+      /<h[1-3]\b[^>]*style="[^"]*font-family:\s*(Inter|Roboto|Arial|system-ui|-apple-system)[^"]*"/i,
+      "P1",
+      "display-sans-on-serif-binding",
+      "Heading overrides serif display token with sans font.",
+      "Use the active display typography token for headings.",
+      screenId
+    );
+  }
+  addRegexFindings(
+    findings,
+    clean,
+    /<section\b(?![^>]*(data-section-id|data-slot-id|data-component-id|aria-label|id=))[^>]*>/i,
+    "P2",
+    "missing-data-od-id",
+    "Section is missing a stable target attribute.",
+    "Add data-section-id or an analogous stable target attribute.",
+    screenId
+  );
+  addRegexFindings(
+    findings,
+    clean,
+    /<svg\b(?![^>]*class="[^"]*(icon|semantic)[^"]*")[\s\S]*?<path\b[^>]*d="[^"]*Q[^"]*Q[^"]*"/i,
+    "P2",
+    "decorative-blob-svg",
+    "Decorative blob SVG detected.",
+    "Use semantic icons or remove decorative blob geometry.",
+    screenId
+  );
+  return findings;
+}
+
+function lintArtifactTree(perScreenHtmlMap, options = {}) {
+  const findings = [];
+  for (const [screenId, html] of perScreenHtmlMap.entries()) {
+    findings.push(...lintArtifactHtml(html, { ...options, screenId }));
+  }
+  return findings;
+}
+
+function summarizeLintFindings(findings) {
+  const summary = { p0: 0, p1: 0, p2: 0, blocking: false };
+  for (const item of Array.isArray(findings) ? findings : []) {
+    if (item.severity === "P0") summary.p0 += 1;
+    if (item.severity === "P1") summary.p1 += 1;
+    if (item.severity === "P2") summary.p2 += 1;
+  }
+  summary.blocking = summary.p0 > 0;
+  return summary;
+}
+
+module.exports = {
+  lintArtifactHtml,
+  lintArtifactTree,
+  stripHtmlComments,
+  summarizeLintFindings,
+};

package/src/lib/prototype-briefs.js

@@ -0,0 +1,125 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+function slugify(value, fallback = "item") {
+  const slug = String(value == null ? "" : value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+
+function normalizeSlot(slot, fallbackId) {
+  if (slot && typeof slot === "object") {
+    const id = slugify(slot.id || slot.key || slot.name || slot.label || fallbackId, fallbackId);
+    return {
+      id,
+      label: String(slot.label || slot.name || slot.title || slot.id || id),
+    };
+  }
+  const label = String(slot == null ? fallbackId : slot);
+  return { id: slugify(label, fallbackId), label };
+}
+
+function normalizeComponent(component, fallbackId) {
+  if (component && typeof component === "object") {
+    const id = slugify(component.id || component.type || component.name || component.label || fallbackId, fallbackId);
+    return {
+      id,
+      label: String(component.label || component.name || component.title || component.type || component.id || id),
+    };
+  }
+  const label = String(component == null ? fallbackId : component);
+  return { id: slugify(label, fallbackId), label };
+}
+
+function normalizeSection(section, index) {
+  const source = section && typeof section === "object" ? section : {};
+  const title = source.title || source.name || `Section ${index + 1}`;
+  const id = slugify(source.id || title, `section-${index + 1}`);
+  const slots = source.data_slots || source.dataSlots || [];
+  const components = source.components || [];
+  return {
+    id,
+    title: String(title),
+    purpose: String(source.purpose || source.description || "Brief-defined section."),
+    components: (Array.isArray(components) ? components : []).map((component, componentIndex) =>
+      normalizeComponent(component, `${id}-component-${componentIndex + 1}`)
+    ),
+    states: Array.isArray(source.states) ? source.states.map((state) => String(state)) : [],
+    interactions: Array.isArray(source.interactions) ? source.interactions.map((interaction) => String(interaction)) : [],
+    data_slots: (Array.isArray(slots) ? slots : []).map((slot, slotIndex) => normalizeSlot(slot, `${id}-slot-${slotIndex + 1}`)),
+  };
+}
+
+function normalizeBrief(raw, filePath) {
+  const source = raw && typeof raw === "object" ? raw : {};
+  const screenId = slugify(source.screen_id || source.screenId || source.id || path.basename(filePath || "screen", ".json"), "screen");
+  const sections = Array.isArray(source.sections) ? source.sections.map(normalizeSection) : [];
+  const topLevelSlots = source.data_slots || source.dataSlots || [];
+  const topLevelComponents = source.components || [];
+  return {
+    screen_id: screenId,
+    screen_title: String(source.screen_title || source.screenTitle || source.title || screenId),
+    purpose: String(source.purpose || ""),
+    user_intent: String(source.user_intent || source.userIntent || ""),
+    route: String(source.route || ""),
+    primary_action: String(source.primary_action || source.primaryAction || "Continue"),
+    template_role: source.template_role || source.templateRole || null,
+    sections,
+    components: (Array.isArray(topLevelComponents) ? topLevelComponents : []).map((component, index) =>
+      normalizeComponent(component, `${screenId}-component-${index + 1}`)
+    ),
+    states: Array.isArray(source.states || source.required_states || source.requiredStates)
+      ? (source.states || source.required_states || source.requiredStates).map((state) => String(state))
+      : [],
+    interactions: Array.isArray(source.interactions) ? source.interactions.map((interaction) => String(interaction)) : [],
+    data_slots: (Array.isArray(topLevelSlots) ? topLevelSlots : []).map((slot, index) => normalizeSlot(slot, `${screenId}-slot-${index + 1}`)),
+    acceptance_criteria: Array.isArray(source.acceptance_criteria || source.acceptanceCriteria)
+      ? (source.acceptance_criteria || source.acceptanceCriteria).map((item) => String(item))
+      : [],
+    source_evidence: source.source_evidence || source.sourceEvidence || null,
+    file_path: filePath,
+  };
+}
+
+function loadPrototypeBriefIndex({ paths }) {
+  const briefsByScreenId = new Map();
+  const findings = [];
+  const root = paths && paths.designScreenBriefsStatePath ? paths.designScreenBriefsStatePath : null;
+  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return {
+      briefsByScreenId,
+      findings: [{ code: "BRIEF_DIR_MISSING", message: ".sdtk/design/screen-briefs directory is missing." }],
+    };
+  }
+  for (const filePath of fs.readdirSync(root).filter((name) => name.toLowerCase().endsWith(".json")).sort()) {
+    const absolutePath = path.join(root, filePath);
+    try {
+      const brief = normalizeBrief(JSON.parse(fs.readFileSync(absolutePath, "utf-8")), absolutePath);
+      if (briefsByScreenId.has(brief.screen_id)) {
+        findings.push({ screenId: brief.screen_id, code: "BRIEF_DUPLICATE", message: `Duplicate brief skipped: ${filePath}` });
+      } else {
+        briefsByScreenId.set(brief.screen_id, brief);
+      }
+    } catch (err) {
+      findings.push({ code: "BRIEF_INVALID_JSON", message: `${filePath}: ${err.message}` });
+    }
+  }
+  return { briefsByScreenId, findings };
+}
+
+function briefForScreen({ screen, briefIndex }) {
+  if (!screen || !briefIndex || !briefIndex.briefsByScreenId) return null;
+  return briefIndex.briefsByScreenId.get(slugify(screen.screenId || screen.id || screen.title, "screen")) || null;
+}
+
+module.exports = {
+  briefForScreen,
+  loadPrototypeBriefIndex,
+  normalizeBrief,
+  slugify,
+};