sdtk-design-kit 0.2.0 → 0.3.0

package/src/commands/start.js

@@ -11,7 +11,7 @@ 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 { writeComponentContractArtifacts, loadBrandTokensV2, loadProjectFactsV1 } = require("../lib/component-contract");
 const { ValidationError } = require("../lib/errors");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
@@ -25,6 +25,8 @@ const START_FLAG_DEFS = {
   "design-brief": { type: "string" },
   "reference-dir": { type: "string" },
   profile: { type: "string" },
+  "brand-tokens": { type: "string" },
+  "project-facts": { type: "string" },
 };
 
 const REQUIRED_WIREFRAME_FILES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
@@ -34,12 +36,14 @@ function cmdStartHelp() {
 
 Usage:
   sdtk-design start --idea "<rough MVP idea>" [--style <preset>] [--project-path <path>] [--force]
-  sdtk-design start --from-spec <projectPath> [--design-brief <file>] [--reference-dir <dir>] [--profile <name>] [--project-path <path>]
+  sdtk-design start --from-spec <projectPath> [--design-brief <file>] [--reference-dir <dir>] [--profile <name>] [--brand-tokens <file>] [--project-facts <file>] [--project-path <path>]
 
 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/design/reference-export --profile b2b-commerce
+  sdtk-design start --from-spec . --profile b2b-commerce --brand-tokens ./brand-tokens.json
+  sdtk-design start --from-spec . --profile b2b-industrial-commerce --project-facts ./facts.json
 
   Style presets:
   ${availableStyleNames().join(", ")}
@@ -134,7 +138,12 @@ function runDesignStartFromSpec({
   designBrief,
   referenceDir,
   profile,
+  brandTokensPath,
+  projectFactsPath,
 }) {
+  // BK-223 + BK-229: validate explicit inputs BEFORE any artifact write (fail-closed).
+  if (brandTokensPath) loadBrandTokensV2(brandTokensPath);
+  if (projectFactsPath) loadProjectFactsV1(projectFactsPath);
   const contractState = buildInputContractState({
     fromSpecPath,
     projectPath,
@@ -147,7 +156,10 @@ function runDesignStartFromSpec({
   let componentContract = null;
   if (contractState.analysisStatus === "INPUT_CONTRACT_READY") {
     screenBriefs = writeScreenBriefArtifacts(contractState.projectPath, contractState);
-    componentContract = writeComponentContractArtifacts(contractState.projectPath, contractState);
+    componentContract = writeComponentContractArtifacts(contractState.projectPath, contractState, {
+      brandTokensPath: brandTokensPath || null,
+      projectFactsPath: projectFactsPath || null,
+    });
   }
   return {
     ...contractState,
@@ -162,7 +174,10 @@ function cmdStart(args) {
   const { flags } = parseFlags(args || [], START_FLAG_DEFS);
   if (flags.help) return cmdStartHelp();
 
-  const contractMode = Boolean(flags["from-spec"] || flags["design-brief"] || flags["reference-dir"] || flags.profile);
+  const contractMode = Boolean(
+    flags["from-spec"] || flags["design-brief"] || flags["reference-dir"] ||
+    flags.profile || flags["brand-tokens"] || flags["project-facts"]
+  );
   if (contractMode) {
     const contractResult = runDesignStartFromSpec({
       fromSpecPath: flags["from-spec"],
@@ -170,6 +185,8 @@ function cmdStart(args) {
       designBrief: flags["design-brief"],
       referenceDir: flags["reference-dir"],
       profile: flags.profile,
+      brandTokensPath: flags["brand-tokens"] || null,
+      projectFactsPath: flags["project-facts"] || null,
     });
     if (contractResult.blockers.length > 0) {
       throw new ValidationError(
@@ -216,7 +233,7 @@ function cmdStart(args) {
   console.log(`[design] Style: ${result.style}`);
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
   console.log("[design] No review, handoff, URL, browser, screenshot, vision, network, .sdtk/atlas, or SDTK-WIKI output was used.");
-  console.log("[design] Next: sdtk-design prototype");
+  console.log("[design] Next: sdtk-design handoff");
   return 0;
 }
 

package/src/commands/status.js

@@ -85,13 +85,21 @@ function inspectDesignStatus(projectPath) {
   if (inputContractState && inputContractState.mode === "from-spec") {
     if (Array.isArray(inputContractState.blockers) && inputContractState.blockers.length > 0) {
       nextCommand = "Provide missing explicit SPEC/design artifacts and re-run sdtk-design start --from-spec.";
-    } else {
+    } else if (prototypeMissing) {
       nextCommand = "sdtk-design prototype";
+    } else if (!reviewExists) {
+      nextCommand = "sdtk-design review --artifact docs/design/prototype/index.html";
+    } else if (handoffMissing) {
+      nextCommand = "sdtk-design handoff";
+    } else {
+      nextCommand = "SDTK-CODE can consume docs/design/DESIGN_HANDOFF.md";
     }
   } else if (coreMissing.length > 0) {
     nextCommand = 'sdtk-design start --idea "<idea>"';
+  } else if (prototypeMissing && handoffMissing) {
+    nextCommand = "sdtk-design handoff";
   } else if (prototypeMissing) {
-    nextCommand = "sdtk-design prototype";
+    nextCommand = "Run sdtk-design start --from-spec with explicit design inputs before sdtk-design prototype.";
   } else if (!reviewExists) {
     nextCommand = "sdtk-design review --artifact docs/design/prototype/index.html";
   } else if (handoffMissing) {

package/src/commands/system.js

@@ -18,17 +18,18 @@ function cmdSystemHelp() {
   console.log(`SDTK-DESIGN System
 
 Usage:
-  sdtk-design system [--style <preset>] [--project-path <path>] [--force]
+  sdtk-design system [--project-path <path>] [--force]
 
 Examples:
   sdtk-design system
-  sdtk-design system --style premium-dashboard
+  sdtk-design system --force
 
-Style presets:
-  ${availableStyleNames().join(", ")}
-  Default: ${DEFAULT_STYLE}
+Reads (token-driven path, from-spec flow):
+  docs/design/DESIGN_TOKENS.json  (schema sdtk.design.tokens.v2 from start --from-spec)
+  docs/design/DESIGN_BRIEF.md
+  docs/design/SCREEN_MAP.md
 
-Reads:
+Reads (legacy path, start --idea flow):
   docs/design/DESIGN_BRIEF.md
   docs/design/SCREEN_MAP.md
 
@@ -44,6 +45,7 @@ Safety:
   return 0;
 }
 
+// Legacy preset-driven path (used when DESIGN_TOKENS.json is absent — start --idea flow).
 function includesAny(text, terms) {
   const value = text.toLowerCase();
   return terms.some((term) => value.includes(term));
@@ -53,8 +55,9 @@ function linesForBullets(items) {
   return items.map((item) => `- ${item}`);
 }
 
-function systemContent(briefContent, screenMapContent, style = DEFAULT_STYLE) {
-  const preset = getStylePreset(style);
+function systemContent(briefContent, screenMapContent, style) {
+  const resolvedStyle = style || DEFAULT_STYLE;
+  const preset = getStylePreset(resolvedStyle);
   const source = `${briefContent}\n${screenMapContent}`;
   const isCrm = includesAny(source, ["crm", "lead", "follow-up", "pipeline"]);
   const primaryAction = isCrm ? "Add first lead" : "Start first workflow";
@@ -71,7 +74,7 @@ function systemContent(briefContent, screenMapContent, style = DEFAULT_STYLE) {
     "",
     "## Visual Preset",
     "",
-    `- Preset: ${resolveStyleName(style)} (${preset.label}).`,
+    `- Preset: ${resolveStyleName(resolvedStyle)} (${preset.label}).`,
     `- Direction: ${preset.summary}`,
     "- Presets are compact SDTK-DESIGN guidance adapted from reference patterns, not imported runtime code.",
     "",
@@ -162,6 +165,159 @@ function systemContent(briefContent, screenMapContent, style = DEFAULT_STYLE) {
   ].join("\n");
 }
 
+// Token-driven path (BK-224): 9-section content from DESIGN_TOKENS.json v2.
+function designSystemContentFromTokens({ tokens }) {
+  const { brand, palette, typography, section, component, profile } = tokens;
+  const state = (palette && palette.state) || {};
+  const ramp = (typography && typography.ramp) || {};
+  const fontFamily = (typography && typography.fontFamily) || {};
+  const radius = (component && component.radius) || {};
+  const shadow = (component && component.shadow) || {};
+  const borderWidth = (component && component.borderWidth) || {};
+
+  const stateRow = (stateKey) => {
+    const s = state[stateKey];
+    return s ? `${s.base} / soft: ${s.soft}` : "N/A";
+  };
+
+  const rampRows = Object.entries(ramp).map(
+    ([level, spec]) => `- ${level}: ${spec.fontSize}px / weight ${spec.fontWeight} / line-height ${spec.lineHeight}`
+  );
+
+  return [
+    "# Design System",
+    "",
+    "## Visual Theme & Atmosphere",
+    "",
+    `- Profile: ${profile}`,
+    `- Brand mood: ${brand.mood}`,
+    `- Density: ${brand.density}`,
+    `- Surface: ${palette.surface} (primary background)`,
+    `- Surface alt: ${palette.surfaceAlt} (content areas, alternating rows)`,
+    `- Primary color: ${palette.primary}`,
+    `- Accent color: ${palette.accent}`,
+    "- Favor clarity, scannability, and obvious next actions over decorative marketing composition.",
+    "- No decorative background gradients, glow layers, or unsourced pattern fills.",
+    "",
+    "## Color Palette & Roles",
+    "",
+    `- Primary: ${palette.primary} / hover: ${palette.primaryHover} / soft: ${palette.primarySoft}`,
+    `- Accent: ${palette.accent} / hover: ${palette.accentHover} / soft: ${palette.accentSoft}`,
+    `- Surface: ${palette.surface}`,
+    `- Surface alt: ${palette.surfaceAlt}`,
+    `- Surface inverse: ${palette.surfaceInverse}`,
+    `- Text primary: ${palette.textPrimary}`,
+    `- Text secondary: ${palette.textSecondary}`,
+    `- Text muted: ${palette.textMuted}`,
+    `- Border: ${palette.border}`,
+    `- Border strong: ${palette.borderStrong}`,
+    `- State success: ${stateRow("success")}`,
+    `- State warning: ${stateRow("warning")}`,
+    `- State error: ${stateRow("error")}`,
+    `- State info: ${stateRow("info")}`,
+    "",
+    "## Typography Rules",
+    "",
+    `- Font family display: ${fontFamily.display || "N/A"}`,
+    `- Font family body: ${fontFamily.body || "N/A"}`,
+    `- Font family mono: ${fontFamily.mono || "N/A"}`,
+    ...rampRows,
+    "- Do not scale font size with viewport width.",
+    "- Keep letter spacing at 0 unless explicitly overridden by brand-tokens.",
+    "- One screen-level h1 before any section heading.",
+    "",
+    "## Component Stylings",
+    "",
+    `- Card radius: ${radius.card}px`,
+    `- Control radius: ${radius.control}px`,
+    `- Pill radius: ${radius.pill}px`,
+    `- Border width default: ${borderWidth.default}px solid ${palette.border}`,
+    `- Border width strong: ${borderWidth.strong}px solid ${palette.borderStrong}`,
+    "- Primary button: filled palette.primary, white label, 40px minimum height.",
+    "- Secondary button: palette.surface background, palette.border outline, palette.textPrimary label.",
+    "- Disabled: 45% opacity, no hover elevation.",
+    "- Cards: use only for repeated records or framed tool surfaces; no nested cards.",
+    "",
+    "## Layout Principles",
+    "",
+    `- Container max width: ${section.containerMaxWidth}px`,
+    `- Content max width: ${section.contentMaxWidth}px`,
+    `- Section gap: ${section.sectionGap}px`,
+    `- Hero min height: ${section.heroMinHeight}px`,
+    `- Grid columns: ${section.gridColumns}`,
+    `- Density: ${brand.density}`,
+    "- Navigation: deterministic route and section order from explicit screen model.",
+    "- Keep fixed-format controls stable with explicit min-height and predictable grid tracks.",
+    "",
+    "## Depth & Elevation",
+    "",
+    `- Shadow none: ${shadow.none}`,
+    `- Shadow sm: ${shadow.sm}`,
+    `- Shadow md: ${shadow.md}`,
+    `- Shadow lg: ${shadow.lg}`,
+    "- Use shadow.sm for cards; shadow.md for modals and dialogs.",
+    "- Do not use heavy drop shadows for decorative layering.",
+    "",
+    "## Do's & Don'ts",
+    "",
+    "- Do: use palette token paths (e.g. palette.primary, palette.state.success.base) in component references.",
+    "- Do: use typography.ramp token paths for heading hierarchy.",
+    "- Do: use section token paths for layout rhythm and container widths.",
+    "- Don't: embed raw hex values outside of generated CSS variables.",
+    "- Don't: extract brand colors or copy from requirement text.",
+    "- Don't: add unsupported decorative backgrounds, blurs, or gradient panels.",
+    "- Don't: invent copy, headings, or imagery from requirement text.",
+    "- Don't: use placeholder or TBD content in renderer output.",
+    "",
+    "## Responsive Behavior",
+    "",
+    `- Max layout width: ${section.containerMaxWidth}px; below this, flow to 100%.`,
+    `- Grid: ${section.gridColumns} columns desktop; collapse to 1 column mobile.`,
+    `- Section gap: ${section.sectionGap}px desktop; reduce proportionally at tablet/mobile.`,
+    "- Typography ramp: use ramp values as-is; do not scale with viewport.",
+    "- Navigation: collapse to hamburger or bottom nav at mobile breakpoint.",
+    "- Touch targets: minimum 44px by 44px for interactive controls.",
+    "",
+    "## Renderer Prompt Guide",
+    "",
+    "- Use token key paths in all component references: palette.primary, typography.ramp.h1, section.heroMinHeight, component.radius.card.",
+    "- Enforce one screen-level h1 before any section heading.",
+    "- Use semantic HTML landmarks: header, main, nav, section, footer.",
+    "- Preserve data/state/component markers from the screen brief; do not invent new ones.",
+    "- Avoid placeholder panels; emit NEEDS_* markers for unsourced content.",
+    `- Token reference: palette.primary=${palette.primary}, typography.ramp.h1=${ramp.h1 ? ramp.h1.fontSize + "px/" + ramp.h1.fontWeight : "N/A"}, section.heroMinHeight=${section.heroMinHeight}px, component.radius.card=${radius.card}px.`,
+    "- State tokens: palette.state.success.base for success states, palette.state.error.base for errors.",
+    `- Layout: respect section.containerMaxWidth (${section.containerMaxWidth}px) and section.gridColumns (${section.gridColumns}) from this contract.`,
+    "",
+  ].join("\n");
+}
+
+function loadDesignTokensV2ForSystem(projectPath) {
+  const paths = describeDesignPaths(projectPath);
+  if (!fs.existsSync(paths.designTokensPath)) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(paths.designTokensPath, "utf-8"));
+  } catch (_err) {
+    throw new ValidationError(
+      "docs/design/DESIGN_TOKENS.json is not valid JSON. Re-run sdtk-design start --from-spec to regenerate. No project files were changed."
+    );
+  }
+  if (raw.schema === "sdtk.design.tokens.v1") {
+    throw new ValidationError(
+      "docs/design/DESIGN_TOKENS.json is schema v1. Re-run sdtk-design start --from-spec to upgrade to v2 tokens. No project files were changed."
+    );
+  }
+  if (raw.schema !== "sdtk.design.tokens.v2") {
+    throw new ValidationError(
+      "docs/design/DESIGN_TOKENS.json has an unrecognized schema. Re-run sdtk-design start --from-spec to regenerate. No project files were changed."
+    );
+  }
+  return raw;
+}
+
 function runDesignSystem({ projectPath, force = false, style = DEFAULT_STYLE }) {
   const styleName = resolveStyleName(style);
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
@@ -180,16 +336,29 @@ function runDesignSystem({ projectPath, force = false, style = DEFAULT_STYLE })
     throw new ValidationError("docs/design/DESIGN_SYSTEM.md already exists. Re-run with --force to replace this managed design system.");
   }
 
-  const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
-  const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
+  // Try v2 token-driven path; fall back to legacy preset path when tokens are absent.
+  const tokens = loadDesignTokensV2ForSystem(resolvedProjectPath);
+
+  let content;
+  let tokenDriven = false;
+  if (tokens) {
+    content = designSystemContentFromTokens({ tokens });
+    tokenDriven = true;
+  } else {
+    const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
+    const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
+    content = systemContent(briefContent, screenMapContent, styleName);
+  }
+
   fs.mkdirSync(path.dirname(paths.designSystemPath), { recursive: true });
-  fs.writeFileSync(paths.designSystemPath, systemContent(briefContent, screenMapContent, styleName), "utf-8");
+  fs.writeFileSync(paths.designSystemPath, content, "utf-8");
 
   return {
     projectPath: resolvedProjectPath,
     relativeDesignSystemPath: "docs/design/DESIGN_SYSTEM.md",
     forced: Boolean(force),
-    style: styleName,
+    style: tokenDriven ? null : styleName,
+    tokenDriven,
   };
 }
 
@@ -204,7 +373,9 @@ function cmdSystem(args) {
   });
 
   console.log(`[design] Wrote ${result.relativeDesignSystemPath}: ${result.projectPath}`);
-  console.log(`[design] Style: ${result.style}`);
+  if (!result.tokenDriven && result.style) {
+    console.log(`[design] Style: ${result.style}`);
+  }
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
   console.log("[design] No .sdtk/atlas, SDTK-WIKI output, source files, network, or app code was modified.");
   console.log("[design] Next: sdtk-design handoff");
@@ -216,4 +387,5 @@ module.exports = {
   cmdSystemHelp,
   runDesignSystem,
   systemContent,
+  designSystemContentFromTokens,
 };

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

@@ -0,0 +1,199 @@
+"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
+  );
+  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,
+};