@wireweave/ux-rules 1.2.2 → 1.3.0-beta.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 +41 -10
- package/dist/index.cjs +85 -5
- package/dist/index.d.cts +32 -2
- package/dist/index.d.ts +32 -2
- package/dist/index.js +86 -5
- package/package.json +2 -2
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);
|
|
37
|
-
console.log(result.
|
|
38
|
-
console.log(result.
|
|
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 |
|
|
94
|
-
|
|
95
|
-
| `error` | Critical UX problem | -10 |
|
|
96
|
-
| `warning` | Should fix | -3 |
|
|
97
|
-
| `info` | Consider improving | -1 |
|
|
98
|
-
|
|
99
|
-
|
|
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
|
|
2304
|
-
const
|
|
2305
|
-
const
|
|
2306
|
-
const
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
2224
|
-
const
|
|
2225
|
-
const
|
|
2226
|
-
const
|
|
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.
|
|
3
|
+
"version": "1.3.0-beta.0",
|
|
4
4
|
"description": "UX validation rules for wireweave",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"release:beta": "release-it --preRelease=beta"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@wireweave/core": "^2.
|
|
28
|
+
"@wireweave/core": "^2.7.0"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
31
|
"@release-it/conventional-changelog": "^10.0.4",
|