@jay-framework/design-system-validator 0.24.0 → 0.24.2

package/dist/index.js

@@ -752,15 +752,16 @@ const validateTokens = (ctx) => {
   const hasBreakpoints = Object.keys(tokens.breakpoints).length > 0;
   const flaggedBreakpoints = /* @__PURE__ */ new Set();
   const byBreakpoint = resolveCascadeByBreakpoint(cssSources, ctx.body);
+  const dsOverrides = ctx.validationOverrides?.["design-system"];
   for (const [breakpoint, cascade] of byBreakpoint) {
-    if (breakpoint && hasBreakpoints && breakpoint.includes("max-width") && !breakpointNames.has(breakpoint)) {
+    if (breakpoint && hasBreakpoints && breakpoint.includes("max-width") && !breakpointNames.has(breakpoint) && !dsOverrides?.["allow-custom-breakpoints"]) {
       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}`
+          suggestion: `Use a ${designMdPath} breakpoint: ${defined}. If intentional, suppress with design-system: { allow-custom-breakpoints: true } in <script type="application/jay-validations">. See agent-kit/designer/validation-guide.md`
         });
       }
     }
@@ -770,7 +771,7 @@ const validateTokens = (ctx) => {
       validateElementStyles(el, styles, tokens, label, designMdPath, findings);
     }
   }
-  if (Object.keys(tokens.animations).length > 0) {
+  if (Object.keys(tokens.animations).length > 0 && !dsOverrides?.["allow-no-reduced-motion"]) {
     checkReducedMotion(cssSources, findings);
   }
   if (findings.length > 0) {
@@ -806,7 +807,7 @@ function checkReducedMotion(cssSources, 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; } }"
+      suggestion: 'Add @media (prefers-reduced-motion: reduce) { * { transition-duration: 0s !important; animation-duration: 0s !important; } }. If intentional, suppress with design-system: { allow-no-reduced-motion: true } in <script type="application/jay-validations">. See agent-kit/designer/validation-guide.md'
     });
   }
 }
@@ -1158,12 +1159,12 @@ const validateFontFallbacks = (ctx) => {
       (ff) => ff.hasLocalSrc && ff.hasMetricOverrides && ff.family.startsWith(family) && ff.family !== family
     );
     const familyItselfIsMetricMatched = metricMatchedFallbacks.has(family);
-    if (!hasFallbackFace && !familyItselfIsMetricMatched) {
+    if (!hasFallbackFace && !familyItselfIsMetricMatched && !ctx.validationOverrides?.["design-system"]?.["allow-font-no-fallback"]) {
       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"}'`
+        suggestion: `Generate a fallback with: npx jay-stack-cli action design-system-validator/fontFallback --input '{"primary":"${family}","fallback":"Arial"}'. If intentional, suppress with design-system: { allow-font-no-fallback: true } in <script type="application/jay-validations">. See agent-kit/designer/validation-guide.md`
       });
     }
   }
@@ -1197,8 +1198,21 @@ function hasAllowComment(decl) {
   }
   return false;
 }
+function findSource(decl, root) {
+  const before = root.toString().substring(0, decl.source?.start?.offset ?? 0);
+  const componentMatch = before.match(/\/\* Component: (\S+) \*\//g);
+  if (componentMatch) {
+    const last = componentMatch[componentMatch.length - 1];
+    const name = last.match(/\/\* Component: (\S+) \*\//)?.[1];
+    if (name) return name;
+  }
+  return "";
+}
 const validateUndefinedVars = (ctx) => {
   if (!ctx.css) return [];
+  if (!ctx.filePath.includes("/pages/") && !ctx.filePath.startsWith("src/pages/")) {
+    return [];
+  }
   const findings = [];
   const definedVars = /* @__PURE__ */ new Set();
   const usedVars = /* @__PURE__ */ new Map();
@@ -1217,6 +1231,7 @@ const validateUndefinedVars = (ctx) => {
           usedVars.set(varName, {
             property: decl.prop,
             selector,
+            source: findSource(decl, root),
             hasFallback: match[2] !== void 0,
             fallbackValue: match[2]?.trim()
           });
@@ -1227,9 +1242,10 @@ const validateUndefinedVars = (ctx) => {
   for (const [varName, usage] of usedVars) {
     if (definedVars.has(varName)) continue;
     const fallbackNote = usage.hasFallback ? ` (falls back to "${usage.fallbackValue}")` : "";
+    const message = usage.source ? `CSS variable "${varName}" used by component "${usage.source}" is not defined${fallbackNote} — add it to the page's CSS or a linked stylesheet` : `CSS variable "${varName}" is used but never defined${fallbackNote}`;
     findings.push({
       severity: "warning",
-      message: `CSS variable "${varName}" is used but never defined${fallbackNote}`,
+      message,
       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.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/design-system-validator",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "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.24.0",
-    "@jay-framework/compiler-shared": "^0.24.0",
-    "@jay-framework/component": "^0.24.0",
-    "@jay-framework/fullstack-component": "^0.24.0",
-    "@jay-framework/plugin-validator": "^0.24.0",
-    "@jay-framework/stack-server-runtime": "^0.24.0",
+    "@jay-framework/compiler-jay-html": "^0.24.2",
+    "@jay-framework/compiler-shared": "^0.24.2",
+    "@jay-framework/component": "^0.24.2",
+    "@jay-framework/fullstack-component": "^0.24.2",
+    "@jay-framework/plugin-validator": "^0.24.2",
+    "@jay-framework/stack-server-runtime": "^0.24.2",
     "js-yaml": "^4.1.0",
     "postcss": "^8.5.6",
     "postcss-selector-parser": "^7.1.0"
   },
   "devDependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.24.0",
-    "@jay-framework/dev-environment": "^0.24.0",
-    "@jay-framework/jay-cli": "^0.24.0",
-    "@jay-framework/jay-stack-cli": "^0.24.0",
+    "@jay-framework/compiler-jay-stack": "^0.24.2",
+    "@jay-framework/dev-environment": "^0.24.2",
+    "@jay-framework/jay-cli": "^0.24.2",
+    "@jay-framework/jay-stack-cli": "^0.24.2",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.21",
     "node-html-parser": "^6.1.0",