sdtk-design-kit 0.2.0 → 0.3.0

package/src/lib/screen-briefs.js

@@ -43,36 +43,107 @@ function listOrNeeds(values, marker) {
   return `- ${needs(marker)}`;
 }
 
-function tokenUsageOrDefault(value) {
+// BK-227: bounded enum — sections with repeated-slot content render NEEDS_* as <a> skeleton.
+const INTERACTIVE_COMPONENT_PATTERNS = [
+  "product-card", "product-row", "order-row", "order-card",
+  "search-result", "search-row", "result-row",
+  "nav-item", "list-item", "category-card", "catalog-card",
+];
+
+const INTERACTIVE_TEMPLATE_CONTEXTS = {
+  category: ["grid", "products", "items", "list", "catalog"],
+  search: ["results", "items", "matches"],
+  "order-history": ["orders", "list", "rows", "history"],
+  home: ["categories", "featured", "grid", "cards"],
+  "product-detail": ["related", "recommendations"],
+};
+
+// BK-230: normalize identifier for naming-convention-agnostic comparison
+// (matches PascalCase, kebab-case, snake_case, spaced — all collapse to lower-alphanum).
+function normalizeIdentifier(value) {
+  return String(value || "").toLowerCase().replace(/[\s_-]+/g, "");
+}
+
+// BK-230: precompute normalized pattern + keyword sets at module load.
+const INTERACTIVE_COMPONENT_PATTERNS_NORM = INTERACTIVE_COMPONENT_PATTERNS.map(normalizeIdentifier);
+const INTERACTIVE_TEMPLATE_CONTEXTS_NORM = Object.fromEntries(
+  Object.entries(INTERACTIVE_TEMPLATE_CONTEXTS).map(([k, kws]) => [
+    normalizeIdentifier(k),
+    kws.map(normalizeIdentifier),
+  ])
+);
+
+function isInteractiveSection(section, screen) {
+  if (!section || !screen) return false;
+  const components = Array.isArray(section.components)
+    ? section.components.map(normalizeIdentifier)
+    : [];
+  // Rule 1: explicit component pattern match (normalized both sides).
+  for (const pattern of INTERACTIVE_COMPONENT_PATTERNS_NORM) {
+    if (components.some((c) => c.includes(pattern))) return true;
+  }
+  // Rule 2: template_role + section title/components keyword (normalized).
+  const templateRole = normalizeIdentifier(screen.templateRole || screen.template_role || "");
+  const contextKeywords = INTERACTIVE_TEMPLATE_CONTEXTS_NORM[templateRole] || [];
+  if (contextKeywords.length === 0) return false;
+  const title = normalizeIdentifier(section.title || "");
+  for (const kw of contextKeywords) {
+    if (title.includes(kw)) return true;
+    if (components.some((c) => c.includes(kw))) return true;
+  }
+  return false;
+}
+
+function interactiveDataSlotsForSection(section, screen) {
+  if (!isInteractiveSection(section, screen)) return [];
+  return Array.isArray(section.data_slots) ? cleanArray(section.data_slots) : [];
+}
+
+// BK-225: v3 visual_token_usage aligned to BK-223 v2 token schema key paths.
+const TOKEN_USAGE_V3_DEFAULTS = {
+  palette_keys: [
+    "palette.surface", "palette.surfaceAlt", "palette.textPrimary", "palette.textMuted",
+    "palette.primary", "palette.accent", "palette.border",
+    "palette.state.success.base", "palette.state.error.base",
+  ],
+  typography_keys: [
+    "typography.fontFamily.body",
+    "typography.ramp.h1", "typography.ramp.h2", "typography.ramp.h3",
+    "typography.ramp.body", "typography.ramp.caption",
+  ],
+  section_keys: [
+    "section.containerMaxWidth", "section.contentMaxWidth",
+    "section.sectionGap", "section.heroMinHeight", "section.gridColumns",
+  ],
+  component_keys: [
+    "component.radius.card", "component.radius.control",
+    "component.shadow.sm", "component.shadow.md",
+    "component.borderWidth.default",
+  ],
+};
+
+function tokenUsageV3OrDefault(value) {
   const payload = value && typeof value === "object" && !Array.isArray(value) ? value : {};
   const tokenUsage = {
     palette_keys: cleanArray(payload.palette_keys || payload.paletteKeys),
     typography_keys: cleanArray(payload.typography_keys || payload.typographyKeys),
-    spacing_keys: cleanArray(payload.spacing_keys || payload.spacingKeys),
-    radius_keys: cleanArray(payload.radius_keys || payload.radiusKeys),
+    section_keys: cleanArray(payload.section_keys || payload.sectionKeys),
+    component_keys: cleanArray(payload.component_keys || payload.componentKeys),
   };
-  if (
-    tokenUsage.palette_keys.length === 0 &&
-    tokenUsage.typography_keys.length === 0 &&
-    tokenUsage.spacing_keys.length === 0 &&
-    tokenUsage.radius_keys.length === 0
-  ) {
-    return {
-      palette_keys: ["color.surface", "color.textPrimary", "color.accentPrimary"],
-      typography_keys: ["typography.fontFamily", "typography.uiWeight"],
-      spacing_keys: ["spacing.md", "spacing.lg", "spacing.sectionGap"],
-      radius_keys: ["radius.card", "radius.control"],
-    };
-  }
-  return tokenUsage;
+  const hasAny =
+    tokenUsage.palette_keys.length > 0 ||
+    tokenUsage.typography_keys.length > 0 ||
+    tokenUsage.section_keys.length > 0 ||
+    tokenUsage.component_keys.length > 0;
+  return hasAny ? tokenUsage : { ...TOKEN_USAGE_V3_DEFAULTS };
 }
 
 function tokenUsageMarkdown(tokenUsage) {
   return [
     `- Palette keys: ${tokenUsage.palette_keys.length > 0 ? tokenUsage.palette_keys.join(", ") : needs("PALETTE_KEYS")}`,
     `- Typography keys: ${tokenUsage.typography_keys.length > 0 ? tokenUsage.typography_keys.join(", ") : needs("TYPOGRAPHY_KEYS")}`,
-    `- Spacing keys: ${tokenUsage.spacing_keys.length > 0 ? tokenUsage.spacing_keys.join(", ") : needs("SPACING_KEYS")}`,
-    `- Radius keys: ${tokenUsage.radius_keys.length > 0 ? tokenUsage.radius_keys.join(", ") : needs("RADIUS_KEYS")}`,
+    `- Section keys: ${tokenUsage.section_keys.length > 0 ? tokenUsage.section_keys.join(", ") : needs("SECTION_KEYS")}`,
+    `- Component keys: ${tokenUsage.component_keys.length > 0 ? tokenUsage.component_keys.join(", ") : needs("COMPONENT_KEYS")}`,
   ].join("\n");
 }
 
@@ -100,6 +171,90 @@ function densityForRole(templateRole) {
   return null;
 }
 
+// BK-225: derive height_band from section position and role.
+function heightBandForSection(index, total, templateRole) {
+  if (index === 0 && templateRole === "home") return "hero";
+  if (index === 0) return "standard";
+  if (index === total - 1) return "compact";
+  return "standard";
+}
+
+// BK-225: build visual_direction block for a section.
+// Only uses explicit handoff fields from the normalized section record.
+function visualDirectionForSection(section, screen, index) {
+  const totalSections = Array.isArray(screen.sections) ? screen.sections.length : 1;
+  const templateRole = screen.templateRole || "generic";
+
+  // Dimension
+  const heightBand = heightBandForSection(index, totalSections, templateRole);
+  const hasColumns = typeof section.column_count === "number" || typeof section.columnCount === "number";
+  const columnCount = hasColumns ? (section.column_count || section.columnCount) : null;
+  const splitRatio = section.split_ratio || section.splitRatio || null;
+  const dimension = {
+    height_band: heightBand,
+    column_count: columnCount !== null ? columnCount : needs("COLUMN_COUNT"),
+    split_ratio: splitRatio || needs("SPLIT_RATIO"),
+  };
+
+  // Layout intent: derive from explicit layout_model or section components.
+  const hasComponents = Array.isArray(section.components) && section.components.length > 0;
+  const sectionLayoutIntent = section.layout_intent || section.layoutIntent || null;
+  let layoutIntent;
+  if (sectionLayoutIntent) {
+    layoutIntent = sectionLayoutIntent;
+  } else if (hasComponents) {
+    layoutIntent = `Render ${section.components.slice(0, 2).join(" and ")} in section.`;
+  } else {
+    layoutIntent = needs("LAYOUT_INTENT");
+  }
+
+  // Content direction: sourced from explicit handoff fields only.
+  const heading = section.title ? section.title : needs("CONTENT_HEADING");
+  const body = section.purpose ? section.purpose : needs("CONTENT_BODY");
+  const hasDataSlots = Array.isArray(section.data_slots) && section.data_slots.length > 0;
+  const dataDirection = hasDataSlots
+    ? `Map data_slots into scannable rows: ${section.data_slots.slice(0, 3).join(", ")}.`
+    : needs("DATA_DIRECTION");
+  const contentDirection = {
+    heading,
+    body,
+    data_direction: dataDirection,
+  };
+
+  // Imagery: sourced from explicit handoff fields only.
+  const imageryPlacement = section.imagery_placement || section.imageryPlacement || needs("IMAGERY_PLACEMENT");
+  const imagerySubject = section.imagery_subject || section.imagerySubject || needs("IMAGERY_SUBJECT");
+  const imageryAspectRatio = section.imagery_aspect_ratio || section.imageryAspectRatio || "16:9";
+  const imageryTreatment = section.imagery_treatment || section.imageryTreatment || "token-bounded, non-decorative";
+  const imagery = {
+    placement: imageryPlacement,
+    subject: imagerySubject,
+    aspect_ratio: imageryAspectRatio,
+    treatment: imageryTreatment,
+  };
+
+  // Source evidence: screen-level is sufficient when section-specific is unavailable.
+  const screenEvidence = screen.sourceEvidence || {};
+  const sourceStatus = screenEvidence.source_status || "explicit";
+  const sourceQuote = screenEvidence.source_quote || needs("SOURCE_QUOTE");
+  const sourceLineRange = Array.isArray(screenEvidence.source_line_range)
+    ? screenEvidence.source_line_range
+    : [1, 1];
+  const sourceEvidence = {
+    source_status: sourceStatus,
+    source_quote: sourceQuote,
+    source_line_range: sourceLineRange,
+  };
+
+  return {
+    dimension,
+    layout_intent: layoutIntent,
+    content_direction: contentDirection,
+    imagery,
+    source_evidence: sourceEvidence,
+  };
+}
+
 function sectionMarkdown(sections) {
   if (!Array.isArray(sections) || sections.length === 0) {
     return `- ${needs("SECTIONS")}`;
@@ -115,6 +270,10 @@ function sectionMarkdown(sections) {
       if (Array.isArray(section.data_slots) && section.data_slots.length > 0) {
         details.push(`data=${section.data_slots.map(escapeMarkdown).join(", ")}`);
       }
+      // BK-227: surface interactive slot list for renderer skill consumption.
+      if (Array.isArray(section.interactive_data_slots) && section.interactive_data_slots.length > 0) {
+        details.push(`interactive=${section.interactive_data_slots.map(escapeMarkdown).join(", ")}`);
+      }
       if (Array.isArray(section.states) && section.states.length > 0) {
         details.push(`states=${section.states.map(escapeMarkdown).join(", ")}`);
       }
@@ -156,14 +315,23 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
   const dataSlots = uniqueStrings([...(screen.dataSlots || []), ...sectionDataSlots]);
   const sourceEvidence = screen.sourceEvidence || {};
   const supportingArtifacts = cleanArray(sourceArtifacts);
+
+  // BK-225: add visual_direction per section.
+  // BK-227: add interactive_data_slots per section (subset of data_slots for repeated-slot contexts).
+  const sectionsWithVisualDirection = sections.map((section, index) => ({
+    ...section,
+    visual_direction: visualDirectionForSection(section, screen, index),
+    interactive_data_slots: interactiveDataSlotsForSection(section, screen),
+  }));
+
   const model = {
-    schema: "sdtk.design.screen-brief.v2",
+    schema: "sdtk.design.screen-brief.v3",
     screen_id: screen.screenId,
     screen_title: screen.title,
     purpose: screen.purpose || needs("SCREEN_PURPOSE"),
     user_intent: screen.userIntent || needs("USER_INTENT"),
     route: screen.route || needs("ROUTE"),
-    sections,
+    sections: sectionsWithVisualDirection,
     section_titles: sections.map((section) => section.title).filter(Boolean),
     layout_model: screen.layoutModel || layoutModelForRole(templateRole) || needs("LAYOUT_MODEL"),
     density: screen.density || densityForRole(templateRole) || needs("DENSITY"),
@@ -179,7 +347,7 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
             "Expose keyboard focus order for navigation, filters, forms, and primary actions.",
             "Keep contrast and touch target sizing aligned with DESIGN_TOKENS guidance.",
           ],
-    visual_token_usage: tokenUsageOrDefault(screen.visualTokenUsage),
+    visual_token_usage: tokenUsageV3OrDefault(screen.visualTokenUsage),
     acceptance_criteria:
       cleanArray(screen.acceptanceCriteria).length > 0
         ? cleanArray(screen.acceptanceCriteria)
@@ -197,7 +365,8 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
     profile: profileSelection || "generic",
     confidence: screen.confidence || "low",
   };
-  model.gaps = [
+
+  const gapSources = [
     model.purpose,
     model.user_intent,
     model.route,
@@ -209,10 +378,49 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
     ...model.data_slots,
     ...model.acceptance_criteria,
     model.source_evidence.source_quote,
-  ].filter((value) => String(value).startsWith("NEEDS_"));
+  ];
+  // BK-225: include visual_direction NEEDS_* markers in gaps.
+  for (const section of sectionsWithVisualDirection) {
+    const vd = section.visual_direction;
+    if (vd) {
+      if (String(vd.layout_intent).startsWith("NEEDS_")) gapSources.push(vd.layout_intent);
+      if (String(vd.dimension && vd.dimension.column_count).startsWith("NEEDS_")) gapSources.push(String(vd.dimension.column_count));
+      if (String(vd.content_direction && vd.content_direction.heading).startsWith("NEEDS_")) gapSources.push(String(vd.content_direction.heading));
+      if (String(vd.imagery && vd.imagery.subject).startsWith("NEEDS_")) gapSources.push(String(vd.imagery.subject));
+    }
+  }
+  model.gaps = gapSources.filter((value) => String(value).startsWith("NEEDS_"));
   return model;
 }
 
+function renderVisualDirectionMarkdown(sections) {
+  if (!Array.isArray(sections) || sections.length === 0) {
+    return `- ${needs("VISUAL_DIRECTION")}`;
+  }
+  return sections
+    .map((section, index) => {
+      const vd = section.visual_direction;
+      if (!vd) return `- Section ${index + 1}: ${needs("VISUAL_DIRECTION")}`;
+      const title = escapeMarkdown(section.title || `Section ${index + 1}`);
+      const dim = vd.dimension || {};
+      return [
+        `### ${title}`,
+        `- Height band: ${escapeMarkdown(dim.height_band || needs("HEIGHT_BAND"))}`,
+        `- Column count: ${escapeMarkdown(String(dim.column_count || needs("COLUMN_COUNT")))}`,
+        `- Split ratio: ${escapeMarkdown(dim.split_ratio || needs("SPLIT_RATIO"))}`,
+        `- Layout intent: ${escapeMarkdown(vd.layout_intent || needs("LAYOUT_INTENT"))}`,
+        `- Content heading: ${escapeMarkdown((vd.content_direction && vd.content_direction.heading) || needs("CONTENT_HEADING"))}`,
+        `- Content body: ${escapeMarkdown((vd.content_direction && vd.content_direction.body) || needs("CONTENT_BODY"))}`,
+        `- Data direction: ${escapeMarkdown((vd.content_direction && vd.content_direction.data_direction) || needs("DATA_DIRECTION"))}`,
+        `- Imagery placement: ${escapeMarkdown((vd.imagery && vd.imagery.placement) || needs("IMAGERY_PLACEMENT"))}`,
+        `- Imagery subject: ${escapeMarkdown((vd.imagery && vd.imagery.subject) || needs("IMAGERY_SUBJECT"))}`,
+        `- Imagery aspect ratio: ${escapeMarkdown((vd.imagery && vd.imagery.aspect_ratio) || "16:9")}`,
+        `- Imagery treatment: ${escapeMarkdown((vd.imagery && vd.imagery.treatment) || "token-bounded, non-decorative")}`,
+      ].join("\n");
+    })
+    .join("\n\n");
+}
+
 function renderScreenBrief({ screen, profileSelection, profilePrimitives, sourceArtifacts }) {
   const model = buildBriefModel({ screen, profileSelection, profilePrimitives, sourceArtifacts });
 
@@ -254,6 +462,9 @@ ${listOrNeeds(model.data_slots, "DATA_SLOTS")}
 ## Visual Token Usage
 ${tokenUsageMarkdown(model.visual_token_usage)}
 
+## Section Visual Direction
+${renderVisualDirectionMarkdown(model.sections)}
+
 ## Accessibility Notes
 ${listOrNeeds(model.accessibility_notes, "ACCESSIBILITY_NOTES")}
 

package/src/lib/prototype-density.js

@@ -1,147 +0,0 @@
-"use strict";
-
-const MIN_TOTAL_SCREEN_BYTES = 80 * 1024;
-
-const ROLE_FLOORS = {
-  home: { minBytes: 8 * 1024 },
-  category: { minBytes: 6 * 1024 },
-  "product-detail": { minBytes: 6 * 1024 },
-  search: { minBytes: 4 * 1024 },
-  cart: { minBytes: 5 * 1024 },
-  checkout: { minBytes: 5 * 1024 },
-  "order-history": { minBytes: 4 * 1024 },
-  "order-detail": { minBytes: 4 * 1024 },
-  "account-info": { minBytes: 4 * 1024 },
-  "configurator-bom": { minBytes: 15 * 1024 },
-  "mode-b-configurator": { minBytes: 15 * 1024 },
-};
-
-function normalizeScreenRole(screen) {
-  const token = `${screen && screen.screenId ? screen.screenId : ""} ${screen && screen.title ? screen.title : ""} ${screen && screen.template_role ? screen.template_role : ""}`.toLowerCase();
-  if (token.includes("home")) return "home";
-  if (token.includes("category") || token.includes("catalog")) 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") && !token.includes("checkout")) 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("bom") || token.includes("mode-b")) return "configurator-bom";
-  return screen && screen.screenId ? screen.screenId : "generic";
-}
-
-function countMatches(html, pattern) {
-  const matches = String(html || "").match(pattern);
-  return matches ? matches.length : 0;
-}
-
-function countTableColumns(html) {
-  const headerRows = String(html || "").match(/<tr[\s\S]*?<\/tr>/gi) || [];
-  let max = 0;
-  for (const row of headerRows) {
-    max = Math.max(max, countMatches(row, /<t[hd]\b/gi));
-  }
-  return max;
-}
-
-function roleStructureFindings(role, html) {
-  const lower = String(html || "").toLowerCase();
-  const findings = [];
-  const requireText = (text, label) => {
-    if (!lower.includes(text)) findings.push(`missing ${label}`);
-  };
-  const requireCount = (pattern, minimum, label) => {
-    const count = countMatches(html, pattern);
-    if (count < minimum) findings.push(`${label} count ${count} < ${minimum}`);
-  };
-
-  if (role === "home") {
-    requireText("hero", "hero");
-    requireCount(/class="[^"]*(feature-card|category-card|product-card)[^"]*"/gi, 3, "feature/category card");
-  } else if (role === "category") {
-    requireText("filter sidebar", "filter sidebar");
-    requireCount(/class="[^"]*product-card[^"]*"/gi, 6, "product card");
-  } else if (role === "product-detail") {
-    requireCount(/<tr\b/gi, 5, "spec table row");
-    requireText("qty-stepper", "quantity stepper");
-    requireText("add to cart", "add-to-cart");
-  } else if (role === "search") {
-    requireText("search-toolbar", "search toolbar");
-    requireText("result-list", "result list");
-    requireText("no-result", "no-result state");
-  } else if (role === "cart") {
-    requireText("cart-table", "cart table");
-    requireText("summary panel", "summary panel");
-    requireText("checkout", "checkout CTA");
-  } else if (role === "checkout") {
-    requireText("checkout-stepper", "multi-step indicator");
-    requireCount(/<(input|select|textarea)\b/gi, 4, "form field");
-    requireText("summary", "summary");
-  } else if (role === "order-history") {
-    requireCount(/<tr\b|class="[^"]*history-row/gi, 3, "order row");
-  } else if (role === "order-detail") {
-    requireText("timeline", "timeline");
-    requireText("detail summary", "detail summary");
-  } else if (role === "account-info") {
-    requireText("account sidebar", "account sidebar");
-    requireCount(/<(input|select|textarea)\b/gi, 4, "form field");
-  } else if (role === "configurator-bom" || role === "mode-b-configurator") {
-    requireText("configurator wizard", "configurator wizard");
-    requireCount(/class="[^"]*stepper-step[^"]*"/gi, 4, "stepper step");
-    const columns = countTableColumns(html);
-    if (columns < 5) findings.push(`table column count ${columns} < 5`);
-    requireText("preview panel", "preview panel");
-  }
-  return findings;
-}
-
-function assessPrototypePage({ screenId, title, role, relativePath, html }) {
-  const normalizedRole = role || normalizeScreenRole({ screenId, title });
-  const byteLength = Buffer.byteLength(String(html || ""), "utf8");
-  const floor = ROLE_FLOORS[normalizedRole] || { minBytes: 0 };
-  const findings = [];
-  if (byteLength < floor.minBytes) {
-    findings.push(`HTML bytes ${byteLength} < ${floor.minBytes}`);
-  }
-  findings.push(...roleStructureFindings(normalizedRole, html));
-  return {
-    screenId,
-    title,
-    role: normalizedRole,
-    relativePath,
-    byteLength,
-    minBytes: floor.minBytes,
-    pass: findings.length === 0,
-    findings,
-  };
-}
-
-function assessPrototypeDensity(pages) {
-  const pageResults = (Array.isArray(pages) ? pages : []).map(assessPrototypePage);
-  const totalBytes = pageResults.reduce((sum, page) => sum + page.byteLength, 0);
-  const findings = [];
-  if (totalBytes < MIN_TOTAL_SCREEN_BYTES) {
-    findings.push(`Total per-screen HTML bytes ${totalBytes} < ${MIN_TOTAL_SCREEN_BYTES}`);
-  }
-  for (const page of pageResults) {
-    if (!page.pass) {
-      findings.push(`${page.screenId}: ${page.findings.join("; ")}`);
-    }
-  }
-  return {
-    pass: findings.length === 0,
-    totalBytes,
-    minTotalBytes: MIN_TOTAL_SCREEN_BYTES,
-    pages: pageResults,
-    findings,
-  };
-}
-
-module.exports = {
-  MIN_TOTAL_SCREEN_BYTES,
-  ROLE_FLOORS,
-  assessPrototypeDensity,
-  assessPrototypePage,
-  normalizeScreenRole,
-};