sdtk-design-kit 0.1.2 → 0.2.1

package/src/lib/component-contract.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const fs = require("fs");
+const { describeDesignPaths } = require("./design-paths");
+const { ValidationError } = require("./errors");
+
+const ECOMMERCE_PATTERNS = [
+  "Header and navigation shell",
+  "Category filter sidebar",
+  "Product card grid",
+  "Product detail spec table and gallery area",
+  "Search result list and no-result state",
+  "Cart table and quantity controls",
+  "Checkout stepper and summary card",
+  "Order history list or table",
+  "Order status timeline and detail summary",
+  "Account sidebar and view or edit form",
+  "Configurator wizard shell",
+  "Preview panel",
+  "BOM and material table",
+  "Exclude and recalculate action",
+];
+
+const BASELINE_PATTERNS = [
+  "Header and navigation shell",
+  "Primary content section",
+  "Secondary support panel",
+  "Summary card",
+  "State badge and status chip",
+  "Primary and secondary action row",
+];
+
+function contractTokens(profile, statePayload) {
+  const mappedRefs =
+    statePayload &&
+    statePayload.referenceMap &&
+    typeof statePayload.referenceMap.mappedCount === "number"
+      ? statePayload.referenceMap.mappedCount
+      : 0;
+  return {
+    schema: "sdtk.design.tokens.v1",
+    profile: profile || "generic",
+    color: {
+      surface: "#FFFFFF",
+      surfaceAlt: "#F7F8FA",
+      textPrimary: "#111827",
+      textMuted: "#64748B",
+      border: "#D8E0EA",
+      accentPrimary: profile === "b2b-commerce" ? "#0F766E" : "#2563EB",
+      accentSecondary: profile === "b2b-commerce" ? "#2563EB" : "#0F8A5F",
+    },
+    typography: {
+      fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
+      headingWeight: 800,
+      bodyWeight: 400,
+      uiWeight: 700,
+      letterSpacing: 0,
+    },
+    spacing: {
+      xs: 4,
+      sm: 8,
+      md: 12,
+      lg: 16,
+      xl: 24,
+      sectionGap: 32,
+    },
+    radius: {
+      card: 8,
+      control: 8,
+      chip: 999,
+    },
+    metadata: {
+      generatedFrom: "START_INPUT_STATE",
+      explicitScreenCount: statePayload.screenModel.totalScreens,
+      mappedReferenceCount: mappedRefs,
+    },
+  };
+}
+
+function markdownLibrary(profile, statePayload) {
+  const mappedRefs =
+    statePayload &&
+    statePayload.referenceMap &&
+    typeof statePayload.referenceMap.mappedCount === "number"
+      ? statePayload.referenceMap.mappedCount
+      : 0;
+  const patterns = profile === "b2b-commerce" ? ECOMMERCE_PATTERNS : BASELINE_PATTERNS;
+  return `# Component Pattern Library
+
+## Contract Meta
+- Profile: ${profile || "generic"}
+- Source: .sdtk/design/START_INPUT_STATE.json
+- Explicit screens: ${statePayload.screenModel.totalScreens}
+- Mapped references: ${mappedRefs}
+
+## Core Pattern Set
+${patterns.map((item) => `- ${item}`).join("\n")}
+
+## Usage Rules
+- Keep component usage screen-role driven from explicit screen model.
+- Reuse token contract from docs/design/DESIGN_TOKENS.json.
+- Keep customer specifics project-local; runtime library stays profile-generic.
+
+## Accessibility Baseline
+- Interactive controls should preserve clear focus styling.
+- Keep readable contrast and deterministic heading hierarchy.
+- Keep touch targets at least 44px where practical in prototype guidance.
+`;
+}
+
+function writeComponentContractArtifacts(projectPath, inputContractState) {
+  const paths = describeDesignPaths(projectPath);
+  if (
+    !inputContractState ||
+    inputContractState.analysisStatus !== "INPUT_CONTRACT_READY" ||
+    !inputContractState.screenModel ||
+    !Array.isArray(inputContractState.screenModel.screens) ||
+    inputContractState.screenModel.screens.length === 0
+  ) {
+    throw new ValidationError(
+      "Component and token contract generation requires INPUT_CONTRACT_READY with explicit screens."
+    );
+  }
+  const profile = inputContractState.profileSelection || null;
+  const tokensPayload = contractTokens(profile, inputContractState);
+  const libraryMarkdown = markdownLibrary(profile, inputContractState);
+
+  fs.writeFileSync(paths.componentPatternLibraryPath, `${libraryMarkdown}\n`, "utf-8");
+  fs.writeFileSync(paths.designTokensPath, `${JSON.stringify(tokensPayload, null, 2)}\n`, "utf-8");
+
+  return {
+    componentLibraryRelativePath: "docs/design/COMPONENT_PATTERN_LIBRARY.md",
+    designTokensRelativePath: "docs/design/DESIGN_TOKENS.json",
+    profile: profile || "generic",
+    patternCount: profile === "b2b-commerce" ? ECOMMERCE_PATTERNS.length : BASELINE_PATTERNS.length,
+  };
+}
+
+module.exports = {
+  writeComponentContractArtifacts,
+};
+

package/src/lib/design-input-contract.js

@@ -6,10 +6,46 @@ const { describeDesignPaths, resolveProjectPath } = require("./design-paths");
 const { resolveProfile } = require("./design-profiles");
 const { ValidationError } = require("./errors");
 
+const EVALUATION_REFERENCE_SEGMENTS = ["docs", "ui"];
+const TEMPLATE_ROLES = new Set([
+  "home",
+  "category",
+  "product-detail",
+  "search",
+  "cart",
+  "checkout",
+  "order-history",
+  "order-detail",
+  "account-info",
+  "configurator-bom",
+  "generic",
+]);
+
 function toPosixRelative(basePath, targetPath) {
   return path.relative(basePath, targetPath).split(path.sep).join("/");
 }
 
+function evaluationReferenceLabel() {
+  return EVALUATION_REFERENCE_SEGMENTS.join("/");
+}
+
+function hasEvaluationReferenceSegments(value) {
+  const normalized = path
+    .normalize(String(value || ""))
+    .split(/[\\/]+/)
+    .map((segment) => segment.toLowerCase())
+    .filter(Boolean);
+  for (let index = 0; index < normalized.length - 1; index++) {
+    if (
+      normalized[index] === EVALUATION_REFERENCE_SEGMENTS[0] &&
+      normalized[index + 1] === EVALUATION_REFERENCE_SEGMENTS[1]
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function findArtifactByPattern(rootPath, relativeDir, pattern) {
   const absoluteDir = path.join(rootPath, relativeDir);
   if (!fs.existsSync(absoluteDir) || !fs.statSync(absoluteDir).isDirectory()) {
@@ -35,7 +71,17 @@ function resolveReferenceDirectory(value, projectPath) {
   if (!value) {
     return { provided: false, status: "NOT_PROVIDED", absolutePath: null };
   }
+  if (hasEvaluationReferenceSegments(value)) {
+    throw new ValidationError(
+      `--reference-dir cannot point at ${evaluationReferenceLabel()}; that folder is evaluation-only and not a generation input. No project files were changed.`
+    );
+  }
   const absolutePath = path.resolve(projectPath, value);
+  if (hasEvaluationReferenceSegments(absolutePath)) {
+    throw new ValidationError(
+      `--reference-dir cannot point at ${evaluationReferenceLabel()}; that folder is evaluation-only and not a generation input. No project files were changed.`
+    );
+  }
   if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isDirectory()) {
     throw new ValidationError(`--reference-dir is not a valid directory: ${absolutePath}. No project files were changed.`);
   }
@@ -196,6 +242,180 @@ function toScreenId(value) {
     .replace(/^-+|-+$/g, "");
 }
 
+function compactString(value) {
+  return typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+}
+
+function firstString(raw, fieldNames) {
+  for (const fieldName of fieldNames) {
+    const value = raw && raw[fieldName];
+    const compacted = compactString(value);
+    if (compacted) {
+      return compacted;
+    }
+  }
+  return "";
+}
+
+function normalizeStringList(value) {
+  if (!Array.isArray(value)) {
+    const single = compactString(value);
+    return single ? [single] : [];
+  }
+  return value
+    .map((item) => {
+      if (typeof item === "string") {
+        return compactString(item);
+      }
+      if (item && typeof item === "object") {
+        return compactString(item.title || item.name || item.label || item.id || item.description);
+      }
+      return "";
+    })
+    .filter(Boolean);
+}
+
+function firstStringList(raw, fieldNames) {
+  for (const fieldName of fieldNames) {
+    const values = normalizeStringList(raw && raw[fieldName]);
+    if (values.length > 0) {
+      return values;
+    }
+  }
+  return [];
+}
+
+function normalizeSectionRecord(value, index) {
+  if (typeof value === "string") {
+    const title = compactString(value);
+    return title
+      ? {
+          id: toScreenId(title) || `section-${index + 1}`,
+          title,
+          purpose: null,
+          components: [],
+          states: [],
+          interactions: [],
+          data_slots: [],
+        }
+      : null;
+  }
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const title = firstString(value, ["title", "name", "label", "heading"]);
+  if (!title) {
+    return null;
+  }
+  return {
+    id: toScreenId(firstString(value, ["id", "slug"]) || title) || `section-${index + 1}`,
+    title,
+    purpose: firstString(value, ["purpose", "intent", "description"]) || null,
+    components: firstStringList(value, ["components", "requiredComponents", "required_components"]),
+    states: firstStringList(value, ["states", "requiredStates", "required_states"]),
+    interactions: firstStringList(value, ["interactions", "interactionNotes", "interaction_notes"]),
+    data_slots: firstStringList(value, ["dataSlots", "data_slots", "contentSlots", "content_slots"]),
+  };
+}
+
+function firstSectionList(raw) {
+  const sectionCandidates = [
+    raw && raw.sections,
+    raw && raw.majorSections,
+    raw && raw.major_sections,
+    raw && raw.sectionsTopToBottom,
+    raw && raw.sections_top_to_bottom,
+  ].filter(Array.isArray);
+  for (const candidate of sectionCandidates) {
+    const sections = candidate.map((item, index) => normalizeSectionRecord(item, index)).filter(Boolean);
+    if (sections.length > 0) {
+      return sections;
+    }
+  }
+  return [];
+}
+
+function normalizeVisualTokenUsage(value) {
+  const payload = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return {
+    palette_keys: firstStringList(payload, ["palette_keys", "paletteKeys"]),
+    typography_keys: firstStringList(payload, ["typography_keys", "typographyKeys"]),
+    spacing_keys: firstStringList(payload, ["spacing_keys", "spacingKeys"]),
+    radius_keys: firstStringList(payload, ["radius_keys", "radiusKeys"]),
+  };
+}
+
+function normalizeTemplateRole(value) {
+  const normalized = toScreenId(value);
+  if (!normalized) {
+    return "";
+  }
+  const aliases = {
+    product: "product-detail",
+    pdp: "product-detail",
+    productdetail: "product-detail",
+    orders: "order-history",
+    order: "order-detail",
+    account: "account-info",
+    configurator: "configurator-bom",
+    bom: "configurator-bom",
+    "mode-b-configurator": "configurator-bom",
+  };
+  const role = aliases[normalized] || normalized;
+  return TEMPLATE_ROLES.has(role) ? role : "";
+}
+
+function inferTemplateRole(raw, screenId, title) {
+  const explicit = normalizeTemplateRole(
+    firstString(raw, ["templateRole", "template_role", "screenRole", "screen_role", "role"])
+  );
+  if (explicit) {
+    return explicit;
+  }
+  const combined = toScreenId(`${screenId} ${title}`);
+  const roleMatchers = [
+    ["product-detail", ["product-detail", "productdetail", "pdp"]],
+    ["order-history", ["order-history", "orderhistory", "orders"]],
+    ["order-detail", ["order-detail", "orderdetail"]],
+    ["account-info", ["account-info", "accountinfo", "account"]],
+    ["configurator-bom", ["configurator", "bom", "mode-b"]],
+    ["checkout", ["checkout"]],
+    ["category", ["category", "catalog"]],
+    ["search", ["search"]],
+    ["cart", ["cart"]],
+    ["home", ["home", "landing"]],
+  ];
+  for (const [role, needles] of roleMatchers) {
+    if (needles.some((needle) => combined.includes(needle))) {
+      return role;
+    }
+  }
+  return "generic";
+}
+
+function normalizeSourceEvidence(raw, sourceArtifact) {
+  const payload =
+    raw && raw.sourceEvidence && typeof raw.sourceEvidence === "object"
+      ? raw.sourceEvidence
+      : raw && raw.source_evidence && typeof raw.source_evidence === "object"
+        ? raw.source_evidence
+        : {};
+  return {
+    source_artifact: firstString(payload, ["source_artifact", "sourceArtifact"]) || sourceArtifact || null,
+    source_status: firstString(raw, ["sourceStatus", "source_status"]) || "explicit",
+    source_quote: firstString(raw, ["source_quote", "sourceQuote"]) || firstString(payload, ["source_quote", "sourceQuote"]) || null,
+    source_line_range: Array.isArray(raw && raw.source_line_range)
+      ? raw.source_line_range
+      : Array.isArray(raw && raw.sourceLineRange)
+        ? raw.sourceLineRange
+        : Array.isArray(payload.source_line_range)
+          ? payload.source_line_range
+          : Array.isArray(payload.sourceLineRange)
+            ? payload.sourceLineRange
+            : null,
+  };
+}
+
 function normalizedScreenRecord(raw, sourceArtifact, fallbackTitle) {
   const title = String(
     (raw && (raw.title || raw.name || raw.screen || raw.label || raw.id)) || fallbackTitle || ""
@@ -204,25 +424,54 @@ function normalizedScreenRecord(raw, sourceArtifact, fallbackTitle) {
     return null;
   }
   const screenId = toScreenId((raw && (raw.id || raw.slug)) || title);
-  const route = raw && typeof raw.route === "string" ? raw.route.trim() : "";
-  const purpose = raw && typeof raw.purpose === "string" ? raw.purpose.trim() : "";
-  const primaryAction = raw && typeof raw.primaryAction === "string" ? raw.primaryAction.trim() : "";
-  const majorSections = Array.isArray(raw && raw.majorSections)
-    ? raw.majorSections.map((value) => String(value).trim()).filter(Boolean)
-    : [];
-  const requiredStates = Array.isArray(raw && raw.requiredStates)
-    ? raw.requiredStates.map((value) => String(value).trim()).filter(Boolean)
-    : [];
-  const populatedCount = [route, purpose, primaryAction].filter(Boolean).length + (majorSections.length > 0 ? 1 : 0) + (requiredStates.length > 0 ? 1 : 0);
+  const route = firstString(raw, ["route", "path", "url"]);
+  const purpose = firstString(raw, ["purpose", "screenPurpose", "screen_purpose", "goal"]);
+  const userIntent = firstString(raw, ["userIntent", "user_intent", "intent"]);
+  const primaryAction = firstString(raw, ["primaryAction", "primary_action", "cta"]);
+  const sections = firstSectionList(raw);
+  const majorSections = sections.map((section) => section.title);
+  const layoutModel = firstString(raw, ["layoutModel", "layout_model"]);
+  const density = firstString(raw, ["density", "layoutDensity", "layout_density"]);
+  const requiredComponents = firstStringList(raw, ["components", "requiredComponents", "required_components", "componentRequirements", "component_requirements"]);
+  const requiredStates = firstStringList(raw, ["states", "requiredStates", "required_states"]);
+  const interactions = firstStringList(raw, ["interactions", "interactionNotes", "interaction_notes"]);
+  const dataSlots = firstStringList(raw, ["dataSlots", "data_slots", "contentSlots", "content_slots"]);
+  const accessibilityNotes = firstStringList(raw, ["accessibilityNotes", "accessibility_notes", "a11y"]);
+  const visualTokenUsage = normalizeVisualTokenUsage((raw && (raw.visualTokenUsage || raw.visual_token_usage)) || {});
+  const acceptanceCriteria = firstStringList(raw, ["acceptanceCriteria", "acceptance_criteria", "criteria"]);
+  const templateRole = inferTemplateRole(raw || {}, screenId, title);
+  const sourceEvidence = normalizeSourceEvidence(raw || {}, sourceArtifact);
+  const populatedCount =
+    [route, purpose, userIntent, primaryAction, layoutModel, density].filter(Boolean).length +
+    (sections.length > 0 ? 1 : 0) +
+    (requiredComponents.length > 0 ? 1 : 0) +
+    (requiredStates.length > 0 ? 1 : 0) +
+    (interactions.length > 0 ? 1 : 0) +
+    (dataSlots.length > 0 ? 1 : 0) +
+    (accessibilityNotes.length > 0 ? 1 : 0) +
+    (acceptanceCriteria.length > 0 ? 1 : 0) +
+    (sourceEvidence.source_quote ? 1 : 0);
   const confidence = populatedCount >= 3 ? "high" : populatedCount >= 1 ? "medium" : "low";
   return {
     screenId,
     title,
     route: route || null,
     purpose: purpose || null,
+    userIntent: userIntent || null,
     primaryAction: primaryAction || null,
+    sections,
     majorSections,
+    layoutModel: layoutModel || null,
+    density: density || null,
+    requiredComponents,
     requiredStates,
+    interactions,
+    dataSlots,
+    accessibilityNotes,
+    visualTokenUsage,
+    acceptanceCriteria,
+    templateRole,
+    sourceEvidence,
     sourceArtifact,
     sourceStatus: "explicit",
     confidence,
@@ -405,7 +654,18 @@ function buildInputContractState({
     artifacts: artifactSummary,
     screenModel: {
       totalScreens: screens.length,
-      missingMetadataCount: screens.filter((screen) => !screen.route || !screen.purpose || !screen.primaryAction).length,
+      missingMetadataCount: screens.filter(
+        (screen) =>
+          !screen.route ||
+          !screen.purpose ||
+          !screen.userIntent ||
+          screen.sections.length === 0 ||
+          screen.requiredComponents.length === 0 ||
+          screen.requiredStates.length === 0 ||
+          screen.interactions.length === 0 ||
+          screen.dataSlots.length === 0 ||
+          screen.acceptanceCriteria.length === 0
+      ).length,
       legacyFallbackUsed: false,
       readiness: screens.length > 0 ? "MULTI_SCREEN_READY" : "NEEDS_EXPLICIT_SCREEN_INPUT",
       screens,

package/src/lib/design-paths.js

@@ -6,15 +6,23 @@ const DESIGN_DOCS_RELATIVE = path.join("docs", "design");
 const DESIGN_WIREFRAMES_RELATIVE = path.join("docs", "design", "wireframes");
 const DESIGN_REVIEWS_RELATIVE = path.join("docs", "design", "reviews");
 const DESIGN_PROTOTYPE_RELATIVE = path.join("docs", "design", "prototype");
+const DESIGN_PROTOTYPE_SCREENS_RELATIVE = path.join("docs", "design", "prototype", "screens");
+const DESIGN_PROTOTYPE_ASSETS_RELATIVE = path.join("docs", "design", "prototype", "assets");
+const DESIGN_SCREENS_RELATIVE = path.join("docs", "design", "screens");
 const DESIGN_PROTOTYPE_INDEX_RELATIVE = path.join("docs", "design", "prototype", "index.html");
+const DESIGN_PROTOTYPE_CSS_RELATIVE = path.join("docs", "design", "prototype", "assets", "prototype.css");
+const DESIGN_PROTOTYPE_JS_RELATIVE = path.join("docs", "design", "prototype", "assets", "prototype.js");
 const DESIGN_README_RELATIVE = path.join("docs", "design", "README.md");
 const DESIGN_BRIEF_RELATIVE = path.join("docs", "design", "DESIGN_BRIEF.md");
 const DESIGN_SCREEN_MAP_RELATIVE = path.join("docs", "design", "SCREEN_MAP.md");
 const DESIGN_SYSTEM_RELATIVE = path.join("docs", "design", "DESIGN_SYSTEM.md");
+const DESIGN_COMPONENT_LIBRARY_RELATIVE = path.join("docs", "design", "COMPONENT_PATTERN_LIBRARY.md");
+const DESIGN_TOKENS_RELATIVE = path.join("docs", "design", "DESIGN_TOKENS.json");
 const DESIGN_HANDOFF_RELATIVE = path.join("docs", "design", "DESIGN_HANDOFF.md");
 const DESIGN_STATE_RELATIVE = path.join(".sdtk", "design");
 const DESIGN_MANIFEST_RELATIVE = path.join(".sdtk", "design", "manifest.json");
 const DESIGN_START_INPUT_STATE_RELATIVE = path.join(".sdtk", "design", "START_INPUT_STATE.json");
+const DESIGN_SCREEN_BRIEFS_STATE_RELATIVE = path.join(".sdtk", "design", "screen-briefs");
 
 function resolveProjectPath(projectPath) {
   return path.resolve(projectPath || process.cwd());
@@ -48,31 +56,47 @@ function describeDesignPaths(projectPath) {
     wireframesPath: path.join(root, DESIGN_WIREFRAMES_RELATIVE),
     reviewsPath: path.join(root, DESIGN_REVIEWS_RELATIVE),
     prototypePath: path.join(root, DESIGN_PROTOTYPE_RELATIVE),
+    prototypeScreensPath: path.join(root, DESIGN_PROTOTYPE_SCREENS_RELATIVE),
+    prototypeAssetsPath: path.join(root, DESIGN_PROTOTYPE_ASSETS_RELATIVE),
+    screensPath: path.join(root, DESIGN_SCREENS_RELATIVE),
     prototypeIndexPath: path.join(root, DESIGN_PROTOTYPE_INDEX_RELATIVE),
+    prototypeCssPath: path.join(root, DESIGN_PROTOTYPE_CSS_RELATIVE),
+    prototypeJsPath: path.join(root, DESIGN_PROTOTYPE_JS_RELATIVE),
     designReadmePath: path.join(root, DESIGN_README_RELATIVE),
     designBriefPath: path.join(root, DESIGN_BRIEF_RELATIVE),
     screenMapPath: path.join(root, DESIGN_SCREEN_MAP_RELATIVE),
     designSystemPath: path.join(root, DESIGN_SYSTEM_RELATIVE),
+    componentPatternLibraryPath: path.join(root, DESIGN_COMPONENT_LIBRARY_RELATIVE),
+    designTokensPath: path.join(root, DESIGN_TOKENS_RELATIVE),
     designHandoffPath: path.join(root, DESIGN_HANDOFF_RELATIVE),
     designStatePath: path.join(root, DESIGN_STATE_RELATIVE),
     manifestPath: path.join(root, DESIGN_MANIFEST_RELATIVE),
     designStartInputStatePath: path.join(root, DESIGN_START_INPUT_STATE_RELATIVE),
+    designScreenBriefsStatePath: path.join(root, DESIGN_SCREEN_BRIEFS_STATE_RELATIVE),
   };
 }
 
 module.exports = {
   DESIGN_BRIEF_RELATIVE,
+  DESIGN_COMPONENT_LIBRARY_RELATIVE,
   DESIGN_DOCS_RELATIVE,
   DESIGN_HANDOFF_RELATIVE,
   DESIGN_MANIFEST_RELATIVE,
   DESIGN_PROTOTYPE_INDEX_RELATIVE,
+  DESIGN_PROTOTYPE_ASSETS_RELATIVE,
+  DESIGN_PROTOTYPE_CSS_RELATIVE,
+  DESIGN_PROTOTYPE_JS_RELATIVE,
   DESIGN_PROTOTYPE_RELATIVE,
+  DESIGN_PROTOTYPE_SCREENS_RELATIVE,
+  DESIGN_SCREEN_BRIEFS_STATE_RELATIVE,
+  DESIGN_SCREENS_RELATIVE,
   DESIGN_README_RELATIVE,
   DESIGN_REVIEWS_RELATIVE,
   DESIGN_SCREEN_MAP_RELATIVE,
   DESIGN_START_INPUT_STATE_RELATIVE,
   DESIGN_STATE_RELATIVE,
   DESIGN_SYSTEM_RELATIVE,
+  DESIGN_TOKENS_RELATIVE,
   DESIGN_WIREFRAMES_RELATIVE,
   assertProjectLocalPath,
   describeDesignPaths,

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