@wireweave/ux-rules 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1236 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  allRules: () => allRules,
+  formatUXResult: () => formatUXResult,
+  getRulesForCategories: () => getRulesForCategories,
+  getUXIssues: () => getUXIssues,
+  getUXScore: () => getUXScore,
+  isUXValid: () => isUXValid,
+  rulesByCategory: () => rulesByCategory,
+  validateUX: () => validateUX
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/rules/accessibility.ts
+var inputRequiresLabel = {
+  id: "a11y-input-label",
+  category: "accessibility",
+  severity: "error",
+  name: "Input requires label",
+  description: "All input fields must have a label for screen reader users",
+  appliesTo: ["Input", "Textarea", "Select"],
+  check: (node, context) => {
+    const hasLabel = "label" in node && node.label;
+    const hasPlaceholder = "placeholder" in node && node.placeholder;
+    if (!hasLabel) {
+      return {
+        ruleId: "a11y-input-label",
+        category: "accessibility",
+        severity: hasPlaceholder ? "warning" : "error",
+        message: `${node.type} is missing a label`,
+        description: "Screen readers rely on labels to describe form fields to users",
+        suggestion: hasPlaceholder ? "Add a label attribute. Placeholder alone is not sufficient for accessibility" : "Add a label attribute to describe this field",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var imageRequiresAlt = {
+  id: "a11y-image-alt",
+  category: "accessibility",
+  severity: "warning",
+  name: "Image requires alt text",
+  description: "Images should have alt text for screen reader users",
+  appliesTo: ["Image"],
+  check: (node, context) => {
+    const hasAlt = "alt" in node && node.alt;
+    if (!hasAlt) {
+      return {
+        ruleId: "a11y-image-alt",
+        category: "accessibility",
+        severity: "warning",
+        message: "Image is missing alt text",
+        description: "Screen readers use alt text to describe images to users",
+        suggestion: "Add an alt attribute describing the image content",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var iconButtonRequiresLabel = {
+  id: "a11y-icon-button-label",
+  category: "accessibility",
+  severity: "error",
+  name: "Icon-only button requires label",
+  description: "Buttons with only an icon must have an accessible label",
+  appliesTo: ["Button"],
+  check: (node, context) => {
+    const hasIcon = "icon" in node && node.icon;
+    const hasContent = "content" in node && node.content && String(node.content).trim();
+    if (hasIcon && !hasContent) {
+      return {
+        ruleId: "a11y-icon-button-label",
+        category: "accessibility",
+        severity: "error",
+        message: "Icon-only button is missing accessible text",
+        description: "Screen readers cannot describe icon-only buttons without text",
+        suggestion: "Add text content or aria-label to describe the button action",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var linkRequiresDescriptiveText = {
+  id: "a11y-link-text",
+  category: "accessibility",
+  severity: "warning",
+  name: "Link requires descriptive text",
+  description: "Links should have descriptive text that indicates where they lead",
+  appliesTo: ["Link"],
+  check: (node, context) => {
+    const content = "content" in node ? String(node.content || "").toLowerCase() : "";
+    const genericTexts = ["click here", "here", "read more", "more", "link"];
+    if (genericTexts.includes(content.trim())) {
+      return {
+        ruleId: "a11y-link-text",
+        category: "accessibility",
+        severity: "warning",
+        message: "Link has generic text that is not descriptive",
+        description: 'Screen reader users often navigate by links, and generic text like "click here" is not helpful',
+        suggestion: `Replace "${content}" with descriptive text that indicates the link destination`,
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var headingHierarchy = {
+  id: "a11y-heading-hierarchy",
+  category: "accessibility",
+  severity: "warning",
+  name: "Heading hierarchy should be sequential",
+  description: "Heading levels should not skip (e.g., h1 to h3)",
+  appliesTo: ["Title"],
+  check: (node, context) => {
+    const level = "level" in node ? Number(node.level) : 1;
+    let prevHeadingLevel = 0;
+    for (let i = 0; i < context.index; i++) {
+      const sibling = context.siblings[i];
+      if (sibling && sibling.type === "Title") {
+        prevHeadingLevel = "level" in sibling ? Number(sibling.level) : 1;
+      }
+    }
+    if (prevHeadingLevel > 0 && level > prevHeadingLevel + 1) {
+      return {
+        ruleId: "a11y-heading-hierarchy",
+        category: "accessibility",
+        severity: "warning",
+        message: `Heading level skipped from h${prevHeadingLevel} to h${level}`,
+        description: "Screen reader users rely on heading hierarchy to understand page structure",
+        suggestion: `Use h${prevHeadingLevel + 1} instead of h${level}, or add intermediate headings`,
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var accessibilityRules = [
+  inputRequiresLabel,
+  imageRequiresAlt,
+  iconButtonRequiresLabel,
+  linkRequiresDescriptiveText,
+  headingHierarchy
+];
+
+// src/rules/form.ts
+var formRequiresSubmit = {
+  id: "form-submit-button",
+  category: "form",
+  severity: "warning",
+  name: "Form should have submit button",
+  description: "Forms with input fields should have a clear submit action",
+  appliesTo: ["Card", "Section", "Modal", "Main"],
+  check: (node, context) => {
+    if (!("children" in node) || !Array.isArray(node.children)) {
+      return null;
+    }
+    let hasInputs = false;
+    let hasSubmitButton = false;
+    function walkChildren(children) {
+      for (const child of children) {
+        if (["Input", "Textarea", "Select", "Checkbox", "Radio"].includes(child.type)) {
+          hasInputs = true;
+        }
+        if (child.type === "Button") {
+          const isPrimary = "primary" in child && child.primary;
+          const content = "content" in child ? String(child.content || "").toLowerCase() : "";
+          const submitWords = ["submit", "save", "send", "create", "add", "update", "confirm", "ok", "done"];
+          if (isPrimary || submitWords.some((w) => content.includes(w))) {
+            hasSubmitButton = true;
+          }
+        }
+        if ("children" in child && Array.isArray(child.children)) {
+          walkChildren(child.children);
+        }
+      }
+    }
+    walkChildren(node.children);
+    if (hasInputs && !hasSubmitButton) {
+      return {
+        ruleId: "form-submit-button",
+        category: "form",
+        severity: "warning",
+        message: "Form area has inputs but no clear submit button",
+        description: "Users need a clear way to submit form data",
+        suggestion: 'Add a primary button with a clear action label (e.g., "Submit", "Save")',
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var requiredFieldIndicator = {
+  id: "form-required-indicator",
+  category: "form",
+  severity: "info",
+  name: "Required fields should be clearly marked",
+  description: "Users should know which fields are required before filling out a form",
+  appliesTo: ["Input", "Textarea", "Select"],
+  check: (node, context) => {
+    const isRequired = "required" in node && node.required;
+    const label = "label" in node ? String(node.label || "") : "";
+    if (isRequired && label && !label.includes("*") && !label.toLowerCase().includes("required")) {
+      return {
+        ruleId: "form-required-indicator",
+        category: "form",
+        severity: "info",
+        message: "Required field label does not indicate it is required",
+        description: "Users should see visual indication that a field is required",
+        suggestion: 'Add an asterisk (*) to the label or include "required" in the label text',
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var passwordConfirmation = {
+  id: "form-password-confirm",
+  category: "form",
+  severity: "info",
+  name: "Password field may need confirmation",
+  description: "Password fields in registration forms should have a confirmation field",
+  appliesTo: ["Input"],
+  check: (node, context) => {
+    const inputType = "inputType" in node ? node.inputType : "";
+    if (inputType !== "password") return null;
+    const label = "label" in node ? String(node.label || "").toLowerCase() : "";
+    const isConfirmField = label.includes("confirm") || label.includes("repeat") || label.includes("retype");
+    if (isConfirmField) return null;
+    let hasConfirmField = false;
+    for (const sibling of context.siblings) {
+      if (sibling.type === "Input" && "inputType" in sibling && sibling.inputType === "password") {
+        const siblingLabel = "label" in sibling ? String(sibling.label || "").toLowerCase() : "";
+        if (siblingLabel.includes("confirm") || siblingLabel.includes("repeat") || siblingLabel.includes("retype")) {
+          hasConfirmField = true;
+          break;
+        }
+      }
+    }
+    const parentLabel = context.parent && "title" in context.parent ? String(context.parent.title || "").toLowerCase() : "";
+    const isRegistration = parentLabel.includes("sign up") || parentLabel.includes("register") || parentLabel.includes("create account");
+    if (isRegistration && !hasConfirmField) {
+      return {
+        ruleId: "form-password-confirm",
+        category: "form",
+        severity: "info",
+        message: "Registration form password field has no confirmation field",
+        description: "Users may mistype their password without a confirmation field",
+        suggestion: 'Add a "Confirm Password" field to prevent typos',
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var appropriateInputType = {
+  id: "form-input-type",
+  category: "form",
+  severity: "warning",
+  name: "Use appropriate input type",
+  description: "Using the correct input type improves UX on mobile and enables browser validation",
+  appliesTo: ["Input"],
+  check: (node, context) => {
+    const inputType = "inputType" in node ? String(node.inputType || "text") : "text";
+    const label = "label" in node ? String(node.label || "").toLowerCase() : "";
+    const placeholder = "placeholder" in node ? String(node.placeholder || "").toLowerCase() : "";
+    const combined = label + " " + placeholder;
+    const suggestions = [
+      { keywords: ["email", "e-mail"], type: "email" },
+      { keywords: ["phone", "tel", "mobile", "cell"], type: "tel" },
+      { keywords: ["url", "website", "link"], type: "url" },
+      { keywords: ["password", "pwd"], type: "password" },
+      { keywords: ["search", "find", "query"], type: "search" },
+      { keywords: ["date", "birthday", "dob"], type: "date" },
+      { keywords: ["number", "quantity", "amount", "count", "age"], type: "number" }
+    ];
+    for (const suggestion of suggestions) {
+      if (suggestion.keywords.some((k) => combined.includes(k)) && inputType !== suggestion.type) {
+        return {
+          ruleId: "form-input-type",
+          category: "form",
+          severity: "warning",
+          message: `Input appears to be for ${suggestion.type} but uses type="${inputType}"`,
+          description: `Using inputType="${suggestion.type}" enables better mobile keyboards and browser validation`,
+          suggestion: `Change inputType to "${suggestion.type}"`,
+          path: context.path,
+          nodeType: node.type,
+          location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+        };
+      }
+    }
+    return null;
+  }
+};
+var formRules = [
+  formRequiresSubmit,
+  requiredFieldIndicator,
+  passwordConfirmation,
+  appropriateInputType
+];
+
+// src/rules/touch-target.ts
+var MIN_TOUCH_TARGET = 44;
+var SIZE_MAP = {
+  xs: 24,
+  sm: 32,
+  md: 40,
+  lg: 48,
+  xl: 56
+};
+function getSizeValue(node) {
+  if (!("size" in node)) return null;
+  const size = node.size;
+  if (typeof size === "number") return size;
+  if (typeof size === "string" && size in SIZE_MAP) return SIZE_MAP[size];
+  return null;
+}
+var buttonTouchTarget = {
+  id: "touch-button-size",
+  category: "touch-target",
+  severity: "warning",
+  name: "Button touch target size",
+  description: "Buttons should be at least 44x44px for comfortable touch interaction",
+  appliesTo: ["Button"],
+  check: (node, context) => {
+    const size = getSizeValue(node);
+    if (size !== null && size < MIN_TOUCH_TARGET) {
+      return {
+        ruleId: "touch-button-size",
+        category: "touch-target",
+        severity: "warning",
+        message: `Button size (${size}px) is below minimum touch target (${MIN_TOUCH_TARGET}px)`,
+        description: "Small touch targets are difficult to tap on mobile devices",
+        suggestion: `Use size="md" or larger for better touch accessibility`,
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var iconButtonTouchTarget = {
+  id: "touch-icon-button-size",
+  category: "touch-target",
+  severity: "warning",
+  name: "Icon button touch target size",
+  description: "Icon-only buttons should have adequate padding for touch",
+  appliesTo: ["Button"],
+  check: (node, context) => {
+    const hasIcon = "icon" in node && node.icon;
+    const hasContent = "content" in node && node.content && String(node.content).trim();
+    if (!hasIcon || hasContent) return null;
+    const size = getSizeValue(node);
+    const padding = "p" in node ? Number(node.p) * 4 : 0;
+    if (size !== null && size < MIN_TOUCH_TARGET && padding < 8) {
+      return {
+        ruleId: "touch-icon-button-size",
+        category: "touch-target",
+        severity: "warning",
+        message: "Icon-only button may have insufficient touch target",
+        description: "Icon buttons need adequate padding to meet touch target requirements",
+        suggestion: "Add padding (p=2 or more) or use a larger size",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var checkboxRadioTouchTarget = {
+  id: "touch-checkbox-radio-size",
+  category: "touch-target",
+  severity: "info",
+  name: "Checkbox/Radio touch target",
+  description: "Checkboxes and radio buttons should be easy to tap",
+  appliesTo: ["Checkbox", "Radio"],
+  check: (node, context) => {
+    const hasLabel = "label" in node && node.label;
+    if (!hasLabel) {
+      return {
+        ruleId: "touch-checkbox-radio-size",
+        category: "touch-target",
+        severity: "info",
+        message: `${node.type} without label has small touch target`,
+        description: "The label extends the touch target area for checkboxes and radio buttons",
+        suggestion: "Add a label to increase the touch target area",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var linkSpacing = {
+  id: "touch-link-spacing",
+  category: "touch-target",
+  severity: "info",
+  name: "Link spacing for touch",
+  description: "Links in close proximity can be difficult to tap accurately",
+  appliesTo: ["Link"],
+  check: (node, context) => {
+    const siblingLinks = context.siblings.filter((s) => s.type === "Link");
+    if (siblingLinks.length > 1) {
+      const parent = context.parent;
+      if (parent && parent.type === "Row") {
+        const gap = "gap" in parent ? Number(parent.gap) : 0;
+        if (gap < 2) {
+          return {
+            ruleId: "touch-link-spacing",
+            category: "touch-target",
+            severity: "info",
+            message: "Multiple links in row may be too close together",
+            description: "Adjacent tap targets should have adequate spacing",
+            suggestion: "Add gap=2 or more to the parent row for better touch separation",
+            path: context.path,
+            nodeType: node.type,
+            location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+          };
+        }
+      }
+    }
+    return null;
+  }
+};
+var avatarTouchTarget = {
+  id: "touch-avatar-size",
+  category: "touch-target",
+  severity: "info",
+  name: "Avatar touch target size",
+  description: "Clickable avatars should meet touch target requirements",
+  appliesTo: ["Avatar"],
+  check: (node, context) => {
+    const size = getSizeValue(node);
+    if (size !== null && size < MIN_TOUCH_TARGET) {
+      return {
+        ruleId: "touch-avatar-size",
+        category: "touch-target",
+        severity: "info",
+        message: `Avatar size (${size}px) may be too small if clickable`,
+        description: "If this avatar is interactive, it should meet minimum touch target size",
+        suggestion: 'Use size="md" or larger for clickable avatars',
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var touchTargetRules = [
+  buttonTouchTarget,
+  iconButtonTouchTarget,
+  checkboxRadioTouchTarget,
+  linkSpacing,
+  avatarTouchTarget
+];
+
+// src/rules/consistency.ts
+var buttonStyleTracker = /* @__PURE__ */ new Map();
+function resetConsistencyTrackers() {
+  buttonStyleTracker.clear();
+}
+function getButtonStyle(node) {
+  if ("primary" in node && node.primary) return "primary";
+  if ("secondary" in node && node.secondary) return "secondary";
+  if ("outline" in node && node.outline) return "outline";
+  if ("ghost" in node && node.ghost) return "ghost";
+  if ("danger" in node && node.danger) return "danger";
+  return "default";
+}
+var consistentButtonStyles = {
+  id: "consistency-button-styles",
+  category: "consistency",
+  severity: "info",
+  name: "Consistent button styles",
+  description: "Action buttons in the same context should use consistent styling",
+  appliesTo: ["Row", "Col", "Card", "Modal"],
+  check: (node, context) => {
+    if (!("children" in node) || !Array.isArray(node.children)) {
+      return null;
+    }
+    const buttons = node.children.filter((c) => c.type === "Button");
+    if (buttons.length < 2) return null;
+    const styles = buttons.map((b) => getButtonStyle(b));
+    const uniqueStyles = [...new Set(styles)];
+    const hasCommonPattern = uniqueStyles.length === 2 && uniqueStyles.includes("primary") && (uniqueStyles.includes("outline") || uniqueStyles.includes("ghost")) || uniqueStyles.length === 2 && uniqueStyles.includes("primary") && uniqueStyles.includes("secondary");
+    if (hasCommonPattern) return null;
+    if (uniqueStyles.length > 2) {
+      return {
+        ruleId: "consistency-button-styles",
+        category: "consistency",
+        severity: "info",
+        message: `Multiple button styles (${uniqueStyles.join(", ")}) in same container`,
+        description: "Using many different button styles can confuse users about action hierarchy",
+        suggestion: "Use primary for main action, outline/ghost for secondary actions",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var consistentSpacing = {
+  id: "consistency-spacing",
+  category: "consistency",
+  severity: "info",
+  name: "Consistent spacing",
+  description: "Spacing should be consistent across similar elements",
+  appliesTo: ["Row", "Col"],
+  check: (node, context) => {
+    const siblingRows = context.siblings.filter((s) => s.type === node.type);
+    if (siblingRows.length < 2) return null;
+    const gaps = siblingRows.map((r) => "gap" in r ? Number(r.gap) : null).filter((g) => g !== null);
+    const uniqueGaps = [...new Set(gaps)];
+    if (uniqueGaps.length > 2) {
+      return {
+        ruleId: "consistency-spacing",
+        category: "consistency",
+        severity: "info",
+        message: "Sibling containers have inconsistent gap values",
+        description: "Consistent spacing creates visual harmony and rhythm",
+        suggestion: "Use the same gap value for sibling containers",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var consistentCardStyling = {
+  id: "consistency-card-styling",
+  category: "consistency",
+  severity: "info",
+  name: "Consistent card styling",
+  description: "Cards in the same context should have consistent visual treatment",
+  appliesTo: ["Card"],
+  check: (node, context) => {
+    const siblingCards = context.siblings.filter((s) => s.type === "Card");
+    if (siblingCards.length < 2) return null;
+    const hasShadow = "shadow" in node && node.shadow;
+    const hasBorder = "border" in node && node.border;
+    const padding = "p" in node ? Number(node.p) : null;
+    let inconsistencies = [];
+    for (const sibling of siblingCards) {
+      if (sibling === node) continue;
+      const sibShadow = "shadow" in sibling && sibling.shadow;
+      const sibBorder = "border" in sibling && sibling.border;
+      const sibPadding = "p" in sibling ? Number(sibling.p) : null;
+      if (!!hasShadow !== !!sibShadow) inconsistencies.push("shadow");
+      if (!!hasBorder !== !!sibBorder) inconsistencies.push("border");
+      if (padding !== sibPadding) inconsistencies.push("padding");
+    }
+    if (inconsistencies.length > 0) {
+      const uniqueIssues = [...new Set(inconsistencies)];
+      return {
+        ruleId: "consistency-card-styling",
+        category: "consistency",
+        severity: "info",
+        message: `Cards have inconsistent ${uniqueIssues.join(", ")}`,
+        description: "Consistent card styling helps users understand that cards are related",
+        suggestion: "Apply the same visual treatment to sibling cards",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var consistentAlertVariants = {
+  id: "consistency-alert-variants",
+  category: "consistency",
+  severity: "warning",
+  name: "Consistent alert variants",
+  description: "Alerts should use appropriate variants for their purpose",
+  appliesTo: ["Alert"],
+  check: (node, context) => {
+    const content = "content" in node ? String(node.content || "").toLowerCase() : "";
+    const variant = "variant" in node ? String(node.variant || "") : "";
+    const errorWords = ["error", "fail", "invalid", "wrong", "denied"];
+    const successWords = ["success", "saved", "created", "updated", "complete"];
+    const warningWords = ["warning", "caution", "attention", "note"];
+    if (errorWords.some((w) => content.includes(w)) && variant !== "danger") {
+      return {
+        ruleId: "consistency-alert-variants",
+        category: "consistency",
+        severity: "warning",
+        message: "Error message should use danger variant",
+        description: "Users expect error messages to be visually distinct (usually red)",
+        suggestion: "Add variant=danger to this error alert",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    if (successWords.some((w) => content.includes(w)) && variant !== "success") {
+      return {
+        ruleId: "consistency-alert-variants",
+        category: "consistency",
+        severity: "warning",
+        message: "Success message should use success variant",
+        description: "Users expect success messages to be visually distinct (usually green)",
+        suggestion: "Add variant=success to this success alert",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    if (warningWords.some((w) => content.includes(w)) && variant !== "warning") {
+      return {
+        ruleId: "consistency-alert-variants",
+        category: "consistency",
+        severity: "info",
+        message: "Warning message should use warning variant",
+        description: "Users expect warning messages to be visually distinct (usually yellow/orange)",
+        suggestion: "Add variant=warning to this warning alert",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var consistencyRules = [
+  consistentButtonStyles,
+  consistentSpacing,
+  consistentCardStyling,
+  consistentAlertVariants
+];
+
+// src/rules/usability.ts
+var noEmptyContainers = {
+  id: "usability-empty-container",
+  category: "usability",
+  severity: "warning",
+  name: "Avoid empty containers",
+  description: "Containers without content may confuse users or indicate missing content",
+  appliesTo: ["Card", "Section", "Modal", "Drawer"],
+  check: (node, context) => {
+    if (!("children" in node) || !Array.isArray(node.children) || node.children.length === 0) {
+      return {
+        ruleId: "usability-empty-container",
+        category: "usability",
+        severity: "warning",
+        message: `${node.type} has no content`,
+        description: "Empty containers may represent incomplete design or confuse users",
+        suggestion: "Add content to this container or use a placeholder to indicate intended content",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var clearCTA = {
+  id: "usability-clear-cta",
+  category: "usability",
+  severity: "info",
+  name: "Clear call to action",
+  description: "Pages should have a clear primary action for users",
+  appliesTo: ["Page"],
+  check: (node, context) => {
+    if (!("children" in node) || !Array.isArray(node.children)) {
+      return null;
+    }
+    let hasPrimaryButton = false;
+    function findPrimaryButton(children) {
+      for (const child of children) {
+        if (child.type === "Button" && "primary" in child && child.primary) {
+          hasPrimaryButton = true;
+          return;
+        }
+        if ("children" in child && Array.isArray(child.children)) {
+          findPrimaryButton(child.children);
+        }
+      }
+    }
+    findPrimaryButton(node.children);
+    if (!hasPrimaryButton) {
+      return {
+        ruleId: "usability-clear-cta",
+        category: "usability",
+        severity: "info",
+        message: "Page has no primary button (CTA)",
+        description: "A clear call-to-action helps guide users to the main action",
+        suggestion: "Add a primary button for the main action on this page",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var loadingStates = {
+  id: "usability-loading-states",
+  category: "usability",
+  severity: "info",
+  name: "Consider loading states",
+  description: "Actions that may take time should have loading indicators",
+  appliesTo: ["Button"],
+  check: (node, context) => {
+    const content = "content" in node ? String(node.content || "").toLowerCase() : "";
+    const hasLoading = "loading" in node;
+    const isPrimary = "primary" in node && node.primary;
+    const asyncActions = ["submit", "save", "send", "upload", "download", "export", "import", "sync", "load"];
+    if (isPrimary && asyncActions.some((a) => content.includes(a)) && !hasLoading) {
+      return {
+        ruleId: "usability-loading-states",
+        category: "usability",
+        severity: "info",
+        message: `Button "${content}" may need a loading state`,
+        description: "Async actions should show progress to prevent double-clicks and inform users",
+        suggestion: "Consider adding a loading variant for this button when action is in progress",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var destructiveActionConfirmation = {
+  id: "usability-destructive-confirm",
+  category: "usability",
+  severity: "warning",
+  name: "Destructive actions need confirmation",
+  description: "Destructive actions should have clear warning styling",
+  appliesTo: ["Button"],
+  check: (node, context) => {
+    const content = "content" in node ? String(node.content || "").toLowerCase() : "";
+    const isDanger = "danger" in node && node.danger;
+    const destructiveWords = ["delete", "remove", "destroy", "clear", "reset", "revoke", "terminate"];
+    if (destructiveWords.some((w) => content.includes(w)) && !isDanger) {
+      return {
+        ruleId: "usability-destructive-confirm",
+        category: "usability",
+        severity: "warning",
+        message: `Destructive action "${content}" should use danger styling`,
+        description: "Users should be visually warned about destructive actions",
+        suggestion: "Add the danger attribute to this button",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var modalCloseButton = {
+  id: "usability-modal-close",
+  category: "usability",
+  severity: "warning",
+  name: "Modal should have close mechanism",
+  description: "Users should be able to close modals easily",
+  appliesTo: ["Modal"],
+  check: (node, context) => {
+    if (!("children" in node) || !Array.isArray(node.children)) {
+      return null;
+    }
+    let hasCloseButton = false;
+    function findCloseButton(children) {
+      for (const child of children) {
+        if (child.type === "Button") {
+          const content = "content" in child ? String(child.content || "").toLowerCase() : "";
+          const icon = "icon" in child ? String(child.icon || "").toLowerCase() : "";
+          if (["close", "cancel", "dismiss", "x"].some((w) => content.includes(w) || icon.includes(w))) {
+            hasCloseButton = true;
+            return;
+          }
+        }
+        if (child.type === "Icon") {
+          const name = "name" in child ? String(child.name || "").toLowerCase() : "";
+          if (name === "x" || name === "close") {
+            hasCloseButton = true;
+            return;
+          }
+        }
+        if ("children" in child && Array.isArray(child.children)) {
+          findCloseButton(child.children);
+        }
+      }
+    }
+    findCloseButton(node.children);
+    if (!hasCloseButton) {
+      return {
+        ruleId: "usability-modal-close",
+        category: "usability",
+        severity: "warning",
+        message: "Modal has no visible close button",
+        description: "Users should have a clear way to dismiss the modal",
+        suggestion: 'Add a close button (icon "x") or a "Cancel" button',
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var maxNestingDepth = {
+  id: "usability-nesting-depth",
+  category: "usability",
+  severity: "warning",
+  name: "Avoid excessive nesting",
+  description: "Deeply nested layouts can be confusing and hard to maintain",
+  appliesTo: ["Row", "Col", "Card", "Section"],
+  check: (node, context) => {
+    const MAX_DEPTH = 6;
+    if (context.depth > MAX_DEPTH) {
+      return {
+        ruleId: "usability-nesting-depth",
+        category: "usability",
+        severity: "warning",
+        message: `Component is nested ${context.depth} levels deep (max recommended: ${MAX_DEPTH})`,
+        description: "Excessive nesting makes layouts harder to understand and maintain",
+        suggestion: "Consider flattening the layout or breaking into separate sections",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var usabilityRules = [
+  noEmptyContainers,
+  clearCTA,
+  loadingStates,
+  destructiveActionConfirmation,
+  modalCloseButton,
+  maxNestingDepth
+];
+
+// src/rules/navigation.ts
+var navItemCount = {
+  id: "nav-item-count",
+  category: "navigation",
+  severity: "warning",
+  name: "Navigation item count",
+  description: "Navigation menus with too many items can overwhelm users",
+  appliesTo: ["Nav"],
+  check: (node, context) => {
+    const MAX_NAV_ITEMS = 7;
+    const items = "items" in node && Array.isArray(node.items) ? node.items : [];
+    if (items.length > MAX_NAV_ITEMS) {
+      return {
+        ruleId: "nav-item-count",
+        category: "navigation",
+        severity: "warning",
+        message: `Navigation has ${items.length} items (recommended max: ${MAX_NAV_ITEMS})`,
+        description: "Too many navigation items can overwhelm users and slow decision-making",
+        suggestion: "Group related items into categories or use a hierarchical navigation",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var navActiveState = {
+  id: "nav-active-state",
+  category: "navigation",
+  severity: "info",
+  name: "Navigation should show active state",
+  description: "Users should know which page they are currently on",
+  appliesTo: ["Nav"],
+  check: (node, context) => {
+    const items = "items" in node && Array.isArray(node.items) ? node.items : [];
+    if (items.length === 0) return null;
+    const hasActiveItem = items.some((item) => {
+      if (typeof item === "object" && item !== null) {
+        return "active" in item && item.active;
+      }
+      return false;
+    });
+    if (!hasActiveItem) {
+      return {
+        ruleId: "nav-active-state",
+        category: "navigation",
+        severity: "info",
+        message: "Navigation has no active state indicated",
+        description: "Users should be able to see which page/section they are currently viewing",
+        suggestion: "Add active attribute to the current navigation item",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var breadcrumbHasHome = {
+  id: "nav-breadcrumb-home",
+  category: "navigation",
+  severity: "info",
+  name: "Breadcrumb should start with home",
+  description: "Breadcrumbs typically start with a home or root link",
+  appliesTo: ["Breadcrumb"],
+  check: (node, context) => {
+    const items = "items" in node && Array.isArray(node.items) ? node.items : [];
+    if (items.length === 0) return null;
+    const firstItem = items[0];
+    const firstLabel = typeof firstItem === "string" ? firstItem.toLowerCase() : firstItem?.label?.toLowerCase() || "";
+    const homeWords = ["home", "dashboard", "main", "start"];
+    if (!homeWords.some((w) => firstLabel.includes(w))) {
+      return {
+        ruleId: "nav-breadcrumb-home",
+        category: "navigation",
+        severity: "info",
+        message: "Breadcrumb does not start with a home/root link",
+        description: "Users expect breadcrumbs to start from a known root location",
+        suggestion: 'Add "Home" or equivalent as the first breadcrumb item',
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var tabCount = {
+  id: "nav-tab-count",
+  category: "navigation",
+  severity: "warning",
+  name: "Tab count",
+  description: "Too many tabs can be overwhelming",
+  appliesTo: ["Tabs"],
+  check: (node, context) => {
+    const MAX_TABS = 5;
+    const items = "items" in node && Array.isArray(node.items) ? node.items : [];
+    const children = "children" in node && Array.isArray(node.children) ? node.children : [];
+    const childTabCount = children.filter((c) => {
+      if (typeof c === "object" && c !== null && "type" in c) {
+        return String(c.type).toLowerCase().includes("tab");
+      }
+      return false;
+    }).length;
+    const tabCount2 = items.length || childTabCount;
+    if (tabCount2 > MAX_TABS) {
+      return {
+        ruleId: "nav-tab-count",
+        category: "navigation",
+        severity: "warning",
+        message: `Tabs has ${tabCount2} items (recommended max: ${MAX_TABS})`,
+        description: "Too many tabs can overwhelm users and may not fit on smaller screens",
+        suggestion: "Consider using a different navigation pattern or grouping related content",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var dropdownHasItems = {
+  id: "nav-dropdown-items",
+  category: "navigation",
+  severity: "warning",
+  name: "Dropdown should have items",
+  description: "Dropdown menus need items to be functional",
+  appliesTo: ["Dropdown"],
+  check: (node, context) => {
+    const items = "items" in node && Array.isArray(node.items) ? node.items : [];
+    const children = "children" in node && Array.isArray(node.children) ? node.children : [];
+    if (items.length === 0 && children.length === 0) {
+      return {
+        ruleId: "nav-dropdown-items",
+        category: "navigation",
+        severity: "warning",
+        message: "Dropdown has no items",
+        description: "An empty dropdown provides no value to users",
+        suggestion: "Add items to the dropdown menu",
+        path: context.path,
+        nodeType: node.type,
+        location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
+      };
+    }
+    return null;
+  }
+};
+var navigationRules = [
+  navItemCount,
+  navActiveState,
+  breadcrumbHasHome,
+  tabCount,
+  dropdownHasItems
+];
+
+// src/rules/index.ts
+var allRules = [
+  ...accessibilityRules,
+  ...formRules,
+  ...touchTargetRules,
+  ...consistencyRules,
+  ...usabilityRules,
+  ...navigationRules
+];
+var rulesByCategory = {
+  accessibility: accessibilityRules,
+  form: formRules,
+  "touch-target": touchTargetRules,
+  consistency: consistencyRules,
+  usability: usabilityRules,
+  navigation: navigationRules
+};
+function getRulesForCategories(categories) {
+  if (categories.length === 0) return allRules;
+  return categories.flatMap((cat) => {
+    const rules = rulesByCategory[cat];
+    return rules || [];
+  });
+}
+
+// src/index.ts
+var SEVERITY_ORDER = {
+  error: 0,
+  warning: 1,
+  info: 2
+};
+function validateUX(ast, options = {}) {
+  const {
+    categories = [],
+    minSeverity = "info",
+    maxIssues = 100,
+    customRules = [],
+    disabledRules = []
+  } = options;
+  resetConsistencyTrackers();
+  let rules = categories.length > 0 ? getRulesForCategories(categories) : allRules;
+  rules = [...rules, ...customRules];
+  if (disabledRules.length > 0) {
+    const disabledSet = new Set(disabledRules);
+    rules = rules.filter((r) => !disabledSet.has(r.id));
+  }
+  const issues = [];
+  const minSeverityOrder = SEVERITY_ORDER[minSeverity];
+  const categoryStats = /* @__PURE__ */ new Map();
+  function initCategoryStats(category) {
+    if (!categoryStats.has(category)) {
+      categoryStats.set(category, { passed: 0, failed: 0, warnings: 0 });
+    }
+  }
+  function recordCheck(rule, issue) {
+    initCategoryStats(rule.category);
+    const stats = categoryStats.get(rule.category);
+    if (issue === null) {
+      stats.passed++;
+    } else if (issue.severity === "error") {
+      stats.failed++;
+    } else {
+      stats.warnings++;
+    }
+  }
+  function addIssue(issue) {
+    if (SEVERITY_ORDER[issue.severity] > minSeverityOrder) {
+      return true;
+    }
+    if (issues.length >= maxIssues) {
+      return false;
+    }
+    issues.push(issue);
+    return true;
+  }
+  function walkNode(node, path, parent, siblings, index, depth) {
+    const context = {
+      path,
+      parent,
+      root: ast.children[0],
+      siblings,
+      index,
+      depth
+    };
+    for (const rule of rules) {
+      if (rule.appliesTo.length > 0 && !rule.appliesTo.includes(node.type)) {
+        continue;
+      }
+      try {
+        const result = rule.check(node, context);
+        if (result === null) {
+          recordCheck(rule, null);
+        } else if (Array.isArray(result)) {
+          for (const issue of result) {
+            recordCheck(rule, issue);
+            if (!addIssue(issue)) return false;
+          }
+        } else {
+          recordCheck(rule, result);
+          if (!addIssue(result)) return false;
+        }
+      } catch {
+      }
+    }
+    if ("children" in node && Array.isArray(node.children)) {
+      const children = node.children;
+      for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child && typeof child === "object" && "type" in child) {
+          const shouldContinue = walkNode(
+            child,
+            `${path}.children[${i}]`,
+            node,
+            children,
+            i,
+            depth + 1
+          );
+          if (!shouldContinue) return false;
+        }
+      }
+    }
+    return true;
+  }
+  if (ast.children) {
+    for (let i = 0; i < ast.children.length; i++) {
+      const page = ast.children[i];
+      const children = ast.children;
+      walkNode(page, `pages[${i}]`, null, children, i, 0);
+    }
+  }
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  const infoCount = issues.filter((i) => i.severity === "info").length;
+  const errorPenalty = errorCount * 10;
+  const warningPenalty = warningCount * 3;
+  const infoPenalty = infoCount * 1;
+  const totalPenalty = errorPenalty + warningPenalty + infoPenalty;
+  const score = Math.max(0, Math.min(100, 100 - totalPenalty));
+  const summary = Array.from(categoryStats.entries()).map(([category, stats]) => ({
+    category,
+    passed: stats.passed,
+    failed: stats.failed,
+    warnings: stats.warnings
+  }));
+  return {
+    valid: errorCount === 0,
+    score,
+    issues,
+    summary,
+    severityCounts: {
+      errors: errorCount,
+      warnings: warningCount,
+      info: infoCount
+    }
+  };
+}
+function isUXValid(ast) {
+  const result = validateUX(ast, { minSeverity: "error", maxIssues: 1 });
+  return result.valid;
+}
+function getUXIssues(ast, options) {
+  return validateUX(ast, options).issues;
+}
+function getUXScore(ast) {
+  return validateUX(ast).score;
+}
+function formatUXResult(result) {
+  const lines = [];
+  lines.push(`UX Validation Score: ${result.score}/100`);
+  lines.push(`Status: ${result.valid ? "PASSED" : "FAILED"}`);
+  lines.push("");
+  if (result.issues.length > 0) {
+    lines.push("Issues:");
+    lines.push("");
+    for (const issue of result.issues) {
+      const icon = issue.severity === "error" ? "\u274C" : issue.severity === "warning" ? "\u26A0\uFE0F" : "\u2139\uFE0F";
+      lines.push(`${icon} [${issue.ruleId}] ${issue.message}`);
+      lines.push(`   Path: ${issue.path}`);
+      lines.push(`   ${issue.suggestion}`);
+      lines.push("");
+    }
+  } else {
+    lines.push("No issues found.");
+  }
+  lines.push("Summary by category:");
+  for (const cat of result.summary) {
+    lines.push(`  ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`);
+  }
+  return lines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  allRules,
+  formatUXResult,
+  getRulesForCategories,
+  getUXIssues,
+  getUXScore,
+  isUXValid,
+  rulesByCategory,
+  validateUX
+});