@wireweave/ux-rules 1.2.3-beta.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -33,9 +33,11 @@ const doc = parse(`
33
33
 
34
34
  // Full validation
35
35
  const result = validateUX(doc);
36
- console.log(result.score); // 0-100
37
- console.log(result.valid); // true if no errors
38
- console.log(result.issues); // Array of UX issues
36
+ console.log(result.score); // 0-100, complexity-normalized
37
+ console.log(result.rawScore); // 0-100, undamped total penalty
38
+ console.log(result.complexity); // { score: 1-10, level: 'simple' | ... }
39
+ console.log(result.valid); // true if no errors
40
+ console.log(result.issues); // Array of UX issues
39
41
 
40
42
  // Quick helpers
41
43
  const score = getUXScore(doc);
@@ -72,6 +74,15 @@ Full validation with score and issues.
72
74
  - `customRules`: Add custom rules
73
75
  - `disabledRules`: Disable rules by ID
74
76
 
77
+ **Returns** `UXValidationResult`:
78
+ - `valid`: `true` if no errors
79
+ - `score`: complexity-normalized score (0-100) — see [Scoring](#scoring)
80
+ - `rawScore`: undamped total-penalty score (0-100)
81
+ - `complexity`: `{ score: 1-10, level }` from core `analyze()`
82
+ - `issues`: array of `UXIssue`
83
+ - `summary`: per-category pass/fail/warning counts
84
+ - `severityCounts`: `{ errors, warnings, info }`
85
+
75
86
  ### `isUXValid(ast)`
76
87
 
77
88
  Quick check - returns `true` if no errors.
@@ -90,13 +101,33 @@ Formats validation result as human-readable string.
90
101
 
91
102
  ## Issue Severity
92
103
 
93
- | Severity | Impact | Score Penalty |
94
- |----------|--------|---------------|
95
- | `error` | Critical UX problem | -10 |
96
- | `warning` | Should fix | -3 |
97
- | `info` | Consider improving | -1 |
98
-
99
- **Score Formula:** `100 - (errors × 10 + warnings × 3 + info × 1)`
104
+ | Severity | Impact | Base Penalty |
105
+ |----------|--------|--------------|
106
+ | `error` | Critical UX problem | -10 (absolute) |
107
+ | `warning` | Should fix | -3 (soft) |
108
+ | `info` | Consider improving | -1 (soft) |
109
+
110
+ ### Scoring
111
+
112
+ `validateUX()` returns two scores:
113
+
114
+ - **`rawScore`** — the undamped total penalty, clamped to `[0, 100]`:
115
+ `100 − (errors × 10 + warnings × 3 + info × 1)`.
116
+ - **`score`** — the headline score. Errors stay an absolute penalty (a hard defect
117
+ is a hard defect at any screen size — no volume discount). The *soft* penalty
118
+ (warnings + info) is damped by the document's achieved complexity:
119
+
120
+ ```
121
+ score = round(100 − errors × 10 − (warnings × 3 + info × 1) × dampingFactor)
122
+ dampingFactor = REFERENCE_COMPLEXITY / max(REFERENCE_COMPLEXITY, complexity.score)
123
+ ```
124
+
125
+ `complexity.score` ∈ `[1, 10]` comes from `@wireweave/core`'s `analyze()`, and
126
+ `REFERENCE_COMPLEXITY` is `3` (core's "moderate" band). At or below the reference
127
+ the factor is `1`, so a trivial screen earns no relief; above it, a dense,
128
+ intent-fitting design gets proportional relief for the per-element
129
+ warning/info heuristics it is expected to accumulate. `score >= rawScore` always
130
+ holds. Both `complexity` and `REFERENCE_COMPLEXITY` are exported.
100
131
 
101
132
  ## All Rules
102
133
 
package/dist/index.cjs CHANGED
@@ -45,6 +45,7 @@ __export(src_exports, {
45
45
  MIN_TOUCH_TARGET: () => MIN_TOUCH_TARGET,
46
46
  PLACEHOLDER_PATTERNS: () => PLACEHOLDER_PATTERNS,
47
47
  RECOMMENDED_TOUCH_TARGET: () => RECOMMENDED_TOUCH_TARGET,
48
+ REFERENCE_COMPLEXITY: () => REFERENCE_COMPLEXITY,
48
49
  SIZE_MAP: () => SIZE_MAP,
49
50
  SUBMIT_WORDS: () => SUBMIT_WORDS,
50
51
  SUCCESS_WORDS: () => SUCCESS_WORDS,
@@ -77,6 +78,7 @@ __export(src_exports, {
77
78
  validateUX: () => validateUX
78
79
  });
79
80
  module.exports = __toCommonJS(src_exports);
81
+ var import_core2 = require("@wireweave/core");
80
82
 
81
83
  // src/constants.ts
82
84
  var MAX_NAV_ITEMS = 7;
@@ -90,6 +92,7 @@ var MAX_TITLE_LENGTH = 60;
90
92
  var MAX_TOOLTIP_LENGTH = 100;
91
93
  var MAX_LIST_ITEMS = 20;
92
94
  var MAX_TABLE_COLUMNS = 8;
95
+ var REFERENCE_COMPLEXITY = 3;
93
96
  var MIN_TOUCH_TARGET = 44;
94
97
  var RECOMMENDED_TOUCH_TARGET = 48;
95
98
  var SIZE_MAP = {
@@ -904,6 +907,7 @@ var consistencyRules = [
904
907
  ];
905
908
 
906
909
  // src/rules/usability.ts
910
+ var import_core = require("@wireweave/core");
907
911
  var noEmptyContainers = {
908
912
  id: "usability-empty-container",
909
913
  category: "usability",
@@ -1184,6 +1188,64 @@ var drawerWidth = {
1184
1188
  return null;
1185
1189
  }
1186
1190
  };
1191
+ function pageDimensions(page) {
1192
+ const explicitW = typeof page.w === "number" ? page.w : void 0;
1193
+ const explicitH = typeof page.h === "number" ? page.h : void 0;
1194
+ if (explicitW !== void 0 && explicitH !== void 0) {
1195
+ return { width: explicitW, height: explicitH };
1196
+ }
1197
+ const vp = (0, import_core.resolveViewport)(page.viewport, page.device);
1198
+ return { width: vp.width, height: vp.height };
1199
+ }
1200
+ function pageBox(page) {
1201
+ const { width, height } = pageDimensions(page);
1202
+ return {
1203
+ x: typeof page.x === "number" ? page.x : 0,
1204
+ y: typeof page.y === "number" ? page.y : 0,
1205
+ w: width,
1206
+ h: height
1207
+ };
1208
+ }
1209
+ function boxesOverlap(a, b) {
1210
+ return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
1211
+ }
1212
+ var noPageOverlap = {
1213
+ id: "usability-page-overlap",
1214
+ category: "usability",
1215
+ severity: "warning",
1216
+ name: "Pages should not overlap on the canvas",
1217
+ description: "Pages placed at explicit coordinates may visually overlap when their bounding boxes intersect",
1218
+ appliesTo: ["Page"],
1219
+ check: (node, context) => {
1220
+ if (node.type !== "Page") return null;
1221
+ const page = node;
1222
+ if (typeof page.x !== "number" || typeof page.y !== "number") return null;
1223
+ const issues = [];
1224
+ const myBox = pageBox(page);
1225
+ for (let i = context.index + 1; i < context.siblings.length; i++) {
1226
+ const other = context.siblings[i];
1227
+ if (!other || other.type !== "Page") continue;
1228
+ const otherPage = other;
1229
+ if (typeof otherPage.x !== "number" || typeof otherPage.y !== "number") continue;
1230
+ if (boxesOverlap(myBox, pageBox(otherPage))) {
1231
+ const myTitle = page.title ?? `pages[${context.index}]`;
1232
+ const otherTitle = otherPage.title ?? `pages[${i}]`;
1233
+ issues.push({
1234
+ ruleId: "usability-page-overlap",
1235
+ category: "usability",
1236
+ severity: "warning",
1237
+ message: `Page "${myTitle}" overlaps page "${otherTitle}" on the canvas`,
1238
+ description: "Two pages with explicit at(x, y) coordinates have intersecting bounding boxes",
1239
+ suggestion: "Move one page so the bounding boxes do not intersect, or remove at() to let the page auto-flow",
1240
+ path: context.path,
1241
+ nodeType: node.type,
1242
+ location: getNodeLocation(node)
1243
+ });
1244
+ }
1245
+ }
1246
+ return issues.length > 0 ? issues : null;
1247
+ }
1248
+ };
1187
1249
  var usabilityRules = [
1188
1250
  noEmptyContainers,
1189
1251
  clearCTA,
@@ -1194,7 +1256,8 @@ var usabilityRules = [
1194
1256
  tooManyButtons,
1195
1257
  tooManyFormFields,
1196
1258
  tooManyPageElements,
1197
- drawerWidth
1259
+ drawerWidth,
1260
+ noPageOverlap
1198
1261
  ];
1199
1262
 
1200
1263
  // src/rules/navigation.ts
@@ -2197,6 +2260,16 @@ var SEVERITY_ORDER = {
2197
2260
  warning: 1,
2198
2261
  info: 2
2199
2262
  };
2263
+ function resolveComplexity(ast) {
2264
+ try {
2265
+ const result = (0, import_core2.analyze)(ast);
2266
+ if (result.success && typeof result.complexity?.score === "number" && Number.isFinite(result.complexity.score) && result.complexity.score > 0) {
2267
+ return { score: result.complexity.score, level: result.complexity.level };
2268
+ }
2269
+ } catch {
2270
+ }
2271
+ return { score: REFERENCE_COMPLEXITY, level: "moderate" };
2272
+ }
2200
2273
  function validateUX(ast, options = {}) {
2201
2274
  const {
2202
2275
  categories = [],
@@ -2300,10 +2373,14 @@ function validateUX(ast, options = {}) {
2300
2373
  const warningCount = issues.filter((i) => i.severity === "warning").length;
2301
2374
  const infoCount = issues.filter((i) => i.severity === "info").length;
2302
2375
  const errorPenalty = errorCount * 10;
2303
- const warningPenalty = warningCount * 3;
2304
- const infoPenalty = infoCount * 1;
2305
- const totalPenalty = errorPenalty + warningPenalty + infoPenalty;
2306
- const score = Math.max(0, Math.min(100, 100 - totalPenalty));
2376
+ const rawSoftPenalty = warningCount * 3 + infoCount * 1;
2377
+ const rawScore = Math.max(0, Math.min(100, 100 - errorPenalty - rawSoftPenalty));
2378
+ const complexity = resolveComplexity(ast);
2379
+ const dampingFactor = REFERENCE_COMPLEXITY / Math.max(REFERENCE_COMPLEXITY, complexity.score);
2380
+ const score = Math.max(
2381
+ 0,
2382
+ Math.min(100, Math.round(100 - errorPenalty - rawSoftPenalty * dampingFactor))
2383
+ );
2307
2384
  const summary = Array.from(categoryStats.entries()).map(([category, stats]) => ({
2308
2385
  category,
2309
2386
  passed: stats.passed,
@@ -2313,6 +2390,8 @@ function validateUX(ast, options = {}) {
2313
2390
  return {
2314
2391
  valid: errorCount === 0,
2315
2392
  score,
2393
+ rawScore,
2394
+ complexity,
2316
2395
  issues,
2317
2396
  summary,
2318
2397
  severityCounts: {
@@ -2383,6 +2462,7 @@ function formatUXResult(result) {
2383
2462
  MIN_TOUCH_TARGET,
2384
2463
  PLACEHOLDER_PATTERNS,
2385
2464
  RECOMMENDED_TOUCH_TARGET,
2465
+ REFERENCE_COMPLEXITY,
2386
2466
  SIZE_MAP,
2387
2467
  SUBMIT_WORDS,
2388
2468
  SUCCESS_WORDS,
package/dist/index.d.cts CHANGED
@@ -46,8 +46,26 @@ interface UXIssue {
46
46
  interface UXValidationResult {
47
47
  /** Whether all checks passed (no errors) */
48
48
  valid: boolean;
49
- /** Total score (0-100) */
49
+ /**
50
+ * Quality score (0-100). Errors are an absolute penalty (-10 each); the soft
51
+ * penalty (warnings + info) is damped by the document's achieved complexity,
52
+ * so a dense, intent-fitting design is not punished merely for having more
53
+ * elements to fault. See `rawScore` for the undamped value.
54
+ */
50
55
  score: number;
56
+ /**
57
+ * Undamped total-penalty score: `100 - (errors*10 + warnings*3 + info*1)`,
58
+ * clamped to [0,100]. Kept for transparency and migration; `score >= rawScore`
59
+ * always holds.
60
+ */
61
+ rawScore: number;
62
+ /** Achieved complexity of the document, from core `analyze()`. */
63
+ complexity: {
64
+ /** Overall complexity score (1-10, higher = more complex). */
65
+ score: number;
66
+ /** Complexity band: `'simple' | 'moderate' | 'complex' | 'very-complex'`. */
67
+ level: string;
68
+ };
51
69
  /** Issues found */
52
70
  issues: UXIssue[];
53
71
  /** Summary by category */
@@ -174,6 +192,18 @@ declare const MAX_TOOLTIP_LENGTH = 100;
174
192
  declare const MAX_LIST_ITEMS = 20;
175
193
  /** Maximum table columns */
176
194
  declare const MAX_TABLE_COLUMNS = 8;
195
+ /**
196
+ * Complexity calibration point for score normalization.
197
+ *
198
+ * The headline score damps the *soft* penalty (warnings + info) by
199
+ * `REFERENCE_COMPLEXITY / max(REFERENCE_COMPLEXITY, complexity.score)`, where
200
+ * `complexity.score` ∈ [1,10] comes from core `analyze()`. At or below this
201
+ * point the factor is 1 (no relief), so a trivial screen can never earn a
202
+ * softer penalty by being simple; above it, a richer design gets proportional
203
+ * relief for the per-element warnings it is expected to accumulate. Errors are
204
+ * never damped. `3` corresponds to core's "moderate" complexity band.
205
+ */
206
+ declare const REFERENCE_COMPLEXITY = 3;
177
207
  /** Minimum touch target size (WCAG 2.5.5 AAA: 44x44px) */
178
208
  declare const MIN_TOUCH_TARGET = 44;
179
209
  /** Recommended touch target size (Material Design: 48x48px) */
@@ -340,4 +370,4 @@ declare function getUXScore(ast: WireframeDocument): number;
340
370
  */
341
371
  declare function formatUXResult(result: UXValidationResult): string;
342
372
 
343
- export { ASYNC_ACTION_WORDS, CLOSE_WORDS, CONTAINER_TYPES, DESTRUCTIVE_WORDS, ERROR_WORDS, FORM_INPUT_TYPES, GENERIC_LINK_TEXTS, HOME_WORDS, INPUT_TYPE_SUGGESTIONS, MAX_BUTTONS, MAX_BUTTON_TEXT_LENGTH, MAX_FORM_FIELDS, MAX_LIST_ITEMS, MAX_NAV_ITEMS, MAX_NESTING_DEPTH, MAX_PAGE_ELEMENTS, MAX_TABLE_COLUMNS, MAX_TABS, MAX_TITLE_LENGTH, MAX_TOAST_DURATION, MAX_TOOLTIP_LENGTH, MIN_TOAST_DURATION, MIN_TOUCH_TARGET, PLACEHOLDER_PATTERNS, RECOMMENDED_TOUCH_TARGET, SIZE_MAP, SUBMIT_WORDS, SUCCESS_WORDS, TEXT_CONTENT_TYPES, type UXIssue, type UXIssueSeverity, type UXRule, type UXRuleCategory, type UXRuleContext, type UXValidationOptions, type UXValidationResult, WARNING_WORDS, allRules, containsAnyWord, countInChildren, filterChildren, findInChildren, formatUXResult, getButtonStyle, getChildren, getNodeItems, getNodeLocation, getNodeText, getNodeTextLower, getRulesForCategories, getSizeValue, getUXIssues, getUXScore, hasChildMatching, hasChildren, isAnyNode, isNodeType, isUXValid, matchesAnyWord, rulesByCategory, toAnyNodeArray, validateUX };
373
+ export { ASYNC_ACTION_WORDS, CLOSE_WORDS, CONTAINER_TYPES, DESTRUCTIVE_WORDS, ERROR_WORDS, FORM_INPUT_TYPES, GENERIC_LINK_TEXTS, HOME_WORDS, INPUT_TYPE_SUGGESTIONS, MAX_BUTTONS, MAX_BUTTON_TEXT_LENGTH, MAX_FORM_FIELDS, MAX_LIST_ITEMS, MAX_NAV_ITEMS, MAX_NESTING_DEPTH, MAX_PAGE_ELEMENTS, MAX_TABLE_COLUMNS, MAX_TABS, MAX_TITLE_LENGTH, MAX_TOAST_DURATION, MAX_TOOLTIP_LENGTH, MIN_TOAST_DURATION, MIN_TOUCH_TARGET, PLACEHOLDER_PATTERNS, RECOMMENDED_TOUCH_TARGET, REFERENCE_COMPLEXITY, SIZE_MAP, SUBMIT_WORDS, SUCCESS_WORDS, TEXT_CONTENT_TYPES, type UXIssue, type UXIssueSeverity, type UXRule, type UXRuleCategory, type UXRuleContext, type UXValidationOptions, type UXValidationResult, WARNING_WORDS, allRules, containsAnyWord, countInChildren, filterChildren, findInChildren, formatUXResult, getButtonStyle, getChildren, getNodeItems, getNodeLocation, getNodeText, getNodeTextLower, getRulesForCategories, getSizeValue, getUXIssues, getUXScore, hasChildMatching, hasChildren, isAnyNode, isNodeType, isUXValid, matchesAnyWord, rulesByCategory, toAnyNodeArray, validateUX };
package/dist/index.d.ts CHANGED
@@ -46,8 +46,26 @@ interface UXIssue {
46
46
  interface UXValidationResult {
47
47
  /** Whether all checks passed (no errors) */
48
48
  valid: boolean;
49
- /** Total score (0-100) */
49
+ /**
50
+ * Quality score (0-100). Errors are an absolute penalty (-10 each); the soft
51
+ * penalty (warnings + info) is damped by the document's achieved complexity,
52
+ * so a dense, intent-fitting design is not punished merely for having more
53
+ * elements to fault. See `rawScore` for the undamped value.
54
+ */
50
55
  score: number;
56
+ /**
57
+ * Undamped total-penalty score: `100 - (errors*10 + warnings*3 + info*1)`,
58
+ * clamped to [0,100]. Kept for transparency and migration; `score >= rawScore`
59
+ * always holds.
60
+ */
61
+ rawScore: number;
62
+ /** Achieved complexity of the document, from core `analyze()`. */
63
+ complexity: {
64
+ /** Overall complexity score (1-10, higher = more complex). */
65
+ score: number;
66
+ /** Complexity band: `'simple' | 'moderate' | 'complex' | 'very-complex'`. */
67
+ level: string;
68
+ };
51
69
  /** Issues found */
52
70
  issues: UXIssue[];
53
71
  /** Summary by category */
@@ -174,6 +192,18 @@ declare const MAX_TOOLTIP_LENGTH = 100;
174
192
  declare const MAX_LIST_ITEMS = 20;
175
193
  /** Maximum table columns */
176
194
  declare const MAX_TABLE_COLUMNS = 8;
195
+ /**
196
+ * Complexity calibration point for score normalization.
197
+ *
198
+ * The headline score damps the *soft* penalty (warnings + info) by
199
+ * `REFERENCE_COMPLEXITY / max(REFERENCE_COMPLEXITY, complexity.score)`, where
200
+ * `complexity.score` ∈ [1,10] comes from core `analyze()`. At or below this
201
+ * point the factor is 1 (no relief), so a trivial screen can never earn a
202
+ * softer penalty by being simple; above it, a richer design gets proportional
203
+ * relief for the per-element warnings it is expected to accumulate. Errors are
204
+ * never damped. `3` corresponds to core's "moderate" complexity band.
205
+ */
206
+ declare const REFERENCE_COMPLEXITY = 3;
177
207
  /** Minimum touch target size (WCAG 2.5.5 AAA: 44x44px) */
178
208
  declare const MIN_TOUCH_TARGET = 44;
179
209
  /** Recommended touch target size (Material Design: 48x48px) */
@@ -340,4 +370,4 @@ declare function getUXScore(ast: WireframeDocument): number;
340
370
  */
341
371
  declare function formatUXResult(result: UXValidationResult): string;
342
372
 
343
- export { ASYNC_ACTION_WORDS, CLOSE_WORDS, CONTAINER_TYPES, DESTRUCTIVE_WORDS, ERROR_WORDS, FORM_INPUT_TYPES, GENERIC_LINK_TEXTS, HOME_WORDS, INPUT_TYPE_SUGGESTIONS, MAX_BUTTONS, MAX_BUTTON_TEXT_LENGTH, MAX_FORM_FIELDS, MAX_LIST_ITEMS, MAX_NAV_ITEMS, MAX_NESTING_DEPTH, MAX_PAGE_ELEMENTS, MAX_TABLE_COLUMNS, MAX_TABS, MAX_TITLE_LENGTH, MAX_TOAST_DURATION, MAX_TOOLTIP_LENGTH, MIN_TOAST_DURATION, MIN_TOUCH_TARGET, PLACEHOLDER_PATTERNS, RECOMMENDED_TOUCH_TARGET, SIZE_MAP, SUBMIT_WORDS, SUCCESS_WORDS, TEXT_CONTENT_TYPES, type UXIssue, type UXIssueSeverity, type UXRule, type UXRuleCategory, type UXRuleContext, type UXValidationOptions, type UXValidationResult, WARNING_WORDS, allRules, containsAnyWord, countInChildren, filterChildren, findInChildren, formatUXResult, getButtonStyle, getChildren, getNodeItems, getNodeLocation, getNodeText, getNodeTextLower, getRulesForCategories, getSizeValue, getUXIssues, getUXScore, hasChildMatching, hasChildren, isAnyNode, isNodeType, isUXValid, matchesAnyWord, rulesByCategory, toAnyNodeArray, validateUX };
373
+ export { ASYNC_ACTION_WORDS, CLOSE_WORDS, CONTAINER_TYPES, DESTRUCTIVE_WORDS, ERROR_WORDS, FORM_INPUT_TYPES, GENERIC_LINK_TEXTS, HOME_WORDS, INPUT_TYPE_SUGGESTIONS, MAX_BUTTONS, MAX_BUTTON_TEXT_LENGTH, MAX_FORM_FIELDS, MAX_LIST_ITEMS, MAX_NAV_ITEMS, MAX_NESTING_DEPTH, MAX_PAGE_ELEMENTS, MAX_TABLE_COLUMNS, MAX_TABS, MAX_TITLE_LENGTH, MAX_TOAST_DURATION, MAX_TOOLTIP_LENGTH, MIN_TOAST_DURATION, MIN_TOUCH_TARGET, PLACEHOLDER_PATTERNS, RECOMMENDED_TOUCH_TARGET, REFERENCE_COMPLEXITY, SIZE_MAP, SUBMIT_WORDS, SUCCESS_WORDS, TEXT_CONTENT_TYPES, type UXIssue, type UXIssueSeverity, type UXRule, type UXRuleCategory, type UXRuleContext, type UXValidationOptions, type UXValidationResult, WARNING_WORDS, allRules, containsAnyWord, countInChildren, filterChildren, findInChildren, formatUXResult, getButtonStyle, getChildren, getNodeItems, getNodeLocation, getNodeText, getNodeTextLower, getRulesForCategories, getSizeValue, getUXIssues, getUXScore, hasChildMatching, hasChildren, isAnyNode, isNodeType, isUXValid, matchesAnyWord, rulesByCategory, toAnyNodeArray, validateUX };
package/dist/index.js CHANGED
@@ -1,3 +1,6 @@
1
+ // src/index.ts
2
+ import { analyze } from "@wireweave/core";
3
+
1
4
  // src/constants.ts
2
5
  var MAX_NAV_ITEMS = 7;
3
6
  var MAX_TABS = 5;
@@ -10,6 +13,7 @@ var MAX_TITLE_LENGTH = 60;
10
13
  var MAX_TOOLTIP_LENGTH = 100;
11
14
  var MAX_LIST_ITEMS = 20;
12
15
  var MAX_TABLE_COLUMNS = 8;
16
+ var REFERENCE_COMPLEXITY = 3;
13
17
  var MIN_TOUCH_TARGET = 44;
14
18
  var RECOMMENDED_TOUCH_TARGET = 48;
15
19
  var SIZE_MAP = {
@@ -824,6 +828,7 @@ var consistencyRules = [
824
828
  ];
825
829
 
826
830
  // src/rules/usability.ts
831
+ import { resolveViewport } from "@wireweave/core";
827
832
  var noEmptyContainers = {
828
833
  id: "usability-empty-container",
829
834
  category: "usability",
@@ -1104,6 +1109,64 @@ var drawerWidth = {
1104
1109
  return null;
1105
1110
  }
1106
1111
  };
1112
+ function pageDimensions(page) {
1113
+ const explicitW = typeof page.w === "number" ? page.w : void 0;
1114
+ const explicitH = typeof page.h === "number" ? page.h : void 0;
1115
+ if (explicitW !== void 0 && explicitH !== void 0) {
1116
+ return { width: explicitW, height: explicitH };
1117
+ }
1118
+ const vp = resolveViewport(page.viewport, page.device);
1119
+ return { width: vp.width, height: vp.height };
1120
+ }
1121
+ function pageBox(page) {
1122
+ const { width, height } = pageDimensions(page);
1123
+ return {
1124
+ x: typeof page.x === "number" ? page.x : 0,
1125
+ y: typeof page.y === "number" ? page.y : 0,
1126
+ w: width,
1127
+ h: height
1128
+ };
1129
+ }
1130
+ function boxesOverlap(a, b) {
1131
+ return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
1132
+ }
1133
+ var noPageOverlap = {
1134
+ id: "usability-page-overlap",
1135
+ category: "usability",
1136
+ severity: "warning",
1137
+ name: "Pages should not overlap on the canvas",
1138
+ description: "Pages placed at explicit coordinates may visually overlap when their bounding boxes intersect",
1139
+ appliesTo: ["Page"],
1140
+ check: (node, context) => {
1141
+ if (node.type !== "Page") return null;
1142
+ const page = node;
1143
+ if (typeof page.x !== "number" || typeof page.y !== "number") return null;
1144
+ const issues = [];
1145
+ const myBox = pageBox(page);
1146
+ for (let i = context.index + 1; i < context.siblings.length; i++) {
1147
+ const other = context.siblings[i];
1148
+ if (!other || other.type !== "Page") continue;
1149
+ const otherPage = other;
1150
+ if (typeof otherPage.x !== "number" || typeof otherPage.y !== "number") continue;
1151
+ if (boxesOverlap(myBox, pageBox(otherPage))) {
1152
+ const myTitle = page.title ?? `pages[${context.index}]`;
1153
+ const otherTitle = otherPage.title ?? `pages[${i}]`;
1154
+ issues.push({
1155
+ ruleId: "usability-page-overlap",
1156
+ category: "usability",
1157
+ severity: "warning",
1158
+ message: `Page "${myTitle}" overlaps page "${otherTitle}" on the canvas`,
1159
+ description: "Two pages with explicit at(x, y) coordinates have intersecting bounding boxes",
1160
+ suggestion: "Move one page so the bounding boxes do not intersect, or remove at() to let the page auto-flow",
1161
+ path: context.path,
1162
+ nodeType: node.type,
1163
+ location: getNodeLocation(node)
1164
+ });
1165
+ }
1166
+ }
1167
+ return issues.length > 0 ? issues : null;
1168
+ }
1169
+ };
1107
1170
  var usabilityRules = [
1108
1171
  noEmptyContainers,
1109
1172
  clearCTA,
@@ -1114,7 +1177,8 @@ var usabilityRules = [
1114
1177
  tooManyButtons,
1115
1178
  tooManyFormFields,
1116
1179
  tooManyPageElements,
1117
- drawerWidth
1180
+ drawerWidth,
1181
+ noPageOverlap
1118
1182
  ];
1119
1183
 
1120
1184
  // src/rules/navigation.ts
@@ -2117,6 +2181,16 @@ var SEVERITY_ORDER = {
2117
2181
  warning: 1,
2118
2182
  info: 2
2119
2183
  };
2184
+ function resolveComplexity(ast) {
2185
+ try {
2186
+ const result = analyze(ast);
2187
+ if (result.success && typeof result.complexity?.score === "number" && Number.isFinite(result.complexity.score) && result.complexity.score > 0) {
2188
+ return { score: result.complexity.score, level: result.complexity.level };
2189
+ }
2190
+ } catch {
2191
+ }
2192
+ return { score: REFERENCE_COMPLEXITY, level: "moderate" };
2193
+ }
2120
2194
  function validateUX(ast, options = {}) {
2121
2195
  const {
2122
2196
  categories = [],
@@ -2220,10 +2294,14 @@ function validateUX(ast, options = {}) {
2220
2294
  const warningCount = issues.filter((i) => i.severity === "warning").length;
2221
2295
  const infoCount = issues.filter((i) => i.severity === "info").length;
2222
2296
  const errorPenalty = errorCount * 10;
2223
- const warningPenalty = warningCount * 3;
2224
- const infoPenalty = infoCount * 1;
2225
- const totalPenalty = errorPenalty + warningPenalty + infoPenalty;
2226
- const score = Math.max(0, Math.min(100, 100 - totalPenalty));
2297
+ const rawSoftPenalty = warningCount * 3 + infoCount * 1;
2298
+ const rawScore = Math.max(0, Math.min(100, 100 - errorPenalty - rawSoftPenalty));
2299
+ const complexity = resolveComplexity(ast);
2300
+ const dampingFactor = REFERENCE_COMPLEXITY / Math.max(REFERENCE_COMPLEXITY, complexity.score);
2301
+ const score = Math.max(
2302
+ 0,
2303
+ Math.min(100, Math.round(100 - errorPenalty - rawSoftPenalty * dampingFactor))
2304
+ );
2227
2305
  const summary = Array.from(categoryStats.entries()).map(([category, stats]) => ({
2228
2306
  category,
2229
2307
  passed: stats.passed,
@@ -2233,6 +2311,8 @@ function validateUX(ast, options = {}) {
2233
2311
  return {
2234
2312
  valid: errorCount === 0,
2235
2313
  score,
2314
+ rawScore,
2315
+ complexity,
2236
2316
  issues,
2237
2317
  summary,
2238
2318
  severityCounts: {
@@ -2302,6 +2382,7 @@ export {
2302
2382
  MIN_TOUCH_TARGET,
2303
2383
  PLACEHOLDER_PATTERNS,
2304
2384
  RECOMMENDED_TOUCH_TARGET,
2385
+ REFERENCE_COMPLEXITY,
2305
2386
  SIZE_MAP,
2306
2387
  SUBMIT_WORDS,
2307
2388
  SUCCESS_WORDS,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wireweave/ux-rules",
3
- "version": "1.2.3-beta.0",
3
+ "version": "1.3.0",
4
4
  "description": "UX validation rules for wireweave",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",