@jay-framework/design-system-validator 0.21.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { JayHtmlValidatorFn } from '@jay-framework/compiler-shared';
+import { PluginReferencesContext, PluginReferencesResult } from '@jay-framework/stack-server-runtime';
+
+declare const validateTokens: JayHtmlValidatorFn;
+
+declare const validateComponents: JayHtmlValidatorFn;
+
+declare const validateStructure: JayHtmlValidatorFn;
+
+declare const validateContrast: JayHtmlValidatorFn;
+
+/**
+ * References handler for design-system-validator plugin.
+ *
+ * Runs during `jay-stack agent-kit` to generate AIditor add-menu entries
+ * from the project's DESIGN.md tokens.
+ */
+
+declare function generateDesignSystemReferences(ctx: PluginReferencesContext): Promise<PluginReferencesResult>;
+
+export { generateDesignSystemReferences, validateComponents, validateContrast, validateStructure, validateTokens };

package/dist/index.js

@@ -0,0 +1,1107 @@
+import postcss from "postcss";
+import yaml from "js-yaml";
+import * as fs from "node:fs";
+import fs__default from "node:fs";
+import * as path from "node:path";
+import path__default from "node:path";
+import selectorParser from "postcss-selector-parser";
+import { selectorSpecificity } from "@csstools/selector-specificity";
+import { walkElements } from "@jay-framework/compiler-shared";
+function extractFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  return match ? match[1] : null;
+}
+function resolveReferences(tokens) {
+  const resolve = (value) => {
+    return value.replace(/\{([^}]+)\}/g, (_, refPath) => {
+      const parts = refPath.split(".");
+      let current = tokens;
+      for (const part of parts) {
+        if (current == null || typeof current !== "object")
+          return `{${refPath}}`;
+        current = current[part];
+      }
+      if (typeof current === "string")
+        return resolve(current);
+      if (typeof current === "number")
+        return String(current);
+      return `{${refPath}}`;
+    });
+  };
+  if (tokens.components) {
+    for (const [name, spec] of Object.entries(tokens.components)) {
+      for (const [prop, value] of Object.entries(spec)) {
+        if (typeof value === "string" && value.includes("{")) {
+          tokens.components[name][prop] = resolve(value);
+        }
+      }
+    }
+  }
+}
+function normalizeStringValues(map) {
+  if (!map)
+    return {};
+  const result = {};
+  for (const [key, value] of Object.entries(map)) {
+    result[key] = String(value);
+  }
+  return result;
+}
+function parseDesignMd(content) {
+  const frontmatter = extractFrontmatter(content);
+  if (!frontmatter)
+    return null;
+  const raw = yaml.load(frontmatter);
+  if (!raw || typeof raw !== "object")
+    return null;
+  resolveReferences(raw);
+  return {
+    name: raw.name,
+    colors: raw.colors || {},
+    typography: raw.typography || {},
+    spacing: normalizeStringValues(raw.spacing),
+    rounded: normalizeStringValues(raw.rounded),
+    animations: raw.animations || {},
+    components: raw.components || {},
+    rules: raw.rules || {}
+  };
+}
+function findDesignMd(filePath, projectRoot) {
+  let dir = path__default.dirname(path__default.resolve(projectRoot, filePath));
+  const root = path__default.resolve(projectRoot);
+  while (dir.startsWith(root)) {
+    const candidate = path__default.join(dir, "DESIGN.md");
+    if (fs__default.existsSync(candidate)) {
+      const content = fs__default.readFileSync(candidate, "utf-8");
+      const tokens = parseDesignMd(content);
+      if (!tokens)
+        return null;
+      const designMdPath = path__default.relative(projectRoot, candidate);
+      return { tokens, designMdPath };
+    }
+    const parent = path__default.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+const ALLOW_COMMENT = "design-system: allow";
+function computeSpecificity(selector) {
+  let result = [0, 0, 0];
+  selectorParser((selectors) => {
+    const first = selectors.first;
+    if (first) {
+      const s = selectorSpecificity(first);
+      result = [s.a, s.b, s.c];
+    }
+  }).processSync(selector);
+  return result;
+}
+function hasAllowComment(decl) {
+  const next = decl.next();
+  if (next?.type === "comment" && next.text.trim() === ALLOW_COMMENT) {
+    return true;
+  }
+  const raw = decl.raws.value;
+  if (raw && typeof raw === "object" && "raw" in raw) {
+    const rawStr = raw.raw;
+    if (rawStr.includes(`/*${ALLOW_COMMENT}*/`) || rawStr.includes(`/* ${ALLOW_COMMENT} */`)) {
+      return true;
+    }
+  }
+  return false;
+}
+function getMediaQuery(rule) {
+  let node = rule.parent;
+  while (node && "type" in node) {
+    if (node.type === "atrule" && node.name === "media") {
+      return node.params;
+    }
+    node = node.parent;
+  }
+  return void 0;
+}
+function parseRules(css, sourceIndexOffset = 0) {
+  const rules = [];
+  let ruleIndex = sourceIndexOffset;
+  const root = postcss.parse(css);
+  root.walkRules((rule) => {
+    const declarations = [];
+    rule.walkDecls((decl) => {
+      declarations.push({
+        property: decl.prop,
+        value: decl.value,
+        important: decl.important,
+        allowed: hasAllowComment(decl)
+      });
+    });
+    const mediaQuery = getMediaQuery(rule);
+    for (const selector of rule.selectors) {
+      const trimmed = selector.trim();
+      if (!trimmed)
+        continue;
+      rules.push({
+        selector: trimmed,
+        specificity: computeSpecificity(trimmed),
+        declarations,
+        sourceIndex: ruleIndex,
+        mediaQuery
+      });
+    }
+    ruleIndex++;
+  });
+  return rules;
+}
+function parseInlineStyles(style) {
+  const declarations = [];
+  for (const part of style.split(";")) {
+    const colonIdx = part.indexOf(":");
+    if (colonIdx === -1)
+      continue;
+    const prop = part.substring(0, colonIdx).trim();
+    const val = part.substring(colonIdx + 1).trim();
+    if (prop && val) {
+      declarations.push({ property: prop, value: val, allowed: false });
+    }
+  }
+  return declarations;
+}
+function matchesSelector(element, selector, root) {
+  try {
+    const matches = root.querySelectorAll(selector);
+    return matches.some((el) => el === element);
+  } catch {
+    return false;
+  }
+}
+function compareSpecificity(a, b) {
+  if (a[0] !== b[0])
+    return a[0] - b[0];
+  if (a[1] !== b[1])
+    return a[1] - b[1];
+  return a[2] - b[2];
+}
+function resolveForElement(element, rules, root) {
+  const resolved = {};
+  const matchingRules = rules.filter((rule) => matchesSelector(element, rule.selector, root));
+  matchingRules.sort((a, b) => {
+    const specCmp = compareSpecificity(a.specificity, b.specificity);
+    if (specCmp !== 0)
+      return specCmp;
+    return a.sourceIndex - b.sourceIndex;
+  });
+  for (const rule of matchingRules) {
+    for (const decl of rule.declarations) {
+      const existing = resolved[decl.property];
+      if (existing?.important && !decl.important)
+        continue;
+      resolved[decl.property] = {
+        property: decl.property,
+        value: decl.value,
+        selector: rule.selector,
+        specificity: rule.specificity,
+        sourceIndex: rule.sourceIndex,
+        important: decl.important,
+        allowed: decl.allowed
+      };
+    }
+  }
+  const jayDesignAllow = element.getAttribute("jay-design") === "allow";
+  const inlineStyle = element.getAttribute("style");
+  if (inlineStyle) {
+    const inlineDecls = parseInlineStyles(inlineStyle);
+    for (const decl of inlineDecls) {
+      const existing = resolved[decl.property];
+      if (existing?.important)
+        continue;
+      resolved[decl.property] = {
+        property: decl.property,
+        value: decl.value,
+        selector: "[inline]",
+        specificity: [1, 0, 0],
+        sourceIndex: Infinity,
+        important: false,
+        allowed: jayDesignAllow
+      };
+    }
+  }
+  return resolved;
+}
+function resolveCascade(cssSources, root) {
+  let offset = 0;
+  const allRules = [];
+  for (const css of cssSources) {
+    const rules = parseRules(css, offset);
+    allRules.push(...rules);
+    offset += rules.length;
+  }
+  const result = /* @__PURE__ */ new Map();
+  function walk(el) {
+    const resolved = resolveForElement(el, allRules, root);
+    if (Object.keys(resolved).length > 0) {
+      result.set(el, resolved);
+    }
+    for (const child of el.childNodes) {
+      if (child.nodeType === 1)
+        walk(child);
+    }
+  }
+  for (const child of root.childNodes) {
+    if (child.nodeType === 1)
+      walk(child);
+  }
+  return result;
+}
+function resolveCascadeByBreakpoint(cssSources, root) {
+  let offset = 0;
+  const allRules = [];
+  for (const css of cssSources) {
+    const rules = parseRules(css, offset);
+    allRules.push(...rules);
+    offset += rules.length;
+  }
+  const breakpoints = /* @__PURE__ */ new Set();
+  for (const rule of allRules) {
+    breakpoints.add(rule.mediaQuery);
+  }
+  const result = /* @__PURE__ */ new Map();
+  for (const breakpoint of breakpoints) {
+    let walk = function(el) {
+      const resolved = resolveForElement(el, rulesForBreakpoint, root);
+      if (Object.keys(resolved).length > 0) {
+        breakpointResult.set(el, resolved);
+      }
+      for (const child of el.childNodes) {
+        if (child.nodeType === 1)
+          walk(child);
+      }
+    };
+    const rulesForBreakpoint = allRules.filter(
+      (r) => r.mediaQuery === void 0 || r.mediaQuery === breakpoint
+    );
+    const breakpointResult = /* @__PURE__ */ new Map();
+    for (const child of root.childNodes) {
+      if (child.nodeType === 1)
+        walk(child);
+    }
+    result.set(breakpoint, breakpointResult);
+  }
+  return result;
+}
+function extractCssSources(root, filePath) {
+  const sources = [];
+  const linkedFiles = root.querySelectorAll('link[rel="stylesheet"]');
+  for (const link of linkedFiles) {
+    const href = link.getAttribute("href");
+    if (href && !href.startsWith("http")) {
+      try {
+        const dir = require("node:path").dirname(filePath);
+        const cssPath = require("node:path").resolve(dir, href);
+        const css = require("node:fs").readFileSync(cssPath, "utf-8");
+        sources.push(css);
+      } catch {
+      }
+    }
+  }
+  const styleBlocks = root.querySelectorAll("style");
+  for (const style of styleBlocks) {
+    const text = style.textContent;
+    if (text)
+      sources.push(text);
+  }
+  return sources;
+}
+function normalizeHex(color) {
+  const hex = color.trim().toLowerCase();
+  if (!/^#[0-9a-f]{3,8}$/.test(hex))
+    return null;
+  if (hex.length === 4) {
+    return `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`;
+  }
+  return hex.length === 7 ? hex : null;
+}
+function parseRgb(value) {
+  const match = value.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (!match)
+    return null;
+  const r = parseInt(match[1], 10);
+  const g = parseInt(match[2], 10);
+  const b = parseInt(match[3], 10);
+  return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+function normalizeColor(value) {
+  const trimmed = value.trim().toLowerCase();
+  if (trimmed.startsWith("#"))
+    return normalizeHex(trimmed);
+  if (trimmed.startsWith("rgb"))
+    return parseRgb(trimmed);
+  return null;
+}
+const COLOR_PROPERTIES = /* @__PURE__ */ new Set([
+  "color",
+  "background-color",
+  "border-color",
+  "border-top-color",
+  "border-right-color",
+  "border-bottom-color",
+  "border-left-color",
+  "outline-color",
+  "text-decoration-color",
+  "fill",
+  "stroke"
+]);
+const SPACING_PROPERTIES = /* @__PURE__ */ new Set([
+  "padding",
+  "padding-top",
+  "padding-right",
+  "padding-bottom",
+  "padding-left",
+  "margin",
+  "margin-top",
+  "margin-right",
+  "margin-bottom",
+  "margin-left",
+  "gap",
+  "row-gap",
+  "column-gap",
+  "top",
+  "right",
+  "bottom",
+  "left"
+]);
+const RADIUS_PROPERTIES = /* @__PURE__ */ new Set([
+  "border-radius",
+  "border-top-left-radius",
+  "border-top-right-radius",
+  "border-bottom-left-radius",
+  "border-bottom-right-radius"
+]);
+function isColorProperty(property) {
+  return COLOR_PROPERTIES.has(property);
+}
+function isSpacingProperty(property) {
+  return SPACING_PROPERTIES.has(property);
+}
+function isRadiusProperty(property) {
+  return RADIUS_PROPERTIES.has(property);
+}
+function isTypographyProperty(property) {
+  return property === "font-size" || property === "font-weight" || property === "line-height" || property === "letter-spacing" || property === "font-family";
+}
+function isAnimationDurationProperty(property) {
+  return property === "transition-duration" || property === "animation-duration";
+}
+function isAnimationEasingProperty(property) {
+  return property === "transition-timing-function" || property === "animation-timing-function";
+}
+function matchColor(value, colorTokens) {
+  if (value.startsWith("var("))
+    return { matches: true };
+  if (value === "transparent" || value === "inherit" || value === "currentColor" || value === "initial" || value === "unset") {
+    return { matches: true };
+  }
+  const normalized = normalizeColor(value);
+  if (!normalized)
+    return { matches: true };
+  const tokenEntries = Object.entries(colorTokens);
+  for (const [name, tokenValue] of tokenEntries) {
+    const normalizedToken = normalizeColor(tokenValue);
+    if (normalizedToken === normalized)
+      return { matches: true };
+  }
+  let closestName = "";
+  let closestDist = Infinity;
+  for (const [name, tokenValue] of tokenEntries) {
+    const nt = normalizeColor(tokenValue);
+    if (!nt)
+      continue;
+    const dist = colorDistance(normalized, nt);
+    if (dist < closestDist) {
+      closestDist = dist;
+      closestName = name;
+    }
+  }
+  const suggestion = closestName ? `Use token {colors.${closestName}} ("${colorTokens[closestName]}")` : "Add this color to DESIGN.md colors section";
+  return { matches: false, suggestion };
+}
+function colorDistance(a, b) {
+  const ar = parseInt(a.slice(1, 3), 16);
+  const ag = parseInt(a.slice(3, 5), 16);
+  const ab = parseInt(a.slice(5, 7), 16);
+  const br = parseInt(b.slice(1, 3), 16);
+  const bg = parseInt(b.slice(3, 5), 16);
+  const bb = parseInt(b.slice(5, 7), 16);
+  return Math.sqrt((ar - br) ** 2 + (ag - bg) ** 2 + (ab - bb) ** 2);
+}
+function matchSpacing(value, spacingTokens) {
+  if (value.startsWith("var(") || value === "auto" || value === "0" || value === "inherit" || value === "initial" || value === "unset") {
+    return { matches: true };
+  }
+  const parts = value.split(/\s+/);
+  const tokenValues = new Set(Object.values(spacingTokens));
+  tokenValues.add("0");
+  for (const part of parts) {
+    if (part === "0" || part === "auto" || part.startsWith("var("))
+      continue;
+    if (!tokenValues.has(part)) {
+      const suggestions = Object.entries(spacingTokens).map(([name, val]) => `{spacing.${name}} ("${val}")`).join(", ");
+      return {
+        matches: false,
+        suggestion: `Use a spacing token: ${suggestions}`
+      };
+    }
+  }
+  return { matches: true };
+}
+function matchRounded(value, roundedTokens) {
+  if (value.startsWith("var(") || value === "0" || value === "inherit" || value === "initial" || value === "unset") {
+    return { matches: true };
+  }
+  const tokenValues = new Set(Object.values(roundedTokens));
+  tokenValues.add("0");
+  if (!tokenValues.has(value)) {
+    const suggestions = Object.entries(roundedTokens).map(([name, val]) => `{rounded.${name}} ("${val}")`).join(", ");
+    return {
+      matches: false,
+      suggestion: `Use a rounded token: ${suggestions}`
+    };
+  }
+  return { matches: true };
+}
+function matchTypographyProperty(property, value, typographyTokens) {
+  if (value.startsWith("var(") || value === "inherit" || value === "initial" || value === "unset") {
+    return { matches: true };
+  }
+  const tokenValues = /* @__PURE__ */ new Set();
+  for (const token of Object.values(typographyTokens)) {
+    if (property === "font-size" && token.fontSize)
+      tokenValues.add(token.fontSize);
+    if (property === "font-weight" && token.fontWeight != null)
+      tokenValues.add(String(token.fontWeight));
+    if (property === "line-height" && token.lineHeight != null)
+      tokenValues.add(String(token.lineHeight));
+    if (property === "letter-spacing" && token.letterSpacing)
+      tokenValues.add(token.letterSpacing);
+    if (property === "font-family" && token.fontFamily)
+      tokenValues.add(token.fontFamily);
+  }
+  if (tokenValues.size === 0)
+    return { matches: true };
+  if (tokenValues.has(value))
+    return { matches: true };
+  if (property === "font-family") {
+    const normalizedValue = value.replace(/['"]/g, "").trim();
+    const primaryFont = normalizedValue.split(",")[0].trim();
+    for (const tv of tokenValues) {
+      if (tv.replace(/['"]/g, "").trim() === primaryFont)
+        return { matches: true };
+    }
+  }
+  return {
+    matches: false,
+    suggestion: `Value "${value}" for ${property} not in typography tokens`
+  };
+}
+function matchAnimationDuration(value, animationTokens) {
+  if (value.startsWith("var(") || value === "0s" || value === "0ms" || value === "inherit" || value === "initial" || value === "unset") {
+    return { matches: true };
+  }
+  const durations = /* @__PURE__ */ new Set();
+  for (const preset of Object.values(animationTokens)) {
+    if (preset.duration)
+      durations.add(preset.duration);
+  }
+  if (durations.size === 0)
+    return { matches: true };
+  if (durations.has(value))
+    return { matches: true };
+  const suggestions = Object.entries(animationTokens).filter(([, p]) => p.duration).map(([name, p]) => `${name} (${p.duration})`).join(", ");
+  return {
+    matches: false,
+    suggestion: `Use an animation preset duration: ${suggestions}`
+  };
+}
+function matchAnimationEasing(value, animationTokens) {
+  if (value.startsWith("var(") || value === "inherit" || value === "initial" || value === "unset") {
+    return { matches: true };
+  }
+  const easings = /* @__PURE__ */ new Set();
+  for (const preset of Object.values(animationTokens)) {
+    if (preset.easing)
+      easings.add(preset.easing);
+  }
+  if (easings.size === 0)
+    return { matches: true };
+  if (easings.has(value))
+    return { matches: true };
+  const normalizedValue = value.replace(/\s/g, "");
+  for (const e of easings) {
+    if (e.replace(/\s/g, "") === normalizedValue)
+      return { matches: true };
+  }
+  const suggestions = Object.entries(animationTokens).filter(([, p]) => p.easing).map(([name, p]) => `${name} (${p.easing})`).join(", ");
+  return {
+    matches: false,
+    suggestion: `Use an animation preset easing: ${suggestions}`
+  };
+}
+function matchComponent(elementStyles, componentSpec, componentName) {
+  const findings = [];
+  const propertyMapping = {
+    backgroundColor: "background-color",
+    textColor: "color",
+    rounded: "border-radius",
+    padding: "padding",
+    height: "height",
+    width: "width"
+  };
+  for (const [specProp, expectedValue] of Object.entries(componentSpec)) {
+    if (specProp === "typography")
+      continue;
+    const cssProp = propertyMapping[specProp] || specProp;
+    const actualValue = elementStyles[cssProp];
+    if (actualValue && actualValue !== expectedValue) {
+      findings.push({
+        matches: false,
+        suggestion: `${cssProp} should be "${expectedValue}" per ${componentName} component spec, found "${actualValue}"`
+      });
+    }
+  }
+  return findings;
+}
+function hexToRgbValues(hex) {
+  const normalized = normalizeHex(hex);
+  if (!normalized)
+    return null;
+  return [
+    parseInt(normalized.slice(1, 3), 16),
+    parseInt(normalized.slice(3, 5), 16),
+    parseInt(normalized.slice(5, 7), 16)
+  ];
+}
+function relativeLuminance(r, g, b) {
+  const [rs, gs, bs] = [r / 255, g / 255, b / 255].map(
+    (c) => c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+  );
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+function contrastRatio(l1, l2) {
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+const DESIGNER_GUIDE$3 = "agent-kit/designer/design-system.md";
+function ref(designMdPath) {
+  return `
+See ${designMdPath} for tokens, ${DESIGNER_GUIDE$3} for usage guide.`;
+}
+function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath, findings) {
+  const tag = el.rawTagName?.toLowerCase() || "element";
+  const prefix = breakpointLabel ? `[${breakpointLabel}] ` : "";
+  const refs = ref(designMdPath);
+  for (const [property, resolved] of Object.entries(styles)) {
+    if (resolved.allowed)
+      continue;
+    if (isColorProperty(property) && Object.keys(tokens.colors).length > 0) {
+      const result = matchColor(resolved.value, tokens.colors);
+      if (!result.matches) {
+        findings.push({
+          severity: "warning",
+          message: `${prefix}Hardcoded color "${resolved.value}" for ${property} not in design system`,
+          suggestion: result.suggestion + refs,
+          element: `<${tag}>`
+        });
+      }
+    }
+    if (isSpacingProperty(property) && Object.keys(tokens.spacing).length > 0) {
+      const result = matchSpacing(resolved.value, tokens.spacing);
+      if (!result.matches) {
+        findings.push({
+          severity: "warning",
+          message: `${prefix}${property} value "${resolved.value}" not in spacing scale`,
+          suggestion: result.suggestion + refs,
+          element: `<${tag}>`
+        });
+      }
+    }
+    if (isRadiusProperty(property) && Object.keys(tokens.rounded).length > 0) {
+      const result = matchRounded(resolved.value, tokens.rounded);
+      if (!result.matches) {
+        findings.push({
+          severity: "warning",
+          message: `${prefix}border-radius "${resolved.value}" not in rounded scale`,
+          suggestion: result.suggestion + refs,
+          element: `<${tag}>`
+        });
+      }
+    }
+    if (isTypographyProperty(property) && Object.keys(tokens.typography).length > 0) {
+      const result = matchTypographyProperty(property, resolved.value, tokens.typography);
+      if (!result.matches) {
+        findings.push({
+          severity: "warning",
+          message: `${prefix}${property} value "${resolved.value}" not in typography tokens`,
+          suggestion: result.suggestion + refs,
+          element: `<${tag}>`
+        });
+      }
+    }
+    if (isAnimationDurationProperty(property) && Object.keys(tokens.animations).length > 0) {
+      const result = matchAnimationDuration(resolved.value, tokens.animations);
+      if (!result.matches) {
+        findings.push({
+          severity: "warning",
+          message: `${prefix}${property} "${resolved.value}" not in animation presets`,
+          suggestion: result.suggestion + refs,
+          element: `<${tag}>`
+        });
+      }
+    }
+    if (isAnimationEasingProperty(property) && Object.keys(tokens.animations).length > 0) {
+      const result = matchAnimationEasing(resolved.value, tokens.animations);
+      if (!result.matches) {
+        findings.push({
+          severity: "warning",
+          message: `${prefix}${property} "${resolved.value}" not in animation presets`,
+          suggestion: result.suggestion + refs,
+          element: `<${tag}>`
+        });
+      }
+    }
+  }
+}
+const validateTokens = (ctx) => {
+  const found = findDesignMd(ctx.filePath, ctx.projectRoot);
+  if (!found)
+    return [];
+  const { tokens, designMdPath } = found;
+  const findings = [];
+  const cssSources = extractCssSources(ctx.body, ctx.filePath);
+  if (cssSources.length === 0)
+    return [];
+  const byBreakpoint = resolveCascadeByBreakpoint(cssSources, ctx.body);
+  for (const [breakpoint, cascade] of byBreakpoint) {
+    const label = breakpoint || "";
+    for (const [el, styles] of cascade) {
+      validateElementStyles(el, styles, tokens, label, designMdPath, findings);
+    }
+  }
+  if (Object.keys(tokens.animations).length > 0) {
+    checkReducedMotion(cssSources, designMdPath, findings);
+  }
+  return findings;
+};
+const ANIMATION_PROPERTIES = /* @__PURE__ */ new Set([
+  "transition",
+  "transition-duration",
+  "transition-property",
+  "animation",
+  "animation-duration",
+  "animation-name"
+]);
+function checkReducedMotion(cssSources, designMdPath, findings) {
+  let hasAnimations = false;
+  let hasReducedMotion = false;
+  for (const css of cssSources) {
+    const root = postcss.parse(css);
+    root.walkDecls((decl) => {
+      if (ANIMATION_PROPERTIES.has(decl.prop) && decl.value !== "none") {
+        hasAnimations = true;
+      }
+    });
+    root.walkAtRules("media", (atRule) => {
+      if (atRule.params.includes("prefers-reduced-motion")) {
+        hasReducedMotion = true;
+      }
+    });
+  }
+  if (hasAnimations && !hasReducedMotion) {
+    findings.push({
+      severity: "warning",
+      message: "Page uses transitions/animations but has no @media (prefers-reduced-motion) override",
+      suggestion: "Add @media (prefers-reduced-motion: reduce) { * { transition-duration: 0s !important; animation-duration: 0s !important; } }" + ref(designMdPath)
+    });
+  }
+}
+const DESIGNER_GUIDE$2 = "agent-kit/designer/design-system.md";
+const validateComponents = (ctx) => {
+  const found = findDesignMd(ctx.filePath, ctx.projectRoot);
+  if (!found || Object.keys(found.tokens.components).length === 0)
+    return [];
+  const { tokens, designMdPath } = found;
+  const refs = `
+See ${designMdPath} for component specs, ${DESIGNER_GUIDE$2} for usage guide.`;
+  const findings = [];
+  const cssSources = extractCssSources(ctx.body, ctx.filePath);
+  const cascade = resolveCascade(cssSources, ctx.body);
+  const jayComponents = /* @__PURE__ */ new Map();
+  const htmlComponents = /* @__PURE__ */ new Map();
+  for (const componentName of Object.keys(tokens.components)) {
+    if (componentName.startsWith("jay:")) {
+      jayComponents.set(componentName.substring(4), []);
+    } else {
+      htmlComponents.set(componentName, `.${componentName}`);
+    }
+  }
+  function walk(el) {
+    const tag = el.rawTagName?.toLowerCase();
+    if (tag?.startsWith("jay:")) {
+      const contractName = tag.substring(4);
+      if (jayComponents.has(contractName)) {
+        const children = el.childNodes.filter((n) => n.nodeType === 1);
+        if (children.length > 0) {
+          jayComponents.get(contractName).push(...children);
+        }
+      }
+    }
+    for (const child of el.childNodes) {
+      if (child.nodeType === 1)
+        walk(child);
+    }
+  }
+  walk(ctx.body);
+  for (const [contractName, elements] of jayComponents) {
+    const componentName = `jay:${contractName}`;
+    const spec = tokens.components[componentName];
+    if (!spec)
+      continue;
+    for (const el of elements) {
+      const styles = cascade.get(el);
+      if (!styles)
+        continue;
+      const styleValues = {};
+      for (const [prop, resolved] of Object.entries(styles)) {
+        if (!resolved.allowed)
+          styleValues[prop] = resolved.value;
+      }
+      const results = matchComponent(styleValues, spec, componentName);
+      for (const result of results) {
+        if (!result.matches) {
+          findings.push({
+            severity: "warning",
+            message: `<${componentName}> inline template: ${result.suggestion}`,
+            suggestion: refs.trim(),
+            element: `<${el.rawTagName || "element"}>`
+          });
+        }
+      }
+    }
+  }
+  for (const [componentName, selector] of htmlComponents) {
+    const spec = tokens.components[componentName];
+    if (!spec)
+      continue;
+    for (const [el, styles] of cascade) {
+      try {
+        const matchedEls = ctx.body.querySelectorAll(selector);
+        if (!matchedEls.some((m) => m === el))
+          continue;
+      } catch {
+        continue;
+      }
+      const styleValues = {};
+      for (const [prop, resolved] of Object.entries(styles)) {
+        if (!resolved.allowed)
+          styleValues[prop] = resolved.value;
+      }
+      const results = matchComponent(styleValues, spec, componentName);
+      for (const result of results) {
+        if (!result.matches) {
+          findings.push({
+            severity: "warning",
+            message: `Component "${componentName}": ${result.suggestion}`,
+            suggestion: refs.trim(),
+            element: `<${el.rawTagName || "element"}>`
+          });
+        }
+      }
+    }
+  }
+  return findings;
+};
+const DESIGNER_GUIDE$1 = "agent-kit/designer/design-system.md";
+const validateStructure = (ctx) => {
+  const found = findDesignMd(ctx.filePath, ctx.projectRoot);
+  if (!found)
+    return [];
+  const { tokens, designMdPath } = found;
+  const refs = `
+See ${designMdPath} for rules, ${DESIGNER_GUIDE$1} for usage guide.`;
+  const findings = [];
+  if (tokens.rules["max-font-weights"]) {
+    const cssSources = extractCssSources(ctx.body, ctx.filePath);
+    const cascade = resolveCascade(cssSources, ctx.body);
+    const fontWeights = /* @__PURE__ */ new Set();
+    for (const [, styles] of cascade) {
+      const fw = styles["font-weight"];
+      if (fw && !fw.allowed)
+        fontWeights.add(fw.value);
+    }
+    const max = tokens.rules["max-font-weights"];
+    if (fontWeights.size > max) {
+      findings.push({
+        severity: "warning",
+        message: `${fontWeights.size} unique font-weight values found (max: ${max}): ${[...fontWeights].join(", ")}`,
+        suggestion: `Reduce to ${max} font-weight values from the typography tokens.${refs}`
+      });
+    }
+  }
+  if (tokens.rules["max-primary-buttons"]) {
+    const primaryButtons = /* @__PURE__ */ new Map();
+    walkElements(ctx.body, ctx, (el) => {
+      const tag = el.rawTagName?.toLowerCase();
+      if (tag !== "button")
+        return;
+      const classes = el.getAttribute?.("class") || "";
+      if (!classes.includes("primary") && !classes.includes("btn-primary"))
+        return;
+      const ref2 = el.getAttribute?.("ref") || "";
+      const text = el.textContent?.trim() || "";
+      const identity = `${ref2}|${text}`;
+      primaryButtons.set(identity, true);
+    });
+    const max = tokens.rules["max-primary-buttons"];
+    if (primaryButtons.size > max) {
+      findings.push({
+        severity: "warning",
+        message: `${primaryButtons.size} distinct primary buttons found (max: ${max})`,
+        suggestion: `Reduce to ${max} primary action button per page. Same button (same ref and text) appearing multiple times counts as one.${refs}`
+      });
+    }
+  }
+  return findings;
+};
+const DESIGNER_GUIDE = "agent-kit/designer/design-system.md";
+function resolveColorValue(value) {
+  if (value.startsWith("#"))
+    return value;
+  if (value.startsWith("rgb")) {
+    const match = value.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+    if (match) {
+      const r = parseInt(match[1], 10);
+      const g = parseInt(match[2], 10);
+      const b = parseInt(match[3], 10);
+      return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+    }
+  }
+  return null;
+}
+function isLargeText(fontSize, fontWeight) {
+  if (!fontSize)
+    return false;
+  const sizeMatch = fontSize.match(/([\d.]+)(px|rem|em)/);
+  if (!sizeMatch)
+    return false;
+  let sizePx = parseFloat(sizeMatch[1]);
+  const unit = sizeMatch[2];
+  if (unit === "rem" || unit === "em")
+    sizePx *= 16;
+  const weight = fontWeight ? parseInt(fontWeight, 10) : 400;
+  return sizePx >= 24 || sizePx >= 18.66 && weight >= 700;
+}
+const validateContrast = (ctx) => {
+  const found = findDesignMd(ctx.filePath, ctx.projectRoot);
+  if (!found || !found.tokens.rules["require-contrast-aa"])
+    return [];
+  const { tokens, designMdPath } = found;
+  const refs = `
+See ${designMdPath} for color tokens, ${DESIGNER_GUIDE} for usage guide.`;
+  const findings = [];
+  const cssSources = extractCssSources(ctx.body, ctx.filePath);
+  if (cssSources.length === 0)
+    return [];
+  const cascade = resolveCascade(cssSources, ctx.body);
+  for (const [el, styles] of cascade) {
+    const colorStyle = styles["color"];
+    const bgStyle = styles["background-color"] || styles["background"];
+    if (!colorStyle || !bgStyle)
+      continue;
+    if (colorStyle.allowed || bgStyle.allowed)
+      continue;
+    const fgHex = resolveColorValue(colorStyle.value);
+    const bgHex = resolveColorValue(bgStyle.value);
+    if (!fgHex || !bgHex)
+      continue;
+    const fgRgb = hexToRgbValues(fgHex);
+    const bgRgb = hexToRgbValues(bgHex);
+    if (!fgRgb || !bgRgb)
+      continue;
+    const fgLum = relativeLuminance(...fgRgb);
+    const bgLum = relativeLuminance(...bgRgb);
+    const ratio = contrastRatio(fgLum, bgLum);
+    const large = isLargeText(styles["font-size"]?.value, styles["font-weight"]?.value);
+    const threshold = large ? 3 : 4.5;
+    if (ratio < threshold) {
+      const tag = el.rawTagName?.toLowerCase() || "element";
+      findings.push({
+        severity: "warning",
+        message: `Contrast ratio ${ratio.toFixed(1)}:1 below WCAG AA (${threshold}:1) for color "${colorStyle.value}" on background "${bgStyle.value}"`,
+        suggestion: `Darken text color or lighten background to meet minimum contrast.${refs}`,
+        element: `<${tag}>`
+      });
+    }
+  }
+  return findings;
+};
+const ADD_MENU_OUTPUT_REL = "agent-kit/aiditor/add-menu/design-system.yaml";
+function buildColorItems(tokens) {
+  const entries = Object.entries(tokens.colors);
+  if (entries.length === 0)
+    return [];
+  const palette = entries.map(([name, value]) => `${name}: ${value}`).join(", ");
+  return [
+    {
+      id: "design-system:color-palette",
+      title: "Color palette",
+      category: "Design System",
+      subCategory: "Colors",
+      prompt: `Apply colors from the project design system.
+Available color tokens: ${palette}.
+Use the exact token values from DESIGN.md. Do not use hardcoded colors outside this palette.`
+    }
+  ];
+}
+function buildTypographyItems(tokens) {
+  const entries = Object.entries(tokens.typography);
+  if (entries.length === 0)
+    return [];
+  const presets = entries.map(([name, t]) => {
+    const parts = [`${name}:`];
+    if (t.fontFamily)
+      parts.push(t.fontFamily);
+    if (t.fontSize)
+      parts.push(t.fontSize);
+    if (t.fontWeight)
+      parts.push(`weight ${t.fontWeight}`);
+    return parts.join(" ");
+  }).join("; ");
+  return [
+    {
+      id: "design-system:typography",
+      title: "Typography presets",
+      category: "Design System",
+      subCategory: "Typography",
+      prompt: `Apply typography from the project design system.
+Available presets: ${presets}.
+Use font-size, font-weight, line-height, and font-family values from these presets. Do not introduce typography values outside the design system.`
+    }
+  ];
+}
+function buildSpacingItems(tokens) {
+  const entries = Object.entries(tokens.spacing);
+  if (entries.length === 0)
+    return [];
+  const scale = entries.map(([name, value]) => `${name}: ${value}`).join(", ");
+  return [
+    {
+      id: "design-system:spacing",
+      title: "Spacing scale",
+      category: "Design System",
+      subCategory: "Layout",
+      prompt: `Apply spacing from the project design system.
+Spacing scale: ${scale}.
+Use these values for padding, margin, and gap. Add /* design-system: allow */ comment to exempt intentional one-off values.`
+    }
+  ];
+}
+function buildRoundedItems(tokens) {
+  const entries = Object.entries(tokens.rounded);
+  if (entries.length === 0)
+    return [];
+  const scale = entries.map(([name, value]) => `${name}: ${value}`).join(", ");
+  return [
+    {
+      id: "design-system:rounded",
+      title: "Border radius",
+      category: "Design System",
+      subCategory: "Shapes",
+      prompt: `Apply border-radius from the project design system.
+Rounded scale: ${scale}.
+Use these values for border-radius. Do not use arbitrary radius values.`
+    }
+  ];
+}
+function buildComponentItems(tokens) {
+  const entries = Object.entries(tokens.components);
+  if (entries.length === 0)
+    return [];
+  return entries.map(([name, spec]) => {
+    const props = Object.entries(spec).map(([prop, value]) => `${prop}: ${value}`).join(", ");
+    const isJayComponent = name.startsWith("jay:");
+    const title = isJayComponent ? name : `Component: ${name}`;
+    return {
+      id: `design-system:component-${name}`,
+      title,
+      category: "Design System",
+      subCategory: "Components",
+      prompt: `Apply the "${name}" component spec from the design system.
+Required styles: ${props}.
+Ensure the element matches these values exactly. The design-system validator will flag mismatches.`
+    };
+  });
+}
+function findAllDesignMdFiles(projectRoot) {
+  const pagesRoot = path.join(projectRoot, "src", "pages");
+  const files = [];
+  const rootDesignMd = path.join(projectRoot, "DESIGN.md");
+  if (fs.existsSync(rootDesignMd))
+    files.push(rootDesignMd);
+  if (fs.existsSync(pagesRoot)) {
+    let walk = function(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name === "DESIGN.md") {
+          files.push(path.join(dir, entry.name));
+        } else if (entry.isDirectory() && !entry.name.startsWith(".")) {
+          walk(path.join(dir, entry.name));
+        }
+      }
+    };
+    walk(pagesRoot);
+  }
+  return files;
+}
+async function generateDesignSystemReferences(ctx) {
+  const designMdFiles = findAllDesignMdFiles(ctx.projectRoot);
+  if (designMdFiles.length === 0) {
+    return { referencesCreated: [], message: "No DESIGN.md found in project" };
+  }
+  const allItems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const filePath of designMdFiles) {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const tokens = parseDesignMd(content);
+    if (!tokens)
+      continue;
+    const items = [
+      ...buildColorItems(tokens),
+      ...buildTypographyItems(tokens),
+      ...buildSpacingItems(tokens),
+      ...buildRoundedItems(tokens),
+      ...buildComponentItems(tokens)
+    ];
+    for (const item of items) {
+      if (!seen.has(item.id)) {
+        seen.add(item.id);
+        allItems.push(item);
+      }
+    }
+  }
+  if (allItems.length === 0) {
+    return { referencesCreated: [], message: "DESIGN.md found but no tokens defined" };
+  }
+  const outputPath = path.join(ctx.projectRoot, ADD_MENU_OUTPUT_REL);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, yaml.dump({ items: allItems }, { lineWidth: 120 }), "utf-8");
+  return {
+    referencesCreated: [ADD_MENU_OUTPUT_REL],
+    message: `Generated ${allItems.length} add-menu items from DESIGN.md tokens`
+  };
+}
+export {
+  generateDesignSystemReferences,
+  validateComponents,
+  validateContrast,
+  validateStructure,
+  validateTokens
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jay-framework/design-system-validator",
+  "version": "0.21.0",
+  "type": "module",
+  "description": "Design system validation plugin for Jay Framework — validates jay-html CSS against DESIGN.md tokens",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "plugin.yaml"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin.yaml": "./plugin.yaml"
+  },
+  "scripts": {
+    "build": "npm run clean && npm run build:server && npm run build:types && npm run validate",
+    "validate": "jay-stack-cli validate-plugin",
+    "build:server": "vite build --ssr",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run test",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@csstools/selector-specificity": "^5.0.0",
+    "@jay-framework/compiler-shared": "^0.21.0",
+    "@jay-framework/stack-server-runtime": "^0.21.0",
+    "js-yaml": "^4.1.0",
+    "postcss": "^8.5.6",
+    "postcss-selector-parser": "^7.1.0"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.21.0",
+    "@jay-framework/jay-stack-cli": "^0.21.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.15.21",
+    "node-html-parser": "^6.1.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,22 @@
+name: design-system-validator
+
+setup:
+  references: generateDesignSystemReferences
+  description: Generate AIditor add-menu entries from DESIGN.md tokens
+
+validators:
+  - name: design-tokens
+    handler: validateTokens
+    description: Validates CSS values against DESIGN.md tokens (colors, spacing, rounded, typography)
+
+  - name: design-components
+    handler: validateComponents
+    description: 'Validates component styles against DESIGN.md component specs (HTML and jay: components)'
+
+  - name: design-structure
+    handler: validateStructure
+    description: Enforces structural design rules (max font weights, primary button count)
+
+  - name: design-contrast
+    handler: validateContrast
+    description: Checks WCAG AA color contrast compliance on statically determinable color pairs