@wireweave/ux-rules 1.4.0-beta.0 → 1.4.1-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 CHANGED
@@ -4,7 +4,13 @@
4
4
  [![npm downloads](https://img.shields.io/npm/dm/@wireweave/ux-rules.svg)](https://www.npmjs.com/package/@wireweave/ux-rules)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
 
7
- UX validation rules for Wireweave DSL. This package provides automated UX best practice validation for wireframe designs.
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); // 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
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 | Rules | Description |
50
- |----------|-------|-------------|
51
- | `accessibility` | 5 | Screen reader support, labels, alt text |
52
- | `form` | 4 | Form UX patterns, input types, validation |
53
- | `usability` | 10 | General usability (empty containers, CTA, loading states, cognitive load) |
54
- | `touch-target` | 5 | Touch target sizes for mobile (WCAG 2.5.5) |
55
- | `navigation` | 5 | Navigation patterns (item count, active states) |
56
- | `consistency` | 4 | Consistent styling across components |
57
- | `content` | 6 | Text quality, placeholder detection, title requirements |
58
- | `data-display` | 6 | Tables, lists, empty states, pagination |
59
- | `feedback` | 6 | Spinners, progress bars, toasts, alerts |
60
- | `interaction` | 8 | Interactive elements need actions defined |
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 | Impact | Base Penalty |
105
- |----------|--------|--------------|
106
- | `error` | Critical UX problem | -10 (absolute) |
107
- | `warning` | Should fix | -3 (soft) |
108
- | `info` | Consider improving | -1 (soft) |
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 *soft* penalty
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 | Severity | Description |
138
- |---------|----------|-------------|
139
- | `a11y-input-label` | error/warning | Input fields must have labels |
140
- | `a11y-image-alt` | warning | Images should have alt text |
141
- | `a11y-icon-button-label` | error | Icon-only buttons need accessible text |
142
- | `a11y-link-text` | warning | Links should have descriptive text |
143
- | `a11y-heading-hierarchy` | warning | Heading levels should be sequential |
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 | Severity | Description |
151
- |---------|----------|-------------|
152
- | `form-submit-button` | warning | Forms with inputs need submit button |
153
- | `form-required-indicator` | info | Required fields should be marked |
154
- | `form-password-confirm` | info | Registration forms may need password confirmation |
155
- | `form-input-type` | warning | Use appropriate input types (email, tel, etc.) |
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 | Severity | Description |
163
- |---------|----------|-------------|
164
- | `usability-empty-container` | warning | Avoid empty containers |
165
- | `usability-clear-cta` | info | Pages should have primary button (CTA) |
166
- | `usability-loading-states` | info | Async buttons may need loading state |
167
- | `usability-destructive-confirm` | warning | Destructive actions need danger styling |
168
- | `usability-modal-close` | warning | Modals need close mechanism |
169
- | `usability-nesting-depth` | warning | Avoid excessive nesting (max 6 levels) |
170
- | `usability-too-many-buttons` | warning | Max 5 buttons per container |
171
- | `usability-too-many-form-fields` | info | Max 10 form fields |
172
- | `usability-page-complexity` | info | Max 50 elements per page |
173
- | `usability-drawer-width` | info | Drawers should have 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 | Severity | Description |
181
- |---------|----------|-------------|
182
- | `touch-button-size` | warning | Button minimum 44px (WCAG AAA) |
183
- | `touch-icon-button-size` | warning | Icon buttons need adequate padding |
184
- | `touch-checkbox-radio-size` | info | Checkbox/Radio should have labels |
185
- | `touch-link-spacing` | info | Adjacent links need spacing |
186
- | `touch-avatar-size` | info | Clickable avatars should be 44px+ |
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 | Severity | Description |
194
- |---------|----------|-------------|
195
- | `nav-item-count` | warning | Max 7 navigation items (Miller's Law) |
196
- | `nav-active-state` | info | Navigation should show active state |
197
- | `nav-breadcrumb-home` | info | Breadcrumb should start with home |
198
- | `nav-tab-count` | warning | Max 5 tabs |
199
- | `nav-dropdown-items` | warning | Dropdown must have 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 | Severity | Description |
207
- |---------|----------|-------------|
208
- | `consistency-button-styles` | info | Consistent button styles in container |
209
- | `consistency-spacing` | info | Consistent gap values |
210
- | `consistency-card-styling` | info | Sibling cards should match |
211
- | `consistency-alert-variants` | warning | Alert variant should match content |
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 | Severity | Description |
219
- |---------|----------|-------------|
220
- | `content-empty-text` | warning | Avoid empty/placeholder text |
221
- | `content-button-text-length` | info | Button text max 25 characters |
222
- | `content-title-length` | info | Title max 60 characters |
223
- | `content-page-title` | warning | Pages should have title |
224
- | `content-link-text` | error | Links must have text |
225
- | `content-no-placeholder` | warning | Replace placeholder content |
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 | Severity | Description |
233
- |---------|----------|-------------|
234
- | `data-table-header` | warning | Tables need headers |
235
- | `data-list-empty-state` | info | Lists should have empty state |
236
- | `data-table-empty-state` | info | Tables should have empty state |
237
- | `data-list-pagination` | info | Long lists (20+) need pagination |
238
- | `data-table-columns` | warning | Max 8 table columns |
239
- | `data-card-grid` | info | Card grids should be consistent |
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 | Severity | Description |
247
- |---------|----------|-------------|
248
- | `feedback-spinner-context` | info | Spinners should have context text |
249
- | `feedback-progress-value` | info | Progress should show value |
250
- | `feedback-toast-duration` | info | Toast duration 2-10 seconds |
251
- | `feedback-alert-dismissible` | info | Non-critical alerts should be dismissible |
252
- | `feedback-tooltip-length` | info | Tooltip max 100 characters |
253
- | `feedback-form-errors` | info | Forms should handle 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 | Severity | Description |
261
- |---------|----------|-------------|
262
- | `interaction-button-action` | warning | Buttons need onClick/action/href |
263
- | `interaction-link-destination` | warning | Links need href/to destination |
264
- | `interaction-form-submit` | warning | Forms need onSubmit/action |
265
- | `interaction-tab-target` | warning | Tabs need target/value |
266
- | `interaction-menu-action` | warning | Menu items need action |
267
- | `interaction-card-action` | info | Clickable cards need action |
268
- | `interaction-icon-button-action` | warning | Icon buttons need action |
269
- | `interaction-modal-close` | info | Modals need close mechanism |
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,
@@ -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
- "error",
147
- "fail",
148
- "invalid",
149
- "wrong",
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
- "Input",
199
- "Textarea",
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 getNodeText(node) {
219
- if ("content" in node && node.content) return String(node.content);
220
- if ("text" in node && node.text) return String(node.text);
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
  }
@@ -820,7 +779,7 @@ var consistentCardStyling = {
820
779
  const hasShadow = "shadow" in node && node.shadow;
821
780
  const hasBorder = "border" in node && node.border;
822
781
  const padding = "p" in node ? Number(node.p) : null;
823
- let inconsistencies = [];
782
+ const inconsistencies = [];
824
783
  for (const sibling of siblingCards) {
825
784
  if (sibling === node) continue;
826
785
  const sibShadow = "shadow" in sibling && sibling.shadow;
@@ -2187,9 +2146,10 @@ var modalHasCloseAction = {
2187
2146
  const hasDismiss = "dismissible" in node || "dismiss" in node;
2188
2147
  const hasCloseChild = hasChildren(node) && hasChildMatching(node, (child) => {
2189
2148
  if (child.type === "Button") {
2190
- const text = "text" in child ? String(child.text || "").toLowerCase() : "";
2191
- const label = "label" in child ? String(child.label || "").toLowerCase() : "";
2192
- const action = "action" in child ? String(child.action || "").toLowerCase() : "";
2149
+ const fields = child;
2150
+ const text = coerceTextLower(fields.text);
2151
+ const label = coerceTextLower(fields.label);
2152
+ const action = coerceTextLower(fields.action);
2193
2153
  return text.includes("close") || text.includes("cancel") || label.includes("close") || label.includes("cancel") || action.includes("close");
2194
2154
  }
2195
2155
  return false;
@@ -2431,7 +2391,9 @@ function formatUXResult(result) {
2431
2391
  }
2432
2392
  lines.push("Summary by category:");
2433
2393
  for (const cat of result.summary) {
2434
- lines.push(` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`);
2394
+ lines.push(
2395
+ ` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`
2396
+ );
2435
2397
  }
2436
2398
  return lines.join("\n");
2437
2399
  }
@@ -2469,6 +2431,8 @@ function formatUXResult(result) {
2469
2431
  TEXT_CONTENT_TYPES,
2470
2432
  WARNING_WORDS,
2471
2433
  allRules,
2434
+ coerceText,
2435
+ coerceTextLower,
2472
2436
  containsAnyWord,
2473
2437
  countInChildren,
2474
2438
  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
- "error",
68
- "fail",
69
- "invalid",
70
- "wrong",
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
- "Input",
120
- "Textarea",
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 getNodeText(node) {
140
- if ("content" in node && node.content) return String(node.content);
141
- if ("text" in node && node.text) return String(node.text);
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
  }
@@ -741,7 +698,7 @@ var consistentCardStyling = {
741
698
  const hasShadow = "shadow" in node && node.shadow;
742
699
  const hasBorder = "border" in node && node.border;
743
700
  const padding = "p" in node ? Number(node.p) : null;
744
- let inconsistencies = [];
701
+ const inconsistencies = [];
745
702
  for (const sibling of siblingCards) {
746
703
  if (sibling === node) continue;
747
704
  const sibShadow = "shadow" in sibling && sibling.shadow;
@@ -2108,9 +2065,10 @@ var modalHasCloseAction = {
2108
2065
  const hasDismiss = "dismissible" in node || "dismiss" in node;
2109
2066
  const hasCloseChild = hasChildren(node) && hasChildMatching(node, (child) => {
2110
2067
  if (child.type === "Button") {
2111
- const text = "text" in child ? String(child.text || "").toLowerCase() : "";
2112
- const label = "label" in child ? String(child.label || "").toLowerCase() : "";
2113
- const action = "action" in child ? String(child.action || "").toLowerCase() : "";
2068
+ const fields = child;
2069
+ const text = coerceTextLower(fields.text);
2070
+ const label = coerceTextLower(fields.label);
2071
+ const action = coerceTextLower(fields.action);
2114
2072
  return text.includes("close") || text.includes("cancel") || label.includes("close") || label.includes("cancel") || action.includes("close");
2115
2073
  }
2116
2074
  return false;
@@ -2352,7 +2310,9 @@ function formatUXResult(result) {
2352
2310
  }
2353
2311
  lines.push("Summary by category:");
2354
2312
  for (const cat of result.summary) {
2355
- lines.push(` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`);
2313
+ lines.push(
2314
+ ` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`
2315
+ );
2356
2316
  }
2357
2317
  return lines.join("\n");
2358
2318
  }
@@ -2389,6 +2349,8 @@ export {
2389
2349
  TEXT_CONTENT_TYPES,
2390
2350
  WARNING_WORDS,
2391
2351
  allRules,
2352
+ coerceText,
2353
+ coerceTextLower,
2392
2354
  containsAnyWord,
2393
2355
  countInChildren,
2394
2356
  filterChildren,
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@wireweave/ux-rules",
3
- "version": "1.4.0-beta.0",
3
+ "version": "1.4.1-beta.0",
4
4
  "description": "UX validation rules for wireweave",
5
5
  "type": "module",
6
- "main": "dist/index.js",
7
- "module": "dist/index.mjs",
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": "^2.7.0"
20
+ "@wireweave/core": "3.1.0-beta.0"
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.0.0",
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/ux-rules.git"
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/ux-rules/issues"
54
+ "url": "https://github.com/wireweave/wireweave/issues"
52
55
  },
53
- "homepage": "https://github.com/wireweave/ux-rules#readme"
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
+ }