@wireweave/ux-rules 1.5.0-beta.11 → 1.5.0-beta.13
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 +14 -311
- package/package.json +14 -18
package/README.md
CHANGED
|
@@ -1,324 +1,27 @@
|
|
|
1
1
|
# @wireweave/ux-rules
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://www.npmjs.com/package/@wireweave/ux-rules)
|
|
5
|
-
[](https://opensource.org/licenses/MIT)
|
|
3
|
+
Deterministic UX diagnostics for Wireweave documents and applications.
|
|
6
4
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## What it does
|
|
10
|
-
|
|
11
|
-
Walks a parsed wireframe AST (from [`@wireweave/core`](https://www.npmjs.com/package/@wireweave/core)) and checks it against 59 UX best-practice rules across 10 categories — accessibility, forms, usability, touch targets, navigation, consistency, content, data display, feedback, and interaction. It returns the matched issues plus a complexity-normalized **0–100 score**.
|
|
12
|
-
|
|
13
|
-
It is a free, fully local linter — no network, no API key. The Wireweave SDK and CLI expose it as the `validate_ux` tool. Validation only; it does not autofix.
|
|
5
|
+
The [public tool contract](../../docs/spec/TOOLING.md#2-pure-library-api) defines this package's APIs, behavior, configuration and compatibility. The [language contract](../../docs/spec/LANGUAGE.md) defines the DSL. [Package metadata](package.json) owns package versions, exports, dependencies and scripts.
|
|
14
6
|
|
|
15
7
|
## Installation
|
|
16
8
|
|
|
17
|
-
|
|
18
|
-
npm install @wireweave/ux-rules
|
|
19
|
-
# or
|
|
20
|
-
pnpm add @wireweave/ux-rules
|
|
21
|
-
# or
|
|
22
|
-
yarn add @wireweave/ux-rules
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Usage
|
|
26
|
-
|
|
27
|
-
```typescript
|
|
28
|
-
import { parse } from '@wireweave/core'
|
|
29
|
-
import { validateUX, getUXScore, getUXIssues } from '@wireweave/ux-rules'
|
|
30
|
-
|
|
31
|
-
const doc = parse(`
|
|
32
|
-
page {
|
|
33
|
-
card {
|
|
34
|
-
input placeholder="Email"
|
|
35
|
-
button "Submit" primary
|
|
36
|
-
}
|
|
37
|
-
}
|
|
38
|
-
`)
|
|
9
|
+
Use Node.js >=22.13.0. Replace `<pinned-version>` with the release selected for your toolchain.
|
|
39
10
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
console.log(result.score) // 0-100, complexity-normalized
|
|
43
|
-
console.log(result.rawScore) // 0-100, undamped total penalty
|
|
44
|
-
console.log(result.complexity) // { score: 1-10, level: 'simple' | ... }
|
|
45
|
-
console.log(result.valid) // true if no errors
|
|
46
|
-
console.log(result.issues) // Array of UX issues
|
|
47
|
-
|
|
48
|
-
// Quick helpers
|
|
49
|
-
const score = getUXScore(doc)
|
|
50
|
-
const issues = getUXIssues(doc)
|
|
11
|
+
```bash
|
|
12
|
+
pnpm add --save-exact '@wireweave/ux-rules@<pinned-version>'
|
|
51
13
|
```
|
|
52
14
|
|
|
53
|
-
##
|
|
54
|
-
|
|
55
|
-
| Category | Rules | Description |
|
|
56
|
-
| --------------- | ----- | ------------------------------------------------------------------------- |
|
|
57
|
-
| `accessibility` | 5 | Screen reader support, labels, alt text |
|
|
58
|
-
| `form` | 4 | Form UX patterns, input types, validation |
|
|
59
|
-
| `usability` | 10 | General usability (empty containers, CTA, loading states, cognitive load) |
|
|
60
|
-
| `touch-target` | 5 | Touch target sizes for mobile (WCAG 2.5.5) |
|
|
61
|
-
| `navigation` | 5 | Navigation patterns (item count, active states) |
|
|
62
|
-
| `consistency` | 4 | Consistent styling across components |
|
|
63
|
-
| `content` | 6 | Text quality, placeholder detection, title requirements |
|
|
64
|
-
| `data-display` | 6 | Tables, lists, empty states, pagination |
|
|
65
|
-
| `feedback` | 6 | Spinners, progress bars, toasts, alerts |
|
|
66
|
-
| `interaction` | 8 | Interactive elements need actions defined |
|
|
67
|
-
|
|
68
|
-
**Total: 59 rules**
|
|
69
|
-
|
|
70
|
-
## API
|
|
71
|
-
|
|
72
|
-
### `validateUX(ast, options?)`
|
|
73
|
-
|
|
74
|
-
Full validation with score and issues.
|
|
75
|
-
|
|
76
|
-
**Options:**
|
|
77
|
-
|
|
78
|
-
- `categories`: Filter by rule categories
|
|
79
|
-
- `minSeverity`: Minimum severity to report (`'error'` | `'warning'` | `'info'`)
|
|
80
|
-
- `maxIssues`: Maximum issues to collect
|
|
81
|
-
- `customRules`: Add custom rules
|
|
82
|
-
- `disabledRules`: Disable rules by ID
|
|
83
|
-
|
|
84
|
-
**Returns** `UXValidationResult`:
|
|
85
|
-
|
|
86
|
-
- `valid`: `true` if no errors
|
|
87
|
-
- `score`: complexity-normalized score (0-100) — see [Scoring](#scoring)
|
|
88
|
-
- `rawScore`: undamped total-penalty score (0-100)
|
|
89
|
-
- `complexity`: `{ score: 1-10, level }` from core `analyze()`
|
|
90
|
-
- `issues`: array of `UXIssue`
|
|
91
|
-
- `summary`: per-category pass/fail/warning counts
|
|
92
|
-
- `severityCounts`: `{ errors, warnings, info }`
|
|
93
|
-
|
|
94
|
-
### `isUXValid(ast)`
|
|
95
|
-
|
|
96
|
-
Quick check - returns `true` if no errors.
|
|
97
|
-
|
|
98
|
-
### `getUXScore(ast)`
|
|
99
|
-
|
|
100
|
-
Returns UX score from 0 to 100.
|
|
101
|
-
|
|
102
|
-
### `getUXIssues(ast, options?)`
|
|
103
|
-
|
|
104
|
-
Returns array of UX issues.
|
|
105
|
-
|
|
106
|
-
### `formatUXResult(result)`
|
|
107
|
-
|
|
108
|
-
Formats validation result as human-readable string.
|
|
109
|
-
|
|
110
|
-
## Issue Severity
|
|
111
|
-
|
|
112
|
-
| Severity | Impact | Base Penalty |
|
|
113
|
-
| --------- | ------------------- | -------------- |
|
|
114
|
-
| `error` | Critical UX problem | -10 (absolute) |
|
|
115
|
-
| `warning` | Should fix | -3 (soft) |
|
|
116
|
-
| `info` | Consider improving | -1 (soft) |
|
|
117
|
-
|
|
118
|
-
### Scoring
|
|
119
|
-
|
|
120
|
-
`validateUX()` returns two scores:
|
|
121
|
-
|
|
122
|
-
- **`rawScore`** — the undamped total penalty, clamped to `[0, 100]`:
|
|
123
|
-
`100 − (errors × 10 + warnings × 3 + info × 1)`.
|
|
124
|
-
- **`score`** — the headline score. Errors stay an absolute penalty (a hard defect
|
|
125
|
-
is a hard defect at any screen size — no volume discount). The _soft_ penalty
|
|
126
|
-
(warnings + info) is damped by the document's achieved complexity:
|
|
127
|
-
|
|
128
|
-
```
|
|
129
|
-
score = round(100 − errors × 10 − (warnings × 3 + info × 1) × dampingFactor)
|
|
130
|
-
dampingFactor = REFERENCE_COMPLEXITY / max(REFERENCE_COMPLEXITY, complexity.score)
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
`complexity.score` ∈ `[1, 10]` comes from `@wireweave/core`'s `analyze()`, and
|
|
134
|
-
`REFERENCE_COMPLEXITY` is `3` (core's "moderate" band). At or below the reference
|
|
135
|
-
the factor is `1`, so a trivial screen earns no relief; above it, a dense,
|
|
136
|
-
intent-fitting design gets proportional relief for the per-element
|
|
137
|
-
warning/info heuristics it is expected to accumulate. `score >= rawScore` always
|
|
138
|
-
holds. Both `complexity` and `REFERENCE_COMPLEXITY` are exported.
|
|
139
|
-
|
|
140
|
-
## All Rules
|
|
141
|
-
|
|
142
|
-
<details>
|
|
143
|
-
<summary><strong>Accessibility (5 rules)</strong></summary>
|
|
144
|
-
|
|
145
|
-
| Rule ID | Severity | Description |
|
|
146
|
-
| ------------------------ | ------------- | -------------------------------------- |
|
|
147
|
-
| `a11y-input-label` | error/warning | Input fields must have labels |
|
|
148
|
-
| `a11y-image-alt` | warning | Images should have alt text |
|
|
149
|
-
| `a11y-icon-button-label` | error | Icon-only buttons need accessible text |
|
|
150
|
-
| `a11y-link-text` | warning | Links should have descriptive text |
|
|
151
|
-
| `a11y-heading-hierarchy` | warning | Heading levels should be sequential |
|
|
15
|
+
## Development
|
|
152
16
|
|
|
153
|
-
|
|
17
|
+
Run from the monorepo root after the [workspace setup](../../README.md).
|
|
154
18
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
| `form-required-indicator` | info | Required fields should be marked |
|
|
162
|
-
| `form-password-confirm` | info | Registration forms may need password confirmation |
|
|
163
|
-
| `form-input-type` | warning | Use appropriate input types (email, tel, etc.) |
|
|
164
|
-
|
|
165
|
-
</details>
|
|
166
|
-
|
|
167
|
-
<details>
|
|
168
|
-
<summary><strong>Usability (10 rules)</strong></summary>
|
|
169
|
-
|
|
170
|
-
| Rule ID | Severity | Description |
|
|
171
|
-
| -------------------------------- | -------- | --------------------------------------- |
|
|
172
|
-
| `usability-empty-container` | warning | Avoid empty containers |
|
|
173
|
-
| `usability-clear-cta` | info | Pages should have primary button (CTA) |
|
|
174
|
-
| `usability-loading-states` | info | Async buttons may need loading state |
|
|
175
|
-
| `usability-destructive-confirm` | warning | Destructive actions need danger styling |
|
|
176
|
-
| `usability-modal-close` | warning | Modals need close mechanism |
|
|
177
|
-
| `usability-nesting-depth` | warning | Avoid excessive nesting (max 6 levels) |
|
|
178
|
-
| `usability-too-many-buttons` | warning | Max 5 buttons per container |
|
|
179
|
-
| `usability-too-many-form-fields` | info | Max 10 form fields |
|
|
180
|
-
| `usability-page-complexity` | info | Max 50 elements per page |
|
|
181
|
-
| `usability-drawer-width` | info | Drawers should have width |
|
|
182
|
-
|
|
183
|
-
</details>
|
|
184
|
-
|
|
185
|
-
<details>
|
|
186
|
-
<summary><strong>Touch Target (5 rules)</strong></summary>
|
|
187
|
-
|
|
188
|
-
| Rule ID | Severity | Description |
|
|
189
|
-
| --------------------------- | -------- | ---------------------------------- |
|
|
190
|
-
| `touch-button-size` | warning | Button minimum 44px (WCAG AAA) |
|
|
191
|
-
| `touch-icon-button-size` | warning | Icon buttons need adequate padding |
|
|
192
|
-
| `touch-checkbox-radio-size` | info | Checkbox/Radio should have labels |
|
|
193
|
-
| `touch-link-spacing` | info | Adjacent links need spacing |
|
|
194
|
-
| `touch-avatar-size` | info | Clickable avatars should be 44px+ |
|
|
195
|
-
|
|
196
|
-
</details>
|
|
197
|
-
|
|
198
|
-
<details>
|
|
199
|
-
<summary><strong>Navigation (5 rules)</strong></summary>
|
|
200
|
-
|
|
201
|
-
| Rule ID | Severity | Description |
|
|
202
|
-
| --------------------- | -------- | ------------------------------------- |
|
|
203
|
-
| `nav-item-count` | warning | Max 7 navigation items (Miller's Law) |
|
|
204
|
-
| `nav-active-state` | info | Navigation should show active state |
|
|
205
|
-
| `nav-breadcrumb-home` | info | Breadcrumb should start with home |
|
|
206
|
-
| `nav-tab-count` | warning | Max 5 tabs |
|
|
207
|
-
| `nav-dropdown-items` | warning | Dropdown must have items |
|
|
208
|
-
|
|
209
|
-
</details>
|
|
210
|
-
|
|
211
|
-
<details>
|
|
212
|
-
<summary><strong>Consistency (4 rules)</strong></summary>
|
|
213
|
-
|
|
214
|
-
| Rule ID | Severity | Description |
|
|
215
|
-
| ---------------------------- | -------- | ------------------------------------- |
|
|
216
|
-
| `consistency-button-styles` | info | Consistent button styles in container |
|
|
217
|
-
| `consistency-spacing` | info | Consistent gap values |
|
|
218
|
-
| `consistency-card-styling` | info | Sibling cards should match |
|
|
219
|
-
| `consistency-alert-variants` | warning | Alert variant should match content |
|
|
220
|
-
|
|
221
|
-
</details>
|
|
222
|
-
|
|
223
|
-
<details>
|
|
224
|
-
<summary><strong>Content (6 rules)</strong></summary>
|
|
225
|
-
|
|
226
|
-
| Rule ID | Severity | Description |
|
|
227
|
-
| ---------------------------- | -------- | ----------------------------- |
|
|
228
|
-
| `content-empty-text` | warning | Avoid empty/placeholder text |
|
|
229
|
-
| `content-button-text-length` | info | Button text max 25 characters |
|
|
230
|
-
| `content-title-length` | info | Title max 60 characters |
|
|
231
|
-
| `content-page-title` | warning | Pages should have title |
|
|
232
|
-
| `content-link-text` | error | Links must have text |
|
|
233
|
-
| `content-no-placeholder` | warning | Replace placeholder content |
|
|
234
|
-
|
|
235
|
-
</details>
|
|
236
|
-
|
|
237
|
-
<details>
|
|
238
|
-
<summary><strong>Data Display (6 rules)</strong></summary>
|
|
239
|
-
|
|
240
|
-
| Rule ID | Severity | Description |
|
|
241
|
-
| ------------------------ | -------- | -------------------------------- |
|
|
242
|
-
| `data-table-header` | warning | Tables need headers |
|
|
243
|
-
| `data-list-empty-state` | info | Lists should have empty state |
|
|
244
|
-
| `data-table-empty-state` | info | Tables should have empty state |
|
|
245
|
-
| `data-list-pagination` | info | Long lists (20+) need pagination |
|
|
246
|
-
| `data-table-columns` | warning | Max 8 table columns |
|
|
247
|
-
| `data-card-grid` | info | Card grids should be consistent |
|
|
248
|
-
|
|
249
|
-
</details>
|
|
250
|
-
|
|
251
|
-
<details>
|
|
252
|
-
<summary><strong>Feedback (6 rules)</strong></summary>
|
|
253
|
-
|
|
254
|
-
| Rule ID | Severity | Description |
|
|
255
|
-
| ---------------------------- | -------- | ----------------------------------------- |
|
|
256
|
-
| `feedback-spinner-context` | info | Spinners should have context text |
|
|
257
|
-
| `feedback-progress-value` | info | Progress should show value |
|
|
258
|
-
| `feedback-toast-duration` | info | Toast duration 2-10 seconds |
|
|
259
|
-
| `feedback-alert-dismissible` | info | Non-critical alerts should be dismissible |
|
|
260
|
-
| `feedback-tooltip-length` | info | Tooltip max 100 characters |
|
|
261
|
-
| `feedback-form-errors` | info | Forms should handle errors |
|
|
262
|
-
|
|
263
|
-
</details>
|
|
264
|
-
|
|
265
|
-
<details>
|
|
266
|
-
<summary><strong>Interaction (8 rules)</strong></summary>
|
|
267
|
-
|
|
268
|
-
| Rule ID | Severity | Description |
|
|
269
|
-
| -------------------------------- | -------- | -------------------------------- |
|
|
270
|
-
| `interaction-button-action` | warning | Buttons need onClick/action/href |
|
|
271
|
-
| `interaction-link-destination` | warning | Links need href/to destination |
|
|
272
|
-
| `interaction-form-submit` | warning | Forms need onSubmit/action |
|
|
273
|
-
| `interaction-tab-target` | warning | Tabs need target/value |
|
|
274
|
-
| `interaction-menu-action` | warning | Menu items need action |
|
|
275
|
-
| `interaction-card-action` | info | Clickable cards need action |
|
|
276
|
-
| `interaction-icon-button-action` | warning | Icon buttons need action |
|
|
277
|
-
| `interaction-modal-close` | info | Modals need close mechanism |
|
|
278
|
-
|
|
279
|
-
</details>
|
|
280
|
-
|
|
281
|
-
## Custom Rules
|
|
282
|
-
|
|
283
|
-
Create custom rules using the exported types and utilities:
|
|
284
|
-
|
|
285
|
-
```typescript
|
|
286
|
-
import { validateUX, UXRule, getNodeText, containsAnyWord } from '@wireweave/ux-rules'
|
|
287
|
-
|
|
288
|
-
const myRule: UXRule = {
|
|
289
|
-
id: 'custom-no-click-here',
|
|
290
|
-
category: 'accessibility',
|
|
291
|
-
severity: 'warning',
|
|
292
|
-
name: 'Avoid "click here" text',
|
|
293
|
-
description: 'Link text should be descriptive',
|
|
294
|
-
appliesTo: ['Button', 'Link'],
|
|
295
|
-
check: (node, context) => {
|
|
296
|
-
const text = getNodeText(node).toLowerCase()
|
|
297
|
-
if (containsAnyWord(text, ['click here', 'click me'])) {
|
|
298
|
-
return {
|
|
299
|
-
ruleId: 'custom-no-click-here',
|
|
300
|
-
category: 'accessibility',
|
|
301
|
-
severity: 'warning',
|
|
302
|
-
message: 'Avoid generic "click here" text',
|
|
303
|
-
description: 'Use descriptive text that indicates the action',
|
|
304
|
-
suggestion: 'Replace with descriptive action text',
|
|
305
|
-
path: context.path,
|
|
306
|
-
nodeType: node.type,
|
|
307
|
-
}
|
|
308
|
-
}
|
|
309
|
-
return null
|
|
310
|
-
},
|
|
311
|
-
}
|
|
312
|
-
|
|
313
|
-
const result = validateUX(doc, { customRules: [myRule] })
|
|
19
|
+
```bash
|
|
20
|
+
pnpm --filter @wireweave/ux-rules run build
|
|
21
|
+
pnpm --filter @wireweave/ux-rules run typecheck
|
|
22
|
+
pnpm --filter @wireweave/ux-rules run lint
|
|
23
|
+
pnpm --filter @wireweave/ux-rules run test
|
|
24
|
+
pnpm --filter @wireweave/ux-rules run format:check
|
|
314
25
|
```
|
|
315
26
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
- [@wireweave/core](https://www.npmjs.com/package/@wireweave/core) - Core parser and renderer
|
|
319
|
-
|
|
320
|
-
Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
|
|
321
|
-
|
|
322
|
-
## License
|
|
323
|
-
|
|
324
|
-
MIT
|
|
27
|
+
License: MIT.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wireweave/ux-rules",
|
|
3
|
-
"version": "1.5.0-beta.
|
|
3
|
+
"version": "1.5.0-beta.13",
|
|
4
4
|
"description": "UX validation rules for wireweave",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -26,25 +26,23 @@
|
|
|
26
26
|
"node": ">=22.13.0"
|
|
27
27
|
},
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"@wireweave/core": "
|
|
29
|
+
"@wireweave/core": "4.0.0-beta.13"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
|
-
"@commitlint/cli": "^21.
|
|
33
|
-
"@commitlint/config-conventional": "^21.
|
|
32
|
+
"@commitlint/cli": "^21.2.2",
|
|
33
|
+
"@commitlint/config-conventional": "^21.2.2",
|
|
34
34
|
"@eslint/js": "^10.0.1",
|
|
35
|
-
"@
|
|
36
|
-
"
|
|
37
|
-
"eslint": "^10.4.0",
|
|
35
|
+
"@types/node": "^22.20.2",
|
|
36
|
+
"eslint": "^10.10.0",
|
|
38
37
|
"husky": "^9.1.7",
|
|
39
|
-
"knip": "^6.
|
|
40
|
-
"lint-staged": "^
|
|
41
|
-
"prettier": "^3.
|
|
42
|
-
"publint": "^0.3.
|
|
43
|
-
"
|
|
44
|
-
"
|
|
45
|
-
"typescript": "^
|
|
46
|
-
"
|
|
47
|
-
"vitest": "^3.1.1"
|
|
38
|
+
"knip": "^6.35.1",
|
|
39
|
+
"lint-staged": "^16.4.0",
|
|
40
|
+
"prettier": "^3.9.6",
|
|
41
|
+
"publint": "^0.3.24",
|
|
42
|
+
"tsup": "^8.5.1",
|
|
43
|
+
"typescript": "^5.9.3",
|
|
44
|
+
"typescript-eslint": "^8.70.0",
|
|
45
|
+
"vitest": "^4.1.11"
|
|
48
46
|
},
|
|
49
47
|
"keywords": [
|
|
50
48
|
"wireframe",
|
|
@@ -69,8 +67,6 @@
|
|
|
69
67
|
"test": "vitest run",
|
|
70
68
|
"test:watch": "vitest",
|
|
71
69
|
"clean": "rm -rf dist",
|
|
72
|
-
"release": "release-it",
|
|
73
|
-
"release:beta": "release-it --preRelease=beta",
|
|
74
70
|
"typecheck": "tsc --noEmit",
|
|
75
71
|
"lint": "eslint .",
|
|
76
72
|
"lint:fix": "eslint . --fix",
|