@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 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,
@@ -78,7 +80,7 @@ __export(src_exports, {
78
80
  validateUX: () => validateUX
79
81
  });
80
82
  module.exports = __toCommonJS(src_exports);
81
- var import_core2 = require("@wireweave/core");
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
- "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
  }
@@ -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: "error",
378
- name: "Icon-only button requires label",
379
- description: "Buttons with only an icon must have an accessible label",
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
- if (hasIcon && !hasContent) {
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: "error",
389
- message: "Icon-only button is missing accessible text",
390
- description: "Screen readers cannot describe icon-only buttons without text",
391
- suggestion: "Add text content or aria-label to describe the button action",
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
- let inconsistencies = [];
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 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() : "";
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, import_core2.analyze)(ast);
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(` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`);
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
- "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
  }
@@ -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: "error",
299
- name: "Icon-only button requires label",
300
- description: "Buttons with only an icon must have an accessible label",
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
- if (hasIcon && !hasContent) {
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: "error",
310
- message: "Icon-only button is missing accessible text",
311
- description: "Screen readers cannot describe icon-only buttons without text",
312
- suggestion: "Add text content or aria-label to describe the button action",
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
- let inconsistencies = [];
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 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() : "";
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(` ${cat.category}: ${cat.passed} passed, ${cat.failed} errors, ${cat.warnings} warnings`);
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.4.0",
3
+ "version": "1.5.0-beta.1",
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.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.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
+ }