sdtk-design-kit 0.2.1 → 0.3.1

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/commands/update.js

@@ -0,0 +1,11 @@
+"use strict";
+
+const { executeUpdate } = require("../lib/update");
+
+async function cmdUpdate(args) {
+  return executeUpdate(args);
+}
+
+module.exports = {
+  cmdUpdate,
+};

package/src/index.js

@@ -10,6 +10,7 @@ const { cmdScreens } = require("./commands/screens");
 const { cmdStart } = require("./commands/start");
 const { cmdStatus } = require("./commands/status");
 const { cmdSystem } = require("./commands/system");
+const { cmdUpdate } = require("./commands/update");
 const { cmdWireframe } = require("./commands/wireframe");
 const { ValidationError } = require("./lib/errors");
 
@@ -76,6 +77,9 @@ async function run(argv) {
   if (command === "status") {
     return cmdStatus(args);
   }
+  if (command === "update") {
+    return cmdUpdate(args);
+  }
   if (DEFERRED_COMMANDS.has(command)) {
     throw new ValidationError(
       `Command "${command}" is planned for ${DEFERRED_COMMANDS.get(command)} and is not implemented yet. Run "sdtk-design --help" for the current Foundation Beta surface.`

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

@@ -109,17 +109,6 @@ function lintArtifactHtml(html, options = {}) {
     "Pull the metric from a real source or remove the claim.",
     screenId
   );
-  addRegexFindings(
-    findings,
-    clean,
-    /class="[^"]*\bdensity-evidence\b[^"]*"/i,
-    "P0",
-    "density-evidence-residue",
-    "Legacy density-evidence filler residue detected.",
-    "Remove filler section emitters from the renderer.",
-    screenId
-  );
-
   const counts = new Map();
   for (const text of articleTexts(clean)) counts.set(text, (counts.get(text) || 0) + 1);
   const fullDuplicates = new Set();