@jay-framework/design-system-validator 0.21.0 → 0.22.0

package/agent-kit/designer/design-system.md

@@ -0,0 +1,222 @@
+# Design System (DESIGN.md)
+
+The project uses a `DESIGN.md` file to define design tokens — colors, typography, spacing, rounded corners, and component specs. The validator enforces these tokens across all `.jay-html` pages.
+
+## How It Works
+
+Place a `DESIGN.md` alongside your pages. It applies to that route and all child routes unless a child has its own `DESIGN.md`.
+
+```
+src/pages/
+  DESIGN.md              ← applies to all routes
+  products/
+    DESIGN.md            ← overrides for /products and children
+  admin/
+    DESIGN.md            ← separate system for /admin
+```
+
+## Token Format
+
+DESIGN.md uses YAML frontmatter following the [DESIGN.md spec](https://github.com/google-labs-code/design.md):
+
+```yaml
+---
+colors:
+  primary: '#2563eb'
+  text: '#0f172a'
+  background: '#ffffff'
+  surface: '#f8fafc'
+
+typography:
+  headline-lg:
+    fontFamily: Inter
+    fontSize: 2.5rem
+    fontWeight: 700
+    lineHeight: 1.2
+  body-md:
+    fontFamily: Inter
+    fontSize: 1rem
+    fontWeight: 400
+    lineHeight: 1.6
+
+spacing:
+  sm: 0.5rem
+  md: 1rem
+  lg: 1.5rem
+
+rounded:
+  sm: 0.25rem
+  md: 0.5rem
+  full: 9999px
+
+breakpoints:
+  mobile: 600px
+  tablet: 768px
+  desktop: 1024px
+
+components:
+  button-primary:
+    backgroundColor: '{colors.primary}'
+    textColor: '{colors.background}'
+    rounded: '{rounded.md}'
+  jay:product-card:
+    backgroundColor: '{colors.surface}'
+    rounded: '{rounded.md}'
+
+animations:
+  fade-in:
+    duration: 300ms
+    easing: cubic-bezier(0, 0, 0.2, 1)
+  slide-up:
+    duration: 500ms
+    easing: cubic-bezier(0.4, 0, 0.2, 1)
+  micro:
+    duration: 150ms
+    easing: ease-in-out
+
+rules:
+  max-font-weights: 3
+  max-primary-buttons: 1
+  require-contrast-aa: true
+---
+```
+
+Values use `{path.to.token}` references — e.g., `{colors.primary}` resolves to `"#2563eb"`.
+
+## Using Tokens in CSS
+
+Use the token values directly in your `<style>` blocks:
+
+```css
+.card {
+  background-color: #f8fafc; /* matches {colors.surface} ✓ */
+  border-radius: 0.5rem; /* matches {rounded.md} ✓ */
+  padding: 1rem; /* matches {spacing.md} ✓ */
+  color: #0f172a; /* matches {colors.text} ✓ */
+  transition: opacity 300ms cubic-bezier(0, 0, 0.2, 1); /* matches fade-in preset ✓ */
+}
+```
+
+CSS custom properties (`var(--name)`) are resolved statically when defined in `:root`. Unresolvable vars are accepted without validation.
+
+## Breakpoints
+
+The `breakpoints` section defines approved responsive breakpoints. Media queries using `max-width` values not in this list are flagged. Breakpoint names are used in validation output for readability.
+
+```yaml
+breakpoints:
+  mobile: 600px
+  tablet: 768px
+  desktop: 1024px
+```
+
+Use only these values in `@media (max-width: ...)` queries:
+
+```css
+@media (max-width: 768px) {
+  /* tablet ✓ */
+}
+@media (max-width: 750px) {
+  /* not in breakpoints ✗ */
+}
+```
+
+## Component Specs
+
+The `components` section defines expected styles for HTML elements (matched by class) and jay headless components (matched by `jay:` prefix):
+
+- `button-primary` → validates elements with class `.button-primary`
+- `jay:product-card` → validates the inline template inside `<jay:product-card>`
+
+## Exceptions
+
+When a value intentionally breaks the design system, exempt it:
+
+**In CSS** — add a comment after the declaration:
+
+```css
+.hero {
+  padding: 7.5rem 0; /* design-system: allow */
+}
+```
+
+**On elements** — add the `jay-design="allow"` attribute:
+
+```html
+<div style="margin-top: 7.5rem" jay-design="allow"></div>
+```
+
+## Validation Errors
+
+These are the errors the validator produces. Use them to align your CSS with the design system.
+
+**Hardcoded color:**
+
+```
+⚠ Hardcoded color "#ff0000" for color not in design system
+  Suggestion: Use token {colors.error} ("#dc2626") or add to DESIGN.md
+```
+
+**Off-scale spacing:**
+
+```
+⚠ padding value "13px" not in spacing scale
+  Suggestion: Use a spacing token: {spacing.md} ("1rem"), {spacing.lg} ("1.5rem")
+```
+
+**Off-scale border-radius:**
+
+```
+⚠ border-radius "10px" not in rounded scale
+  Suggestion: Use a rounded token: {rounded.md} ("0.5rem"), {rounded.full} ("9999px")
+```
+
+**Component mismatch:**
+
+```
+⚠ <jay:product-card> inline template: background-color should be "#f8fafc"
+  per jay:product-card component spec, found "#ffffff"
+```
+
+**Too many font weights:**
+
+```
+⚠ 4 unique font-weight values found (max: 3)
+  Suggestion: Reduce to 3 font-weight values from the typography tokens
+```
+
+**Animation duration not in presets:**
+
+```
+⚠ transition-duration "200ms" not in animation presets
+  Suggestion: Use an animation preset duration: fade-in (300ms), slide-up (500ms), micro (150ms)
+```
+
+**Animation easing not in presets:**
+
+```
+⚠ transition-timing-function "ease" not in animation presets
+  Suggestion: Use an animation preset easing: fade-in (cubic-bezier(0, 0, 0.2, 1)), micro (ease-in-out)
+```
+
+**Missing reduced-motion media query:**
+
+```
+⚠ 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; } }
+```
+
+**Non-standard breakpoint:**
+
+```
+⚠ Media query @media (max-width: 750px) not in DESIGN.md breakpoints
+  Suggestion: Use a DESIGN.md breakpoint: mobile (600px), tablet (768px), desktop (1024px)
+```
+
+**Low contrast:**
+
+```
+⚠ Contrast ratio 2.8:1 below WCAG AA (4.5:1) for color "#94a3b8"
+  on background "#f8fafc"
+  Suggestion: Darken text color or lighten background
+```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { JayHtmlValidatorFn } from '@jay-framework/compiler-shared';
-import { PluginReferencesContext, PluginReferencesResult } from '@jay-framework/stack-server-runtime';
+import { PluginAgentKitContext, PluginAgentKitResult } from '@jay-framework/stack-server-runtime';
 
 declare const validateTokens: JayHtmlValidatorFn;
 
@@ -13,9 +13,9 @@ 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.
+ * from the project's DESIGN.md tokens — one item per design token, with HTML previews.
  */
 
-declare function generateDesignSystemReferences(ctx: PluginReferencesContext): Promise<PluginReferencesResult>;
+declare function generateDesignSystemAgentKit(ctx: PluginAgentKitContext): Promise<PluginAgentKitResult>;
 
-export { generateDesignSystemReferences, validateComponents, validateContrast, validateStructure, validateTokens };
+export { generateDesignSystemAgentKit, validateComponents, validateContrast, validateStructure, validateTokens };

package/dist/index.js

@@ -54,6 +54,12 @@ function parseDesignMd(content) {
   const raw = yaml.load(frontmatter);
   if (!raw || typeof raw !== "object")
     return null;
+  const rawComponents = {};
+  if (raw.components) {
+    for (const [name, spec] of Object.entries(raw.components)) {
+      rawComponents[name] = { ...spec };
+    }
+  }
   resolveReferences(raw);
   return {
     name: raw.name,
@@ -61,8 +67,10 @@ function parseDesignMd(content) {
     typography: raw.typography || {},
     spacing: normalizeStringValues(raw.spacing),
     rounded: normalizeStringValues(raw.rounded),
+    breakpoints: normalizeStringValues(raw.breakpoints),
     animations: raw.animations || {},
     components: raw.components || {},
+    rawComponents,
     rules: raw.rules || {}
   };
 }
@@ -122,11 +130,21 @@ function getMediaQuery(rule) {
   }
   return void 0;
 }
-function parseRules(css, sourceIndexOffset = 0) {
+function parseRules(css, sourceIndexOffset = 0, customProperties) {
   const rules = [];
   let ruleIndex = sourceIndexOffset;
   const root = postcss.parse(css);
   root.walkRules((rule) => {
+    if (customProperties && !getMediaQuery(rule)) {
+      const isRoot = rule.selectors.some((s) => s.trim() === ":root" || s.trim() === "html");
+      if (isRoot) {
+        rule.walkDecls((decl) => {
+          if (decl.prop.startsWith("--")) {
+            customProperties.set(decl.prop, decl.value);
+          }
+        });
+      }
+    }
     const declarations = [];
     rule.walkDecls((decl) => {
       declarations.push({
@@ -153,6 +171,19 @@ function parseRules(css, sourceIndexOffset = 0) {
   });
   return rules;
 }
+function resolveVarReferences(value, customProperties) {
+  return value.replace(
+    /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();
+      return _;
+    }
+  );
+}
 function parseInlineStyles(style) {
   const declarations = [];
   for (const part of style.split(";")) {
@@ -167,13 +198,19 @@ function parseInlineStyles(style) {
   }
   return declarations;
 }
-function matchesSelector(element, selector, root) {
-  try {
-    const matches = root.querySelectorAll(selector);
-    return matches.some((el) => el === element);
-  } catch {
-    return false;
+function buildSelectorCache(rules, root) {
+  const cache = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    if (cache.has(rule.selector))
+      continue;
+    try {
+      const matches = root.querySelectorAll(rule.selector);
+      cache.set(rule.selector, new Set(matches));
+    } catch {
+      cache.set(rule.selector, /* @__PURE__ */ new Set());
+    }
   }
+  return cache;
 }
 function compareSpecificity(a, b) {
   if (a[0] !== b[0])
@@ -182,9 +219,11 @@ function compareSpecificity(a, b) {
     return a[1] - b[1];
   return a[2] - b[2];
 }
-function resolveForElement(element, rules, root) {
+function resolveForElement(element, rules, selectorCache) {
   const resolved = {};
-  const matchingRules = rules.filter((rule) => matchesSelector(element, rule.selector, root));
+  const matchingRules = rules.filter(
+    (rule) => selectorCache.get(rule.selector)?.has(element) ?? false
+  );
   matchingRules.sort((a, b) => {
     const specCmp = compareSpecificity(a.specificity, b.specificity);
     if (specCmp !== 0)
@@ -231,15 +270,24 @@ function resolveForElement(element, rules, root) {
 function resolveCascade(cssSources, root) {
   let offset = 0;
   const allRules = [];
+  const customProperties = /* @__PURE__ */ new Map();
   for (const css of cssSources) {
-    const rules = parseRules(css, offset);
+    const rules = parseRules(css, offset, customProperties);
     allRules.push(...rules);
     offset += rules.length;
   }
+  const selectorCache = buildSelectorCache(allRules, root);
   const result = /* @__PURE__ */ new Map();
   function walk(el) {
-    const resolved = resolveForElement(el, allRules, root);
+    const resolved = resolveForElement(el, allRules, selectorCache);
     if (Object.keys(resolved).length > 0) {
+      if (customProperties.size > 0) {
+        for (const style of Object.values(resolved)) {
+          if (style.value.includes("var(")) {
+            style.value = resolveVarReferences(style.value, customProperties);
+          }
+        }
+      }
       result.set(el, resolved);
     }
     for (const child of el.childNodes) {
@@ -256,8 +304,9 @@ function resolveCascade(cssSources, root) {
 function resolveCascadeByBreakpoint(cssSources, root) {
   let offset = 0;
   const allRules = [];
+  const customProperties = /* @__PURE__ */ new Map();
   for (const css of cssSources) {
-    const rules = parseRules(css, offset);
+    const rules = parseRules(css, offset, customProperties);
     allRules.push(...rules);
     offset += rules.length;
   }
@@ -268,8 +317,15 @@ function resolveCascadeByBreakpoint(cssSources, root) {
   const result = /* @__PURE__ */ new Map();
   for (const breakpoint of breakpoints) {
     let walk = function(el) {
-      const resolved = resolveForElement(el, rulesForBreakpoint, root);
+      const resolved = resolveForElement(el, rulesForBreakpoint, selectorCache);
       if (Object.keys(resolved).length > 0) {
+        if (customProperties.size > 0) {
+          for (const style of Object.values(resolved)) {
+            if (style.value.includes("var(")) {
+              style.value = resolveVarReferences(style.value, customProperties);
+            }
+          }
+        }
         breakpointResult.set(el, resolved);
       }
       for (const child of el.childNodes) {
@@ -280,6 +336,7 @@ function resolveCascadeByBreakpoint(cssSources, root) {
     const rulesForBreakpoint = allRules.filter(
       (r) => r.mediaQuery === void 0 || r.mediaQuery === breakpoint
     );
+    const selectorCache = buildSelectorCache(rulesForBreakpoint, root);
     const breakpointResult = /* @__PURE__ */ new Map();
     for (const child of root.childNodes) {
       if (child.nodeType === 1)
@@ -289,29 +346,6 @@ function resolveCascadeByBreakpoint(cssSources, root) {
   }
   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))
@@ -445,10 +479,9 @@ function matchSpacing(value, spacingTokens) {
     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}`
+        suggestion: `Use a DESIGN.md spacing token`
       };
     }
   }
@@ -461,10 +494,9 @@ function matchRounded(value, roundedTokens) {
   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}`
+      suggestion: `Use a DESIGN.md rounded token`
     };
   }
   return { matches: true };
@@ -500,7 +532,7 @@ function matchTypographyProperty(property, value, typographyTokens) {
   }
   return {
     matches: false,
-    suggestion: `Value "${value}" for ${property} not in typography tokens`
+    suggestion: `Use a DESIGN.md typography token`
   };
 }
 function matchAnimationDuration(value, animationTokens) {
@@ -516,10 +548,9 @@ function matchAnimationDuration(value, animationTokens) {
     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}`
+    suggestion: `Use a DESIGN.md animation preset duration`
   };
 }
 function matchAnimationEasing(value, animationTokens) {
@@ -540,14 +571,13 @@ function matchAnimationEasing(value, animationTokens) {
     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}`
+    suggestion: `Use a DESIGN.md animation preset easing`
   };
 }
-function matchComponent(elementStyles, componentSpec, componentName) {
-  const findings = [];
+function matchComponent(elementStyles, componentSpec, rawSpec) {
+  const mismatches = [];
   const propertyMapping = {
     backgroundColor: "background-color",
     textColor: "color",
@@ -562,13 +592,72 @@ function matchComponent(elementStyles, componentSpec, componentName) {
     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}"`
+      const rawValue = rawSpec?.[specProp];
+      mismatches.push({
+        cssProp,
+        expected: expectedValue,
+        expectedRaw: rawValue !== expectedValue ? rawValue : void 0,
+        actual: actualValue
       });
     }
   }
-  return findings;
+  return mismatches;
+}
+function formatComponentMismatches(componentName, mismatches, elementDescription) {
+  const specPath = `DESIGN.md components.${componentName}`;
+  const header = elementDescription ? `${specPath} on ${elementDescription}:` : `${specPath}:`;
+  const lines = [header];
+  for (let i = 0; i < mismatches.length; i++) {
+    const m = mismatches[i];
+    const expectedDisplay = m.expectedRaw ? `${m.expectedRaw} (${m.expected})` : `"${m.expected}"`;
+    lines.push(`  ${i + 1}. ${m.cssProp} should be ${expectedDisplay}, found "${m.actual}"`);
+  }
+  return lines.join("\n");
+}
+function isBackgroundShorthand(property) {
+  return property === "background";
+}
+function splitTopLevelCommas(value) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of value) {
+    if (ch === "(" || ch === "[")
+      depth++;
+    else if (ch === ")" || ch === "]")
+      depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim())
+    parts.push(current.trim());
+  return parts;
+}
+function extractBackgroundColors(value) {
+  if (value.startsWith("var(") || value === "transparent" || value === "none" || value === "inherit" || value === "initial" || value === "unset") {
+    return [];
+  }
+  const layers = splitTopLevelCommas(value);
+  const colors = [];
+  for (const layer of layers) {
+    if (/^(linear-gradient|radial-gradient|conic-gradient|repeating-|url)\s*\(/i.test(layer)) {
+      continue;
+    }
+    const hexMatch = layer.match(/(^|\s)(#[0-9a-fA-F]{3,8})(\s|$)/);
+    if (hexMatch) {
+      colors.push(hexMatch[2]);
+      continue;
+    }
+    const rgbMatch = layer.match(/(^|\s)(rgba?\s*\([^)]+\))/);
+    if (rgbMatch) {
+      colors.push(rgbMatch[2]);
+    }
+  }
+  return colors;
 }
 function hexToRgbValues(hex) {
   const normalized = normalizeHex(hex);
@@ -591,15 +680,25 @@ function contrastRatio(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.`;
+const GUIDE_SUGGESTION$1 = "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");
+  const text = el.textContent?.trim();
+  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}"`);
+  parts.push(">");
+  if (truncated)
+    parts.push(`"${truncated}"`);
+  return parts.join(" ");
 }
 function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath, findings) {
-  const tag = el.rawTagName?.toLowerCase() || "element";
+  const hint = elementHint(el);
   const prefix = breakpointLabel ? `[${breakpointLabel}] ` : "";
-  const refs = ref(designMdPath);
+  const sug = (s) => s?.replace("DESIGN.md", designMdPath);
   for (const [property, resolved] of Object.entries(styles)) {
     if (resolved.allowed)
       continue;
@@ -608,9 +707,9 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
       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}>`
+          message: `${prefix}${hint} — Hardcoded color "${resolved.value}" for ${property} not in design system`,
+          suggestion: sug(result.suggestion),
+          element: hint
         });
       }
     }
@@ -619,9 +718,9 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
       if (!result.matches) {
         findings.push({
           severity: "warning",
-          message: `${prefix}${property} value "${resolved.value}" not in spacing scale`,
-          suggestion: result.suggestion + refs,
-          element: `<${tag}>`
+          message: `${prefix}${hint} — ${property} value "${resolved.value}" not in spacing scale`,
+          suggestion: sug(result.suggestion),
+          element: hint
         });
       }
     }
@@ -630,9 +729,9 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
       if (!result.matches) {
         findings.push({
           severity: "warning",
-          message: `${prefix}border-radius "${resolved.value}" not in rounded scale`,
-          suggestion: result.suggestion + refs,
-          element: `<${tag}>`
+          message: `${prefix}${hint} — border-radius "${resolved.value}" not in rounded scale`,
+          suggestion: sug(result.suggestion),
+          element: hint
         });
       }
     }
@@ -641,9 +740,9 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
       if (!result.matches) {
         findings.push({
           severity: "warning",
-          message: `${prefix}${property} value "${resolved.value}" not in typography tokens`,
-          suggestion: result.suggestion + refs,
-          element: `<${tag}>`
+          message: `${prefix}${hint} — ${property} value "${resolved.value}" not in typography tokens`,
+          suggestion: sug(result.suggestion),
+          element: hint
         });
       }
     }
@@ -652,9 +751,9 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
       if (!result.matches) {
         findings.push({
           severity: "warning",
-          message: `${prefix}${property} "${resolved.value}" not in animation presets`,
-          suggestion: result.suggestion + refs,
-          element: `<${tag}>`
+          message: `${prefix}${hint} — ${property} "${resolved.value}" not in animation presets`,
+          suggestion: sug(result.suggestion),
+          element: hint
         });
       }
     }
@@ -663,12 +762,26 @@ function validateElementStyles(el, styles, tokens, breakpointLabel, designMdPath
       if (!result.matches) {
         findings.push({
           severity: "warning",
-          message: `${prefix}${property} "${resolved.value}" not in animation presets`,
-          suggestion: result.suggestion + refs,
-          element: `<${tag}>`
+          message: `${prefix}${hint} — ${property} "${resolved.value}" not in animation presets`,
+          suggestion: sug(result.suggestion),
+          element: hint
         });
       }
     }
+    if (isBackgroundShorthand(property) && Object.keys(tokens.colors).length > 0) {
+      const bgColors = extractBackgroundColors(resolved.value);
+      for (const bgColor of bgColors) {
+        const result = matchColor(bgColor, tokens.colors);
+        if (!result.matches) {
+          findings.push({
+            severity: "warning",
+            message: `${prefix}${hint} — Hardcoded color "${bgColor}" in background not in design system`,
+            suggestion: sug(result.suggestion),
+            element: hint
+          });
+        }
+      }
+    }
   }
 }
 const validateTokens = (ctx) => {
@@ -677,18 +790,39 @@ const validateTokens = (ctx) => {
     return [];
   const { tokens, designMdPath } = found;
   const findings = [];
-  const cssSources = extractCssSources(ctx.body, ctx.filePath);
-  if (cssSources.length === 0)
+  if (!ctx.css)
     return [];
+  const cssSources = [ctx.css];
+  const breakpointNames = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(tokens.breakpoints)) {
+    breakpointNames.set(`(max-width: ${value})`, name);
+  }
+  const hasBreakpoints = Object.keys(tokens.breakpoints).length > 0;
+  const flaggedBreakpoints = /* @__PURE__ */ new Set();
   const byBreakpoint = resolveCascadeByBreakpoint(cssSources, ctx.body);
   for (const [breakpoint, cascade] of byBreakpoint) {
-    const label = breakpoint || "";
+    if (breakpoint && hasBreakpoints && breakpoint.includes("max-width") && !breakpointNames.has(breakpoint)) {
+      if (!flaggedBreakpoints.has(breakpoint)) {
+        flaggedBreakpoints.add(breakpoint);
+        const defined = Object.entries(tokens.breakpoints).map(([n, v]) => `${n} (${v})`).join(", ");
+        findings.push({
+          severity: "warning",
+          message: `Media query @media ${breakpoint} not in DESIGN.md breakpoints`,
+          suggestion: `Use a ${designMdPath} breakpoint: ${defined}`
+        });
+      }
+    }
+    const name = breakpoint ? breakpointNames.get(breakpoint) : void 0;
+    const label = name ? `${name}` : 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);
+    checkReducedMotion(cssSources, findings);
+  }
+  if (findings.length > 0) {
+    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION$1 });
   }
   return findings;
 };
@@ -700,7 +834,7 @@ const ANIMATION_PROPERTIES = /* @__PURE__ */ new Set([
   "animation-duration",
   "animation-name"
 ]);
-function checkReducedMotion(cssSources, designMdPath, findings) {
+function checkReducedMotion(cssSources, findings) {
   let hasAnimations = false;
   let hasReducedMotion = false;
   for (const css of cssSources) {
@@ -720,21 +854,35 @@ function checkReducedMotion(cssSources, designMdPath, findings) {
     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)
+      suggestion: "Add @media (prefers-reduced-motion: reduce) { * { transition-duration: 0s !important; animation-duration: 0s !important; } }"
     });
   }
 }
-const DESIGNER_GUIDE$2 = "agent-kit/designer/design-system.md";
+const GUIDE_SUGGESTION = "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}"`);
+  parts.push(">");
+  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 [];
   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);
+  if (!ctx.css)
+    return [];
+  const cascade = resolveCascade([ctx.css], ctx.body);
   const jayComponents = /* @__PURE__ */ new Map();
   const htmlComponents = /* @__PURE__ */ new Map();
   for (const componentName of Object.keys(tokens.components)) {
@@ -764,6 +912,7 @@ See ${designMdPath} for component specs, ${DESIGNER_GUIDE$2} for usage guide.`;
   for (const [contractName, elements] of jayComponents) {
     const componentName = `jay:${contractName}`;
     const spec = tokens.components[componentName];
+    const rawSpec = tokens.rawComponents[componentName];
     if (!spec)
       continue;
     for (const el of elements) {
@@ -775,21 +924,21 @@ See ${designMdPath} for component specs, ${DESIGNER_GUIDE$2} for usage guide.`;
         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"}>`
-          });
-        }
+      const mismatches = matchComponent(styleValues, spec, rawSpec);
+      if (mismatches.length > 0) {
+        const desc = describeElement(el);
+        findings.push({
+          severity: "warning",
+          message: formatComponentMismatches(componentName, mismatches, desc),
+          suggestion: `See ${designMdPath} components section`,
+          element: desc
+        });
       }
     }
   }
   for (const [componentName, selector] of htmlComponents) {
     const spec = tokens.components[componentName];
+    const rawSpec = tokens.rawComponents[componentName];
     if (!spec)
       continue;
     for (const [el, styles] of cascade) {
@@ -805,33 +954,31 @@ See ${designMdPath} for component specs, ${DESIGNER_GUIDE$2} for usage guide.`;
         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"}>`
-          });
-        }
+      const mismatches = matchComponent(styleValues, spec, rawSpec);
+      if (mismatches.length > 0) {
+        const desc = describeElement(el);
+        findings.push({
+          severity: "warning",
+          message: formatComponentMismatches(componentName, mismatches, desc),
+          suggestion: `See ${designMdPath} components section`,
+          element: desc
+        });
       }
     }
   }
+  if (findings.length > 0) {
+    findings.push({ severity: "warning", message: "", suggestion: GUIDE_SUGGESTION });
+  }
   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 { tokens } = found;
   const findings = [];
-  if (tokens.rules["max-font-weights"]) {
-    const cssSources = extractCssSources(ctx.body, ctx.filePath);
-    const cascade = resolveCascade(cssSources, ctx.body);
+  if (tokens.rules["max-font-weights"] && ctx.css) {
+    const cascade = resolveCascade([ctx.css], ctx.body);
     const fontWeights = /* @__PURE__ */ new Set();
     for (const [, styles] of cascade) {
       const fw = styles["font-weight"];
@@ -843,7 +990,7 @@ See ${designMdPath} for rules, ${DESIGNER_GUIDE$1} for usage guide.`;
       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}`
+        suggestion: `Reduce to ${max} font-weight values from the DESIGN.md typography tokens`
       });
     }
   }
@@ -856,9 +1003,9 @@ See ${designMdPath} for rules, ${DESIGNER_GUIDE$1} for usage guide.`;
       const classes = el.getAttribute?.("class") || "";
       if (!classes.includes("primary") && !classes.includes("btn-primary"))
         return;
-      const ref2 = el.getAttribute?.("ref") || "";
+      const ref = el.getAttribute?.("ref") || "";
       const text = el.textContent?.trim() || "";
-      const identity = `${ref2}|${text}`;
+      const identity = `${ref}|${text}`;
       primaryButtons.set(identity, true);
     });
     const max = tokens.rules["max-primary-buttons"];
@@ -866,13 +1013,12 @@ See ${designMdPath} for rules, ${DESIGNER_GUIDE$1} for usage guide.`;
       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}`
+        suggestion: `Reduce to ${max} primary action button per page`
       });
     }
   }
   return findings;
 };
-const DESIGNER_GUIDE = "agent-kit/designer/design-system.md";
 function resolveColorValue(value) {
   if (value.startsWith("#"))
     return value;
@@ -904,14 +1050,10 @@ 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)
+  if (!ctx.css)
     return [];
-  const cascade = resolveCascade(cssSources, ctx.body);
+  const cascade = resolveCascade([ctx.css], ctx.body);
   for (const [el, styles] of cascade) {
     const colorStyle = styles["color"];
     const bgStyle = styles["background-color"] || styles["background"];
@@ -937,7 +1079,7 @@ See ${designMdPath} for color tokens, ${DESIGNER_GUIDE} for usage guide.`;
       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}`,
+        suggestion: "Darken text color or lighten background to meet minimum contrast",
         element: `<${tag}>`
       });
     }
@@ -945,99 +1087,187 @@ See ${designMdPath} for color tokens, ${DESIGNER_GUIDE} for usage guide.`;
   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 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";
 }
-function buildTypographyItems(tokens) {
-  const entries = Object.entries(tokens.typography);
-  if (entries.length === 0)
-    return [];
-  const presets = entries.map(([name, t]) => {
-    const parts = [`${name}:`];
+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]) => ({
+    id: `design-system:color-${name}`,
+    title: `${name} (${value})`,
+    category,
+    subCategory: "Colors",
+    prompt: `Use color token "${name}" with value ${value} from DESIGN.md.`,
+    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>`
+  }));
+}
+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}`);
-    return parts.join(" ");
-  }).join("; ");
-  return [
-    {
-      id: "design-system:typography",
-      title: "Typography presets",
-      category: "Design System",
+    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 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.`
-    }
-  ];
+      prompt: `Apply typography preset "${name}" from DESIGN.md: ${desc}.`,
+      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) {
-  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 buildSpacingItems(tokens, category) {
+  return Object.entries(tokens.spacing).map(([name, value]) => ({
+    id: `design-system:spacing-${name}`,
+    title: `${name} (${value})`,
+    category,
+    subCategory: "Spacing",
+    prompt: `Use spacing token "${name}" with value ${value} from DESIGN.md for padding, margin, or gap.`,
+    html: `<div style="display:flex;align-items:center;gap:8px;font-family:sans-serif;">
+  <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>`
+  }));
 }
-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 buildRoundedItems(tokens, category) {
+  return Object.entries(tokens.rounded).map(([name, value]) => ({
+    id: `design-system:rounded-${name}`,
+    title: `${name} (${value})`,
+    category,
+    subCategory: "Rounded",
+    prompt: `Use border-radius token "${name}" with value ${value} from DESIGN.md.`,
+    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>`
+  }));
+}
+function buildBreakpointItems(tokens, category) {
+  return Object.entries(tokens.breakpoints).map(([name, value]) => ({
+    id: `design-system:breakpoint-${name}`,
+    title: `${name} (${value})`,
+    category,
+    subCategory: "Breakpoints",
+    prompt: `Use breakpoint "${name}" at max-width ${value} from DESIGN.md: @media (max-width: ${value}) { ... }`
+  }));
+}
+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);
+    const desc = parts.join(", ");
+    const dur = preset.duration || "300ms";
+    const ease = preset.easing || "ease";
+    return {
+      id: `design-system:animation-${name}`,
+      title: name,
+      category,
+      subCategory: "Animations",
+      prompt: `Use animation preset "${name}" from DESIGN.md: ${desc}. Apply to transition-duration and transition-timing-function.`,
+      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;">
+    <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>`
+    };
+  });
 }
-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}`;
+function buildComponentItems(tokens, category) {
+  return Object.entries(tokens.components).map(([name, spec]) => {
+    const rawSpec = tokens.rawComponents[name];
+    const props = Object.entries(spec).map(([prop, value]) => {
+      const raw = rawSpec?.[prop];
+      return raw && raw !== value ? `${prop}: ${raw} (${value})` : `${prop}: ${value}`;
+    }).join(", ");
+    const previewStyles = [];
+    const propertyMapping = {
+      backgroundColor: "background-color",
+      textColor: "color",
+      rounded: "border-radius",
+      padding: "padding",
+      borderColor: "border-color"
+    };
+    for (const [prop, value] of Object.entries(spec)) {
+      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);
     return {
       id: `design-system:component-${name}`,
-      title,
-      category: "Design System",
+      title: name,
+      category,
       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.`
+      prompt: `Apply the "${name}" component spec from DESIGN.md. Required styles: ${props}. The design-system validator will flag mismatches.`,
+      html: `<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>`
     };
   });
 }
@@ -1061,10 +1291,10 @@ function findAllDesignMdFiles(projectRoot) {
   }
   return files;
 }
-async function generateDesignSystemReferences(ctx) {
+async function generateDesignSystemAgentKit(ctx) {
   const designMdFiles = findAllDesignMdFiles(ctx.projectRoot);
   if (designMdFiles.length === 0) {
-    return { referencesCreated: [], message: "No DESIGN.md found in project" };
+    return { agentKitCreated: [], message: "No DESIGN.md found in project" };
   }
   const allItems = [];
   const seen = /* @__PURE__ */ new Set();
@@ -1073,12 +1303,15 @@ async function generateDesignSystemReferences(ctx) {
     const tokens = parseDesignMd(content);
     if (!tokens)
       continue;
+    const category = categoryName(filePath, ctx.projectRoot, tokens);
     const items = [
-      ...buildColorItems(tokens),
-      ...buildTypographyItems(tokens),
-      ...buildSpacingItems(tokens),
-      ...buildRoundedItems(tokens),
-      ...buildComponentItems(tokens)
+      ...buildColorItems(tokens, category),
+      ...buildTypographyItems(tokens, category),
+      ...buildSpacingItems(tokens, category),
+      ...buildRoundedItems(tokens, category),
+      ...buildBreakpointItems(tokens, category),
+      ...buildAnimationItems(tokens, category),
+      ...buildComponentItems(tokens, category)
     ];
     for (const item of items) {
       if (!seen.has(item.id)) {
@@ -1088,18 +1321,18 @@ async function generateDesignSystemReferences(ctx) {
     }
   }
   if (allItems.length === 0) {
-    return { referencesCreated: [], message: "DESIGN.md found but no tokens defined" };
+    return { agentKitCreated: [], 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`
+    agentKitCreated: [ADD_MENU_OUTPUT_REL],
+    message: `Generated ${allItems.length} add-menu items from ${designMdFiles.length} DESIGN.md file(s)`
   };
 }
 export {
-  generateDesignSystemReferences,
+  generateDesignSystemAgentKit,
   validateComponents,
   validateContrast,
   validateStructure,

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@jay-framework/design-system-validator",
-  "version": "0.21.0",
+  "version": "0.22.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"
+    "plugin.yaml",
+    "agent-kit"
   ],
   "exports": {
     ".": "./dist/index.js",
@@ -25,15 +26,15 @@
   },
   "dependencies": {
     "@csstools/selector-specificity": "^5.0.0",
-    "@jay-framework/compiler-shared": "^0.21.0",
-    "@jay-framework/stack-server-runtime": "^0.21.0",
+    "@jay-framework/compiler-shared": "^0.22.0",
+    "@jay-framework/stack-server-runtime": "^0.22.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",
+    "@jay-framework/dev-environment": "^0.22.0",
+    "@jay-framework/jay-stack-cli": "^0.22.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.21",
     "node-html-parser": "^6.1.0",

package/plugin.yaml

@@ -1,8 +1,7 @@
 name: design-system-validator
 
-setup:
-  references: generateDesignSystemReferences
-  description: Generate AIditor add-menu entries from DESIGN.md tokens
+agentkit: generateDesignSystemAgentKit
+description: Generate AIditor add-menu entries from DESIGN.md tokens
 
 validators:
   - name: design-tokens