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

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

@@ -97,7 +97,7 @@ Use the token values directly in your `<style>` blocks:
 }
 ```
 
-CSS custom properties (`var(--name)`) are resolved statically when defined in `:root`. Unresolvable vars are accepted without validation.
+CSS custom properties (`var(--name)`) are resolved statically when defined in the page's CSS (inline `<style>` or linked local stylesheets). Variables that are used but never defined are flagged as warnings.
 
 ## Breakpoints
 
@@ -132,12 +132,18 @@ The `components` section defines expected styles for HTML elements (matched by c
 
 When a value intentionally breaks the design system, exempt it:
 
-**In CSS** — add a comment after the declaration:
+**In CSS** — add a comment on the same line or the line immediately after the declaration:
 
 ```css
 .hero {
   padding: 7.5rem 0; /* design-system: allow */
 }
+
+/* or on the next line: */
+.hero {
+  padding: 7.5rem 0;
+  /* design-system: allow */
+}
 ```
 
 **On elements** — add the `jay-design="allow"` attribute:
@@ -213,6 +219,14 @@ These are the errors the validator produces. Use them to align your CSS with the
   Suggestion: Use a DESIGN.md breakpoint: mobile (600px), tablet (768px), desktop (1024px)
 ```
 
+**Undefined CSS variable:**
+
+```
+⚠ CSS variable "--color-surface-tint" is used but never defined
+  Suggestion: Define --color-surface-tint in a :root block, or replace with a DESIGN.md token value directly.
+  To suppress: add /* design-system: allow */ on the same line or the line after the declaration.
+```
+
 **Low contrast:**
 
 ```

package/dist/index.d.ts

@@ -15,6 +15,8 @@ declare const validateContrast: JayHtmlValidatorFn;
 
 declare const validateFontFallbacks: JayHtmlValidatorFn;
 
+declare const validateUndefinedVars: JayHtmlValidatorFn;
+
 interface FontFallbackInput {
     primary: string;
     fallback: string;
@@ -106,4 +108,4 @@ declare const regenerateDesignSystemAddMenu: _jay_framework_fullstack_component.
     message: any;
 }, []>;
 
-export { ADD_MENU_GENERATED_REL, fontFallback, generateDesignSystemAgentKit, getDesignSystemSettingsStatus, loadDesignSystemAddMenuCatalog, regenerateDesignSystemAddMenu, runDesignSystemAnalysisAction as runDesignSystemAnalysis, saveDesignSystemAddMenuCatalog, validateComponents, validateContrast, validateFontFallbacks, validateStructure, validateTokens };
+export { ADD_MENU_GENERATED_REL, fontFallback, generateDesignSystemAgentKit, getDesignSystemSettingsStatus, loadDesignSystemAddMenuCatalog, regenerateDesignSystemAddMenu, runDesignSystemAnalysisAction as runDesignSystemAnalysis, saveDesignSystemAddMenuCatalog, validateComponents, validateContrast, validateFontFallbacks, validateStructure, validateTokens, validateUndefinedVars };

package/dist/index.js

@@ -91,7 +91,7 @@ function findDesignMd(filePath, projectRoot) {
   }
   return null;
 }
-const ALLOW_COMMENT = "design-system: allow";
+const ALLOW_COMMENT$1 = "design-system: allow";
 function computeSpecificity(selector) {
   let result = [0, 0, 0];
   selectorParser((selectors) => {
@@ -103,15 +103,15 @@ function computeSpecificity(selector) {
   }).processSync(selector);
   return result;
 }
-function hasAllowComment(decl) {
+function hasAllowComment$1(decl) {
   const next = decl.next();
-  if (next?.type === "comment" && next.text.trim() === ALLOW_COMMENT) {
+  if (next?.type === "comment" && next.text.trim() === ALLOW_COMMENT$1) {
     return true;
   }
   const raw = decl.raws.value;
   if (raw && typeof raw === "object" && "raw" in raw) {
     const rawStr = raw.raw;
-    if (rawStr.includes(`/*${ALLOW_COMMENT}*/`) || rawStr.includes(`/* ${ALLOW_COMMENT} */`)) {
+    if (rawStr.includes(`/*${ALLOW_COMMENT$1}*/`) || rawStr.includes(`/* ${ALLOW_COMMENT$1} */`)) {
       return true;
     }
   }
@@ -148,7 +148,7 @@ function parseRules(css, sourceIndexOffset = 0, customProperties) {
         property: decl.prop,
         value: decl.value,
         important: decl.important,
-        allowed: hasAllowComment(decl)
+        allowed: hasAllowComment$1(decl)
       });
     });
     const mediaQuery = getMediaQuery(rule);
@@ -1181,6 +1181,62 @@ const validateFontFallbacks = (ctx) => {
   }
   return findings;
 };
+const ALLOW_COMMENT = "design-system: allow";
+const VAR_REGEX = /var\(\s*(--[a-zA-Z0-9-]+)(?:\s*,\s*([^)]+))?\s*\)/g;
+function hasAllowComment(decl) {
+  const next = decl.next();
+  if (next?.type === "comment" && next.text.trim() === ALLOW_COMMENT) {
+    return true;
+  }
+  const raw = decl.raws.value;
+  if (raw && typeof raw === "object" && "raw" in raw) {
+    const rawStr = raw.raw;
+    if (rawStr.includes(`/*${ALLOW_COMMENT}*/`) || rawStr.includes(`/* ${ALLOW_COMMENT} */`)) {
+      return true;
+    }
+  }
+  return false;
+}
+const validateUndefinedVars = (ctx) => {
+  if (!ctx.css) return [];
+  const findings = [];
+  const definedVars = /* @__PURE__ */ new Set();
+  const usedVars = /* @__PURE__ */ new Map();
+  const root = postcss.parse(ctx.css);
+  root.walkDecls((decl) => {
+    if (decl.prop.startsWith("--")) {
+      definedVars.add(decl.prop);
+    }
+    if (decl.value.includes("var(") && !hasAllowComment(decl)) {
+      const selector = decl.parent && "selector" in decl.parent ? decl.parent.selector : "[unknown]";
+      let match;
+      VAR_REGEX.lastIndex = 0;
+      while ((match = VAR_REGEX.exec(decl.value)) !== null) {
+        const varName = match[1];
+        if (!usedVars.has(varName)) {
+          usedVars.set(varName, {
+            property: decl.prop,
+            selector,
+            hasFallback: match[2] !== void 0,
+            fallbackValue: match[2]?.trim()
+          });
+        }
+      }
+    }
+  });
+  for (const [varName, usage] of usedVars) {
+    if (definedVars.has(varName)) continue;
+    const fallbackNote = usage.hasFallback ? ` (falls back to "${usage.fallbackValue}")` : "";
+    findings.push({
+      severity: "warning",
+      message: `CSS variable "${varName}" is used but never defined${fallbackNote}`,
+      suggestion: `Define ${varName} in a :root block, or replace with a DESIGN.md token value directly.
+To suppress: add /* design-system: allow */ on the same line or the line after the declaration.
+See agent-kit/designer/design-system.md for usage guide.`
+    });
+  }
+  return findings;
+};
 async function loadMetrics(familyName) {
   const camelCase = fontFamilyToCamelCase(familyName);
   try {
@@ -1823,5 +1879,6 @@ export {
   validateContrast,
   validateFontFallbacks,
   validateStructure,
-  validateTokens
+  validateTokens,
+  validateUndefinedVars
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/design-system-validator",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "type": "module",
   "description": "Design system validation plugin for Jay Framework — validates jay-html CSS against DESIGN.md tokens",
   "license": "Apache-2.0",
@@ -36,21 +36,21 @@
     "@capsizecss/metrics": "^4.2.0",
     "@capsizecss/unpack": "^4.0.1",
     "@csstools/selector-specificity": "^5.0.0",
-    "@jay-framework/compiler-jay-html": "^0.23.1",
-    "@jay-framework/compiler-shared": "^0.23.1",
-    "@jay-framework/component": "^0.23.1",
-    "@jay-framework/fullstack-component": "^0.23.1",
-    "@jay-framework/plugin-validator": "^0.23.1",
-    "@jay-framework/stack-server-runtime": "^0.23.1",
+    "@jay-framework/compiler-jay-html": "^0.24.1",
+    "@jay-framework/compiler-shared": "^0.24.1",
+    "@jay-framework/component": "^0.24.1",
+    "@jay-framework/fullstack-component": "^0.24.1",
+    "@jay-framework/plugin-validator": "^0.24.1",
+    "@jay-framework/stack-server-runtime": "^0.24.1",
     "js-yaml": "^4.1.0",
     "postcss": "^8.5.6",
     "postcss-selector-parser": "^7.1.0"
   },
   "devDependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.23.1",
-    "@jay-framework/dev-environment": "^0.23.1",
-    "@jay-framework/jay-cli": "^0.23.1",
-    "@jay-framework/jay-stack-cli": "^0.23.1",
+    "@jay-framework/compiler-jay-stack": "^0.24.1",
+    "@jay-framework/dev-environment": "^0.24.1",
+    "@jay-framework/jay-cli": "^0.24.1",
+    "@jay-framework/jay-stack-cli": "^0.24.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.21",
     "node-html-parser": "^6.1.0",

package/plugin.yaml

@@ -39,3 +39,7 @@ validators:
   - name: font-fallbacks
     handler: validateFontFallbacks
     description: Detects web fonts loaded via @font-face URL without a metric-matched local fallback (causes CLS)
+
+  - name: undefined-vars
+    handler: validateUndefinedVars
+    description: Flags CSS var(--name) references that are never defined as custom properties