@wireweave/ux-rules 1.5.0-beta.10 → 1.5.0-beta.12

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