sdtk-design-kit 0.1.2 → 0.2.1

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");
 
@@ -75,6 +76,238 @@ function includesAny(content, terms) {
   return terms.some((term) => lower.includes(term.toLowerCase()));
 }
 
+function readInputContractState(paths) {
+  if (!fs.existsSync(paths.designStartInputStatePath) || !fs.statSync(paths.designStartInputStatePath).isFile()) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(paths.designStartInputStatePath, "utf-8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function normalizeScreenRole(screen) {
+  const token = `${screen.screenId || ""} ${screen.title || ""}`.toLowerCase();
+  if (token.includes("home")) return "home";
+  if (token.includes("category")) return "category";
+  if (token.includes("product-detail") || token.includes("product detail") || token.includes("pdp")) return "product-detail";
+  if (token.includes("search")) return "search";
+  if (token.includes("cart")) return "cart";
+  if (token.includes("checkout")) return "checkout";
+  if (token.includes("order-history") || token.includes("order history")) return "order-history";
+  if (token.includes("order-detail") || token.includes("order detail")) return "order-detail";
+  if (token.includes("account")) return "account-info";
+  if (token.includes("configurator") || token.includes("mode-b")) return "mode-b-configurator";
+  return screen.screenId || "screen";
+}
+
+function requiredRoleMarkers(role) {
+  const map = {
+    home: ["hero", "featured products", "configurator"],
+    category: ["filter sidebar", "product grid"],
+    "product-detail": ["spec-table", "add to cart"],
+    search: ["search-toolbar", "no-result"],
+    cart: ["cart-table", "checkout"],
+    checkout: ["checkout-stepper", "summary card"],
+    "order-history": ["order history list"],
+    "order-detail": ["timeline", "detail summary"],
+    "account-info": ["account sidebar", "view or edit form"],
+    "mode-b-configurator": ["configurator wizard", "preview panel", "bom table", "recalculate", "add bom to cart"],
+  };
+  return map[role] || [];
+}
+
+function listPrototypeScreenFiles(paths) {
+  if (!fs.existsSync(paths.prototypeScreensPath) || !fs.statSync(paths.prototypeScreensPath).isDirectory()) {
+    return [];
+  }
+  return fs
+    .readdirSync(paths.prototypeScreensPath)
+    .filter((name) => name.toLowerCase().endsWith(".html"))
+    .sort()
+    .map((name) => path.join(paths.prototypeScreensPath, name));
+}
+
+function combinedPrototypeReviewContent({ artifactPath, artifactContent, paths }) {
+  const screenFiles = listPrototypeScreenFiles(paths);
+  if (screenFiles.length === 0) {
+    return artifactContent;
+  }
+  const parts = [artifactContent];
+  if (path.resolve(artifactPath) !== path.resolve(paths.prototypeIndexPath) && fs.existsSync(paths.prototypeIndexPath)) {
+    parts.push(fs.readFileSync(paths.prototypeIndexPath, "utf-8"));
+  }
+  for (const filePath of screenFiles) {
+    if (path.resolve(filePath) === path.resolve(artifactPath)) {
+      continue;
+    }
+    parts.push(fs.readFileSync(filePath, "utf-8"));
+  }
+  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 || [];
+  const profile = statePayload.profileSelection || "none";
+  const hasTokens = fs.existsSync(paths.designTokensPath);
+  const hasComponentLibrary = fs.existsSync(paths.componentPatternLibraryPath);
+  const hasPre = html.includes("<pre");
+  const hasRawJsonRisk = html.includes("json.stringify") || html.includes("raw json") || html.includes("{\"") || html.includes("not_found");
+  const hasNav = html.includes('aria-label="screen navigation"') || html.includes("screen navigation");
+  const hasStateChips = html.includes('data-chip-type="state"') || html.includes("chip");
+  const sectionRows = [];
+  let missingCount = 0;
+  for (const screen of screens) {
+    const id = String(screen.screenId || "");
+    const title = String(screen.title || id);
+    const role = normalizeScreenRole(screen);
+    const idMarker = `id="screen-${id}"`;
+    const navMarkers = [`href="#screen-${id}"`, `href="screens/${id}.html"`, `href="${id}.html"`];
+    const roleMarkers = requiredRoleMarkers(role);
+    const missing = [];
+    if (!html.includes(idMarker.toLowerCase())) missing.push("missing screen section id");
+    if (!navMarkers.some((marker) => html.includes(marker.toLowerCase()))) missing.push("missing navigation link");
+    for (const marker of roleMarkers) {
+      if (!html.includes(marker)) missing.push(`missing component marker: ${marker}`);
+    }
+    if (missing.length > 0) missingCount += 1;
+    sectionRows.push({
+      title,
+      role,
+      missing,
+      pass: missing.length === 0,
+    });
+  }
+
+  let verdict = "PASS_HIGH_FIDELITY_READY";
+  const blockers = [];
+  if (screens.length === 0) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("explicit screen model is empty");
+  }
+  if (!hasComponentLibrary) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("component pattern library missing");
+  }
+  if (!hasTokens) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("design tokens missing");
+  }
+  if (!hasNav) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("inter-screen navigation contract missing");
+  }
+  if (!hasStateChips) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("state chip coverage missing");
+  }
+  if (missingCount > 0) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push(`${missingCount} screen(s) missing required component markers`);
+  }
+  if (hasPre || hasRawJsonRisk) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("debug/raw JSON UI risk detected");
+  }
+  if (profile === "b2b-commerce" && !html.includes("configurator wizard")) {
+    verdict = "FAIL_WITH_PRODUCT_GAPS";
+    blockers.push("configurator completeness missing");
+  }
+  if (html.includes("main layout</h3>") && html.includes("primary action</h3>")) {
+    verdict = "FAIL_HIGH_FIDELITY_NOT_READY";
+    blockers.push("generic scaffold markers detected (Main layout / Primary action)");
+  }
+  return {
+    verdict,
+    blockers,
+    profile,
+    sectionRows,
+    hasTokens,
+    hasComponentLibrary,
+    hasNav,
+    hasStateChips,
+    hasPre,
+    hasRawJsonRisk,
+    projectPath,
+  };
+}
+
+function fidelityReviewContent(result) {
+  return [
+    "# Design Fidelity Review",
+    "",
+    `- Verdict: ${result.verdict}`,
+    `- Profile: ${result.profile}`,
+    `- Component library: ${result.hasComponentLibrary ? "present" : "missing"}`,
+    `- Design tokens: ${result.hasTokens ? "present" : "missing"}`,
+    `- Navigation contract: ${result.hasNav ? "present" : "missing"}`,
+    `- State coverage markers: ${result.hasStateChips ? "present" : "missing"}`,
+    `- Raw <pre> debug risk: ${result.hasPre ? "detected" : "not detected"}`,
+    `- Raw JSON debug risk: ${result.hasRawJsonRisk ? "detected" : "not detected"}`,
+    "",
+    "## Screen-By-Screen Coverage",
+    "",
+    "| Screen | Role | Result | Actionable notes |",
+    "|---|---|---|---|",
+    ...result.sectionRows.map((row) => `| ${row.title} | ${row.role} | ${row.pass ? "PASS" : "FAIL"} | ${row.pass ? "coverage complete" : row.missing.join("; ")} |`),
+    "",
+    "## Gate Findings",
+    "",
+    ...(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.",
+    "- Ensure design tokens and component pattern library are generated before review.",
+    "- Remove raw debug UI surfaces (`<pre>` and JSON dumps) from customer-facing prototype output.",
+    "- Re-run `sdtk-design prototype` and `sdtk-design review --artifact docs/design/prototype/index.html`.",
+    "",
+  ].join("\n");
+}
+
 function visualPolishChecks({ artifactRelativePath, artifactContent, prototypeHtml }) {
   const lower = String(artifactContent || "").toLowerCase();
   const hasLanding = lower.includes("section-landing") || lower.includes("landing");
@@ -191,12 +424,62 @@ function runDesignReview({ artifact, projectPath, force = false }) {
 
   const artifactContent = fs.readFileSync(artifactPath, "utf-8");
   const artifactRelativePath = toPosix(path.relative(resolvedProjectPath, artifactPath));
+  const statePayload = readInputContractState(paths);
+  const shouldRunFidelityGate =
+    isPrototypeHtmlArtifact(artifactRelativePath, artifactContent) &&
+    statePayload &&
+    statePayload.mode === "from-spec" &&
+    statePayload.analysisStatus === "INPUT_CONTRACT_READY" &&
+    statePayload.screenModel &&
+    Array.isArray(statePayload.screenModel.screens) &&
+    statePayload.screenModel.screens.length >= 4;
   fs.mkdirSync(paths.reviewsPath, { recursive: true });
   fs.writeFileSync(reportPath, reviewContent({ artifactRelativePath, artifactContent }), "utf-8");
 
+  let fidelityReportRelativePath = null;
+  let fidelityVerdict = null;
+  let antiSlopLint = null;
+  if (shouldRunFidelityGate) {
+    const fidelityArtifactContent = combinedPrototypeReviewContent({
+      artifactPath,
+      artifactContent,
+      paths,
+    });
+    const fidelityResult = evaluateHighFidelityGate({
+      artifactContent: fidelityArtifactContent,
+      statePayload,
+      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) {
+      throw new ValidationError(`docs/design/reviews/${fidelityName} already exists. Re-run with --force to replace this managed fidelity review report.`);
+    }
+    fs.writeFileSync(fidelityPath, fidelityReviewContent(fidelityResult), "utf-8");
+    fidelityReportRelativePath = `docs/design/reviews/${fidelityName}`;
+    fidelityVerdict = fidelityResult.verdict;
+  }
+
   return {
     projectPath: resolvedProjectPath,
     relativeReportPath: `docs/design/reviews/${reportName}`,
+    fidelityReportRelativePath,
+    fidelityVerdict,
+    antiSlopLint,
     forced: Boolean(force),
   };
 }
@@ -212,16 +495,30 @@ function cmdReview(args) {
   });
 
   console.log(`[design] Wrote ${result.relativeReportPath}: ${result.projectPath}`);
+  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/commands/start.js

@@ -10,6 +10,8 @@ const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
 const { availableProfileNames } = require("../lib/design-profiles");
 const { buildInputContractState, writeInputContractState } = require("../lib/design-input-contract");
+const { writeScreenBriefArtifacts } = require("../lib/screen-briefs");
+const { writeComponentContractArtifacts } = require("../lib/component-contract");
 const { ValidationError } = require("../lib/errors");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
@@ -37,7 +39,7 @@ Usage:
 Example:
   sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads."
   sdtk-design start --idea "ClientPulse for consultants" --style premium-dashboard
-  sdtk-design start --from-spec . --reference-dir ./docs/ui/claude-design-export --profile b2b-commerce
+  sdtk-design start --from-spec . --reference-dir ./docs/design/reference-export --profile b2b-commerce
 
   Style presets:
   ${availableStyleNames().join(", ")}
@@ -62,6 +64,10 @@ Creates:
     docs/design/DESIGN_SYSTEM.md
   from-spec mode:
     .sdtk/design/START_INPUT_STATE.json
+    docs/design/screens/*_DESIGN_BRIEF.md (when INPUT_CONTRACT_READY)
+    .sdtk/design/screen-briefs/*.json (managed sidecars for deterministic renderer intake)
+    docs/design/COMPONENT_PATTERN_LIBRARY.md (when INPUT_CONTRACT_READY)
+    docs/design/DESIGN_TOKENS.json (when INPUT_CONTRACT_READY)
 
 Safety:
   Local files only.
@@ -137,10 +143,18 @@ function runDesignStartFromSpec({
     profile,
   });
   const statePath = writeInputContractState(contractState.projectPath, contractState);
+  let screenBriefs = null;
+  let componentContract = null;
+  if (contractState.analysisStatus === "INPUT_CONTRACT_READY") {
+    screenBriefs = writeScreenBriefArtifacts(contractState.projectPath, contractState);
+    componentContract = writeComponentContractArtifacts(contractState.projectPath, contractState);
+  }
   return {
     ...contractState,
     statePath,
     stateRelativePath: ".sdtk/design/START_INPUT_STATE.json",
+    screenBriefs,
+    componentContract,
   };
 }
 
@@ -165,6 +179,14 @@ function cmdStart(args) {
     console.log(`[design] Started SDTK-DESIGN package: ${contractResult.projectPath}`);
     console.log(`[design] Mode: from-spec`);
     console.log(`[design] Wrote ${contractResult.stateRelativePath}`);
+    if (contractResult.screenBriefs) {
+      console.log(`[design] Wrote per-screen briefs: ${contractResult.screenBriefs.generatedCount} artifact(s)`);
+    }
+    if (contractResult.componentContract) {
+      console.log(
+        `[design] Wrote component/token contract: ${contractResult.componentContract.componentLibraryRelativePath}, ${contractResult.componentContract.designTokensRelativePath}`
+      );
+    }
     console.log(`[design] Screen model: ${contractResult.screenModel.totalScreens} explicit screen(s), readiness=${contractResult.screenModel.readiness}`);
     if (contractResult.referenceDirectory && contractResult.referenceDirectory.provided) {
       console.log(

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,
+};