super-ux 0.19.0 → 0.26.1

package/CHANGELOG.md

@@ -1,5 +1,405 @@
 # Changelog
 
+## 0.26.1 — 2026-07-29
+
+0.26.0 gave practice selection two new profile dimensions but no place in the
+chain to read them from — the foundation had no field for either, so the
+profile could only be built by asking again every session. This closes that
+loop.
+
+### Added
+- **Foundation contract §7 — Product mechanics** (`scenario-format.md`,
+  `templates/foundation.md`): personalization (none / rule-based / inferred),
+  engagement mechanics (none / streaks-tiers / points-badges-leaderboards),
+  and the accessibility regime (none stated / EAA / ADA / both) with its
+  owner. Three facts the profile reads and cannot infer from the rest of the
+  chain; each recorded mechanic carries its consequence into `flows.md` — a
+  recovery flow (BP-142), a correction path (BP-144), per-scenario checks
+  (BP-138).
+- `ux-foundation` records the section as a step of its own; "none" is a valid
+  and useful answer.
+
+The section is optional and additive — the contract stays **v4** and every
+existing `foundation.md` remains valid without it.
+
+## 0.26.0 — 2026-07-29
+
+A pass over what the catalog could not answer about the *surface* of a
+product. Motion existed as one line of stance (BP-054) with no system behind
+it. Page weight, the narrow viewport, and input capability were absent
+entirely. Accessibility had a standard (BP-059) but nothing about how real
+products miss it — which is a short, repetitive list. Nothing measured
+frustration, nothing governed adopting a look, and personalization was
+implied by the paywall practices without ever being designed. Seventeen
+practices close those gaps, all anchored to field data rather than to trend
+copy.
+
+### Added
+- **Motion — BP-130..132**: durations and easings as a named token scale
+  (the motion twin of BP-085's spacing grid); reduced motion as a supported
+  mode with a real branch in code, pause/stop for anything auto-playing past
+  five seconds, large-transform effects first to go; scroll-driven
+  storytelling as enhancement only — the content is complete and readable
+  with every effect removed, one scroll clock, capped animated layers.
+- **Page weight, responsiveness & device reality — BP-133..135**: a stated,
+  enforced byte and script budget (field medians are the competition, not
+  the target), image/font/video/WebGL policy, DOM bloat watched; the small
+  viewport designed first with breakpoints from content and a verified 320px
+  / 200%-zoom reflow; hover, fine pointer and touch treated as independent
+  capabilities — no hover-only affordances.
+- **Accessibility as it actually fails — BP-136..138**: native semantics
+  first with ARIA only for what HTML cannot say (pages carrying ARIA measure
+  roughly twice the detected errors); overlays are not remediation and a
+  clean scan is not coverage — the evidence is a keyboard and screen-reader
+  walk; accessibility decided in the chain, with the applicable regime
+  (European Accessibility Act since June 2025, ADA litigation exposure) as a
+  ship requirement with an owner.
+- **Frustration telemetry — BP-139..140**: rage/dead clicks, failed submits,
+  error loops and field-level abandonment instrumented next to the funnel
+  and segmented; every recurring cluster routed back into the chain as a
+  scenario or a finding with an owner — telemetry nobody owns is decoration.
+- **Gamification — BP-141..142**: mechanics amplify the traced core job or
+  they don't ship (extrinsic rewards crowd out the intrinsic motive;
+  leaderboards demotivate everyone outside the top); every streak, tier or
+  expiring-progress mechanic ships a recovery valve, because the loss moment
+  is otherwise a churn trigger at peak engagement.
+- **Personalization & progressive profiling — BP-143..144**: split the ask
+  across sessions, derive what can be derived, never re-ask what is known;
+  personalization shown with its reason, correctable in one tap, with the
+  unpersonalized path still reachable.
+- **Trend governance — BP-145..146**: BP-001 applied to looks — a trend is
+  adopted through its mechanism, its identity fit, its accessibility and
+  weight cost, and a review date, recorded in the style pack rather than in
+  one screen; styles with documented debt (neumorphic surfaces, deliberate
+  anti-design, unconventional navigation, immersive 3D) ship only with the
+  compensation named, and the audit checks the compensation in the built UI.
+- Six source keys — **[WebAIM]**, **[HTTPArchive]**, **[CSq]**,
+  **[A11yLaw]**, **[WSG]**, **[SDT]** — plus an explicit note that
+  vendor-published "state of" survey figures are directional only and never
+  a practice's sole justification.
+
+### Changed
+- `practice-selection.md`: two new profile dimensions (personalization,
+  engagement mechanics); motion, look, weight, responsiveness and
+  accessibility routed from the profile; five new per-artifact rows
+  (animated/scroll-driven surface, responsive layout pass, accessibility
+  pass, gamified/streak surface, personalized/adaptive surface).
+- `ux-design-principles.md`: accessibility, motion behavior and
+  responsiveness are specified in the chain, in text, before the UI exists;
+  two anti-patterns added (a look adopted with no mechanism or review date;
+  treating accessibility, motion or weight as post-build polish).
+- `ux-audit`: the practice pass now verifies in code the four things that
+  fail silently — the reduced-motion branch and content-without-effects, the
+  weight budget, narrow-viewport/zoom reflow and hover-only affordances, and
+  ARIA sitting only where no native element says it. An accessibility claim
+  backed by a scanner alone is BLOCKED, not PASS.
+- `visual-identity.md`: motion floors and trend adoption added to the
+  division of labor — the pack picks the values, super-ux decides whether the
+  floors apply and whether the trend is adopted at all; the audit checks the
+  BP-146 compensation in the built UI.
+- `component-guidelines.md`: the cross-platform stance now states the
+  native-element-first rule ahead of the ARIA APG patterns.
+- Existing entries updated with field prevalence and cross-links: BP-054
+  (points to the motion system), BP-055 (checkout-rebuild yield, defers to
+  BP-143), BP-058 (points to the weight budget), BP-059 and BP-081 (the
+  ~95% failure rate and low contrast as the single most common defect),
+  BP-077 (points to progressive profiling).
+
+## 0.25.0 — 2026-07-29
+
+The catalog knew how to sell inside an app and almost nothing about selling
+on the web. Two funnels were missing: web-to-web (landing → pricing →
+checkout → recurring billing → cancel) had only generic form advice, and
+web2app was a single entry (BP-078) stating the economics with none of the
+design work. Both are now full sets, and the chain routes to them from the
+foundation's purchase surface.
+
+### Added
+- **Web funnels — BP-116..123** (`best-practices.md`): one promise from ad to
+  landing to first product screen; one page, one job, with proof beside each
+  CTA rather than in a bottom section most visitors never reach; pricing page
+  as three tiers with one visibly recommended and annual framed in absolute
+  money; signup asking the smallest identity that unblocks value (card only
+  when the trial is deliberately opt-out); total price — currency, tax, fees —
+  shown before the last step, wallets above the card form; abandonment as a
+  designed branch with surviving state and a resume link, not a leak; dunning
+  as a UX surface (pre-expiry notice, one-tap in-product card update, retries
+  that end in a real message); cancel self-serve and honest with exactly one
+  save offer.
+- **Web-to-app funnels — BP-124..129**: the web funnel replaces onboarding,
+  not just the paywall; the paid handoff is a first-class scenario with its
+  failure branches (wrong account, mail never arrived, purchase not yet
+  propagated, second device, refunded) — a paying user must never meet a
+  paywall; context carried across the store gap by deferred deep link with a
+  deliberately designed magic-link fallback; storefront rules as a per-region
+  variable re-checked each ship (US external links after the April 2025
+  ruling, entitlement elsewhere, EU its own regime, IAP as fallback); the tax,
+  SCA, refund and invoice duties the store used to absorb; and one funnel
+  measured web session → purchase → install → activation, not stopping at the
+  sale.
+- Two source keys — **[CRO26]** (Baymard checkout research, ChartMogul/Paddle
+  trial and failed-payment data, landing/pricing-page A/B aggregations) and
+  **[W2A26]** (RevenueCat/Adapty/Superwall funnel benchmarks, Apple/Google
+  storefront policy after the 2025 US anti-steering ruling) — with an explicit
+  note that their figures are industry aggregates the product's own numbers
+  overrule.
+- Tag taxonomy: `billing`, `cancel` (stage), `landing-page`, `web2app`
+  (domain).
+
+### Changed
+- **`practice-selection.md` routes to the new sets.** New profile dimension
+  **Purchase surface** (none / IAP / web checkout / web2app); Step-2 mandatory
+  sets for web-direct money products (BP-116..123), for any off-store purchase
+  (BP-127, BP-128) and for web2app (BP-124..126, BP-129); Step-3 checklists
+  for landing/campaign page, web pricing page, abandonment recovery, dunning,
+  and the web2app funnel + paid handoff, with the existing forms/checkout and
+  cancel rows extended.
+- **The foundation now declares where the money is taken.** `Purchase surface`
+  added to the Monetization section (`scenario-format.md`,
+  `templates/foundation.md`, `ux-foundation` skill and Cursor rule); money
+  moments now name checkout, failed payment and cancel; when the surface is
+  web or web2app, the web funnel and the paid handoff are flows of this
+  product, held to the same rigor as in-app screens (`ux-flows`,
+  `ux-scenarios` completeness checklists and Cursor rule).
+- Plugin/marketplace descriptions de-numbered again — a practice count had
+  crept back in and gone stale; they now say "a tag-indexed best-practices
+  catalog". README says 129 and names the two new areas.
+
+## 0.24.0 — 2026-07-29
+
+Checked what the plugin claims about Figma against the official Figma MCP's
+actual tools and their contracts. Several instructions would have failed.
+
+### Fixed
+- **The MCP gates its own tools behind guidance skills, and super-ux ignored
+  two of the three gates.** `use_figma` requires `/figma-use` first,
+  `create_new_file` requires `/figma-create-new-file`, `get_design_context`
+  requires `/figma-design-to-code` — skipping them is the server's documented
+  cause of hard-to-debug failures. Only the first was mentioned, and only in
+  one step of the design loop; the preflight told the agent to call
+  `create_new_file` and Improve mode to call `get_design_context` with no gate
+  at all. All three are now stated where the call is made, with the
+  `skill://figma/<name>/SKILL.md` fallback for setups without the slash
+  commands.
+- **"Create a Figma file" was an unrunnable instruction.** `create_new_file`
+  needs a plan key (from `whoami`, asking the user when there are several
+  teams/orgs) and an `editorType`; neither was mentioned.
+- `generate_figma_design` was listed as a plain alternative for mockups. It is
+  narrower than that — the server's own guidance reserves it for capturing a
+  *web app* page pixel-perfect the first time, run beside `use_figma`; for
+  non-web and from-scratch design, `use_figma` only. Stated as such, and as
+  "where the setup exposes it", since not every install has it.
+
+### Added
+- **A tool map in `figma-integration.md`** — need → tool, for the whole
+  surface the chain actually touches: writes (`use_figma`), structure reads
+  (`get_metadata`), implementation reads (`get_design_context`), screenshots,
+  variables (`get_variable_defs`), libraries, assets
+  (`download_assets` / `upload_assets`), Code Connect, and FigJam. Explicitly
+  a map, not a contract: a missing tool degrades to what is there, and the
+  agent never invents a call. Plus how `node-id` and `fileKey` come out of the
+  links `screens.md` already stores.
+- **Drift checks that use the cheap tool.** Frame existence and naming are
+  verified with `get_metadata` (ids, names, types, sizes — no full design
+  context needed), in both directions: a listed state without a frame, and a
+  frame whose `SCR-ID`/state is in no `screens.md` row.
+- **Token parity is now checkable, not assumed.** `get_variable_defs` reads
+  what a frame actually references, so "built on the style pack's tokens"
+  becomes a verdict with evidence — a frame full of raw hexes is the
+  design-side twin of hard-coded colors in code.
+
+## 0.23.2 — 2026-07-28
+
+Open-source hygiene pass — the repo is public, so the files a first-time
+contributor looks for now exist.
+
+### Added
+- `SECURITY.md` — what the skill and its installer actually run (two `claude`
+  calls, explicit argv, no network from the linter), what they write, and private
+  reporting.
+- `CODE_OF_CONDUCT.md` and a pull-request template that asks for the command
+  output rather than a "tests pass" claim.
+- README now points at the security policy and the code of conduct alongside
+  contributing.
+
+## 0.23.1 — 2026-07-28
+
+### Changed
+- Consistent American spelling across every agent-facing file (`labour` →
+  `labor`, `honour` → `honor`, `neighbouring` → `neighboring`) — the docs
+  were mixing both, which reads as sloppy in a repo whose whole pitch is that
+  small inconsistencies compound.
+- Reflowed three paragraphs left ragged by the previous pass's mechanical
+  edits (`figma-integration.md` intro, the `ux-flows` build gate), and the
+  build gate now names the style pack alongside the chain and the Figma
+  mockups.
+
+## 0.23.0 — 2026-07-28
+
+Production pass over the public repo: every file read again, the remaining
+contradictions fixed, and the front door rewritten for people who have never
+seen this project.
+
+### Fixed
+- **The hard rule described a three-layer chain.** The most-copied text in the
+  project — the rule installed into every `CLAUDE.md`, the always-on Cursor
+  rule, the README, `/ux-rule`, the `ux-flows` build gate — said
+  "foundation → flows → scenarios" while `screens.md` has been a first-class
+  layer with its own same-change rule since 0.16.0. All five copies now say
+  foundation → flows → **screens** → scenarios.
+- **`ux-foundation` didn't know about a section it owns.** The contract gives
+  `foundation.md` a Design tooling block (Figma on/off + file URL), but
+  neither the skill nor its Cursor rule ever mentioned it, so the field was
+  only ever filled by whoever happened to read the template. Both now cover it
+  — and state that everything else visual (design system, style pack, frame
+  links) belongs to `screens.md`.
+- The README's mermaid diagram used `\n` for line breaks, which GitHub renders
+  literally; it is `<br/>` now — and the diagram shows the current chain
+  (foundation → flows → screens → scenarios → build → audit → plan) instead of
+  the pre-flows one.
+- `/ux`'s own description advertised "foundation/scenarios/audits"; menu item 3
+  said "design user flows" without mentioning that it also registers screens.
+  Inspect now also reports unexecuted plans in `docs/ux/plans/`.
+- `ux-flows` Design had visual identity, wireframes, and Figma crammed into one
+  numbered step; identity is now its own step, before anything gets drawn.
+
+### Added
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — repo layout (including *why* the
+  contracts are duplicated per skill), the edit → sync → validate loop, the
+  conventions, how to test a change from a packed tarball rather than the
+  working tree, and the release checklist.
+- Issue templates for bug reports and ideas, both asking for the thing that
+  actually resolves a report: the file that says otherwise, and the check that
+  would fail.
+- Validator check: the plugin description in `marketplace.json` must equal the
+  one in `plugin.json` — the ecosystem requires both copies, so the duplication
+  gets a check instead of trust.
+- `package.json` gains a `bugs` URL; `.gitignore` covers `npm pack` tarballs.
+
+### Changed
+- **README restructured for a first-time reader**: what goes wrong and what
+  super-ux does about it, the chain diagram, what you get, quick start per
+  channel, the hard rule, the typical cycle, companions, then the internals
+  (skills, commands, and a second table for the contracts). Value first,
+  reference last.
+- Manifest descriptions rewritten to describe the current system — the whole
+  chain, the four skills, the linter, and the style pack — instead of the
+  0.17-era feature list.
+- The historical `docs/superpowers/` spec and plan carry a banner marking them
+  as v0.1.0 provenance, with pointers to the live contract; they described two
+  skills and four commands and are not maintained.
+
+## 0.22.0 — 2026-07-28
+
+### Added
+- **The visual layer has an owner: the `sheleg-design` companion.** super-ux
+  decided what every screen must contain and which craft floors it had to
+  clear, then left the actual look to be invented frame by frame — the visual
+  half of the drift this system exists to prevent. New reference
+  [`visual-identity.md`](plugins/super-ux/skills/references/visual-identity.md)
+  makes one **style pack** the identity for the whole product: picked with the
+  sheleg-design skill (`workbench` for product UI, dashboards and tools;
+  `instrument-console`; `editorial-luxury`; or a new pack authored on its
+  contract), recorded once, obeyed everywhere. A cinematic scroll-driven
+  landing also takes that skill's motion methodology.
+- **`Style pack` field** in `screens.md` → Design system (contract + template).
+  One owner per fact: the pack is named there and referenced from everywhere
+  else, with its token file location beside it.
+- **Wired into every design entry point** — `ux-flows` Design (before a frame
+  is drawn, not after), `/ux` step 0 beside the Figma question, `/ux-flows`,
+  the Figma design loop (pack tokens become the Figma variable collections),
+  the Cursor `ux-flows` rule, the hard rule in `templates/claude-rule.md` and
+  `/ux-rule`, and the seeded `docs/ux/README.md`.
+- **Audited like any other record.** When a `Style pack` is recorded, the deep
+  audit's practice pass checks the built UI honors it — tokens referenced
+  instead of raw values, the pack's bans respected, dark mode from its twin;
+  a screen ignoring the recorded pack is `drifted`. No pack and an improvised
+  visual layer → the companion is suggested once, as an opportunity finding.
+- Validator guard: the hard rule embedded in `/ux-rule` must be byte-identical
+  to `templates/claude-rule.md`. They had already drifted apart in wording —
+  two copies of a rule is the exact failure the plugin preaches against.
+
+### Changed
+- Recommendation, not dependency, in both directions: one offer with its
+  one-time install, then the user's answer stands and the chain continues on
+  platform defaults. A project that already has a design system records that
+  instead — two identities are worse than any one.
+- Conflict rule stated where both sides live (`practice-selection.md`,
+  `ux-design-principles.md`): the style pack owns identity and wins on look;
+  BP-079..090 are floors (contrast, tap targets, line length, spacing rhythm)
+  and win on safety. The conflict and its resolution go in the compliance
+  table.
+- README gains a Companions table (sheleg-design at VISUALIZE/BUILD,
+  task-pipeline after a plan) and the hard rule gains its style-pack bullet.
+
+## 0.21.0 — 2026-07-28
+
+Full-repo consistency pass: every file read, every contradiction between the
+contract, the skills, the Cursor rules, the templates, and the tooling fixed.
+
+### Fixed
+- **`npx super-ux --cursor` crashed for every npm user.** `package.json`
+  `files[]` never shipped `plugins/super-ux/scripts/ux_lint.py`, so the CLI
+  installed the rules and templates and then died with an ENOENT stack trace
+  while copying the linter (reproduced against a packed 0.20.0 tarball). The
+  script is now in `files[]`, and a missing linter degrades to a warning with
+  a download link instead of a crash.
+- **The linter mis-read story priorities.** `ST-NNN` bodies were scanned with
+  a fixed 600-character window, so a neighboring story's `**Priority:**`
+  line leaked into the previous story and produced false "must/should story
+  has no scenario" warnings. The scan now stops at the next heading.
+- **The UX-plan example rendered broken.** The `` ```markdown `` block in the
+  contract contained a nested three-backtick fence, which closed the outer
+  block early and inverted the rest of the section; it is a four-backtick
+  fence now.
+- Duplicate `refs(flows, "SCR")` computation in the linter collapsed into one.
+- `release.yml` referenced a `pipeline.example.json` path that does not exist
+  in this repo and installed `jsonschema` the stdlib-only validator never
+  used.
+
+### Changed
+- **One owner per fact:** `**Design system:**` is gone from `foundation.md` →
+  Design tooling (it contradicted `screens.md`, `figma-integration.md`, and
+  the templates). Foundation records the Figma on/off choice and the file
+  URL; `screens.md` → Design system records the library, tokens, components,
+  and assets. `figma-structure.md` and `system-map.md` say the same thing.
+- Cursor rules resynced with ux-contract v4: `ux-flows` documented a stale
+  `Screens & states` table (it is `Screens traversed` + the `screens.md`
+  entry shape); `ux-scenarios` was missing the `Alt paths` field and the
+  monetization entries of the per-product checklist; `ux-audit` said "git SHA
+  of scenarios.md" (the contract says `docs/ux`) and never mentioned
+  flow/screen conformance or the `coverage` scope; `super-ux` told Cursor
+  users to run `/ux-lint`, a Claude-Code-only command.
+- `/ux` reports every layer (it said "all three"); `/ux-init` is incremental —
+  existing layers are left untouched and only the missing ones initialized,
+  instead of talking about "both files" from a two-file era; README no longer
+  says the skills CLI installs "both skills".
+- `docs/ux/plans/` is created by the installers, `/ux-rule`, and `/ux`
+  alongside `audits/` — the contract has required the directory since v4.
+- `install.sh --help` described seeding one file; it seeds the whole skeleton
+  plus the linter. README's Development section documents the four-way
+  version sync and the `sync_references.py` step.
+
+### Added
+- Validator check: every asset `bin/super-ux.js` copies must be covered by
+  `package.json` `files[]`, parsed from the CLI source rather than a
+  hand-kept list — the packaging regression above cannot come back silently.
+- `templates/flows.md` carries the contract's `Wireframe` field.
+
+## 0.20.0 — 2026-07-28
+
+### Changed
+- Skill descriptions restructured English-first: every Russian trigger now sits
+  beside its English equivalent (`"user flow" / "юзер флоу"`) instead of forming
+  a Russian-only tail, and the `/ux` routing table follows the same pairing.
+- README is English-only: the Russian section is gone, replaced by a plain
+  statement of what the skill gives you and an author/links block.
+
+### Added
+- Validator enforces the three description canon rules on every skill —
+  `Use when` opening, Russian trigger aliases present, front-matter under 1024
+  characters. Twelve new checks; all four skills pass.
+
 ## 0.19.0 — 2026-07-25
 
 Review pass — the contracts were not reaching non-Claude agents.