super-ux 0.23.2 → 0.26.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/CHANGELOG.md CHANGED
@@ -1,5 +1,213 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.26.1 — 2026-07-29
4
+
5
+ 0.26.0 gave practice selection two new profile dimensions but no place in the
6
+ chain to read them from — the foundation had no field for either, so the
7
+ profile could only be built by asking again every session. This closes that
8
+ loop.
9
+
10
+ ### Added
11
+ - **Foundation contract §7 — Product mechanics** (`scenario-format.md`,
12
+ `templates/foundation.md`): personalization (none / rule-based / inferred),
13
+ engagement mechanics (none / streaks-tiers / points-badges-leaderboards),
14
+ and the accessibility regime (none stated / EAA / ADA / both) with its
15
+ owner. Three facts the profile reads and cannot infer from the rest of the
16
+ chain; each recorded mechanic carries its consequence into `flows.md` — a
17
+ recovery flow (BP-142), a correction path (BP-144), per-scenario checks
18
+ (BP-138).
19
+ - `ux-foundation` records the section as a step of its own; "none" is a valid
20
+ and useful answer.
21
+
22
+ The section is optional and additive — the contract stays **v4** and every
23
+ existing `foundation.md` remains valid without it.
24
+
25
+ ## 0.26.0 — 2026-07-29
26
+
27
+ A pass over what the catalog could not answer about the *surface* of a
28
+ product. Motion existed as one line of stance (BP-054) with no system behind
29
+ it. Page weight, the narrow viewport, and input capability were absent
30
+ entirely. Accessibility had a standard (BP-059) but nothing about how real
31
+ products miss it — which is a short, repetitive list. Nothing measured
32
+ frustration, nothing governed adopting a look, and personalization was
33
+ implied by the paywall practices without ever being designed. Seventeen
34
+ practices close those gaps, all anchored to field data rather than to trend
35
+ copy.
36
+
37
+ ### Added
38
+ - **Motion — BP-130..132**: durations and easings as a named token scale
39
+ (the motion twin of BP-085's spacing grid); reduced motion as a supported
40
+ mode with a real branch in code, pause/stop for anything auto-playing past
41
+ five seconds, large-transform effects first to go; scroll-driven
42
+ storytelling as enhancement only — the content is complete and readable
43
+ with every effect removed, one scroll clock, capped animated layers.
44
+ - **Page weight, responsiveness & device reality — BP-133..135**: a stated,
45
+ enforced byte and script budget (field medians are the competition, not
46
+ the target), image/font/video/WebGL policy, DOM bloat watched; the small
47
+ viewport designed first with breakpoints from content and a verified 320px
48
+ / 200%-zoom reflow; hover, fine pointer and touch treated as independent
49
+ capabilities — no hover-only affordances.
50
+ - **Accessibility as it actually fails — BP-136..138**: native semantics
51
+ first with ARIA only for what HTML cannot say (pages carrying ARIA measure
52
+ roughly twice the detected errors); overlays are not remediation and a
53
+ clean scan is not coverage — the evidence is a keyboard and screen-reader
54
+ walk; accessibility decided in the chain, with the applicable regime
55
+ (European Accessibility Act since June 2025, ADA litigation exposure) as a
56
+ ship requirement with an owner.
57
+ - **Frustration telemetry — BP-139..140**: rage/dead clicks, failed submits,
58
+ error loops and field-level abandonment instrumented next to the funnel
59
+ and segmented; every recurring cluster routed back into the chain as a
60
+ scenario or a finding with an owner — telemetry nobody owns is decoration.
61
+ - **Gamification — BP-141..142**: mechanics amplify the traced core job or
62
+ they don't ship (extrinsic rewards crowd out the intrinsic motive;
63
+ leaderboards demotivate everyone outside the top); every streak, tier or
64
+ expiring-progress mechanic ships a recovery valve, because the loss moment
65
+ is otherwise a churn trigger at peak engagement.
66
+ - **Personalization & progressive profiling — BP-143..144**: split the ask
67
+ across sessions, derive what can be derived, never re-ask what is known;
68
+ personalization shown with its reason, correctable in one tap, with the
69
+ unpersonalized path still reachable.
70
+ - **Trend governance — BP-145..146**: BP-001 applied to looks — a trend is
71
+ adopted through its mechanism, its identity fit, its accessibility and
72
+ weight cost, and a review date, recorded in the style pack rather than in
73
+ one screen; styles with documented debt (neumorphic surfaces, deliberate
74
+ anti-design, unconventional navigation, immersive 3D) ship only with the
75
+ compensation named, and the audit checks the compensation in the built UI.
76
+ - Six source keys — **[WebAIM]**, **[HTTPArchive]**, **[CSq]**,
77
+ **[A11yLaw]**, **[WSG]**, **[SDT]** — plus an explicit note that
78
+ vendor-published "state of" survey figures are directional only and never
79
+ a practice's sole justification.
80
+
81
+ ### Changed
82
+ - `practice-selection.md`: two new profile dimensions (personalization,
83
+ engagement mechanics); motion, look, weight, responsiveness and
84
+ accessibility routed from the profile; five new per-artifact rows
85
+ (animated/scroll-driven surface, responsive layout pass, accessibility
86
+ pass, gamified/streak surface, personalized/adaptive surface).
87
+ - `ux-design-principles.md`: accessibility, motion behavior and
88
+ responsiveness are specified in the chain, in text, before the UI exists;
89
+ two anti-patterns added (a look adopted with no mechanism or review date;
90
+ treating accessibility, motion or weight as post-build polish).
91
+ - `ux-audit`: the practice pass now verifies in code the four things that
92
+ fail silently — the reduced-motion branch and content-without-effects, the
93
+ weight budget, narrow-viewport/zoom reflow and hover-only affordances, and
94
+ ARIA sitting only where no native element says it. An accessibility claim
95
+ backed by a scanner alone is BLOCKED, not PASS.
96
+ - `visual-identity.md`: motion floors and trend adoption added to the
97
+ division of labor — the pack picks the values, super-ux decides whether the
98
+ floors apply and whether the trend is adopted at all; the audit checks the
99
+ BP-146 compensation in the built UI.
100
+ - `component-guidelines.md`: the cross-platform stance now states the
101
+ native-element-first rule ahead of the ARIA APG patterns.
102
+ - Existing entries updated with field prevalence and cross-links: BP-054
103
+ (points to the motion system), BP-055 (checkout-rebuild yield, defers to
104
+ BP-143), BP-058 (points to the weight budget), BP-059 and BP-081 (the
105
+ ~95% failure rate and low contrast as the single most common defect),
106
+ BP-077 (points to progressive profiling).
107
+
108
+ ## 0.25.0 — 2026-07-29
109
+
110
+ The catalog knew how to sell inside an app and almost nothing about selling
111
+ on the web. Two funnels were missing: web-to-web (landing → pricing →
112
+ checkout → recurring billing → cancel) had only generic form advice, and
113
+ web2app was a single entry (BP-078) stating the economics with none of the
114
+ design work. Both are now full sets, and the chain routes to them from the
115
+ foundation's purchase surface.
116
+
117
+ ### Added
118
+ - **Web funnels — BP-116..123** (`best-practices.md`): one promise from ad to
119
+ landing to first product screen; one page, one job, with proof beside each
120
+ CTA rather than in a bottom section most visitors never reach; pricing page
121
+ as three tiers with one visibly recommended and annual framed in absolute
122
+ money; signup asking the smallest identity that unblocks value (card only
123
+ when the trial is deliberately opt-out); total price — currency, tax, fees —
124
+ shown before the last step, wallets above the card form; abandonment as a
125
+ designed branch with surviving state and a resume link, not a leak; dunning
126
+ as a UX surface (pre-expiry notice, one-tap in-product card update, retries
127
+ that end in a real message); cancel self-serve and honest with exactly one
128
+ save offer.
129
+ - **Web-to-app funnels — BP-124..129**: the web funnel replaces onboarding,
130
+ not just the paywall; the paid handoff is a first-class scenario with its
131
+ failure branches (wrong account, mail never arrived, purchase not yet
132
+ propagated, second device, refunded) — a paying user must never meet a
133
+ paywall; context carried across the store gap by deferred deep link with a
134
+ deliberately designed magic-link fallback; storefront rules as a per-region
135
+ variable re-checked each ship (US external links after the April 2025
136
+ ruling, entitlement elsewhere, EU its own regime, IAP as fallback); the tax,
137
+ SCA, refund and invoice duties the store used to absorb; and one funnel
138
+ measured web session → purchase → install → activation, not stopping at the
139
+ sale.
140
+ - Two source keys — **[CRO26]** (Baymard checkout research, ChartMogul/Paddle
141
+ trial and failed-payment data, landing/pricing-page A/B aggregations) and
142
+ **[W2A26]** (RevenueCat/Adapty/Superwall funnel benchmarks, Apple/Google
143
+ storefront policy after the 2025 US anti-steering ruling) — with an explicit
144
+ note that their figures are industry aggregates the product's own numbers
145
+ overrule.
146
+ - Tag taxonomy: `billing`, `cancel` (stage), `landing-page`, `web2app`
147
+ (domain).
148
+
149
+ ### Changed
150
+ - **`practice-selection.md` routes to the new sets.** New profile dimension
151
+ **Purchase surface** (none / IAP / web checkout / web2app); Step-2 mandatory
152
+ sets for web-direct money products (BP-116..123), for any off-store purchase
153
+ (BP-127, BP-128) and for web2app (BP-124..126, BP-129); Step-3 checklists
154
+ for landing/campaign page, web pricing page, abandonment recovery, dunning,
155
+ and the web2app funnel + paid handoff, with the existing forms/checkout and
156
+ cancel rows extended.
157
+ - **The foundation now declares where the money is taken.** `Purchase surface`
158
+ added to the Monetization section (`scenario-format.md`,
159
+ `templates/foundation.md`, `ux-foundation` skill and Cursor rule); money
160
+ moments now name checkout, failed payment and cancel; when the surface is
161
+ web or web2app, the web funnel and the paid handoff are flows of this
162
+ product, held to the same rigor as in-app screens (`ux-flows`,
163
+ `ux-scenarios` completeness checklists and Cursor rule).
164
+ - Plugin/marketplace descriptions de-numbered again — a practice count had
165
+ crept back in and gone stale; they now say "a tag-indexed best-practices
166
+ catalog". README says 129 and names the two new areas.
167
+
168
+ ## 0.24.0 — 2026-07-29
169
+
170
+ Checked what the plugin claims about Figma against the official Figma MCP's
171
+ actual tools and their contracts. Several instructions would have failed.
172
+
173
+ ### Fixed
174
+ - **The MCP gates its own tools behind guidance skills, and super-ux ignored
175
+ two of the three gates.** `use_figma` requires `/figma-use` first,
176
+ `create_new_file` requires `/figma-create-new-file`, `get_design_context`
177
+ requires `/figma-design-to-code` — skipping them is the server's documented
178
+ cause of hard-to-debug failures. Only the first was mentioned, and only in
179
+ one step of the design loop; the preflight told the agent to call
180
+ `create_new_file` and Improve mode to call `get_design_context` with no gate
181
+ at all. All three are now stated where the call is made, with the
182
+ `skill://figma/<name>/SKILL.md` fallback for setups without the slash
183
+ commands.
184
+ - **"Create a Figma file" was an unrunnable instruction.** `create_new_file`
185
+ needs a plan key (from `whoami`, asking the user when there are several
186
+ teams/orgs) and an `editorType`; neither was mentioned.
187
+ - `generate_figma_design` was listed as a plain alternative for mockups. It is
188
+ narrower than that — the server's own guidance reserves it for capturing a
189
+ *web app* page pixel-perfect the first time, run beside `use_figma`; for
190
+ non-web and from-scratch design, `use_figma` only. Stated as such, and as
191
+ "where the setup exposes it", since not every install has it.
192
+
193
+ ### Added
194
+ - **A tool map in `figma-integration.md`** — need → tool, for the whole
195
+ surface the chain actually touches: writes (`use_figma`), structure reads
196
+ (`get_metadata`), implementation reads (`get_design_context`), screenshots,
197
+ variables (`get_variable_defs`), libraries, assets
198
+ (`download_assets` / `upload_assets`), Code Connect, and FigJam. Explicitly
199
+ a map, not a contract: a missing tool degrades to what is there, and the
200
+ agent never invents a call. Plus how `node-id` and `fileKey` come out of the
201
+ links `screens.md` already stores.
202
+ - **Drift checks that use the cheap tool.** Frame existence and naming are
203
+ verified with `get_metadata` (ids, names, types, sizes — no full design
204
+ context needed), in both directions: a listed state without a frame, and a
205
+ frame whose `SCR-ID`/state is in no `screens.md` row.
206
+ - **Token parity is now checkable, not assumed.** `get_variable_defs` reads
207
+ what a frame actually references, so "built on the style pack's tokens"
208
+ becomes a verdict with evidence — a frame full of raw hexes is the
209
+ design-side twin of hard-coded colors in code.
210
+
3
211
  ## 0.23.2 — 2026-07-28
4
212
 
5
213
  Open-source hygiene pass — the repo is public, so the files a first-time
package/README.md CHANGED
@@ -155,9 +155,11 @@ fine without either.
155
155
  | At VISUALIZE / BUILD — a frame or a screen is about to be drawn | **[sheleg-design](https://github.com/ssheleg/sheleg-design-skill)** | The look: one locked style pack (palette, type, texture, motion tokens, bans) with ready token CSS — `workbench` for product UI, dashboards and tools; `instrument-console`; `editorial-luxury`; or a new pack on its contract. Plus the motion methodology for cinematic scroll-driven landings. The pack is recorded in `screens.md`; its tokens become the Figma variables *and* the code tokens. `npx sheleg-design-skill` |
156
156
  | After an audit or an Improve pass produced a UX plan | **[task-pipeline](https://github.com/ssheleg/task-pipeline)** | Executes the plan end-to-end through gated stages: spec → plan → subagent build → tests → deploy → docs. `/task-pipeline docs/ux/plans/<file>` |
157
157
 
158
- The boundary that keeps them from fighting: BP-079..090 are craft **floors**
159
- (contrast, line length, tap targets, spacing rhythm) and always win on safety;
160
- the style pack owns **identity** and wins on look. Both decisions land in the
158
+ The boundary that keeps them from fighting: BP-079..090 and BP-130..135 are
159
+ craft **floors** (contrast, line length, tap targets, spacing rhythm, a motion
160
+ token scale, reduced motion, the narrow viewport) and always win on safety;
161
+ the style pack owns **identity** and wins on look. Whether a trend is adopted
162
+ at all — its mechanism, its cost, its review date — is BP-145/BP-146. Both decisions land in the
161
163
  compliance table. Full protocol:
162
164
  [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md).
163
165
 
@@ -184,7 +186,7 @@ The contracts every skill reads:
184
186
  | [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md) | **The contract (ux-contract v4).** File layout, every field name, stable IDs (`P` `JTBD` `JRN` `ST` `FLW` `SCR` `SCN`), completeness checklists, the `draft → validated → implemented` lifecycle, audit verdicts and severities, the UX-plan format |
185
187
  | [system-map.md](plugins/super-ux/skills/references/system-map.md) | The whole system on one page — pipeline, files, skills, companions, and the four sync rules; every skill points here |
186
188
  | [ux-design-principles.md](plugins/super-ux/skills/references/ux-design-principles.md) | How the agent thinks: the design pipeline (forward and backwards), task analysis, flow rules, heuristics PRN-01..16, the improvement procedure, anti-patterns |
187
- | [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 115 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries, web2app), visual craft, Figma structure |
189
+ | [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 146 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries), web funnels end to end (landing, pricing, checkout, dunning, cancel) and web2app (paid handoff, deferred deep links, storefront rules), motion and page weight (HTTP Archive field data, W3C sustainability), accessibility as it actually fails (WebAIM Million, EAA/ADA exposure), frustration telemetry, gamification and trend governance, visual craft, Figma structure |
188
190
  | [practice-selection.md](plugins/super-ux/skills/references/practice-selection.md) | The deterministic bridge: product profile → mandatory consideration sets → per-artifact checklists → a compliance table where every pulled practice gets a verdict. No silent skips, no cargo cult |
189
191
  | [component-guidelines.md](plugins/super-ux/skills/references/component-guidelines.md) | Which control for which job (radios/select/switch, sheet/alert, modal/disclosure, combobox, nav bar/rail, FAB, dates, toasts) and the platform rules — Apple HIG, Material 3, W3C ARIA APG, GOV.UK |
190
192
  | [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md) | The visual layer and its owner: one style pack for the whole product, where it's recorded, how it meets Figma and code, and the division of labor with the craft floors |
@@ -43,8 +43,10 @@ deleted.
43
43
  complete; must/should stories have scenarios).
44
44
 
45
45
  Two more sections this file owns, filled when they apply: **Monetization**
46
- (model + value metric + free boundary + money moments + acquisition
47
- coherence — each money moment becomes a first-class flow) and **Design
46
+ (model + value metric + free boundary + purchase surface + money moments +
47
+ acquisition coherence — each money moment becomes a first-class flow, and a
48
+ web/web2app purchase surface makes the web funnel and the paid handoff flows
49
+ of this product too) and **Design
48
50
  tooling** (the Figma on/off choice, default on, plus the project's Figma file
49
51
  URL — asked once per project). Everything else about the visual layer, the
50
52
  design system and the style pack, lives in `docs/ux/screens.md`.
@@ -40,7 +40,9 @@ Per-product: first-run onboarding, every core flow, settings, multi-entity
40
40
  flows (e.g. second project), account/data lifecycle, and — when the product
41
41
  earns money — the monetization flows: paywall (first-session placement),
42
42
  trial start/end, upgrade-at-limit, cancel + winback, rating prompt after
43
- success moments.
43
+ success moments, plus the web funnel (landing, pricing, signup, checkout,
44
+ abandonment, failed payment) and the paid handoff with its failure branches
45
+ when money is taken on the web.
44
46
 
45
47
  ## Workflows
46
48
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "super-ux",
3
- "version": "0.23.2",
3
+ "version": "0.26.1",
4
4
  "description": "Scenario-driven UI development for AI agents (Claude Code, Cursor, 70+ agents): a versioned design chain in docs/ux/, a scenario-first hard rule, a deterministic drift linter, and evidence-backed UX audits. This package is the installer CLI.",
5
5
  "bin": {
6
6
  "super-ux": "bin/super-ux.js"
@@ -33,8 +33,18 @@ data/observation, recognizable by a real user. -->
33
33
  - **Model:** hard paywall | freemium | hybrid | trial (type, length) — and why
34
34
  - **Value metric:** <what the paid tier meters>
35
35
  - **Free boundary:** <what stays free, where the visible limit sits>
36
- - **Money moments:** <paywall placement, upgrade triggers, rating prompts, winback>
37
- - **Acquisition coherence:** <the one story ad -> listing -> onboarding tells>
36
+ - **Purchase surface:** in-app (IAP) | web checkout | web2app (web funnel -> app) — BP-030/BP-078/BP-127, and which storefronts
37
+ - **Money moments:** <paywall placement, upgrade triggers, checkout, failed payment, cancel, rating prompts, winback>
38
+ - **Acquisition coherence:** <the one story ad -> landing/listing -> onboarding tells>
39
+ -->
40
+
41
+ ## Product mechanics
42
+
43
+ <!-- Two dimensions the practice-selection profile reads; record them once,
44
+ even when the answer is "none":
45
+ - **Personalization:** none | rule-based | inferred/model-driven — BP-143/BP-144 (what gets asked when, and how a wrong inference is corrected)
46
+ - **Engagement mechanics:** none | streaks/tiers | points/badges/leaderboards — BP-141/BP-142 (which traced job each mechanic reinforces, and the recovery path when progress is lost)
47
+ - **Accessibility regime:** none stated | EAA (EU) | ADA (US) | both — BP-138, with the owner
38
48
  -->
39
49
 
40
50
  ## Design tooling