@wireweave/ux-rules 1.4.0 → 1.5.0-beta.1
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 +125 -115
- package/dist/index.cjs +156 -78
- package/dist/index.d.cts +10 -1
- package/dist/index.d.ts +10 -1
- package/dist/index.js +152 -76
- package/package.json +35 -17
package/README.md
CHANGED
|
@@ -4,7 +4,13 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@wireweave/ux-rules)
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
|
|
7
|
-
UX validation rules for Wireweave DSL.
|
|
7
|
+
UX validation rules for Wireweave DSL.
|
|
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.
|
|
8
14
|
|
|
9
15
|
## Installation
|
|
10
16
|
|
|
@@ -19,8 +25,8 @@ yarn add @wireweave/ux-rules
|
|
|
19
25
|
## Usage
|
|
20
26
|
|
|
21
27
|
```typescript
|
|
22
|
-
import { parse } from '@wireweave/core'
|
|
23
|
-
import { validateUX, getUXScore, getUXIssues } from '@wireweave/ux-rules'
|
|
28
|
+
import { parse } from '@wireweave/core'
|
|
29
|
+
import { validateUX, getUXScore, getUXIssues } from '@wireweave/ux-rules'
|
|
24
30
|
|
|
25
31
|
const doc = parse(`
|
|
26
32
|
page {
|
|
@@ -29,35 +35,35 @@ const doc = parse(`
|
|
|
29
35
|
button "Submit" primary
|
|
30
36
|
}
|
|
31
37
|
}
|
|
32
|
-
`)
|
|
38
|
+
`)
|
|
33
39
|
|
|
34
40
|
// Full validation
|
|
35
|
-
const result = validateUX(doc)
|
|
36
|
-
console.log(result.score)
|
|
37
|
-
console.log(result.rawScore)
|
|
38
|
-
console.log(result.complexity)
|
|
39
|
-
console.log(result.valid)
|
|
40
|
-
console.log(result.issues)
|
|
41
|
+
const result = validateUX(doc)
|
|
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
|
|
41
47
|
|
|
42
48
|
// Quick helpers
|
|
43
|
-
const score = getUXScore(doc)
|
|
44
|
-
const issues = getUXIssues(doc)
|
|
49
|
+
const score = getUXScore(doc)
|
|
50
|
+
const issues = getUXIssues(doc)
|
|
45
51
|
```
|
|
46
52
|
|
|
47
53
|
## Rule Categories
|
|
48
54
|
|
|
49
|
-
| Category
|
|
50
|
-
|
|
51
|
-
| `accessibility` | 5
|
|
52
|
-
| `form`
|
|
53
|
-
| `usability`
|
|
54
|
-
| `touch-target`
|
|
55
|
-
| `navigation`
|
|
56
|
-
| `consistency`
|
|
57
|
-
| `content`
|
|
58
|
-
| `data-display`
|
|
59
|
-
| `feedback`
|
|
60
|
-
| `interaction`
|
|
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 |
|
|
61
67
|
|
|
62
68
|
**Total: 59 rules**
|
|
63
69
|
|
|
@@ -68,6 +74,7 @@ const issues = getUXIssues(doc);
|
|
|
68
74
|
Full validation with score and issues.
|
|
69
75
|
|
|
70
76
|
**Options:**
|
|
77
|
+
|
|
71
78
|
- `categories`: Filter by rule categories
|
|
72
79
|
- `minSeverity`: Minimum severity to report (`'error'` | `'warning'` | `'info'`)
|
|
73
80
|
- `maxIssues`: Maximum issues to collect
|
|
@@ -75,6 +82,7 @@ Full validation with score and issues.
|
|
|
75
82
|
- `disabledRules`: Disable rules by ID
|
|
76
83
|
|
|
77
84
|
**Returns** `UXValidationResult`:
|
|
85
|
+
|
|
78
86
|
- `valid`: `true` if no errors
|
|
79
87
|
- `score`: complexity-normalized score (0-100) — see [Scoring](#scoring)
|
|
80
88
|
- `rawScore`: undamped total-penalty score (0-100)
|
|
@@ -101,11 +109,11 @@ Formats validation result as human-readable string.
|
|
|
101
109
|
|
|
102
110
|
## Issue Severity
|
|
103
111
|
|
|
104
|
-
| Severity
|
|
105
|
-
|
|
106
|
-
| `error`
|
|
107
|
-
| `warning` | Should fix
|
|
108
|
-
| `info`
|
|
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) |
|
|
109
117
|
|
|
110
118
|
### Scoring
|
|
111
119
|
|
|
@@ -114,7 +122,7 @@ Formats validation result as human-readable string.
|
|
|
114
122
|
- **`rawScore`** — the undamped total penalty, clamped to `[0, 100]`:
|
|
115
123
|
`100 − (errors × 10 + warnings × 3 + info × 1)`.
|
|
116
124
|
- **`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
|
|
125
|
+
is a hard defect at any screen size — no volume discount). The _soft_ penalty
|
|
118
126
|
(warnings + info) is damped by the document's achieved complexity:
|
|
119
127
|
|
|
120
128
|
```
|
|
@@ -134,139 +142,139 @@ Formats validation result as human-readable string.
|
|
|
134
142
|
<details>
|
|
135
143
|
<summary><strong>Accessibility (5 rules)</strong></summary>
|
|
136
144
|
|
|
137
|
-
| Rule ID
|
|
138
|
-
|
|
139
|
-
| `a11y-input-label`
|
|
140
|
-
| `a11y-image-alt`
|
|
141
|
-
| `a11y-icon-button-label` | error
|
|
142
|
-
| `a11y-link-text`
|
|
143
|
-
| `a11y-heading-hierarchy` | warning
|
|
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 |
|
|
144
152
|
|
|
145
153
|
</details>
|
|
146
154
|
|
|
147
155
|
<details>
|
|
148
156
|
<summary><strong>Form (4 rules)</strong></summary>
|
|
149
157
|
|
|
150
|
-
| Rule ID
|
|
151
|
-
|
|
152
|
-
| `form-submit-button`
|
|
153
|
-
| `form-required-indicator` | info
|
|
154
|
-
| `form-password-confirm`
|
|
155
|
-
| `form-input-type`
|
|
158
|
+
| Rule ID | Severity | Description |
|
|
159
|
+
| ------------------------- | -------- | ------------------------------------------------- |
|
|
160
|
+
| `form-submit-button` | warning | Forms with inputs need submit button |
|
|
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.) |
|
|
156
164
|
|
|
157
165
|
</details>
|
|
158
166
|
|
|
159
167
|
<details>
|
|
160
168
|
<summary><strong>Usability (10 rules)</strong></summary>
|
|
161
169
|
|
|
162
|
-
| Rule ID
|
|
163
|
-
|
|
164
|
-
| `usability-empty-container`
|
|
165
|
-
| `usability-clear-cta`
|
|
166
|
-
| `usability-loading-states`
|
|
167
|
-
| `usability-destructive-confirm`
|
|
168
|
-
| `usability-modal-close`
|
|
169
|
-
| `usability-nesting-depth`
|
|
170
|
-
| `usability-too-many-buttons`
|
|
171
|
-
| `usability-too-many-form-fields` | info
|
|
172
|
-
| `usability-page-complexity`
|
|
173
|
-
| `usability-drawer-width`
|
|
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 |
|
|
174
182
|
|
|
175
183
|
</details>
|
|
176
184
|
|
|
177
185
|
<details>
|
|
178
186
|
<summary><strong>Touch Target (5 rules)</strong></summary>
|
|
179
187
|
|
|
180
|
-
| Rule ID
|
|
181
|
-
|
|
182
|
-
| `touch-button-size`
|
|
183
|
-
| `touch-icon-button-size`
|
|
184
|
-
| `touch-checkbox-radio-size` | info
|
|
185
|
-
| `touch-link-spacing`
|
|
186
|
-
| `touch-avatar-size`
|
|
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+ |
|
|
187
195
|
|
|
188
196
|
</details>
|
|
189
197
|
|
|
190
198
|
<details>
|
|
191
199
|
<summary><strong>Navigation (5 rules)</strong></summary>
|
|
192
200
|
|
|
193
|
-
| Rule ID
|
|
194
|
-
|
|
195
|
-
| `nav-item-count`
|
|
196
|
-
| `nav-active-state`
|
|
197
|
-
| `nav-breadcrumb-home` | info
|
|
198
|
-
| `nav-tab-count`
|
|
199
|
-
| `nav-dropdown-items`
|
|
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 |
|
|
200
208
|
|
|
201
209
|
</details>
|
|
202
210
|
|
|
203
211
|
<details>
|
|
204
212
|
<summary><strong>Consistency (4 rules)</strong></summary>
|
|
205
213
|
|
|
206
|
-
| Rule ID
|
|
207
|
-
|
|
208
|
-
| `consistency-button-styles`
|
|
209
|
-
| `consistency-spacing`
|
|
210
|
-
| `consistency-card-styling`
|
|
211
|
-
| `consistency-alert-variants` | warning
|
|
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 |
|
|
212
220
|
|
|
213
221
|
</details>
|
|
214
222
|
|
|
215
223
|
<details>
|
|
216
224
|
<summary><strong>Content (6 rules)</strong></summary>
|
|
217
225
|
|
|
218
|
-
| Rule ID
|
|
219
|
-
|
|
220
|
-
| `content-empty-text`
|
|
221
|
-
| `content-button-text-length` | info
|
|
222
|
-
| `content-title-length`
|
|
223
|
-
| `content-page-title`
|
|
224
|
-
| `content-link-text`
|
|
225
|
-
| `content-no-placeholder`
|
|
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 |
|
|
226
234
|
|
|
227
235
|
</details>
|
|
228
236
|
|
|
229
237
|
<details>
|
|
230
238
|
<summary><strong>Data Display (6 rules)</strong></summary>
|
|
231
239
|
|
|
232
|
-
| Rule ID
|
|
233
|
-
|
|
234
|
-
| `data-table-header`
|
|
235
|
-
| `data-list-empty-state`
|
|
236
|
-
| `data-table-empty-state` | info
|
|
237
|
-
| `data-list-pagination`
|
|
238
|
-
| `data-table-columns`
|
|
239
|
-
| `data-card-grid`
|
|
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 |
|
|
240
248
|
|
|
241
249
|
</details>
|
|
242
250
|
|
|
243
251
|
<details>
|
|
244
252
|
<summary><strong>Feedback (6 rules)</strong></summary>
|
|
245
253
|
|
|
246
|
-
| Rule ID
|
|
247
|
-
|
|
248
|
-
| `feedback-spinner-context`
|
|
249
|
-
| `feedback-progress-value`
|
|
250
|
-
| `feedback-toast-duration`
|
|
251
|
-
| `feedback-alert-dismissible` | info
|
|
252
|
-
| `feedback-tooltip-length`
|
|
253
|
-
| `feedback-form-errors`
|
|
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 |
|
|
254
262
|
|
|
255
263
|
</details>
|
|
256
264
|
|
|
257
265
|
<details>
|
|
258
266
|
<summary><strong>Interaction (8 rules)</strong></summary>
|
|
259
267
|
|
|
260
|
-
| Rule ID
|
|
261
|
-
|
|
262
|
-
| `interaction-button-action`
|
|
263
|
-
| `interaction-link-destination`
|
|
264
|
-
| `interaction-form-submit`
|
|
265
|
-
| `interaction-tab-target`
|
|
266
|
-
| `interaction-menu-action`
|
|
267
|
-
| `interaction-card-action`
|
|
268
|
-
| `interaction-icon-button-action` | warning
|
|
269
|
-
| `interaction-modal-close`
|
|
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 |
|
|
270
278
|
|
|
271
279
|
</details>
|
|
272
280
|
|
|
@@ -275,7 +283,7 @@ Formats validation result as human-readable string.
|
|
|
275
283
|
Create custom rules using the exported types and utilities:
|
|
276
284
|
|
|
277
285
|
```typescript
|
|
278
|
-
import { validateUX, UXRule, getNodeText, containsAnyWord } from '@wireweave/ux-rules'
|
|
286
|
+
import { validateUX, UXRule, getNodeText, containsAnyWord } from '@wireweave/ux-rules'
|
|
279
287
|
|
|
280
288
|
const myRule: UXRule = {
|
|
281
289
|
id: 'custom-no-click-here',
|
|
@@ -285,7 +293,7 @@ const myRule: UXRule = {
|
|
|
285
293
|
description: 'Link text should be descriptive',
|
|
286
294
|
appliesTo: ['Button', 'Link'],
|
|
287
295
|
check: (node, context) => {
|
|
288
|
-
const text = getNodeText(node).toLowerCase()
|
|
296
|
+
const text = getNodeText(node).toLowerCase()
|
|
289
297
|
if (containsAnyWord(text, ['click here', 'click me'])) {
|
|
290
298
|
return {
|
|
291
299
|
ruleId: 'custom-no-click-here',
|
|
@@ -296,19 +304,21 @@ const myRule: UXRule = {
|
|
|
296
304
|
suggestion: 'Replace with descriptive action text',
|
|
297
305
|
path: context.path,
|
|
298
306
|
nodeType: node.type,
|
|
299
|
-
}
|
|
307
|
+
}
|
|
300
308
|
}
|
|
301
|
-
return null
|
|
309
|
+
return null
|
|
302
310
|
},
|
|
303
|
-
}
|
|
311
|
+
}
|
|
304
312
|
|
|
305
|
-
const result = validateUX(doc, { customRules: [myRule] })
|
|
313
|
+
const result = validateUX(doc, { customRules: [myRule] })
|
|
306
314
|
```
|
|
307
315
|
|
|
308
316
|
## Related Packages
|
|
309
317
|
|
|
310
318
|
- [@wireweave/core](https://www.npmjs.com/package/@wireweave/core) - Core parser and renderer
|
|
311
319
|
|
|
320
|
+
Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
|
|
321
|
+
|
|
312
322
|
## License
|
|
313
323
|
|
|
314
324
|
MIT
|
package/dist/index.cjs
CHANGED
|
@@ -52,6 +52,8 @@ __export(src_exports, {
|
|
|
52
52
|
TEXT_CONTENT_TYPES: () => TEXT_CONTENT_TYPES,
|
|
53
53
|
WARNING_WORDS: () => WARNING_WORDS,
|
|
54
54
|
allRules: () => allRules,
|
|
55
|
+
coerceText: () => coerceText,
|
|
56
|
+
coerceTextLower: () => coerceTextLower,
|
|
55
57
|
containsAnyWord: () => containsAnyWord,
|
|
56
58
|
countInChildren: () => countInChildren,
|
|
57
59
|
filterChildren: () => filterChildren,
|
|
@@ -78,7 +80,7 @@ __export(src_exports, {
|
|
|
78
80
|
validateUX: () => validateUX
|
|
79
81
|
});
|
|
80
82
|
module.exports = __toCommonJS(src_exports);
|
|
81
|
-
var
|
|
83
|
+
var import_core3 = require("@wireweave/core");
|
|
82
84
|
|
|
83
85
|
// src/constants.ts
|
|
84
86
|
var MAX_NAV_ITEMS = 7;
|
|
@@ -104,13 +106,7 @@ var SIZE_MAP = {
|
|
|
104
106
|
};
|
|
105
107
|
var MIN_TOAST_DURATION = 2e3;
|
|
106
108
|
var MAX_TOAST_DURATION = 1e4;
|
|
107
|
-
var GENERIC_LINK_TEXTS = [
|
|
108
|
-
"click here",
|
|
109
|
-
"here",
|
|
110
|
-
"read more",
|
|
111
|
-
"more",
|
|
112
|
-
"link"
|
|
113
|
-
];
|
|
109
|
+
var GENERIC_LINK_TEXTS = ["click here", "here", "read more", "more", "link"];
|
|
114
110
|
var ASYNC_ACTION_WORDS = [
|
|
115
111
|
"submit",
|
|
116
112
|
"save",
|
|
@@ -142,38 +138,11 @@ var SUBMIT_WORDS = [
|
|
|
142
138
|
"ok",
|
|
143
139
|
"done"
|
|
144
140
|
];
|
|
145
|
-
var ERROR_WORDS = [
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
"denied"
|
|
151
|
-
];
|
|
152
|
-
var SUCCESS_WORDS = [
|
|
153
|
-
"success",
|
|
154
|
-
"saved",
|
|
155
|
-
"created",
|
|
156
|
-
"updated",
|
|
157
|
-
"complete"
|
|
158
|
-
];
|
|
159
|
-
var WARNING_WORDS = [
|
|
160
|
-
"warning",
|
|
161
|
-
"caution",
|
|
162
|
-
"attention",
|
|
163
|
-
"note"
|
|
164
|
-
];
|
|
165
|
-
var HOME_WORDS = [
|
|
166
|
-
"home",
|
|
167
|
-
"dashboard",
|
|
168
|
-
"main",
|
|
169
|
-
"start"
|
|
170
|
-
];
|
|
171
|
-
var CLOSE_WORDS = [
|
|
172
|
-
"close",
|
|
173
|
-
"cancel",
|
|
174
|
-
"dismiss",
|
|
175
|
-
"x"
|
|
176
|
-
];
|
|
141
|
+
var ERROR_WORDS = ["error", "fail", "invalid", "wrong", "denied"];
|
|
142
|
+
var SUCCESS_WORDS = ["success", "saved", "created", "updated", "complete"];
|
|
143
|
+
var WARNING_WORDS = ["warning", "caution", "attention", "note"];
|
|
144
|
+
var HOME_WORDS = ["home", "dashboard", "main", "start"];
|
|
145
|
+
var CLOSE_WORDS = ["close", "cancel", "dismiss", "x"];
|
|
177
146
|
var PLACEHOLDER_PATTERNS = [
|
|
178
147
|
"lorem ipsum",
|
|
179
148
|
"dolor sit amet",
|
|
@@ -194,33 +163,23 @@ var INPUT_TYPE_SUGGESTIONS = [
|
|
|
194
163
|
{ keywords: ["date", "birthday", "dob"], type: "date" },
|
|
195
164
|
{ keywords: ["number", "quantity", "amount", "count", "age"], type: "number" }
|
|
196
165
|
];
|
|
197
|
-
var FORM_INPUT_TYPES = [
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
"Select",
|
|
201
|
-
"Checkbox",
|
|
202
|
-
"Radio"
|
|
203
|
-
];
|
|
204
|
-
var CONTAINER_TYPES = [
|
|
205
|
-
"Card",
|
|
206
|
-
"Section",
|
|
207
|
-
"Modal",
|
|
208
|
-
"Drawer",
|
|
209
|
-
"Main"
|
|
210
|
-
];
|
|
211
|
-
var TEXT_CONTENT_TYPES = [
|
|
212
|
-
"Text",
|
|
213
|
-
"Title",
|
|
214
|
-
"Label"
|
|
215
|
-
];
|
|
166
|
+
var FORM_INPUT_TYPES = ["Input", "Textarea", "Select", "Checkbox", "Radio"];
|
|
167
|
+
var CONTAINER_TYPES = ["Card", "Section", "Modal", "Drawer", "Main"];
|
|
168
|
+
var TEXT_CONTENT_TYPES = ["Text", "Title", "Label"];
|
|
216
169
|
|
|
217
170
|
// src/utils.ts
|
|
218
|
-
function
|
|
219
|
-
if (
|
|
220
|
-
if (
|
|
221
|
-
if ("label" in node && node.label) return String(node.label);
|
|
171
|
+
function coerceText(value) {
|
|
172
|
+
if (typeof value === "string") return value;
|
|
173
|
+
if (typeof value === "number") return String(value);
|
|
222
174
|
return "";
|
|
223
175
|
}
|
|
176
|
+
function coerceTextLower(value) {
|
|
177
|
+
return coerceText(value).toLowerCase();
|
|
178
|
+
}
|
|
179
|
+
function getNodeText(node) {
|
|
180
|
+
const record = node;
|
|
181
|
+
return coerceText(record.content) || coerceText(record.text) || coerceText(record.label);
|
|
182
|
+
}
|
|
224
183
|
function getNodeTextLower(node) {
|
|
225
184
|
return getNodeText(node).toLowerCase();
|
|
226
185
|
}
|
|
@@ -371,24 +330,33 @@ var imageRequiresAlt = {
|
|
|
371
330
|
return null;
|
|
372
331
|
}
|
|
373
332
|
};
|
|
333
|
+
function getAccessibleNameAttr(node) {
|
|
334
|
+
const record = node;
|
|
335
|
+
const candidates = [record.aria, record["aria-label"], record.title];
|
|
336
|
+
for (const value of candidates) {
|
|
337
|
+
if (typeof value === "string" && value.trim()) return value.trim();
|
|
338
|
+
}
|
|
339
|
+
return "";
|
|
340
|
+
}
|
|
374
341
|
var iconButtonRequiresLabel = {
|
|
375
342
|
id: "a11y-icon-button-label",
|
|
376
343
|
category: "accessibility",
|
|
377
|
-
severity: "
|
|
378
|
-
name: "Icon-only button
|
|
379
|
-
description: "Buttons with only an icon
|
|
344
|
+
severity: "warning",
|
|
345
|
+
name: "Icon-only button should have an accessible name",
|
|
346
|
+
description: "Buttons with only an icon should have an accessible name (aria-label or title)",
|
|
380
347
|
appliesTo: ["Button"],
|
|
381
348
|
check: (node, context) => {
|
|
382
349
|
const hasIcon = "icon" in node && node.icon;
|
|
383
350
|
const hasContent = getNodeText(node).trim();
|
|
384
|
-
|
|
351
|
+
const hasAccessibleName = getAccessibleNameAttr(node);
|
|
352
|
+
if (hasIcon && !hasContent && !hasAccessibleName) {
|
|
385
353
|
return {
|
|
386
354
|
ruleId: "a11y-icon-button-label",
|
|
387
355
|
category: "accessibility",
|
|
388
|
-
severity: "
|
|
389
|
-
message: "Icon-only button is missing accessible
|
|
390
|
-
description: "Screen readers cannot describe icon-only buttons without
|
|
391
|
-
suggestion:
|
|
356
|
+
severity: "warning",
|
|
357
|
+
message: "Icon-only button is missing an accessible name",
|
|
358
|
+
description: "Screen readers cannot describe icon-only buttons without an accessible name",
|
|
359
|
+
suggestion: 'Add an aria attribute (e.g. button "" icon="search" aria="Search") or text content',
|
|
392
360
|
path: context.path,
|
|
393
361
|
nodeType: node.type,
|
|
394
362
|
location: getNodeLocation(node)
|
|
@@ -820,7 +788,7 @@ var consistentCardStyling = {
|
|
|
820
788
|
const hasShadow = "shadow" in node && node.shadow;
|
|
821
789
|
const hasBorder = "border" in node && node.border;
|
|
822
790
|
const padding = "p" in node ? Number(node.p) : null;
|
|
823
|
-
|
|
791
|
+
const inconsistencies = [];
|
|
824
792
|
for (const sibling of siblingCards) {
|
|
825
793
|
if (sibling === node) continue;
|
|
826
794
|
const sibShadow = "shadow" in sibling && sibling.shadow;
|
|
@@ -1409,6 +1377,7 @@ var navigationRules = [
|
|
|
1409
1377
|
];
|
|
1410
1378
|
|
|
1411
1379
|
// src/rules/content.ts
|
|
1380
|
+
var import_core2 = require("@wireweave/core");
|
|
1412
1381
|
var emptyTextContent = {
|
|
1413
1382
|
id: "content-empty-text",
|
|
1414
1383
|
category: "content",
|
|
@@ -1565,13 +1534,117 @@ var noPlaceholderContent = {
|
|
|
1565
1534
|
return null;
|
|
1566
1535
|
}
|
|
1567
1536
|
};
|
|
1537
|
+
var unknownIcon = {
|
|
1538
|
+
id: "content-unknown-icon",
|
|
1539
|
+
category: "content",
|
|
1540
|
+
severity: "warning",
|
|
1541
|
+
name: "Icon name should resolve to a known icon",
|
|
1542
|
+
description: "Icon names must reference a valid Lucide icon so they render as a real glyph",
|
|
1543
|
+
appliesTo: ["Button", "Input", "Icon"],
|
|
1544
|
+
check: (node, context) => {
|
|
1545
|
+
const iconName = node.type === "Icon" ? "name" in node && typeof node.name === "string" ? node.name : void 0 : "icon" in node && typeof node.icon === "string" ? node.icon : void 0;
|
|
1546
|
+
if (!iconName || !iconName.trim()) {
|
|
1547
|
+
return null;
|
|
1548
|
+
}
|
|
1549
|
+
if ((0, import_core2.getIconData)(iconName) === void 0) {
|
|
1550
|
+
return {
|
|
1551
|
+
ruleId: "content-unknown-icon",
|
|
1552
|
+
category: "content",
|
|
1553
|
+
severity: "warning",
|
|
1554
|
+
message: `Unknown icon name "${iconName}"`,
|
|
1555
|
+
description: 'The icon name does not resolve to a known Lucide icon and will render as a "?" placeholder',
|
|
1556
|
+
suggestion: `Use a valid lucide kebab-case icon name (e.g. the overflow menu is "ellipsis-vertical", not "${iconName}")`,
|
|
1557
|
+
path: context.path,
|
|
1558
|
+
nodeType: node.type,
|
|
1559
|
+
location: getNodeLocation(node)
|
|
1560
|
+
};
|
|
1561
|
+
}
|
|
1562
|
+
return null;
|
|
1563
|
+
}
|
|
1564
|
+
};
|
|
1565
|
+
var controlValueRange = {
|
|
1566
|
+
id: "content-control-value-range",
|
|
1567
|
+
category: "content",
|
|
1568
|
+
severity: "warning",
|
|
1569
|
+
name: "Control value should lie within its range",
|
|
1570
|
+
description: "Slider/Progress values must fall within their declared min..max",
|
|
1571
|
+
appliesTo: ["Slider", "Progress"],
|
|
1572
|
+
check: (node, context) => {
|
|
1573
|
+
let min;
|
|
1574
|
+
let max;
|
|
1575
|
+
let value;
|
|
1576
|
+
if (node.type === "Slider") {
|
|
1577
|
+
if (typeof node.value !== "number") return null;
|
|
1578
|
+
min = typeof node.min === "number" ? node.min : 0;
|
|
1579
|
+
max = typeof node.max === "number" ? node.max : 100;
|
|
1580
|
+
value = node.value;
|
|
1581
|
+
} else if (node.type === "Progress") {
|
|
1582
|
+
if (typeof node.value !== "number") return null;
|
|
1583
|
+
min = 0;
|
|
1584
|
+
max = typeof node.max === "number" ? node.max : 100;
|
|
1585
|
+
value = node.value;
|
|
1586
|
+
} else {
|
|
1587
|
+
return null;
|
|
1588
|
+
}
|
|
1589
|
+
if (value < min || value > max) {
|
|
1590
|
+
const label = "label" in node && typeof node.label === "string" && node.label.trim() ? node.label : node.type;
|
|
1591
|
+
return {
|
|
1592
|
+
ruleId: "content-control-value-range",
|
|
1593
|
+
category: "content",
|
|
1594
|
+
severity: "warning",
|
|
1595
|
+
message: `${node.type} "${label}" value ${value} is outside its range [${min}, ${max}]`,
|
|
1596
|
+
description: "A value outside the declared range renders a misleading control position and announces an impossible value",
|
|
1597
|
+
suggestion: `Set value within [${min}, ${max}], or widen min/max to include ${value}`,
|
|
1598
|
+
path: context.path,
|
|
1599
|
+
nodeType: node.type,
|
|
1600
|
+
location: getNodeLocation(node)
|
|
1601
|
+
};
|
|
1602
|
+
}
|
|
1603
|
+
return null;
|
|
1604
|
+
}
|
|
1605
|
+
};
|
|
1606
|
+
var duplicateControlLabel = {
|
|
1607
|
+
id: "content-duplicate-control-label",
|
|
1608
|
+
category: "content",
|
|
1609
|
+
severity: "warning",
|
|
1610
|
+
name: "Control label should not duplicate an adjacent text",
|
|
1611
|
+
description: "A control's own label should not be repeated by an adjacent sibling text node",
|
|
1612
|
+
appliesTo: ["Slider", "Input"],
|
|
1613
|
+
check: (node, context) => {
|
|
1614
|
+
const ownLabel = "label" in node && typeof node.label === "string" ? node.label.trim().toLowerCase() : "";
|
|
1615
|
+
if (!ownLabel) return null;
|
|
1616
|
+
const { siblings, index } = context;
|
|
1617
|
+
const adjacent = [siblings[index - 1], siblings[index + 1]];
|
|
1618
|
+
for (const sib of adjacent) {
|
|
1619
|
+
if (!sib || sib.type !== "Text") continue;
|
|
1620
|
+
const sibText = getNodeText(sib).trim().toLowerCase();
|
|
1621
|
+
if (sibText && sibText === ownLabel) {
|
|
1622
|
+
return {
|
|
1623
|
+
ruleId: "content-duplicate-control-label",
|
|
1624
|
+
category: "content",
|
|
1625
|
+
severity: "warning",
|
|
1626
|
+
message: `${node.type} label duplicates an adjacent text "${getNodeText(sib).trim()}"`,
|
|
1627
|
+
description: "The control already renders this label, so the adjacent text node repeats it verbatim",
|
|
1628
|
+
suggestion: "Remove the standalone text and rely on the control label, or differentiate the two strings",
|
|
1629
|
+
path: context.path,
|
|
1630
|
+
nodeType: node.type,
|
|
1631
|
+
location: getNodeLocation(node)
|
|
1632
|
+
};
|
|
1633
|
+
}
|
|
1634
|
+
}
|
|
1635
|
+
return null;
|
|
1636
|
+
}
|
|
1637
|
+
};
|
|
1568
1638
|
var contentRules = [
|
|
1569
1639
|
emptyTextContent,
|
|
1570
1640
|
buttonTextLength,
|
|
1571
1641
|
titleLength,
|
|
1572
1642
|
pageHasTitle,
|
|
1573
1643
|
linkHasText,
|
|
1574
|
-
noPlaceholderContent
|
|
1644
|
+
noPlaceholderContent,
|
|
1645
|
+
unknownIcon,
|
|
1646
|
+
controlValueRange,
|
|
1647
|
+
duplicateControlLabel
|
|
1575
1648
|
];
|
|
1576
1649
|
|
|
1577
1650
|
// src/rules/data-display.ts
|
|
@@ -2187,9 +2260,10 @@ var modalHasCloseAction = {
|
|
|
2187
2260
|
const hasDismiss = "dismissible" in node || "dismiss" in node;
|
|
2188
2261
|
const hasCloseChild = hasChildren(node) && hasChildMatching(node, (child) => {
|
|
2189
2262
|
if (child.type === "Button") {
|
|
2190
|
-
const
|
|
2191
|
-
const
|
|
2192
|
-
const
|
|
2263
|
+
const fields = child;
|
|
2264
|
+
const text = coerceTextLower(fields.text);
|
|
2265
|
+
const label = coerceTextLower(fields.label);
|
|
2266
|
+
const action = coerceTextLower(fields.action);
|
|
2193
2267
|
return text.includes("close") || text.includes("cancel") || label.includes("close") || label.includes("cancel") || action.includes("close");
|
|
2194
2268
|
}
|
|
2195
2269
|
return false;
|
|
@@ -2262,7 +2336,7 @@ var SEVERITY_ORDER = {
|
|
|
2262
2336
|
};
|
|
2263
2337
|
function resolveComplexity(ast) {
|
|
2264
2338
|
try {
|
|
2265
|
-
const result = (0,
|
|
2339
|
+
const result = (0, import_core3.analyze)(ast);
|
|
2266
2340
|
if (result.success && typeof result.complexity?.score === "number" && Number.isFinite(result.complexity.score) && result.complexity.score > 0) {
|
|
2267
2341
|
return { score: result.complexity.score, level: result.complexity.level };
|
|
2268
2342
|
}
|
|
@@ -2431,7 +2505,9 @@ function formatUXResult(result) {
|
|
|
2431
2505
|
}
|
|
2432
2506
|
lines.push("Summary by category:");
|
|
2433
2507
|
for (const cat of result.summary) {
|
|
2434
|
-
lines.push(
|
|
2508
|
+
lines.push(
|
|
2509
|
+
` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`
|
|
2510
|
+
);
|
|
2435
2511
|
}
|
|
2436
2512
|
return lines.join("\n");
|
|
2437
2513
|
}
|
|
@@ -2469,6 +2545,8 @@ function formatUXResult(result) {
|
|
|
2469
2545
|
TEXT_CONTENT_TYPES,
|
|
2470
2546
|
WARNING_WORDS,
|
|
2471
2547
|
allRules,
|
|
2548
|
+
coerceText,
|
|
2549
|
+
coerceTextLower,
|
|
2472
2550
|
containsAnyWord,
|
|
2473
2551
|
countInChildren,
|
|
2474
2552
|
filterChildren,
|
package/dist/index.d.cts
CHANGED
|
@@ -252,6 +252,15 @@ declare const TEXT_CONTENT_TYPES: string[];
|
|
|
252
252
|
* Helper functions for common rule patterns.
|
|
253
253
|
*/
|
|
254
254
|
|
|
255
|
+
/**
|
|
256
|
+
* Coerce an unknown property value to a string, but only when it is a
|
|
257
|
+
* primitive (string/number). Avoids `[object Object]` stringification.
|
|
258
|
+
*/
|
|
259
|
+
declare function coerceText(value: unknown): string;
|
|
260
|
+
/**
|
|
261
|
+
* Coerce an unknown property value to a lowercase string (primitive only).
|
|
262
|
+
*/
|
|
263
|
+
declare function coerceTextLower(value: unknown): string;
|
|
255
264
|
/**
|
|
256
265
|
* Safely get text content from a node.
|
|
257
266
|
* Checks 'content', 'text', and 'label' properties.
|
|
@@ -370,4 +379,4 @@ declare function getUXScore(ast: WireframeDocument): number;
|
|
|
370
379
|
*/
|
|
371
380
|
declare function formatUXResult(result: UXValidationResult): string;
|
|
372
381
|
|
|
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 };
|
|
382
|
+
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, coerceText, coerceTextLower, 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
|
@@ -252,6 +252,15 @@ declare const TEXT_CONTENT_TYPES: string[];
|
|
|
252
252
|
* Helper functions for common rule patterns.
|
|
253
253
|
*/
|
|
254
254
|
|
|
255
|
+
/**
|
|
256
|
+
* Coerce an unknown property value to a string, but only when it is a
|
|
257
|
+
* primitive (string/number). Avoids `[object Object]` stringification.
|
|
258
|
+
*/
|
|
259
|
+
declare function coerceText(value: unknown): string;
|
|
260
|
+
/**
|
|
261
|
+
* Coerce an unknown property value to a lowercase string (primitive only).
|
|
262
|
+
*/
|
|
263
|
+
declare function coerceTextLower(value: unknown): string;
|
|
255
264
|
/**
|
|
256
265
|
* Safely get text content from a node.
|
|
257
266
|
* Checks 'content', 'text', and 'label' properties.
|
|
@@ -370,4 +379,4 @@ declare function getUXScore(ast: WireframeDocument): number;
|
|
|
370
379
|
*/
|
|
371
380
|
declare function formatUXResult(result: UXValidationResult): string;
|
|
372
381
|
|
|
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 };
|
|
382
|
+
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, coerceText, coerceTextLower, 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
|
@@ -25,13 +25,7 @@ var SIZE_MAP = {
|
|
|
25
25
|
};
|
|
26
26
|
var MIN_TOAST_DURATION = 2e3;
|
|
27
27
|
var MAX_TOAST_DURATION = 1e4;
|
|
28
|
-
var GENERIC_LINK_TEXTS = [
|
|
29
|
-
"click here",
|
|
30
|
-
"here",
|
|
31
|
-
"read more",
|
|
32
|
-
"more",
|
|
33
|
-
"link"
|
|
34
|
-
];
|
|
28
|
+
var GENERIC_LINK_TEXTS = ["click here", "here", "read more", "more", "link"];
|
|
35
29
|
var ASYNC_ACTION_WORDS = [
|
|
36
30
|
"submit",
|
|
37
31
|
"save",
|
|
@@ -63,38 +57,11 @@ var SUBMIT_WORDS = [
|
|
|
63
57
|
"ok",
|
|
64
58
|
"done"
|
|
65
59
|
];
|
|
66
|
-
var ERROR_WORDS = [
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
"denied"
|
|
72
|
-
];
|
|
73
|
-
var SUCCESS_WORDS = [
|
|
74
|
-
"success",
|
|
75
|
-
"saved",
|
|
76
|
-
"created",
|
|
77
|
-
"updated",
|
|
78
|
-
"complete"
|
|
79
|
-
];
|
|
80
|
-
var WARNING_WORDS = [
|
|
81
|
-
"warning",
|
|
82
|
-
"caution",
|
|
83
|
-
"attention",
|
|
84
|
-
"note"
|
|
85
|
-
];
|
|
86
|
-
var HOME_WORDS = [
|
|
87
|
-
"home",
|
|
88
|
-
"dashboard",
|
|
89
|
-
"main",
|
|
90
|
-
"start"
|
|
91
|
-
];
|
|
92
|
-
var CLOSE_WORDS = [
|
|
93
|
-
"close",
|
|
94
|
-
"cancel",
|
|
95
|
-
"dismiss",
|
|
96
|
-
"x"
|
|
97
|
-
];
|
|
60
|
+
var ERROR_WORDS = ["error", "fail", "invalid", "wrong", "denied"];
|
|
61
|
+
var SUCCESS_WORDS = ["success", "saved", "created", "updated", "complete"];
|
|
62
|
+
var WARNING_WORDS = ["warning", "caution", "attention", "note"];
|
|
63
|
+
var HOME_WORDS = ["home", "dashboard", "main", "start"];
|
|
64
|
+
var CLOSE_WORDS = ["close", "cancel", "dismiss", "x"];
|
|
98
65
|
var PLACEHOLDER_PATTERNS = [
|
|
99
66
|
"lorem ipsum",
|
|
100
67
|
"dolor sit amet",
|
|
@@ -115,33 +82,23 @@ var INPUT_TYPE_SUGGESTIONS = [
|
|
|
115
82
|
{ keywords: ["date", "birthday", "dob"], type: "date" },
|
|
116
83
|
{ keywords: ["number", "quantity", "amount", "count", "age"], type: "number" }
|
|
117
84
|
];
|
|
118
|
-
var FORM_INPUT_TYPES = [
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
"Select",
|
|
122
|
-
"Checkbox",
|
|
123
|
-
"Radio"
|
|
124
|
-
];
|
|
125
|
-
var CONTAINER_TYPES = [
|
|
126
|
-
"Card",
|
|
127
|
-
"Section",
|
|
128
|
-
"Modal",
|
|
129
|
-
"Drawer",
|
|
130
|
-
"Main"
|
|
131
|
-
];
|
|
132
|
-
var TEXT_CONTENT_TYPES = [
|
|
133
|
-
"Text",
|
|
134
|
-
"Title",
|
|
135
|
-
"Label"
|
|
136
|
-
];
|
|
85
|
+
var FORM_INPUT_TYPES = ["Input", "Textarea", "Select", "Checkbox", "Radio"];
|
|
86
|
+
var CONTAINER_TYPES = ["Card", "Section", "Modal", "Drawer", "Main"];
|
|
87
|
+
var TEXT_CONTENT_TYPES = ["Text", "Title", "Label"];
|
|
137
88
|
|
|
138
89
|
// src/utils.ts
|
|
139
|
-
function
|
|
140
|
-
if (
|
|
141
|
-
if (
|
|
142
|
-
if ("label" in node && node.label) return String(node.label);
|
|
90
|
+
function coerceText(value) {
|
|
91
|
+
if (typeof value === "string") return value;
|
|
92
|
+
if (typeof value === "number") return String(value);
|
|
143
93
|
return "";
|
|
144
94
|
}
|
|
95
|
+
function coerceTextLower(value) {
|
|
96
|
+
return coerceText(value).toLowerCase();
|
|
97
|
+
}
|
|
98
|
+
function getNodeText(node) {
|
|
99
|
+
const record = node;
|
|
100
|
+
return coerceText(record.content) || coerceText(record.text) || coerceText(record.label);
|
|
101
|
+
}
|
|
145
102
|
function getNodeTextLower(node) {
|
|
146
103
|
return getNodeText(node).toLowerCase();
|
|
147
104
|
}
|
|
@@ -292,24 +249,33 @@ var imageRequiresAlt = {
|
|
|
292
249
|
return null;
|
|
293
250
|
}
|
|
294
251
|
};
|
|
252
|
+
function getAccessibleNameAttr(node) {
|
|
253
|
+
const record = node;
|
|
254
|
+
const candidates = [record.aria, record["aria-label"], record.title];
|
|
255
|
+
for (const value of candidates) {
|
|
256
|
+
if (typeof value === "string" && value.trim()) return value.trim();
|
|
257
|
+
}
|
|
258
|
+
return "";
|
|
259
|
+
}
|
|
295
260
|
var iconButtonRequiresLabel = {
|
|
296
261
|
id: "a11y-icon-button-label",
|
|
297
262
|
category: "accessibility",
|
|
298
|
-
severity: "
|
|
299
|
-
name: "Icon-only button
|
|
300
|
-
description: "Buttons with only an icon
|
|
263
|
+
severity: "warning",
|
|
264
|
+
name: "Icon-only button should have an accessible name",
|
|
265
|
+
description: "Buttons with only an icon should have an accessible name (aria-label or title)",
|
|
301
266
|
appliesTo: ["Button"],
|
|
302
267
|
check: (node, context) => {
|
|
303
268
|
const hasIcon = "icon" in node && node.icon;
|
|
304
269
|
const hasContent = getNodeText(node).trim();
|
|
305
|
-
|
|
270
|
+
const hasAccessibleName = getAccessibleNameAttr(node);
|
|
271
|
+
if (hasIcon && !hasContent && !hasAccessibleName) {
|
|
306
272
|
return {
|
|
307
273
|
ruleId: "a11y-icon-button-label",
|
|
308
274
|
category: "accessibility",
|
|
309
|
-
severity: "
|
|
310
|
-
message: "Icon-only button is missing accessible
|
|
311
|
-
description: "Screen readers cannot describe icon-only buttons without
|
|
312
|
-
suggestion:
|
|
275
|
+
severity: "warning",
|
|
276
|
+
message: "Icon-only button is missing an accessible name",
|
|
277
|
+
description: "Screen readers cannot describe icon-only buttons without an accessible name",
|
|
278
|
+
suggestion: 'Add an aria attribute (e.g. button "" icon="search" aria="Search") or text content',
|
|
313
279
|
path: context.path,
|
|
314
280
|
nodeType: node.type,
|
|
315
281
|
location: getNodeLocation(node)
|
|
@@ -741,7 +707,7 @@ var consistentCardStyling = {
|
|
|
741
707
|
const hasShadow = "shadow" in node && node.shadow;
|
|
742
708
|
const hasBorder = "border" in node && node.border;
|
|
743
709
|
const padding = "p" in node ? Number(node.p) : null;
|
|
744
|
-
|
|
710
|
+
const inconsistencies = [];
|
|
745
711
|
for (const sibling of siblingCards) {
|
|
746
712
|
if (sibling === node) continue;
|
|
747
713
|
const sibShadow = "shadow" in sibling && sibling.shadow;
|
|
@@ -1330,6 +1296,7 @@ var navigationRules = [
|
|
|
1330
1296
|
];
|
|
1331
1297
|
|
|
1332
1298
|
// src/rules/content.ts
|
|
1299
|
+
import { getIconData } from "@wireweave/core";
|
|
1333
1300
|
var emptyTextContent = {
|
|
1334
1301
|
id: "content-empty-text",
|
|
1335
1302
|
category: "content",
|
|
@@ -1486,13 +1453,117 @@ var noPlaceholderContent = {
|
|
|
1486
1453
|
return null;
|
|
1487
1454
|
}
|
|
1488
1455
|
};
|
|
1456
|
+
var unknownIcon = {
|
|
1457
|
+
id: "content-unknown-icon",
|
|
1458
|
+
category: "content",
|
|
1459
|
+
severity: "warning",
|
|
1460
|
+
name: "Icon name should resolve to a known icon",
|
|
1461
|
+
description: "Icon names must reference a valid Lucide icon so they render as a real glyph",
|
|
1462
|
+
appliesTo: ["Button", "Input", "Icon"],
|
|
1463
|
+
check: (node, context) => {
|
|
1464
|
+
const iconName = node.type === "Icon" ? "name" in node && typeof node.name === "string" ? node.name : void 0 : "icon" in node && typeof node.icon === "string" ? node.icon : void 0;
|
|
1465
|
+
if (!iconName || !iconName.trim()) {
|
|
1466
|
+
return null;
|
|
1467
|
+
}
|
|
1468
|
+
if (getIconData(iconName) === void 0) {
|
|
1469
|
+
return {
|
|
1470
|
+
ruleId: "content-unknown-icon",
|
|
1471
|
+
category: "content",
|
|
1472
|
+
severity: "warning",
|
|
1473
|
+
message: `Unknown icon name "${iconName}"`,
|
|
1474
|
+
description: 'The icon name does not resolve to a known Lucide icon and will render as a "?" placeholder',
|
|
1475
|
+
suggestion: `Use a valid lucide kebab-case icon name (e.g. the overflow menu is "ellipsis-vertical", not "${iconName}")`,
|
|
1476
|
+
path: context.path,
|
|
1477
|
+
nodeType: node.type,
|
|
1478
|
+
location: getNodeLocation(node)
|
|
1479
|
+
};
|
|
1480
|
+
}
|
|
1481
|
+
return null;
|
|
1482
|
+
}
|
|
1483
|
+
};
|
|
1484
|
+
var controlValueRange = {
|
|
1485
|
+
id: "content-control-value-range",
|
|
1486
|
+
category: "content",
|
|
1487
|
+
severity: "warning",
|
|
1488
|
+
name: "Control value should lie within its range",
|
|
1489
|
+
description: "Slider/Progress values must fall within their declared min..max",
|
|
1490
|
+
appliesTo: ["Slider", "Progress"],
|
|
1491
|
+
check: (node, context) => {
|
|
1492
|
+
let min;
|
|
1493
|
+
let max;
|
|
1494
|
+
let value;
|
|
1495
|
+
if (node.type === "Slider") {
|
|
1496
|
+
if (typeof node.value !== "number") return null;
|
|
1497
|
+
min = typeof node.min === "number" ? node.min : 0;
|
|
1498
|
+
max = typeof node.max === "number" ? node.max : 100;
|
|
1499
|
+
value = node.value;
|
|
1500
|
+
} else if (node.type === "Progress") {
|
|
1501
|
+
if (typeof node.value !== "number") return null;
|
|
1502
|
+
min = 0;
|
|
1503
|
+
max = typeof node.max === "number" ? node.max : 100;
|
|
1504
|
+
value = node.value;
|
|
1505
|
+
} else {
|
|
1506
|
+
return null;
|
|
1507
|
+
}
|
|
1508
|
+
if (value < min || value > max) {
|
|
1509
|
+
const label = "label" in node && typeof node.label === "string" && node.label.trim() ? node.label : node.type;
|
|
1510
|
+
return {
|
|
1511
|
+
ruleId: "content-control-value-range",
|
|
1512
|
+
category: "content",
|
|
1513
|
+
severity: "warning",
|
|
1514
|
+
message: `${node.type} "${label}" value ${value} is outside its range [${min}, ${max}]`,
|
|
1515
|
+
description: "A value outside the declared range renders a misleading control position and announces an impossible value",
|
|
1516
|
+
suggestion: `Set value within [${min}, ${max}], or widen min/max to include ${value}`,
|
|
1517
|
+
path: context.path,
|
|
1518
|
+
nodeType: node.type,
|
|
1519
|
+
location: getNodeLocation(node)
|
|
1520
|
+
};
|
|
1521
|
+
}
|
|
1522
|
+
return null;
|
|
1523
|
+
}
|
|
1524
|
+
};
|
|
1525
|
+
var duplicateControlLabel = {
|
|
1526
|
+
id: "content-duplicate-control-label",
|
|
1527
|
+
category: "content",
|
|
1528
|
+
severity: "warning",
|
|
1529
|
+
name: "Control label should not duplicate an adjacent text",
|
|
1530
|
+
description: "A control's own label should not be repeated by an adjacent sibling text node",
|
|
1531
|
+
appliesTo: ["Slider", "Input"],
|
|
1532
|
+
check: (node, context) => {
|
|
1533
|
+
const ownLabel = "label" in node && typeof node.label === "string" ? node.label.trim().toLowerCase() : "";
|
|
1534
|
+
if (!ownLabel) return null;
|
|
1535
|
+
const { siblings, index } = context;
|
|
1536
|
+
const adjacent = [siblings[index - 1], siblings[index + 1]];
|
|
1537
|
+
for (const sib of adjacent) {
|
|
1538
|
+
if (!sib || sib.type !== "Text") continue;
|
|
1539
|
+
const sibText = getNodeText(sib).trim().toLowerCase();
|
|
1540
|
+
if (sibText && sibText === ownLabel) {
|
|
1541
|
+
return {
|
|
1542
|
+
ruleId: "content-duplicate-control-label",
|
|
1543
|
+
category: "content",
|
|
1544
|
+
severity: "warning",
|
|
1545
|
+
message: `${node.type} label duplicates an adjacent text "${getNodeText(sib).trim()}"`,
|
|
1546
|
+
description: "The control already renders this label, so the adjacent text node repeats it verbatim",
|
|
1547
|
+
suggestion: "Remove the standalone text and rely on the control label, or differentiate the two strings",
|
|
1548
|
+
path: context.path,
|
|
1549
|
+
nodeType: node.type,
|
|
1550
|
+
location: getNodeLocation(node)
|
|
1551
|
+
};
|
|
1552
|
+
}
|
|
1553
|
+
}
|
|
1554
|
+
return null;
|
|
1555
|
+
}
|
|
1556
|
+
};
|
|
1489
1557
|
var contentRules = [
|
|
1490
1558
|
emptyTextContent,
|
|
1491
1559
|
buttonTextLength,
|
|
1492
1560
|
titleLength,
|
|
1493
1561
|
pageHasTitle,
|
|
1494
1562
|
linkHasText,
|
|
1495
|
-
noPlaceholderContent
|
|
1563
|
+
noPlaceholderContent,
|
|
1564
|
+
unknownIcon,
|
|
1565
|
+
controlValueRange,
|
|
1566
|
+
duplicateControlLabel
|
|
1496
1567
|
];
|
|
1497
1568
|
|
|
1498
1569
|
// src/rules/data-display.ts
|
|
@@ -2108,9 +2179,10 @@ var modalHasCloseAction = {
|
|
|
2108
2179
|
const hasDismiss = "dismissible" in node || "dismiss" in node;
|
|
2109
2180
|
const hasCloseChild = hasChildren(node) && hasChildMatching(node, (child) => {
|
|
2110
2181
|
if (child.type === "Button") {
|
|
2111
|
-
const
|
|
2112
|
-
const
|
|
2113
|
-
const
|
|
2182
|
+
const fields = child;
|
|
2183
|
+
const text = coerceTextLower(fields.text);
|
|
2184
|
+
const label = coerceTextLower(fields.label);
|
|
2185
|
+
const action = coerceTextLower(fields.action);
|
|
2114
2186
|
return text.includes("close") || text.includes("cancel") || label.includes("close") || label.includes("cancel") || action.includes("close");
|
|
2115
2187
|
}
|
|
2116
2188
|
return false;
|
|
@@ -2352,7 +2424,9 @@ function formatUXResult(result) {
|
|
|
2352
2424
|
}
|
|
2353
2425
|
lines.push("Summary by category:");
|
|
2354
2426
|
for (const cat of result.summary) {
|
|
2355
|
-
lines.push(
|
|
2427
|
+
lines.push(
|
|
2428
|
+
` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`
|
|
2429
|
+
);
|
|
2356
2430
|
}
|
|
2357
2431
|
return lines.join("\n");
|
|
2358
2432
|
}
|
|
@@ -2389,6 +2463,8 @@ export {
|
|
|
2389
2463
|
TEXT_CONTENT_TYPES,
|
|
2390
2464
|
WARNING_WORDS,
|
|
2391
2465
|
allRules,
|
|
2466
|
+
coerceText,
|
|
2467
|
+
coerceTextLower,
|
|
2392
2468
|
containsAnyWord,
|
|
2393
2469
|
countInChildren,
|
|
2394
2470
|
filterChildren,
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wireweave/ux-rules",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0-beta.1",
|
|
4
4
|
"description": "UX validation rules for wireweave",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"main": "dist/index.
|
|
7
|
-
"module": "dist/index.
|
|
6
|
+
"main": "dist/index.cjs",
|
|
7
|
+
"module": "dist/index.js",
|
|
8
8
|
"types": "dist/index.d.ts",
|
|
9
9
|
"exports": {
|
|
10
10
|
".": {
|
|
@@ -16,23 +16,25 @@
|
|
|
16
16
|
"files": [
|
|
17
17
|
"dist"
|
|
18
18
|
],
|
|
19
|
-
"scripts": {
|
|
20
|
-
"build": "tsup",
|
|
21
|
-
"test": "vitest run",
|
|
22
|
-
"test:watch": "vitest",
|
|
23
|
-
"clean": "rm -rf dist",
|
|
24
|
-
"release": "release-it",
|
|
25
|
-
"release:beta": "release-it --preRelease=beta"
|
|
26
|
-
},
|
|
27
19
|
"dependencies": {
|
|
28
|
-
"@wireweave/core": "
|
|
20
|
+
"@wireweave/core": "3.1.0-beta.1"
|
|
29
21
|
},
|
|
30
22
|
"devDependencies": {
|
|
23
|
+
"@commitlint/cli": "^21.0.2",
|
|
24
|
+
"@commitlint/config-conventional": "^21.0.2",
|
|
25
|
+
"@eslint/js": "^10.0.1",
|
|
31
26
|
"@release-it/conventional-changelog": "^10.0.4",
|
|
32
|
-
"@types/node": "^22
|
|
27
|
+
"@types/node": "^22",
|
|
28
|
+
"eslint": "^10.4.0",
|
|
29
|
+
"husky": "^9.1.7",
|
|
30
|
+
"knip": "^6.14.2",
|
|
31
|
+
"lint-staged": "^17.0.5",
|
|
32
|
+
"prettier": "^3.8.3",
|
|
33
|
+
"publint": "^0.3.21",
|
|
33
34
|
"release-it": "^19.2.3",
|
|
34
35
|
"tsup": "^8.3.5",
|
|
35
36
|
"typescript": "^5.7.2",
|
|
37
|
+
"typescript-eslint": "^8.60.0",
|
|
36
38
|
"vitest": "^3.1.1"
|
|
37
39
|
},
|
|
38
40
|
"keywords": [
|
|
@@ -45,10 +47,26 @@
|
|
|
45
47
|
"license": "MIT",
|
|
46
48
|
"repository": {
|
|
47
49
|
"type": "git",
|
|
48
|
-
"url": "git+https://github.com/wireweave/
|
|
50
|
+
"url": "git+https://github.com/wireweave/wireweave.git",
|
|
51
|
+
"directory": "packages/ux-rules"
|
|
49
52
|
},
|
|
50
53
|
"bugs": {
|
|
51
|
-
"url": "https://github.com/wireweave/
|
|
54
|
+
"url": "https://github.com/wireweave/wireweave/issues"
|
|
52
55
|
},
|
|
53
|
-
"homepage": "https://
|
|
54
|
-
|
|
56
|
+
"homepage": "https://docs.wireweave.org",
|
|
57
|
+
"scripts": {
|
|
58
|
+
"build": "tsup",
|
|
59
|
+
"test": "vitest run",
|
|
60
|
+
"test:watch": "vitest",
|
|
61
|
+
"clean": "rm -rf dist",
|
|
62
|
+
"release": "release-it",
|
|
63
|
+
"release:beta": "release-it --preRelease=beta",
|
|
64
|
+
"typecheck": "tsc --noEmit",
|
|
65
|
+
"lint": "eslint .",
|
|
66
|
+
"lint:fix": "eslint . --fix",
|
|
67
|
+
"format": "prettier --write .",
|
|
68
|
+
"format:check": "prettier --check .",
|
|
69
|
+
"knip": "knip",
|
|
70
|
+
"publint": "publint"
|
|
71
|
+
}
|
|
72
|
+
}
|