@jay-framework/design-system-validator 0.22.1 → 0.23.1

package/dist/index.js

@@ -1,12 +1,17 @@
 import postcss from "postcss";
-import yaml from "js-yaml";
+import yaml, { load, dump } from "js-yaml";
 import * as fs from "node:fs";
-import fs__default from "node:fs";
+import fs__default, { promises } 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";
+import { walkElements, JAY_EXTENSION } from "@jay-framework/compiler-shared";
+import { makeJayAction, makeJayQuery, makeJayStackComponent, phaseOutput } from "@jay-framework/fullstack-component";
+import { fontFamilyToCamelCase } from "@capsizecss/metrics";
+import { createFontStack } from "@capsizecss/core";
+import { fileURLToPath } from "node:url";
+import { parseJayFile, JAY_IMPORT_RESOLVER } from "@jay-framework/compiler-jay-html";
 function extractFrontmatter(content) {
   const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
   return match ? match[1] : null;
@@ -17,14 +22,11 @@ function resolveReferences(tokens) {
       const parts = refPath.split(".");
       let current = tokens;
       for (const part of parts) {
-        if (current == null || typeof current !== "object")
-          return `{${refPath}}`;
+        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);
+      if (typeof current === "string") return resolve(current);
+      if (typeof current === "number") return String(current);
       return `{${refPath}}`;
     });
   };
@@ -39,8 +41,7 @@ function resolveReferences(tokens) {
   }
 }
 function normalizeStringValues(map) {
-  if (!map)
-    return {};
+  if (!map) return {};
   const result = {};
   for (const [key, value] of Object.entries(map)) {
     result[key] = String(value);
@@ -49,11 +50,9 @@ function normalizeStringValues(map) {
 }
 function parseDesignMd(content) {
   const frontmatter = extractFrontmatter(content);
-  if (!frontmatter)
-    return null;
+  if (!frontmatter) return null;
   const raw = yaml.load(frontmatter);
-  if (!raw || typeof raw !== "object")
-    return null;
+  if (!raw || typeof raw !== "object") return null;
   const rawComponents = {};
   if (raw.components) {
     for (const [name, spec] of Object.entries(raw.components)) {
@@ -82,14 +81,12 @@ function findDesignMd(filePath, projectRoot) {
     if (fs__default.existsSync(candidate)) {
       const content = fs__default.readFileSync(candidate, "utf-8");
       const tokens = parseDesignMd(content);
-      if (!tokens)
-        return null;
+      if (!tokens) return null;
       const designMdPath = path__default.relative(projectRoot, candidate);
       return { tokens, designMdPath };
     }
     const parent = path__default.dirname(dir);
-    if (parent === dir)
-      break;
+    if (parent === dir) break;
     dir = parent;
   }
   return null;
@@ -157,8 +154,7 @@ function parseRules(css, sourceIndexOffset = 0, customProperties) {
     const mediaQuery = getMediaQuery(rule);
     for (const selector of rule.selectors) {
       const trimmed = selector.trim();
-      if (!trimmed)
-        continue;
+      if (!trimmed) continue;
       rules.push({
         selector: trimmed,
         specificity: computeSpecificity(trimmed),
@@ -176,10 +172,8 @@ function resolveVarReferences(value, customProperties) {
     /var\(\s*(--[a-zA-Z0-9-]+)(?:\s*,\s*([^)]+))?\s*\)/g,
     (_, name, fallback) => {
       const resolved = customProperties.get(name);
-      if (resolved !== void 0)
-        return resolveVarReferences(resolved, customProperties);
-      if (fallback !== void 0)
-        return fallback.trim();
+      if (resolved !== void 0) return resolveVarReferences(resolved, customProperties);
+      if (fallback !== void 0) return fallback.trim();
       return _;
     }
   );
@@ -188,8 +182,7 @@ function parseInlineStyles(style) {
   const declarations = [];
   for (const part of style.split(";")) {
     const colonIdx = part.indexOf(":");
-    if (colonIdx === -1)
-      continue;
+    if (colonIdx === -1) continue;
     const prop = part.substring(0, colonIdx).trim();
     const val = part.substring(colonIdx + 1).trim();
     if (prop && val) {
@@ -201,8 +194,7 @@ function parseInlineStyles(style) {
 function buildSelectorCache(rules, root) {
   const cache = /* @__PURE__ */ new Map();
   for (const rule of rules) {
-    if (cache.has(rule.selector))
-      continue;
+    if (cache.has(rule.selector)) continue;
     try {
       const matches = root.querySelectorAll(rule.selector);
       cache.set(rule.selector, new Set(matches));
@@ -213,10 +205,8 @@ function buildSelectorCache(rules, root) {
   return cache;
 }
 function compareSpecificity(a, b) {
-  if (a[0] !== b[0])
-    return a[0] - b[0];
-  if (a[1] !== b[1])
-    return a[1] - b[1];
+  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, selectorCache) {
@@ -226,15 +216,13 @@ function resolveForElement(element, rules, selectorCache) {
   );
   matchingRules.sort((a, b) => {
     const specCmp = compareSpecificity(a.specificity, b.specificity);
-    if (specCmp !== 0)
-      return specCmp;
+    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;
+      if (existing?.important && !decl.important) continue;
       resolved[decl.property] = {
         property: decl.property,
         value: decl.value,
@@ -252,8 +240,7 @@ function resolveForElement(element, rules, selectorCache) {
     const inlineDecls = parseInlineStyles(inlineStyle);
     for (const decl of inlineDecls) {
       const existing = resolved[decl.property];
-      if (existing?.important)
-        continue;
+      if (existing?.important) continue;
       resolved[decl.property] = {
         property: decl.property,
         value: decl.value,
@@ -291,13 +278,11 @@ function resolveCascade(cssSources, root) {
       result.set(el, resolved);
     }
     for (const child of el.childNodes) {
-      if (child.nodeType === 1)
-        walk(child);
+      if (child.nodeType === 1) walk(child);
     }
   }
   for (const child of root.childNodes) {
-    if (child.nodeType === 1)
-      walk(child);
+    if (child.nodeType === 1) walk(child);
   }
   return result;
 }
@@ -329,8 +314,7 @@ function resolveCascadeByBreakpoint(cssSources, root) {
         breakpointResult.set(el, resolved);
       }
       for (const child of el.childNodes) {
-        if (child.nodeType === 1)
-          walk(child);
+        if (child.nodeType === 1) walk(child);
       }
     };
     const rulesForBreakpoint = allRules.filter(
@@ -339,8 +323,7 @@ function resolveCascadeByBreakpoint(cssSources, root) {
     const selectorCache = buildSelectorCache(rulesForBreakpoint, root);
     const breakpointResult = /* @__PURE__ */ new Map();
     for (const child of root.childNodes) {
-      if (child.nodeType === 1)
-        walk(child);
+      if (child.nodeType === 1) walk(child);
     }
     result.set(breakpoint, breakpointResult);
   }
@@ -348,8 +331,7 @@ function resolveCascadeByBreakpoint(cssSources, root) {
 }
 function normalizeHex(color) {
   const hex = color.trim().toLowerCase();
-  if (!/^#[0-9a-f]{3,8}$/.test(hex))
-    return null;
+  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]}`;
   }
@@ -357,8 +339,7 @@ function normalizeHex(color) {
 }
 function parseRgb(value) {
   const match = value.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-  if (!match)
-    return null;
+  if (!match) return null;
   const r = parseInt(match[1], 10);
   const g = parseInt(match[2], 10);
   const b = parseInt(match[3], 10);
@@ -366,10 +347,8 @@ function parseRgb(value) {
 }
 function normalizeColor(value) {
   const trimmed = value.trim().toLowerCase();
-  if (trimmed.startsWith("#"))
-    return normalizeHex(trimmed);
-  if (trimmed.startsWith("rgb"))
-    return parseRgb(trimmed);
+  if (trimmed.startsWith("#")) return normalizeHex(trimmed);
+  if (trimmed.startsWith("rgb")) return parseRgb(trimmed);
   return null;
 }
 const COLOR_PROPERTIES = /* @__PURE__ */ new Set([
@@ -430,26 +409,22 @@ 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.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 };
+  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 };
+    if (normalizedToken === normalized) return { matches: true };
   }
   let closestName = "";
   let closestDist = Infinity;
   for (const [name, tokenValue] of tokenEntries) {
     const nt = normalizeColor(tokenValue);
-    if (!nt)
-      continue;
+    if (!nt) continue;
     const dist = colorDistance(normalized, nt);
     if (dist < closestDist) {
       closestDist = dist;
@@ -476,8 +451,7 @@ function matchSpacing(value, spacingTokens) {
   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 (part === "0" || part === "auto" || part.startsWith("var(")) continue;
     if (!tokenValues.has(part)) {
       return {
         matches: false,
@@ -507,27 +481,22 @@ function matchTypographyProperty(property, value, typographyTokens) {
   }
   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-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 (property === "font-family" && token.fontFamily) tokenValues.add(token.fontFamily);
   }
-  if (tokenValues.size === 0)
-    return { matches: true };
-  if (tokenValues.has(value))
-    return { matches: true };
+  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 };
+      if (tv.replace(/['"]/g, "").trim() === primaryFont) return { matches: true };
     }
   }
   return {
@@ -541,13 +510,10 @@ function matchAnimationDuration(value, animationTokens) {
   }
   const durations = /* @__PURE__ */ new Set();
   for (const preset of Object.values(animationTokens)) {
-    if (preset.duration)
-      durations.add(preset.duration);
+    if (preset.duration) durations.add(preset.duration);
   }
-  if (durations.size === 0)
-    return { matches: true };
-  if (durations.has(value))
-    return { matches: true };
+  if (durations.size === 0) return { matches: true };
+  if (durations.has(value)) return { matches: true };
   return {
     matches: false,
     suggestion: `Use a DESIGN.md animation preset duration`
@@ -559,17 +525,13 @@ function matchAnimationEasing(value, animationTokens) {
   }
   const easings = /* @__PURE__ */ new Set();
   for (const preset of Object.values(animationTokens)) {
-    if (preset.easing)
-      easings.add(preset.easing);
+    if (preset.easing) easings.add(preset.easing);
   }
-  if (easings.size === 0)
-    return { matches: true };
-  if (easings.has(value))
-    return { matches: true };
+  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 };
+    if (e.replace(/\s/g, "") === normalizedValue) return { matches: true };
   }
   return {
     matches: false,
@@ -587,8 +549,7 @@ function matchComponent(elementStyles, componentSpec, rawSpec) {
     width: "width"
   };
   for (const [specProp, expectedValue] of Object.entries(componentSpec)) {
-    if (specProp === "typography")
-      continue;
+    if (specProp === "typography") continue;
     const cssProp = propertyMapping[specProp] || specProp;
     const actualValue = elementStyles[cssProp];
     if (actualValue && actualValue !== expectedValue) {
@@ -622,10 +583,8 @@ function splitTopLevelCommas(value) {
   let depth = 0;
   let current = "";
   for (const ch of value) {
-    if (ch === "(" || ch === "[")
-      depth++;
-    else if (ch === ")" || ch === "]")
-      depth--;
+    if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth--;
     if (ch === "," && depth === 0) {
       parts.push(current.trim());
       current = "";
@@ -633,8 +592,7 @@ function splitTopLevelCommas(value) {
       current += ch;
     }
   }
-  if (current.trim())
-    parts.push(current.trim());
+  if (current.trim()) parts.push(current.trim());
   return parts;
 }
 function extractBackgroundColors(value) {
@@ -661,8 +619,7 @@ function extractBackgroundColors(value) {
 }
 function hexToRgbValues(hex) {
   const normalized = normalizeHex(hex);
-  if (!normalized)
-    return null;
+  if (!normalized) return null;
   return [
     parseInt(normalized.slice(1, 3), 16),
     parseInt(normalized.slice(3, 5), 16),
@@ -680,7 +637,7 @@ function contrastRatio(l1, l2) {
   const darker = Math.min(l1, l2);
   return (lighter + 0.05) / (darker + 0.05);
 }
-const GUIDE_SUGGESTION$1 = "See design-system-validator agent-kit/designer/design-system.md for usage guide";
+const GUIDE_SUGGESTION$2 = "See design-system-validator agent-kit/designer/design-system.md for usage guide";
 function elementHint(el) {
   const tag = el.rawTagName?.toLowerCase() || "element";
   const cls = el.getAttribute?.("class");
@@ -688,20 +645,17 @@ function elementHint(el) {
   const words = text ? text.split(/\s+/).slice(0, 3).join(" ") : "";
   const truncated = words && text.split(/\s+/).length > 3 ? words + "..." : words;
   const parts = [`<${tag}`];
-  if (cls)
-    parts.push(`class="${cls}"`);
+  if (cls) parts.push(`class="${cls}"`);
   parts.push(">");
-  if (truncated)
-    parts.push(`"${truncated}"`);
+  if (truncated) parts.push(`"${truncated}"`);
   return parts.join(" ");
 }
 function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath, findings) {
   const hint = elementHint(el);
   const prefix = breakpointLabel ? `[${breakpointLabel}] ` : "";
-  const sug = (s) => s?.replace("DESIGN.md", designMdPath);
+  const sug = (s) => s ? s.replace("DESIGN.md", designMdPath) + "\nTo suppress intentional exceptions, see: agent-kit/designer/design-system.md" : void 0;
   for (const [property, resolved] of Object.entries(styles)) {
-    if (resolved.allowed)
-      continue;
+    if (resolved.allowed) continue;
     if (isColorProperty(property) && Object.keys(tokens.colors).length > 0) {
       const result = matchColor(resolved.value, tokens.colors);
       if (!result.matches) {
@@ -786,12 +740,10 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
 }
 const validateTokens = (ctx) => {
   const found = findDesignMd(ctx.filePath, ctx.projectRoot);
-  if (!found)
-    return [];
+  if (!found) return [];
   const { tokens, designMdPath } = found;
   const findings = [];
-  if (!ctx.css)
-    return [];
+  if (!ctx.css) return [];
   const cssSources = [ctx.css];
   const breakpointNames = /* @__PURE__ */ new Map();
   for (const [name, value] of Object.entries(tokens.breakpoints)) {
@@ -822,7 +774,7 @@ const validateTokens = (ctx) => {
     checkReducedMotion(cssSources, findings);
   }
   if (findings.length > 0) {
-    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION$1 });
+    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION$2 });
   }
   return findings;
 };
@@ -858,30 +810,25 @@ function checkReducedMotion(cssSources, findings) {
     });
   }
 }
-const GUIDE_SUGGESTION = "See design-system-validator agent-kit/designer/design-system.md for usage guide";
+const GUIDE_SUGGESTION$1 = "See design-system-validator agent-kit/designer/design-system.md for usage guide";
 function describeElement(el) {
   const tag = el.rawTagName?.toLowerCase() || "element";
   const cls = el.getAttribute?.("class");
   const ref = el.getAttribute?.("ref");
   const text = el.textContent?.trim().slice(0, 30);
   const parts = [`<${tag}`];
-  if (cls)
-    parts.push(`class="${cls}"`);
-  if (ref)
-    parts.push(`ref="${ref}"`);
+  if (cls) parts.push(`class="${cls}"`);
+  if (ref) parts.push(`ref="${ref}"`);
   parts.push(">");
-  if (text)
-    parts.push(`"${text}${el.textContent.trim().length > 30 ? "…" : ""}"`);
+  if (text) parts.push(`"${text}${el.textContent.trim().length > 30 ? "…" : ""}"`);
   return parts.join(" ");
 }
 const validateComponents = (ctx) => {
   const found = findDesignMd(ctx.filePath, ctx.projectRoot);
-  if (!found || Object.keys(found.tokens.components).length === 0)
-    return [];
+  if (!found || Object.keys(found.tokens.components).length === 0) return [];
   const { tokens, designMdPath } = found;
   const findings = [];
-  if (!ctx.css)
-    return [];
+  if (!ctx.css) return [];
   const cascade = resolveCascade([ctx.css], ctx.body);
   const jayComponents = /* @__PURE__ */ new Map();
   const htmlComponents = /* @__PURE__ */ new Map();
@@ -904,8 +851,7 @@ const validateComponents = (ctx) => {
       }
     }
     for (const child of el.childNodes) {
-      if (child.nodeType === 1)
-        walk(child);
+      if (child.nodeType === 1) walk(child);
     }
   }
   walk(ctx.body);
@@ -913,16 +859,13 @@ const validateComponents = (ctx) => {
     const componentName = `jay:${contractName}`;
     const spec = tokens.components[componentName];
     const rawSpec = tokens.rawComponents[componentName];
-    if (!spec)
-      continue;
+    if (!spec) continue;
     for (const el of elements) {
       const styles = cascade.get(el);
-      if (!styles)
-        continue;
+      if (!styles) continue;
       const styleValues = {};
       for (const [prop, resolved] of Object.entries(styles)) {
-        if (!resolved.allowed)
-          styleValues[prop] = resolved.value;
+        if (!resolved.allowed) styleValues[prop] = resolved.value;
       }
       const mismatches = matchComponent(styleValues, spec, rawSpec);
       if (mismatches.length > 0) {
@@ -939,20 +882,17 @@ const validateComponents = (ctx) => {
   for (const [componentName, selector] of htmlComponents) {
     const spec = tokens.components[componentName];
     const rawSpec = tokens.rawComponents[componentName];
-    if (!spec)
-      continue;
+    if (!spec) continue;
     for (const [el, styles] of cascade) {
       try {
         const matchedEls = ctx.body.querySelectorAll(selector);
-        if (!matchedEls.some((m) => m === el))
-          continue;
+        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;
+        if (!resolved.allowed) styleValues[prop] = resolved.value;
       }
       const mismatches = matchComponent(styleValues, spec, rawSpec);
       if (mismatches.length > 0) {
@@ -967,14 +907,13 @@ const validateComponents = (ctx) => {
     }
   }
   if (findings.length > 0) {
-    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION });
+    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION$1 });
   }
   return findings;
 };
 const validateStructure = (ctx) => {
   const found = findDesignMd(ctx.filePath, ctx.projectRoot);
-  if (!found)
-    return [];
+  if (!found) return [];
   const { tokens } = found;
   const findings = [];
   if (tokens.rules["max-font-weights"] && ctx.css) {
@@ -982,8 +921,7 @@ const validateStructure = (ctx) => {
     const fontWeights = /* @__PURE__ */ new Set();
     for (const [, styles] of cascade) {
       const fw = styles["font-weight"];
-      if (fw && !fw.allowed)
-        fontWeights.add(fw.value);
+      if (fw && !fw.allowed) fontWeights.add(fw.value);
     }
     const max = tokens.rules["max-font-weights"];
     if (fontWeights.size > max) {
@@ -998,11 +936,9 @@ const validateStructure = (ctx) => {
     const primaryButtons = /* @__PURE__ */ new Map();
     walkElements(ctx.body, ctx, (el) => {
       const tag = el.rawTagName?.toLowerCase();
-      if (tag !== "button")
-        return;
+      if (tag !== "button") return;
       const classes = el.getAttribute?.("class") || "";
-      if (!classes.includes("primary") && !classes.includes("btn-primary"))
-        return;
+      if (!classes.includes("primary") && !classes.includes("btn-primary")) return;
       const ref = el.getAttribute?.("ref") || "";
       const text = el.textContent?.trim() || "";
       const identity = `${ref}|${text}`;
@@ -1020,8 +956,7 @@ const validateStructure = (ctx) => {
   return findings;
 };
 function resolveColorValue(value) {
-  if (value.startsWith("#"))
-    return 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) {
@@ -1034,41 +969,33 @@ function resolveColorValue(value) {
   return null;
 }
 function isLargeText(fontSize, fontWeight) {
-  if (!fontSize)
-    return false;
+  if (!fontSize) return false;
   const sizeMatch = fontSize.match(/([\d.]+)(px|rem|em)/);
-  if (!sizeMatch)
-    return false;
+  if (!sizeMatch) return false;
   let sizePx = parseFloat(sizeMatch[1]);
   const unit = sizeMatch[2];
-  if (unit === "rem" || unit === "em")
-    sizePx *= 16;
+  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 [];
+  if (!found || !found.tokens.rules["require-contrast-aa"]) return [];
+  const { tokens } = found;
   const findings = [];
-  if (!ctx.css)
-    return [];
+  if (!ctx.css) return [];
   const cascade = resolveCascade([ctx.css], 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;
+    if (!colorStyle || !bgStyle) continue;
+    if (colorStyle.allowed || bgStyle.allowed) continue;
     const fgHex = resolveColorValue(colorStyle.value);
     const bgHex = resolveColorValue(bgStyle.value);
-    if (!fgHex || !bgHex)
-      continue;
+    if (!fgHex || !bgHex) continue;
     const fgRgb = hexToRgbValues(fgHex);
     const bgRgb = hexToRgbValues(bgHex);
-    if (!fgRgb || !bgRgb)
-      continue;
+    if (!fgRgb || !bgRgb) continue;
     const fgLum = relativeLuminance(...fgRgb);
     const bgLum = relativeLuminance(...bgRgb);
     const ratio = contrastRatio(fgLum, bgLum);
@@ -1086,164 +1013,420 @@ const validateContrast = (ctx) => {
   }
   return findings;
 };
-const ADD_MENU_OUTPUT_REL = "agent-kit/aiditor/add-menu/design-system.yaml";
-function categoryName(designMdPath, projectRoot, tokens) {
-  if (tokens.name)
-    return tokens.name;
-  const rel = path.relative(projectRoot, designMdPath);
-  if (rel === "DESIGN.md")
-    return "Design System";
-  const dir = path.dirname(rel).replace(/^src\/pages\/?/, "");
-  return dir ? `Design System (${dir})` : "Design System";
+const GUIDE_SUGGESTION = "See design-system-validator agent-kit/designer/font-fallback-patterns.md for usage guide";
+const METRIC_OVERRIDE_PROPERTIES = /* @__PURE__ */ new Set([
+  "size-adjust",
+  "ascent-override",
+  "descent-override",
+  "line-gap-override"
+]);
+function unquote(value) {
+  return value.replace(/^(['"])(.*)\1$/, "$2");
 }
+function parseFontFaces(css) {
+  const result = [];
+  const root = postcss.parse(css);
+  root.walkAtRules("font-face", (atRule) => {
+    let family = "";
+    let hasUrlSrc = false;
+    let hasLocalSrc = false;
+    let hasMetricOverrides = false;
+    atRule.walkDecls((decl) => {
+      if (decl.prop === "font-family") {
+        family = unquote(decl.value);
+      }
+      if (decl.prop === "src") {
+        if (/url\s*\(/.test(decl.value)) hasUrlSrc = true;
+        if (/local\s*\(/.test(decl.value)) hasLocalSrc = true;
+      }
+      if (METRIC_OVERRIDE_PROPERTIES.has(decl.prop)) {
+        hasMetricOverrides = true;
+      }
+    });
+    if (family) {
+      result.push({ family, hasUrlSrc, hasLocalSrc, hasMetricOverrides });
+    }
+  });
+  return result;
+}
+const FONT_SERVICE_HOSTS = [
+  "fonts.googleapis.com",
+  "fonts.bunny.net",
+  "fonts.cdnfonts.com",
+  "use.typekit.net"
+];
+function parseFontServiceUrl(url) {
+  if (!FONT_SERVICE_HOSTS.some((host) => url.includes(host))) return [];
+  const queryStart = url.indexOf("?");
+  if (queryStart === -1) return [];
+  const query = url.substring(queryStart + 1);
+  const families = [];
+  for (const param of query.split("&")) {
+    const eqIdx = param.indexOf("=");
+    const key = eqIdx === -1 ? param : param.substring(0, eqIdx);
+    const value = eqIdx === -1 ? "" : param.substring(eqIdx + 1);
+    if (key === "family") {
+      const parts = value.split("|");
+      for (const part of parts) {
+        const name = decodeURIComponent(part.split(":")[0]).replace(/\+/g, " ");
+        if (name) families.push(name);
+      }
+    }
+  }
+  return families;
+}
+function parseFontImports(css) {
+  const families = [];
+  const root = postcss.parse(css);
+  root.walkAtRules("import", (atRule) => {
+    const raw = atRule.params;
+    const urlMatch = raw.match(/url\s*\(\s*(['"]?)(.+?)\1\s*\)/) || raw.match(/(['"]?)(.+?)\1/);
+    if (!urlMatch) return;
+    const url = urlMatch[2];
+    families.push(...parseFontServiceUrl(url));
+  });
+  return families;
+}
+function parseFontLinks(head) {
+  if (!head?.links) return [];
+  const families = [];
+  for (const link of head.links) {
+    if (link.rel !== "stylesheet") continue;
+    const staticParts = link.href.filter((p) => p.kind === "static");
+    if (staticParts.length !== link.href.length) continue;
+    const url = staticParts.map((p) => p.value).join("");
+    families.push(...parseFontServiceUrl(url));
+  }
+  return families;
+}
+function parseFontFamilyStacks(css) {
+  const stacks = /* @__PURE__ */ new Map();
+  const root = postcss.parse(css);
+  root.walkDecls("font-family", (decl) => {
+    const parent = decl.parent;
+    if (parent?.type === "atrule" && parent.name === "font-face") return;
+    const families = decl.value.split(",").map((f) => unquote(f.trim()));
+    const key = families.join(",");
+    if (!stacks.has(key)) {
+      stacks.set(key, families);
+    }
+  });
+  return stacks;
+}
+const validateFontFallbacks = (ctx) => {
+  const findings = [];
+  const fontFaces = ctx.css ? parseFontFaces(ctx.css) : [];
+  const importedFonts = ctx.css ? parseFontImports(ctx.css) : [];
+  const linkedFonts = parseFontLinks(ctx.head);
+  if (fontFaces.length === 0 && importedFonts.length === 0 && linkedFonts.length === 0)
+    return findings;
+  if (!ctx.css && linkedFonts.length === 0) return findings;
+  const webFontFamilies = /* @__PURE__ */ new Set();
+  const metricMatchedFallbacks = /* @__PURE__ */ new Set();
+  for (const ff of fontFaces) {
+    if (ff.hasUrlSrc) {
+      webFontFamilies.add(ff.family);
+    }
+    if (ff.hasLocalSrc && ff.hasMetricOverrides) {
+      metricMatchedFallbacks.add(ff.family);
+    }
+  }
+  for (const family of importedFonts) {
+    webFontFamilies.add(family);
+  }
+  for (const family of linkedFonts) {
+    webFontFamilies.add(family);
+  }
+  if (webFontFamilies.size === 0) return findings;
+  const fontStacks = ctx.css ? parseFontFamilyStacks(ctx.css) : /* @__PURE__ */ new Map();
+  const designMd = findDesignMd(ctx.filePath, ctx.projectRoot);
+  if (designMd) {
+    for (const [, token] of Object.entries(designMd.tokens.typography)) {
+      if (token.fontFamily) {
+        const families = token.fontFamily.split(",").map((f) => unquote(f.trim()));
+        const key = families.join(",");
+        if (!fontStacks.has(key)) {
+          fontStacks.set(key, families);
+        }
+      }
+    }
+  }
+  const flagged = /* @__PURE__ */ new Set();
+  function flagIfMissing(family) {
+    if (flagged.has(family)) return;
+    const hasFallbackFace = fontFaces.some(
+      (ff) => ff.hasLocalSrc && ff.hasMetricOverrides && ff.family.startsWith(family) && ff.family !== family
+    );
+    const familyItselfIsMetricMatched = metricMatchedFallbacks.has(family);
+    if (!hasFallbackFace && !familyItselfIsMetricMatched) {
+      flagged.add(family);
+      findings.push({
+        severity: "warning",
+        message: `font-family "${family}" loads from a URL but has no metric-matched fallback. This causes layout shift (CLS) when the font loads.`,
+        suggestion: `Generate a fallback with: npx jay-stack-cli action design-system-validator/fontFallback --input '{"primary":"${family}","fallback":"Arial"}'`
+      });
+    }
+  }
+  for (const [, families] of fontStacks) {
+    for (const family of families) {
+      if (!webFontFamilies.has(family)) continue;
+      flagIfMissing(family);
+    }
+  }
+  for (const family of webFontFamilies) {
+    flagIfMissing(family);
+  }
+  if (findings.length > 0) {
+    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION });
+  }
+  return findings;
+};
+async function loadMetrics(familyName) {
+  const camelCase = fontFamilyToCamelCase(familyName);
+  try {
+    const mod = await import(`@capsizecss/metrics/${camelCase}`);
+    return mod.default;
+  } catch {
+    throw new Error(
+      `Font "${familyName}" not found in @capsizecss/metrics. Use a known Google Font or system font name (e.g. "Inter", "Arial", "Georgia").`
+    );
+  }
+}
+const fontFallback = makeJayAction("designSystem.fontFallback").withHandler(
+  async (input) => {
+    const primaryMetrics = await loadMetrics(input.primary);
+    const fallbackMetrics = await loadMetrics(input.fallback);
+    const result = createFontStack([primaryMetrics, fallbackMetrics]);
+    return {
+      fontFamily: result.fontFamily,
+      fontFaces: result.fontFaces
+    };
+  }
+);
+const PLUGIN_ATTRS = {
+  pluginName: "design-system-validator",
+  packageName: "@jay-framework/design-system-validator"
+};
 function esc(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function buildColorItems(tokens, category) {
-  return Object.entries(tokens.colors).map(([name, value]) => ({
+function scopedFragment(innerHtml, scopedCss = "") {
+  const styleBlock = `<style>@scope { ${scopedCss} }</style>`;
+  return `<div>${styleBlock}${innerHtml}</div>`;
+}
+function isLargeFontSize(fontSize) {
+  if (!fontSize) return false;
+  if (/\d+(\.\d+)?\s*(vw|vh|vmin|vmax)\b/.test(fontSize)) return true;
+  const clampMatch = fontSize.match(/clamp\([^,]+,[^,]+,\s*([\d.]+)\s*(px|rem|em)/);
+  if (clampMatch) {
+    const max = parseFloat(clampMatch[1]);
+    const unit = clampMatch[2];
+    if (unit === "px") return max > 20;
+    return max > 1.25;
+  }
+  const simple = parseFloat(fontSize);
+  if (isNaN(simple)) return false;
+  if (fontSize.includes("rem") || fontSize.includes("em")) return simple > 1.25;
+  return simple > 20;
+}
+function spacingBrowseSize(value) {
+  if (/calc|clamp|var\(/.test(value)) return "large";
+  const px = parseFloat(value);
+  if (!isNaN(px) && !value.includes("rem") && !value.includes("em")) {
+    if (px <= 30) return "small";
+    if (px > 100) return "large";
+    return void 0;
+  }
+  const rem = parseFloat(value);
+  if (!isNaN(rem)) {
+    if (rem <= 2) return "small";
+    if (rem > 6) return "large";
+  }
+  return void 0;
+}
+function buildColorItem(name, value, category) {
+  return {
     id: `design-system:color-${name}`,
-    title: `${name} (${value})`,
+    ...PLUGIN_ATTRS,
+    title: name,
     category,
     subCategory: "Colors",
+    browse: { size: "small" },
     prompt: `Use color token "${name}" with value ${value} from DESIGN.md.`,
+    interaction: {
+      mode: "stage-place",
+      stagePromptTemplate: `Apply the color token "${name}" (${value}) from DESIGN.md at this location.`
+    },
     presentation: {
       type: "html-fragment",
-      html: `<div style="display:flex;align-items:center;gap:10px;font-family:sans-serif;">
-  <div style="width:40px;height:40px;border-radius:6px;background:${esc(value)};border:1px solid rgba(0,0,0,0.1);flex-shrink:0;"></div>
-  <div>
-    <div style="font-size:13px;font-weight:600;">${esc(name)}</div>
-    <div style="font-size:11px;color:#888;font-family:monospace;">${esc(value)}</div>
-  </div>
-</div>`
+      html: scopedFragment(`<div style="display:flex;flex-direction:column;align-items:center;justify-content:center;gap:4px;font-family:sans-serif;height:100%;">
+  <div style="width:40px;height:40px;border-radius:6px;background:${esc(value)};border:1px solid rgba(0,0,0,0.1);"></div>
+  <div style="font-size:10px;color:#888;font-family:monospace;">${esc(value)}</div>
+</div>`)
     }
-  }));
-}
-function buildTypographyItems(tokens, category) {
-  return Object.entries(tokens.typography).map(([name, t]) => {
-    const parts = [];
-    if (t.fontFamily)
-      parts.push(t.fontFamily);
-    if (t.fontSize)
-      parts.push(t.fontSize);
-    if (t.fontWeight)
-      parts.push(`weight ${t.fontWeight}`);
-    if (t.lineHeight)
-      parts.push(`line-height ${t.lineHeight}`);
-    if (t.letterSpacing)
-      parts.push(`letter-spacing ${t.letterSpacing}`);
-    const desc = parts.join(", ");
-    const styles = [];
-    if (t.fontFamily)
-      styles.push(`font-family:${t.fontFamily},sans-serif`);
-    if (t.fontSize)
-      styles.push(`font-size:${t.fontSize}`);
-    if (t.fontWeight)
-      styles.push(`font-weight:${t.fontWeight}`);
-    if (t.lineHeight)
-      styles.push(`line-height:${t.lineHeight}`);
-    if (t.letterSpacing)
-      styles.push(`letter-spacing:${t.letterSpacing}`);
-    return {
-      id: `design-system:typography-${name}`,
-      title: name,
-      category,
-      subCategory: "Typography",
-      prompt: `Apply typography preset "${name}" from DESIGN.md: ${desc}.`,
-      presentation: {
-        type: "html-fragment",
-        html: `<div style="font-family:sans-serif;">
-  <div style="${styles.join(";")};margin:0;">The quick brown fox</div>
-  <div style="font-size:10px;color:#888;margin-top:6px;font-family:monospace;">${esc(name)}: ${esc(desc)}</div>
-</div>`
-      }
-    };
-  });
+  };
 }
-function buildSpacingItems(tokens, category) {
-  return Object.entries(tokens.spacing).map(([name, value]) => ({
+function buildSpacingItem(name, value, category) {
+  return {
     id: `design-system:spacing-${name}`,
-    title: `${name} (${value})`,
+    ...PLUGIN_ATTRS,
+    title: name,
     category,
     subCategory: "Spacing",
     prompt: `Use spacing token "${name}" with value ${value} from DESIGN.md for padding, margin, or gap.`,
+    ...spacingBrowseSize(value) ? { browse: { size: spacingBrowseSize(value) } } : {},
+    interaction: {
+      mode: "stage-place",
+      stagePromptTemplate: `Apply the spacing token "${name}" (${value}) from DESIGN.md at this location.`
+    },
     presentation: {
       type: "html-fragment",
-      html: `<div style="display:flex;align-items:center;gap:8px;font-family:sans-serif;">
+      html: scopedFragment(`<div style="display:flex;flex-direction:column;align-items:center;justify-content:center;gap:4px;font-family:sans-serif;height:100%;">
   <div style="display:flex;align-items:center;gap:0;">
     <div style="width:16px;height:24px;background:#cbd5e1;border-radius:2px 0 0 2px;"></div>
     <div style="width:${esc(value)};height:24px;background:repeating-linear-gradient(45deg,#e0f2fe,#e0f2fe 2px,#bae6fd 2px,#bae6fd 4px);"></div>
     <div style="width:16px;height:24px;background:#cbd5e1;border-radius:0 2px 2px 0;"></div>
   </div>
-  <div>
-    <span style="font-size:12px;font-weight:600;">${esc(name)}</span>
-    <span style="font-size:11px;color:#888;font-family:monospace;margin-left:4px;">${esc(value)}</span>
-  </div>
-</div>`
+  <div style="font-size:10px;color:#888;font-family:monospace;">${esc(value)}</div>
+</div>`)
     }
-  }));
+  };
 }
-function buildRoundedItems(tokens, category) {
-  return Object.entries(tokens.rounded).map(([name, value]) => ({
+function buildRoundedItem(name, value, category) {
+  return {
     id: `design-system:rounded-${name}`,
-    title: `${name} (${value})`,
+    ...PLUGIN_ATTRS,
+    title: name,
     category,
     subCategory: "Rounded",
+    browse: { size: "small" },
     prompt: `Use border-radius token "${name}" with value ${value} from DESIGN.md.`,
+    interaction: {
+      mode: "stage-place",
+      stagePromptTemplate: `Apply the border-radius token "${name}" (${value}) from DESIGN.md at this location.`
+    },
     presentation: {
       type: "html-fragment",
-      html: `<div style="display:flex;align-items:center;gap:10px;font-family:sans-serif;">
-  <div style="width:40px;height:40px;border-radius:${esc(value)};background:#e2e8f0;border:1.5px solid #94a3b8;flex-shrink:0;"></div>
-  <div>
-    <div style="font-size:12px;font-weight:600;">${esc(name)}</div>
-    <div style="font-size:11px;color:#888;font-family:monospace;">${esc(value)}</div>
-  </div>
-</div>`
+      html: scopedFragment(`<div style="display:flex;flex-direction:column;align-items:center;justify-content:center;gap:4px;font-family:sans-serif;height:100%;">
+  <div style="width:40px;height:40px;border-radius:${esc(value)};background:#e2e8f0;border:1.5px solid #94a3b8;"></div>
+  <div style="font-size:10px;color:#888;font-family:monospace;">${esc(value)}</div>
+</div>`)
     }
-  }));
+  };
+}
+function formatTypographyCssValue(value) {
+  return String(value);
+}
+function buildTypographyItem(name, typography, category) {
+  const parts = [];
+  if (typography.fontFamily) parts.push(typography.fontFamily);
+  if (typography.fontSize) parts.push(typography.fontSize);
+  if (typography.fontWeight != null) {
+    parts.push(`weight ${formatTypographyCssValue(typography.fontWeight)}`);
+  }
+  if (typography.lineHeight != null) {
+    parts.push(`line-height ${formatTypographyCssValue(typography.lineHeight)}`);
+  }
+  if (typography.letterSpacing) parts.push(`letter-spacing ${typography.letterSpacing}`);
+  const desc = parts.join(", ");
+  const styles = [];
+  if (typography.fontFamily) styles.push(`font-family:${typography.fontFamily},sans-serif`);
+  if (typography.fontSize) styles.push(`font-size:${typography.fontSize}`);
+  if (typography.fontWeight != null) {
+    styles.push(`font-weight:${formatTypographyCssValue(typography.fontWeight)}`);
+  }
+  if (typography.lineHeight != null) {
+    styles.push(`line-height:${formatTypographyCssValue(typography.lineHeight)}`);
+  }
+  if (typography.letterSpacing) styles.push(`letter-spacing:${typography.letterSpacing}`);
+  const isLargeFont = isLargeFontSize(typography.fontSize);
+  return {
+    id: `design-system:typography-${name}`,
+    ...PLUGIN_ATTRS,
+    title: name,
+    category,
+    subCategory: "Typography",
+    prompt: `Apply typography preset "${name}" from DESIGN.md: ${desc}.`,
+    interaction: {
+      mode: "stage-place",
+      stagePromptTemplate: `Apply the typography preset "${name}" (${desc}) from DESIGN.md at this location.`
+    },
+    ...isLargeFont ? { browse: { size: "large" } } : {},
+    presentation: {
+      type: "html-fragment",
+      html: scopedFragment(`<div style="font-family:sans-serif;">
+  <div style="${styles.join(";")};margin:0;">The quick brown fox</div>
+  <div style="font-size:10px;color:#888;margin-top:6px;font-family:monospace;">${esc(name)}: ${esc(desc)}</div>
+</div>`)
+    }
+  };
+}
+function buildColorItems(tokens, category) {
+  return Object.entries(tokens.colors).map(
+    ([name, value]) => buildColorItem(name, value, category)
+  );
+}
+function buildTypographyItems(tokens, category) {
+  return Object.entries(tokens.typography).map(
+    ([name, typography]) => buildTypographyItem(name, typography, category)
+  );
+}
+function buildSpacingItems(tokens, category) {
+  return Object.entries(tokens.spacing).map(
+    ([name, value]) => buildSpacingItem(name, value, category)
+  );
+}
+function buildRoundedItems(tokens, category) {
+  return Object.entries(tokens.rounded).map(
+    ([name, value]) => buildRoundedItem(name, value, category)
+  );
 }
 function buildBreakpointItems(tokens, category) {
   return Object.entries(tokens.breakpoints).map(([name, value]) => ({
     id: `design-system:breakpoint-${name}`,
+    ...PLUGIN_ATTRS,
     title: `${name} (${value})`,
     category,
     subCategory: "Breakpoints",
-    prompt: `Use breakpoint "${name}" at max-width ${value} from DESIGN.md: @media (max-width: ${value}) { ... }`
+    prompt: `Use breakpoint "${name}" at max-width ${value} from DESIGN.MD: @media (max-width: ${value}) { ... }`,
+    interaction: {
+      mode: "stage-place",
+      stagePromptTemplate: `Add a responsive breakpoint at "${name}" (${value}) from DESIGN.md for this element.`
+    }
   }));
 }
 function buildAnimationItems(tokens, category) {
   return Object.entries(tokens.animations).map(([name, preset]) => {
     const parts = [];
-    if (preset.duration)
-      parts.push(preset.duration);
-    if (preset.easing)
-      parts.push(preset.easing);
+    if (preset.duration) parts.push(preset.duration);
+    if (preset.easing) parts.push(preset.easing);
     const desc = parts.join(", ");
     const dur = preset.duration || "300ms";
     const ease = preset.easing || "ease";
     return {
       id: `design-system:animation-${name}`,
+      ...PLUGIN_ATTRS,
       title: name,
       category,
       subCategory: "Animations",
       prompt: `Use animation preset "${name}" from DESIGN.md: ${desc}. Apply to transition-duration and transition-timing-function.`,
+      interaction: {
+        mode: "stage-place",
+        stagePromptTemplate: `Apply the animation preset "${name}" (${desc}) from DESIGN.md to this element's transitions.`
+      },
       presentation: {
         type: "html-fragment",
-        html: `<div style="font-family:sans-serif;">
-  <style>
-    @scope {
-      .anim-preview { width:40px;height:40px;border-radius:6px;background:#8b5cf6;transition:transform ${esc(dur)} ${esc(ease)};cursor:pointer; }
-      .anim-preview:hover { transform:scale(1.3); }
-    }
-  </style>
-  <div style="display:flex;align-items:center;gap:10px;">
+        html: scopedFragment(
+          `<div style="display:flex;align-items:center;gap:10px;font-family:sans-serif;">
     <div class="anim-preview"></div>
     <div>
       <div style="font-size:12px;font-weight:600;">${esc(name)}</div>
       <div style="font-size:11px;color:#888;font-family:monospace;">${esc(desc)}</div>
       <div style="font-size:10px;color:#aaa;">hover to preview</div>
     </div>
-  </div>
-</div>`
+  </div>`,
+          `.anim-preview { width:40px;height:40px;border-radius:6px;background:#8b5cf6;transition:transform ${esc(dur)} ${esc(ease)};cursor:pointer; } .anim-preview:hover { transform:scale(1.3); }`
+        )
       }
     };
   });
@@ -1264,63 +1447,125 @@ function buildComponentItems(tokens, category) {
       borderColor: "border-color"
     };
     for (const [prop, value] of Object.entries(spec)) {
-      if (prop === "typography")
-        continue;
+      if (prop === "typography") continue;
       const cssProp = propertyMapping[prop] || prop;
       previewStyles.push(`${cssProp}:${value}`);
     }
-    if (!spec.padding)
-      previewStyles.push("padding:8px 16px");
-    if (spec.borderColor)
-      previewStyles.push("border:1.5px solid " + spec.borderColor);
+    if (!spec.padding) previewStyles.push("padding:8px 16px");
+    if (spec.borderColor) previewStyles.push("border:1.5px solid " + spec.borderColor);
     return {
       id: `design-system:component-${name}`,
+      ...PLUGIN_ATTRS,
       title: name,
       category,
       subCategory: "Components",
       prompt: `Apply the "${name}" component spec from DESIGN.md. Required styles: ${props}. The design-system validator will flag mismatches.`,
+      interaction: {
+        mode: "stage-place",
+        stagePromptTemplate: `Apply the "${name}" component styles (${props}) from DESIGN.md to this element.`
+      },
       presentation: {
         type: "html-fragment",
-        html: `<div style="font-family:sans-serif;">
+        html: scopedFragment(`<div style="font-family:sans-serif;">
   <div style="${previewStyles.join(";")};display:inline-block;font-size:13px;min-width:80px;text-align:center;">${esc(name)}</div>
   <div style="font-size:10px;color:#888;margin-top:6px;font-family:monospace;">${esc(props)}</div>
-</div>`
+</div>`)
       }
     };
   });
 }
+const ADD_MENU_GENERATED_REL = "agent-kit/aiditor/add-menu/design-system.generated.yaml";
+function readAddMenuCatalog(projectRoot) {
+  const catalogPath = path.join(projectRoot, ADD_MENU_GENERATED_REL);
+  if (!fs.existsSync(catalogPath)) {
+    return [];
+  }
+  const parsed = load(fs.readFileSync(catalogPath, "utf-8"));
+  if (!Array.isArray(parsed.items)) {
+    return [];
+  }
+  return parsed.items;
+}
+function writeAddMenuCatalog(projectRoot, items) {
+  const outputPath = path.join(projectRoot, ADD_MENU_GENERATED_REL);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, dump({ items }, { lineWidth: 120, noRefs: true }), "utf-8");
+  return ADD_MENU_GENERATED_REL;
+}
+const AIDITOR_SETTINGS_OUTPUT_REL = "agent-kit/aiditor/settings/design-system-validator.yaml";
+const SETTINGS_TEMPLATE_REL = "agent-kit/aiditor/settings.template.yaml";
+function resolvePackagedAgentKitPath(relativePath, moduleUrl = import.meta.url) {
+  let directory = path.dirname(fileURLToPath(moduleUrl));
+  for (let depth = 0; depth < 4; depth++) {
+    const candidate = path.join(directory, relativePath);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      break;
+    }
+    directory = parent;
+  }
+  return null;
+}
+function writeAiditorSettingsContribution(projectRoot, templatePath, force = false) {
+  const outputPath = path.join(projectRoot, AIDITOR_SETTINGS_OUTPUT_REL);
+  if (fs.existsSync(outputPath) && !force) {
+    return null;
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.copyFileSync(templatePath, outputPath);
+  return AIDITOR_SETTINGS_OUTPUT_REL;
+}
+function materializeDesignSystemAiditorSettings(projectRoot, force = false) {
+  const templatePath = resolvePackagedAgentKitPath(SETTINGS_TEMPLATE_REL);
+  if (!templatePath) {
+    return null;
+  }
+  return writeAiditorSettingsContribution(projectRoot, templatePath, force);
+}
 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(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);
+    walkDesignMdDir(pagesRoot, files);
   }
   return files;
 }
+function walkDesignMdDir(dir, files) {
+  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(".")) {
+      walkDesignMdDir(path.join(dir, entry.name), files);
+    }
+  }
+}
+function categoryName(designMdPath, projectRoot, tokens) {
+  if (tokens.name) return tokens.name;
+  const rel = path.relative(projectRoot, designMdPath);
+  if (rel === "DESIGN.md") return "Design System";
+  const dir = path.dirname(rel).replace(/^src\/pages\/?/, "");
+  return dir ? `Design System (${dir})` : "Design System";
+}
 async function generateDesignSystemAgentKit(ctx) {
   const designMdFiles = findAllDesignMdFiles(ctx.projectRoot);
+  const settingsGenerated = materializeDesignSystemAiditorSettings(ctx.projectRoot, ctx.force);
   if (designMdFiles.length === 0) {
-    return { agentKitCreated: [], message: "No DESIGN.md found in project" };
+    return {
+      agentKitCreated: settingsGenerated ? [settingsGenerated] : [],
+      message: settingsGenerated ? "AIditor settings materialized; no DESIGN.md found for add-menu" : "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;
+    if (!tokens) continue;
     const category = categoryName(filePath, ctx.projectRoot, tokens);
     const items = [
       ...buildColorItems(tokens, category),
@@ -1339,20 +1584,244 @@ async function generateDesignSystemAgentKit(ctx) {
     }
   }
   if (allItems.length === 0) {
-    return { agentKitCreated: [], message: "DESIGN.md found but no tokens defined" };
+    return {
+      agentKitCreated: settingsGenerated ? [settingsGenerated] : [],
+      message: "DESIGN.md found but no tokens defined"
+    };
+  }
+  writeAddMenuCatalog(ctx.projectRoot, allItems);
+  const agentKitCreated = [ADD_MENU_GENERATED_REL];
+  if (settingsGenerated) {
+    agentKitCreated.push(settingsGenerated);
   }
-  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 {
-    agentKitCreated: [ADD_MENU_OUTPUT_REL],
+    agentKitCreated,
     message: `Generated ${allItems.length} add-menu items from ${designMdFiles.length} DESIGN.md file(s)`
   };
 }
+const DESIGN_VALIDATORS = [
+  { name: "design-tokens", run: validateTokens },
+  { name: "design-components", run: validateComponents },
+  { name: "design-structure", run: validateStructure },
+  { name: "design-contrast", run: validateContrast }
+];
+async function findJayHtmlFiles(scanDir) {
+  const files = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path__default.join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        await walk(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(JAY_EXTENSION)) {
+        files.push(fullPath);
+      }
+    }
+  }
+  await walk(scanDir);
+  return files;
+}
+function toAnalysisFinding(relativePath, validator, finding) {
+  if (!finding.message) return null;
+  return {
+    file: relativePath,
+    validator,
+    severity: finding.severity === "error" ? "error" : "warning",
+    message: finding.message,
+    suggestion: finding.suggestion
+  };
+}
+function buildValidationContext(projectRoot, relativePath, parsed) {
+  return {
+    filePath: relativePath,
+    body: parsed.body,
+    css: parsed.css,
+    head: parsed.headMeta,
+    headlessImports: parsed.headlessImports.map((imp) => ({
+      key: imp.key,
+      contractName: imp.contractName,
+      contract: imp.contract ? {
+        name: imp.contract.name,
+        tags: imp.contract.tags,
+        props: imp.contract.props,
+        params: imp.contract.params
+      } : void 0
+    })),
+    projectRoot
+  };
+}
+async function runDesignSystemAnalysis(projectRoot) {
+  const pagesDir = path__default.join(projectRoot, "src", "pages");
+  const componentsDir = path__default.join(projectRoot, "src", "components");
+  const jayHtmlFiles = [
+    ...await findJayHtmlFiles(pagesDir).catch(() => []),
+    ...await findJayHtmlFiles(componentsDir).catch(() => [])
+  ];
+  const findings = [];
+  for (const jayHtmlPath of jayHtmlFiles) {
+    const relativePath = path__default.relative(projectRoot, jayHtmlPath);
+    const filename = path__default.basename(jayHtmlPath.replace(JAY_EXTENSION, ""));
+    const dirname = path__default.dirname(jayHtmlPath);
+    let parsed;
+    try {
+      const content = await promises.readFile(jayHtmlPath, "utf-8");
+      const parseResult = await parseJayFile(
+        content,
+        filename,
+        dirname,
+        {},
+        JAY_IMPORT_RESOLVER,
+        projectRoot
+      );
+      if (!parseResult.value) continue;
+      parsed = parseResult.value;
+    } catch {
+      continue;
+    }
+    const ctx = buildValidationContext(projectRoot, relativePath, parsed);
+    for (const validator of DESIGN_VALIDATORS) {
+      const validatorFindings = await Promise.resolve(validator.run(ctx));
+      for (const finding of validatorFindings) {
+        const mapped = toAnalysisFinding(relativePath, validator.name, finding);
+        if (mapped) findings.push(mapped);
+      }
+    }
+  }
+  const errorCount = findings.filter((finding) => finding.severity === "error").length;
+  const warningCount = findings.filter((finding) => finding.severity === "warning").length;
+  return {
+    filesScanned: jayHtmlFiles.length,
+    findings,
+    errorCount,
+    warningCount
+  };
+}
+function countAddMenuItems(projectRoot) {
+  return readAddMenuCatalog(projectRoot).length;
+}
+function summarizeDesignMd(projectRoot, filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const tokens = parseDesignMd(content);
+  if (!tokens) return null;
+  const relativePath = path.relative(projectRoot, filePath);
+  const name = tokens.name ?? (relativePath === "DESIGN.md" ? "Design System" : `Design System (${path.dirname(relativePath)})`);
+  return {
+    relativePath,
+    name,
+    colorCount: Object.keys(tokens.colors).length,
+    typographyCount: Object.keys(tokens.typography).length,
+    spacingCount: Object.keys(tokens.spacing).length,
+    componentCount: Object.keys(tokens.components).length
+  };
+}
+const getDesignSystemSettingsStatus = makeJayQuery(
+  "designSystem.getDesignSystemSettingsStatus"
+).withHandler(async () => {
+  const projectRoot = process.cwd();
+  const designMdPaths = findAllDesignMdFiles(projectRoot);
+  const designFiles = designMdPaths.map((filePath) => summarizeDesignMd(projectRoot, filePath)).filter((summary) => summary !== null);
+  return {
+    hasDesignMd: designFiles.length > 0,
+    designFiles,
+    addMenuItemCount: countAddMenuItems(projectRoot),
+    addMenuCatalogRel: ADD_MENU_GENERATED_REL,
+    message: designFiles.length > 0 ? `${designFiles.length} DESIGN.md file(s); ${countAddMenuItems(projectRoot)} Add Menu items.` : "No DESIGN.md found — add one at the project root or under src/pages/."
+  };
+});
+const runDesignSystemAnalysisAction = makeJayQuery(
+  "designSystem.runDesignSystemAnalysis"
+).withHandler(async () => {
+  const projectRoot = process.cwd();
+  return runDesignSystemAnalysis(projectRoot);
+});
+const loadDesignSystemAddMenuCatalog = makeJayQuery(
+  "designSystem.loadAddMenuCatalog"
+).withHandler(async () => {
+  const projectRoot = process.cwd();
+  const items = readAddMenuCatalog(projectRoot);
+  return {
+    items,
+    outputRel: ADD_MENU_GENERATED_REL,
+    itemCount: items.length
+  };
+});
+const saveDesignSystemAddMenuCatalog = makeJayAction(
+  "designSystem.saveAddMenuCatalog"
+).withHandler(async (input) => {
+  const projectRoot = process.cwd();
+  const outputRel = writeAddMenuCatalog(projectRoot, input.items);
+  return {
+    itemCount: input.items.length,
+    outputRel,
+    message: `Saved ${input.items.length} add-menu items to ${outputRel}.`
+  };
+});
+const regenerateDesignSystemAddMenu = makeJayQuery(
+  "designSystem.regenerateDesignSystemAddMenu"
+).withHandler(async () => {
+  const projectRoot = process.cwd();
+  const ctx = {
+    projectRoot,
+    referencesDir: path.join(projectRoot, "agent-kit", "references", "design-system-validator"),
+    force: true
+  };
+  const result = await generateDesignSystemAgentKit(ctx);
+  const itemCount = countAddMenuItems(projectRoot);
+  return {
+    itemCount,
+    outputRel: ADD_MENU_GENERATED_REL,
+    agentKitCreated: result.agentKitCreated,
+    message: result.message
+  };
+});
+async function renderFast() {
+  return phaseOutput({
+    statusMessage: "",
+    statusTone: "info",
+    showStatusMessage: false,
+    catalogLoading: true,
+    showNoCatalog: false,
+    addMenuListRows: [],
+    showAddMenuEditor: false,
+    editorTitle: "",
+    editorSubCategory: "",
+    editorTokenValue: "",
+    editorFontSize: "",
+    editorFontWeight: "",
+    editorFontFamily: "",
+    showTypographyFields: false,
+    showTokenValueField: false,
+    editorReadOnly: false,
+    editorReadOnlyReason: "",
+    unsavedChangeCount: 0,
+    saveButtonLabel: "Save and sync",
+    saveDisabled: true,
+    discardDisabled: true,
+    showAnalysisSection: false,
+    showReport: false,
+    reportSummary: "",
+    reportBody: ""
+  }, {});
+}
+const designSystemSettingsPage = makeJayStackComponent().withProps().withFastRender(renderFast).withInteractiveMark();
 export {
+  ADD_MENU_GENERATED_REL,
+  designSystemSettingsPage,
+  fontFallback,
   generateDesignSystemAgentKit,
+  getDesignSystemSettingsStatus,
+  loadDesignSystemAddMenuCatalog,
+  regenerateDesignSystemAddMenu,
+  runDesignSystemAnalysisAction as runDesignSystemAnalysis,
+  saveDesignSystemAddMenuCatalog,
   validateComponents,
   validateContrast,
+  validateFontFallbacks,
   validateStructure,
   validateTokens
 };