sdtk-design-kit 0.2.1 → 0.3.0

package/src/lib/component-contract.js

@@ -30,53 +30,300 @@ const BASELINE_PATTERNS = [
   "Primary and secondary action row",
 ];
 
-function contractTokens(profile, statePayload) {
+const TYPOGRAPHY_RAMP_V2 = {
+  display: { fontSize: 48, fontWeight: 800, lineHeight: 1.05, letterSpacing: 0 },
+  h1: { fontSize: 40, fontWeight: 800, lineHeight: 1.1, letterSpacing: 0 },
+  h2: { fontSize: 32, fontWeight: 750, lineHeight: 1.15, letterSpacing: 0 },
+  h3: { fontSize: 24, fontWeight: 700, lineHeight: 1.2, letterSpacing: 0 },
+  h4: { fontSize: 20, fontWeight: 700, lineHeight: 1.25, letterSpacing: 0 },
+  h5: { fontSize: 18, fontWeight: 700, lineHeight: 1.3, letterSpacing: 0 },
+  h6: { fontSize: 16, fontWeight: 700, lineHeight: 1.35, letterSpacing: 0 },
+  bodyLg: { fontSize: 18, fontWeight: 400, lineHeight: 1.55, letterSpacing: 0 },
+  body: { fontSize: 16, fontWeight: 400, lineHeight: 1.55, letterSpacing: 0 },
+  bodySm: { fontSize: 14, fontWeight: 400, lineHeight: 1.5, letterSpacing: 0 },
+  caption: { fontSize: 12, fontWeight: 600, lineHeight: 1.4, letterSpacing: 0 },
+};
+
+const FONT_FAMILY_V2 = {
+  display: "Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
+  body: "Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
+  mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+};
+
+const SECTION_TOKENS_V2 = {
+  containerMaxWidth: 1180,
+  contentMaxWidth: 760,
+  sectionGap: 40,
+  heroMinHeight: 520,
+  gridColumns: 12,
+};
+
+const COMPONENT_TOKENS_V2 = {
+  radius: { card: 8, control: 8, pill: 999 },
+  shadow: {
+    none: "none",
+    sm: "0 1px 2px rgba(15, 23, 42, 0.08)",
+    md: "0 8px 24px rgba(15, 23, 42, 0.10)",
+    lg: "0 18px 45px rgba(15, 23, 42, 0.12)",
+  },
+  borderWidth: { hairline: 1, default: 1, strong: 2 },
+};
+
+const STATE_TOKENS_V2 = {
+  success: { base: "#15803D", soft: "#DCFCE7", text: "#166534" },
+  warning: { base: "#B45309", soft: "#FEF3C7", text: "#92400E" },
+  error: { base: "#B91C1C", soft: "#FEE2E2", text: "#991B1B" },
+  info: { base: "#2563EB", soft: "#DBEAFE", text: "#1E40AF" },
+};
+
+const PROFILE_PALETTE_DEFAULTS = {
+  "b2b-commerce": {
+    primary: "#0F766E", primaryHover: "#115E59", primarySoft: "#CCFBF1",
+    accent: "#2563EB", accentHover: "#1D4ED8", accentSoft: "#DBEAFE",
+    surface: "#FFFFFF", surfaceAlt: "#F7F8FA", surfaceInverse: "#111827",
+    textPrimary: "#111827", textSecondary: "#334155", textMuted: "#64748B",
+    border: "#D8E0EA", borderStrong: "#94A3B8",
+    state: STATE_TOKENS_V2,
+  },
+  "b2b-industrial-commerce": {
+    primary: "#0F766E", primaryHover: "#115E59", primarySoft: "#CCFBF1",
+    accent: "#2563EB", accentHover: "#1D4ED8", accentSoft: "#DBEAFE",
+    surface: "#FFFFFF", surfaceAlt: "#F7F8FA", surfaceInverse: "#111827",
+    textPrimary: "#111827", textSecondary: "#334155", textMuted: "#64748B",
+    border: "#D8E0EA", borderStrong: "#94A3B8",
+    state: STATE_TOKENS_V2,
+  },
+  generic: {
+    primary: "#2563EB", primaryHover: "#1D4ED8", primarySoft: "#DBEAFE",
+    accent: "#0F766E", accentHover: "#115E59", accentSoft: "#CCFBF1",
+    surface: "#FFFFFF", surfaceAlt: "#F7F8FA", surfaceInverse: "#111827",
+    textPrimary: "#111827", textSecondary: "#334155", textMuted: "#64748B",
+    border: "#D8E0EA", borderStrong: "#94A3B8",
+    state: STATE_TOKENS_V2,
+  },
+};
+
+const PROFILE_BRAND_DEFAULTS = {
+  "b2b-commerce": { mood: "professional-b2b", density: "balanced" },
+  "b2b-industrial-commerce": { mood: "industrial-b2b", density: "balanced" },
+  generic: { mood: "general-purpose", density: "balanced" },
+};
+
+const HEX_COLOR_RE = /^#[0-9A-Fa-f]{6}$/;
+const BRAND_OVERRIDE_HEX_KEYS = [
+  "primary", "primaryHover", "primarySoft",
+  "accent", "accentHover", "accentSoft",
+  "surface", "surfaceAlt", "surfaceInverse",
+  "textPrimary", "textSecondary", "textMuted",
+  "border", "borderStrong",
+];
+const VALID_DENSITIES = ["compact", "balanced", "spacious"];
+
+function isValidHex(value) {
+  return typeof value === "string" && HEX_COLOR_RE.test(value);
+}
+
+function validateBrandOverride(override, filePath) {
+  const ctx = filePath ? ` in ${filePath}` : "";
+  if (!override || typeof override !== "object" || Array.isArray(override)) {
+    throw new ValidationError(`--brand-tokens must be a JSON object${ctx}. No project files were changed.`);
+  }
+  if (override.palette !== undefined) {
+    if (typeof override.palette !== "object" || Array.isArray(override.palette)) {
+      throw new ValidationError(`--brand-tokens palette must be an object${ctx}. No project files were changed.`);
+    }
+    for (const key of BRAND_OVERRIDE_HEX_KEYS) {
+      if (key in override.palette && !isValidHex(override.palette[key])) {
+        throw new ValidationError(
+          `--brand-tokens palette.${key} must be a valid 6-digit hex color (e.g. "#0F766E")${ctx}. No project files were changed.`
+        );
+      }
+    }
+  }
+  if (override.fontFamily !== undefined && (typeof override.fontFamily !== "object" || Array.isArray(override.fontFamily))) {
+    throw new ValidationError(`--brand-tokens fontFamily must be an object${ctx}. No project files were changed.`);
+  }
+  if (override.mood !== undefined && (typeof override.mood !== "string" || !override.mood.trim())) {
+    throw new ValidationError(`--brand-tokens mood must be a non-empty string${ctx}. No project files were changed.`);
+  }
+  if (override.density !== undefined && !VALID_DENSITIES.includes(override.density)) {
+    throw new ValidationError(
+      `--brand-tokens density must be one of: ${VALID_DENSITIES.join(", ")}${ctx}. No project files were changed.`
+    );
+  }
+}
+
+function loadBrandTokensV2(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new ValidationError(`--brand-tokens file not found: ${filePath}. No project files were changed.`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (_err) {
+    throw new ValidationError(`--brand-tokens file is not valid JSON: ${filePath}. No project files were changed.`);
+  }
+  validateBrandOverride(raw, filePath);
+  return raw;
+}
+
+// BK-229: project-facts validation + loader (factual content provenance, governance-safe).
+const PROJECT_FACTS_STRING_KEYS = ["name", "company"];
+const PROJECT_FACTS_URL_KEYS = ["contactUrl", "privacyUrl", "termsUrl"];
+const PROJECT_FACTS_ALLOWED_TOP_KEYS = new Set([
+  ...PROJECT_FACTS_STRING_KEYS,
+  ...PROJECT_FACTS_URL_KEYS,
+  "categories",
+]);
+const PROJECT_FACTS_URL_RE = /^https?:\/\//i;
+const PROJECT_FACTS_CATEGORY_KEY_RE = /^[a-z0-9-]+$/;
+
+function validateProjectFacts(facts, filePath) {
+  const ctx = filePath ? ` in ${filePath}` : "";
+  if (!facts || typeof facts !== "object" || Array.isArray(facts)) {
+    throw new ValidationError(`--project-facts must be a JSON object${ctx}. No project files were changed.`);
+  }
+  for (const k of Object.keys(facts)) {
+    if (!PROJECT_FACTS_ALLOWED_TOP_KEYS.has(k)) {
+      throw new ValidationError(
+        `--project-facts contains unknown top-level field "${k}"${ctx}. Allowed: ${Array.from(PROJECT_FACTS_ALLOWED_TOP_KEYS).join(", ")}. No project files were changed.`
+      );
+    }
+  }
+  for (const k of PROJECT_FACTS_STRING_KEYS) {
+    if (facts[k] !== undefined) {
+      if (typeof facts[k] !== "string" || !facts[k].trim() || facts[k].length > 200) {
+        throw new ValidationError(
+          `--project-facts ${k} must be a non-empty string <=200 chars${ctx}. No project files were changed.`
+        );
+      }
+    }
+  }
+  for (const k of PROJECT_FACTS_URL_KEYS) {
+    if (facts[k] !== undefined) {
+      if (typeof facts[k] !== "string" || !PROJECT_FACTS_URL_RE.test(facts[k]) || facts[k].length > 500) {
+        throw new ValidationError(
+          `--project-facts ${k} must be a string starting with http(s):// and <=500 chars${ctx}. No project files were changed.`
+        );
+      }
+    }
+  }
+  if (facts.categories !== undefined) {
+    if (!Array.isArray(facts.categories) || facts.categories.length > 50) {
+      throw new ValidationError(
+        `--project-facts categories must be an array of <=50 items${ctx}. No project files were changed.`
+      );
+    }
+    for (let i = 0; i < facts.categories.length; i++) {
+      const c = facts.categories[i];
+      if (!c || typeof c !== "object" || Array.isArray(c)) {
+        throw new ValidationError(`--project-facts categories[${i}] must be an object${ctx}. No project files were changed.`);
+      }
+      if (typeof c.key !== "string" || !PROJECT_FACTS_CATEGORY_KEY_RE.test(c.key)) {
+        throw new ValidationError(
+          `--project-facts categories[${i}].key must match ^[a-z0-9-]+$${ctx}. No project files were changed.`
+        );
+      }
+      if (typeof c.label !== "string" || !c.label.trim() || c.label.length > 200) {
+        throw new ValidationError(
+          `--project-facts categories[${i}].label must be a non-empty string <=200 chars${ctx}. No project files were changed.`
+        );
+      }
+      for (const ck of Object.keys(c)) {
+        if (ck !== "key" && ck !== "label") {
+          throw new ValidationError(
+            `--project-facts categories[${i}] contains unknown field "${ck}"${ctx}. Allowed: key, label. No project files were changed.`
+          );
+        }
+      }
+    }
+  }
+}
+
+function loadProjectFactsV1(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new ValidationError(`--project-facts file not found: ${filePath}. No project files were changed.`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (_err) {
+    throw new ValidationError(`--project-facts file is not valid JSON: ${filePath}. No project files were changed.`);
+  }
+  validateProjectFacts(raw, filePath);
+  return raw;
+}
+
+function profileDefaultTokensV2(profile, statePayload, brandOverride, brandTokensPath, projectFacts, projectFactsPath) {
+  const resolvedProfile = profile && PROFILE_PALETTE_DEFAULTS[profile] ? profile : "generic";
+  const paletteBase = PROFILE_PALETTE_DEFAULTS[resolvedProfile];
+  const brandBase = PROFILE_BRAND_DEFAULTS[resolvedProfile];
   const mappedRefs =
     statePayload &&
     statePayload.referenceMap &&
     typeof statePayload.referenceMap.mappedCount === "number"
       ? statePayload.referenceMap.mappedCount
       : 0;
+
+  const overridePalette = brandOverride && brandOverride.palette ? brandOverride.palette : {};
+  const overrideFontFamily = brandOverride && brandOverride.fontFamily ? brandOverride.fontFamily : {};
+  const overrideMood = brandOverride && typeof brandOverride.mood === "string" ? brandOverride.mood : null;
+  const overrideDensity = brandOverride && VALID_DENSITIES.includes(brandOverride.density) ? brandOverride.density : null;
+
+  // Merge palette flat keys; state tokens always come from profile default.
+  const palette = { ...paletteBase, ...overridePalette, state: paletteBase.state };
+  const fontFamily = { ...FONT_FAMILY_V2, ...overrideFontFamily };
+
+  // BK-229: brand.source value matrix.
+  const hasFacts = !!(projectFacts && Object.keys(projectFacts).length > 0);
+  const hasBrandOverride = !!brandOverride;
+  let brandSource = "profile-default";
+  if (hasFacts && hasBrandOverride) brandSource = "project-facts+brand-tokens";
+  else if (hasFacts) brandSource = "project-facts";
+  else if (hasBrandOverride) brandSource = "brand-tokens";
+  const facts = projectFacts || {};
+
   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",
+    schema: "sdtk.design.tokens.v2",
+    version: 2,
+    profile: resolvedProfile,
+    brand: {
+      source: brandSource,
+      name: typeof facts.name === "string" ? facts.name : null,
+      company: typeof facts.company === "string" ? facts.company : null,
+      contactUrl: typeof facts.contactUrl === "string" ? facts.contactUrl : null,
+      privacyUrl: typeof facts.privacyUrl === "string" ? facts.privacyUrl : null,
+      termsUrl: typeof facts.termsUrl === "string" ? facts.termsUrl : null,
+      categories: Array.isArray(facts.categories) ? facts.categories : [],
+      mood: overrideMood || brandBase.mood,
+      density: overrideDensity || brandBase.density,
     },
+    palette,
     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,
+      fontFamily,
+      ramp: TYPOGRAPHY_RAMP_V2,
     },
+    section: SECTION_TOKENS_V2,
+    component: COMPONENT_TOKENS_V2,
     metadata: {
       generatedFrom: "START_INPUT_STATE",
       explicitScreenCount: statePayload.screenModel.totalScreens,
       mappedReferenceCount: mappedRefs,
+      brandTokensPath: brandTokensPath || null,
+      projectFactsPath: projectFactsPath || null,
+      sourcePolicy: "profile-default-or-explicit-brand-tokens-and-project-facts-only",
     },
   };
 }
 
+function contractTokens(profile, statePayload, options) {
+  const brandOverride = options && options.brandOverride ? options.brandOverride : null;
+  const brandTokensPath = options && options.brandTokensPath ? options.brandTokensPath : null;
+  const projectFacts = options && options.projectFacts ? options.projectFacts : null;
+  const projectFactsPath = options && options.projectFactsPath ? options.projectFactsPath : null;
+  return profileDefaultTokensV2(profile, statePayload, brandOverride, brandTokensPath, projectFacts, projectFactsPath);
+}
+
 function markdownLibrary(profile, statePayload) {
   const mappedRefs =
     statePayload &&
@@ -84,7 +331,8 @@ function markdownLibrary(profile, statePayload) {
     typeof statePayload.referenceMap.mappedCount === "number"
       ? statePayload.referenceMap.mappedCount
       : 0;
-  const patterns = profile === "b2b-commerce" ? ECOMMERCE_PATTERNS : BASELINE_PATTERNS;
+  const isCommerce = profile === "b2b-commerce" || profile === "b2b-industrial-commerce";
+  const patterns = isCommerce ? ECOMMERCE_PATTERNS : BASELINE_PATTERNS;
   return `# Component Pattern Library
 
 ## Contract Meta
@@ -108,7 +356,7 @@ ${patterns.map((item) => `- ${item}`).join("\n")}
 `;
 }
 
-function writeComponentContractArtifacts(projectPath, inputContractState) {
+function writeComponentContractArtifacts(projectPath, inputContractState, options) {
   const paths = describeDesignPaths(projectPath);
   if (
     !inputContractState ||
@@ -122,21 +370,39 @@ function writeComponentContractArtifacts(projectPath, inputContractState) {
     );
   }
   const profile = inputContractState.profileSelection || null;
-  const tokensPayload = contractTokens(profile, inputContractState);
+  const brandTokensPath = options && options.brandTokensPath ? options.brandTokensPath : null;
+  const projectFactsPath = options && options.projectFactsPath ? options.projectFactsPath : null;
+
+  // BK-223 + BK-229: validate and load both inputs before any write (fail-closed).
+  let brandOverride = null;
+  if (brandTokensPath) {
+    brandOverride = loadBrandTokensV2(brandTokensPath);
+  }
+  let projectFacts = null;
+  if (projectFactsPath) {
+    projectFacts = loadProjectFactsV1(projectFactsPath);
+  }
+
+  const tokensPayload = contractTokens(profile, inputContractState, {
+    brandOverride, brandTokensPath, projectFacts, projectFactsPath,
+  });
   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");
 
+  const isCommerce = profile === "b2b-commerce" || profile === "b2b-industrial-commerce";
   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,
+    patternCount: isCommerce ? ECOMMERCE_PATTERNS.length : BASELINE_PATTERNS.length,
   };
 }
 
 module.exports = {
+  loadBrandTokensV2,
+  loadProjectFactsV1,
+  validateProjectFacts,
   writeComponentContractArtifacts,
 };
-

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

@@ -337,11 +337,12 @@ function firstSectionList(raw) {
 
 function normalizeVisualTokenUsage(value) {
   const payload = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  // BK-225: v3 groups — section_keys and component_keys replace spacing_keys and radius_keys.
   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"]),
+    section_keys: firstStringList(payload, ["section_keys", "sectionKeys"]),
+    component_keys: firstStringList(payload, ["component_keys", "componentKeys"]),
   };
 }
 

package/src/lib/design-paths.js

@@ -9,6 +9,7 @@ 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_MANIFEST_RELATIVE = path.join("docs", "design", "prototype", ".manifest.json");
 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");
@@ -59,6 +60,7 @@ function describeDesignPaths(projectPath) {
     prototypeScreensPath: path.join(root, DESIGN_PROTOTYPE_SCREENS_RELATIVE),
     prototypeAssetsPath: path.join(root, DESIGN_PROTOTYPE_ASSETS_RELATIVE),
     screensPath: path.join(root, DESIGN_SCREENS_RELATIVE),
+    prototypeManifestPath: path.join(root, DESIGN_PROTOTYPE_MANIFEST_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),
@@ -83,6 +85,7 @@ module.exports = {
   DESIGN_HANDOFF_RELATIVE,
   DESIGN_MANIFEST_RELATIVE,
   DESIGN_PROTOTYPE_INDEX_RELATIVE,
+  DESIGN_PROTOTYPE_MANIFEST_RELATIVE,
   DESIGN_PROTOTYPE_ASSETS_RELATIVE,
   DESIGN_PROTOTYPE_CSS_RELATIVE,
   DESIGN_PROTOTYPE_JS_RELATIVE,

package/src/lib/design-profiles.js

@@ -32,6 +32,37 @@ const DESIGN_PROFILES = {
       "mode-b-configurator": ["configurator wizard", "bom/material table", "sticky purchase/cta"],
     },
   },
+  "b2b-industrial-commerce": {
+    name: "b2b-industrial-commerce",
+    summary: "B2B industrial commerce primitives for product catalog, configuration, and procurement workflows.",
+    primitives: [
+      "catalog grid",
+      "filter sidebar",
+      "product card",
+      "pdp gallery/spec/cta",
+      "technical spec table",
+      "search results/no-result",
+      "cart line items/summary",
+      "checkout steps",
+      "order history/detail",
+      "account shell",
+      "configurator wizard",
+      "bom/material table",
+      "procurement summary panel",
+    ],
+    screenRoleHints: {
+      home: ["catalog grid", "product card", "procurement summary panel"],
+      category: ["filter sidebar", "catalog grid", "product card"],
+      "product-detail": ["pdp gallery/spec/cta", "technical spec table", "sticky purchase/cta"],
+      search: ["search results/no-result", "product card", "filter sidebar"],
+      cart: ["cart line items/summary", "sticky purchase/cta"],
+      checkout: ["checkout steps", "cart line items/summary", "procurement summary panel"],
+      "order-history": ["order history/detail"],
+      "order-detail": ["order history/detail"],
+      "account-info": ["account shell"],
+      "mode-b-configurator": ["configurator wizard", "bom/material table", "technical spec table"],
+    },
+  },
 };
 
 function availableProfileNames() {