super-ux 0.26.5 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 0.28.0 — 2026-08-05
+
+Closes the carry-over ledger the 0.27 audit opened. Twenty-three practices,
+five principles, three optional contract fields, a prototype step, and an
+index over a catalog that had grown past the point of being read whole.
+
+### Added
+- **Motion craft — BP-157..164.** BP-130 said durations and easings should be
+  tokens and stopped there. These make the decisions it does not: whether the
+  element animates at all (frequency decides — a hundred times a day means
+  never), what the durations actually are, why `ease-in` is wrong on
+  interface motion, entering from a visible state rather than `scale(0)`,
+  anchored surfaces growing from their trigger, asymmetric enter/exit,
+  interruptibility for anything retriggerable, and hover gated behind a
+  hover-capable pointer.
+- **Perceived quality — BP-165..168.** Why a technically correct interface
+  still reads as unfinished: mixed icon families and stroke weights, emoji
+  used as structural icons, pressed states that reflow their neighbours, and
+  a scrim too weak to separate the layers it exists to separate. None of
+  these fail an automated check, which is why they survive audits that only
+  measure.
+- **Generated-default tells — BP-169..172.** super-ux is a tool agents build
+  interfaces with, so it should know the signature of its own defaults: fake
+  product screenshots built from markup, implausible placeholder data, the
+  three-equal-cards row that means nobody decided the hierarchy, and the
+  cluster (`#000000`, two accents, `100vh`, no max-width) that marks a
+  question never asked.
+- **Interface state, platform surfaces and locale — BP-173..179**, from the
+  Web Interface Guidelines: state in the URL, undo for reversible actions
+  instead of a confirmation nobody reads, unsaved work that survives,
+  dark mode covering the surfaces the browser draws, localization as a
+  design constraint rather than a translation step, scroll containment and
+  touch defaults in overlays, and lists virtualized before they ship long.
+- **Motivation principles — PRN-17..21.** Goal-gradient, Zeigarnik, IKEA,
+  endowment, zero-price. Each carries a fourth column naming where it turns
+  coercive, and a rule that any of them recorded as `applied` says which side
+  of that line it is on. They are motivation mechanisms; the same levers
+  aimed at the product's interest are dark patterns.
+- **`Telemetry` on a scenario (optional).** The bridge the chain was missing:
+  BP-139, BP-140 and BP-129 all assume events exist, and nothing tied a named
+  event to the behavior it measures — so renaming a step silently re-pointed
+  a dashboard. `object_action`, snake_case, verb last.
+- **`Kill criteria` on a story (optional).** `dropped` has been a valid
+  status since v1 with nothing defining when it applies, so it was only ever
+  reached by someone losing interest.
+- **A verdict on audit reports — REFINE / REDESIGN / NEW.** Findings alone
+  read as a to-do list, and a surface that should be rebuilt gets patched
+  indefinitely, one true finding at a time.
+- **A prototype step in `ux-flows`** for the question documents cannot
+  settle, plus *diverge before converging*: two genuinely different shapes
+  before picking one, and a line on why the loser lost.
+- **`best-practices-index.md`**, generated by
+  `plugins/super-ux/scripts/bp_index.py` — 274 lines of tag → ids over a
+  catalog that is now 1400+. The validator fails when it drifts.
+
+### Changed
+- Taxonomy gains `i18n`; source keys gain `[EmilK]` and `[WIG]`.
+- `PRN-01..16` becomes `PRN-01..21` everywhere it is referenced.
+
+The contract stays **v4**. All three new fields are optional and additive, on
+the same precedent as 0.26.1 — no existing `docs/ux` file changes shape and
+there is nothing to migrate.
+
+## 0.27.1 — 2026-08-05
+
+Re-cut of 0.27.0 on the correct base. The 0.27.0 tag was pushed from a tree
+that predated 0.26.2–0.26.5, so the GitHub release it produced was missing
+the MIT declarations, the `/ux-audit` front-matter fix, `displayName`, and
+the npm-publish workflow. Nothing was published to npm from it. The content
+of 0.27.0 is unchanged and listed below it; this release only puts it on top
+of the history it belongs to.
+
+## 0.27.0 — 2026-08-04
+
+An audit of 51 external UX, product and growth skills, kept only where they
+found something this catalog did not already say better. Most of the overlap
+went the other way — on monetization, forms and activation the catalog was
+the stronger of the two, and with sources where the others had none. Four
+gaps survived that test.
+
+### Added
+- **Growth loops and referral — BP-147..151.** BP-067 has been telling
+  readers since 0.19 that freemium only works when free users feed a growth
+  loop, while the catalog described no loop anywhere. BP-147 names the three
+  kinds and the reference now resolves. The rest: virality riding the
+  product's own output rather than a "refer a friend" page, planning for a
+  viral coefficient around 0.2 with the loop's cycle time treated as the
+  other multiplier, rewards paid in the product's own unit on the invitee's
+  milestone, and abuse designed against before launch.
+- **Empty states — BP-152.** Three layers after NN/g: what happened, what
+  this place is for, and a way in — including inspecting the feature on demo
+  data. A blank panel is a defect, not a neutral state.
+- **Authentication and form recovery — BP-153..156.** The word "password"
+  appeared zero times across 146 practices. NIST SP 800-63B rev 4 (August
+  2025) made paste normative and composition rules prohibited; the field must
+  not fight the password manager; a passwordless door where the account
+  allows one; and a rejected form keeps the work instead of clearing it
+  (WCAG 2.2 redundant entry).
+- **Audit reports: a required "Scope and limits" section**
+  (`scenario-format.md`, `templates/audit-report.md`, `ux-audit`). A batched
+  audit reads a slice of the code, so silence about the rest was being read
+  as coverage. Absence from a report never means PASS.
+- **`validate_catalog()` in `test/validate.py`.** The catalog's shape — five
+  fields per entry, unbroken ids, tags from the taxonomy, and every practice
+  reachable from `practice-selection.md` — was an invariant held by hand
+  since the first entry. A practice no skill routes to is a practice that
+  does not exist; nothing checked for that until now.
+
+### Changed
+- Tag taxonomy gains `virality`, `referral` (mechanism) and `auth` (domain);
+  source keys gain `[NIST]` and `[Viral26]`.
+
+Two figures from the source material were dropped rather than repeated — a
+15–30% referral conversion norm and a 60% fraud threshold, neither of which
+survived a check. A third was corrected in the opposite direction: a viral
+coefficient of 0.3–0.7 is a strong result, not the practical target the
+source called it.
+
+The contract stays **v4**: the report section is additive and no existing
+`docs/ux` file changes shape.
+
 ## 0.26.5 — 2026-07-30
 
 ### Added

package/README.md

@@ -185,8 +185,9 @@ The contracts every skill reads:
 |---|---|
 | [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 |
 | [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 |
-| [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 |
-| [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 |
+| [best-practices-index.md](plugins/super-ux/skills/references/best-practices-index.md) | Generated tag index over the catalog — tag → ids, id → title. Read it to decide which entries to open; regenerated by `plugins/super-ux/scripts/bp_index.py` and checked for drift by the validator |
+| [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..21, the improvement procedure, anti-patterns |
+| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 179 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, growth loops and referral mechanics, empty states, authentication (NIST SP 800-63B rev 4) and form recovery, motion craft and perceived quality, the defaults that make an interface read as generated, interface state, locale and platform surfaces (Web Interface Guidelines), visual craft, Figma structure |
 | [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 |
 | [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 |
 | [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 |
@@ -228,7 +229,7 @@ edits to `plugins/super-ux/skills/references/` need
 
 Built by ssheleg — [sshlg.me](https://sshlg.me)
 
-- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
+- X / Twitter — [@sshlg93](https://x.com/sshlg93)
 - Telegram — [@sshlg](https://t.me/sshlg)
 
 Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):

package/cursor/rules/ux-audit.mdc

@@ -13,6 +13,16 @@ rule) — there is nothing to audit against.
 **Evidence discipline:** every verdict cites `file:line`. Cannot verify →
 verdict BLOCKED with the exact reason. Never guess, never a courtesy PASS.
 
+**Scope and limits (required section):** the report ends with what was
+covered, what was left out and why, what could not be verified, and what the
+code cannot answer. An audit reads a slice; absence from the report never
+means PASS.
+
+**Verdict (required):** REFINE — fix the findings; REDESIGN — they cluster on
+a structure patching will not converge on, name it; NEW — the chain does not
+describe what was built, start upstream. Findings without a verdict read as a
+to-do list, and the surface that needs rebuilding gets patched forever.
+
 ## Loop
 
 1. Read the base (and foundation/flows/screens when they exist); scope =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.26.5",
+  "version": "0.28.0",
   "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.",
   "bin": {
     "super-ux": "bin/super-ux.js"
@@ -20,7 +20,10 @@
     "url": "https://github.com/ssheleg/super-ux/issues"
   },
   "license": "MIT",
-  "author": "ssheleg",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
   "engines": {
     "node": ">=16"
   },

package/templates/audit-report.md

@@ -29,6 +29,20 @@ Heuristic findings (deep): [PRN-NN] (severity) node — issue -> fix
 | # | Scenario | Severity | Finding | Suggested fix |
 |---|----------|----------|---------|---------------|
 
+## Scope and limits
+
+<!-- Required. An audit reads a finite slice of the code; absence from this
+report never means PASS. -->
+
+- **Covered:**
+- **Not covered:**
+- **Could not verify:**
+- **Open questions:**
+
+## Verdict
+
+<REFINE | REDESIGN | NEW> — <one line of reasoning, and the scope it covers>
+
 ## Practice compliance (deep audits)
 
 | Practice | Verdict | How / why not |

package/templates/foundation.md

@@ -65,5 +65,6 @@ this section just records the on/off choice and the file location.
 - **Acceptance criteria:**
   - Given <precondition>, when <action>, then <observable result>.
 - **Priority:** must | should | could
+- **Kill criteria:** <metric below threshold by date -> drop | iterate, or omit>
 - **Status:** proposed
 -->

package/templates/scenarios.md

@@ -32,6 +32,7 @@ action per step paired with the observable system response:
 - **UI elements:** <every button, field, link, dialog, toast involved>
 - **States covered:** <loading | empty | error | success>
 - **Errors & recovery:** <each failure: what the user sees, how they recover>
+- **Telemetry:** <`object_action` event + params, or omit if none>
 - **Status:** draft
 - **Coverage:** none yet
 -->