super-ux 0.7.0 → 0.17.1

package/CHANGELOG.md

@@ -4,6 +4,273 @@ All notable changes to this project are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.17.1] - 2026-07-23
+
+### Fixed
+
+- Manifest descriptions no longer hardcode a practice count ("100" was
+  already stale at 115) — they now say "a tag-indexed best-practices
+  catalog + PRN heuristics + component guidelines", so the catalog can grow
+  without a description bump.
+
+## [0.17.0] - 2026-07-23
+
+### Added
+
+- **Component & control guidelines** (`references/component-guidelines.md`)
+  + 15 practices (BP-101..115) from verified design systems (Apple HIG,
+  Material Design 3, W3C ARIA Authoring Practices Guide, GOV.UK Design
+  System): a "which control for the job" decision table (radios vs
+  checkboxes vs select, switch vs checkbox, action sheet vs alert, modal vs
+  disclosure, combobox, bottom nav vs rail, FAB budget, dates, toasts) plus
+  platform rules (one-primary/never-destructive-primary, focus-trap+ESC+
+  return for modals, APG combobox roles/keys, every-control-ships-all-states)
+  and the "use the platform component of record" stance. Taxonomy gains a
+  Components group; practice-selection routes every graphical UI to
+  BP-101..115; wired into `ux-flows` screen registration, the principles
+  doc, and the system map.
+
+## [0.16.2] - 2026-07-23
+
+### Fixed
+
+- Marketplace/plugin descriptions now reflect the full system (flows, the
+  screens.md UI map with Figma frames, the linter, the practice catalog) —
+  they had lagged at the foundation/scenarios/audit-only wording.
+
+## [0.16.1] - 2026-07-23
+
+### Fixed
+
+- Consistency pass across all docs: unified every contract stamp to
+  `ux-contract v4` (were mixed v2/v3/v4); added the `screens.md` MAP step
+  and Figma mockups to the pipeline in `ux-design-principles.md` (8 steps,
+  aligned with the v4 chain); `practice-selection.md` now spans the full
+  catalog (BP-001..100) and routes Figma-enabled products to BP-091..100;
+  README reflects 100 practices and links the Figma references. No
+  behavioral change — documentation coherence only.
+
+## [0.16.0] - 2026-07-23
+
+### Added
+
+- **Figma file-structure guide** (`references/figma-structure.md`) + 10
+  practices (BP-091..BP-100) from verified sources (Figma Best Practices,
+  Figma Learn, Design Systems Collective's 2025/26 Variables playbook,
+  zeroheight): cover+index pages, one page per flow, **frames named
+  `SCR-NN/<Screen>/<state>` to match `screens.md` exactly** (deterministic
+  lookup, checkable drift), purpose-based code-matched naming, variables as
+  three-tier tokens (primitive → semantic → component) with modes,
+  variants-for-states vs components-for-objects, auto layout everywhere,
+  build-on-the-library, layer hygiene, one-convention-plus-an-owner
+  governance. Taxonomy gains `figma`/`design-system`/`handoff`/
+  `maintainability`. Wired into `figma-integration.md`, the `ux-flows`
+  design loop, and the system map.
+
+## [0.15.0] - 2026-07-23
+
+### Added
+
+- **Deterministic linter** (`plugins/super-ux/scripts/ux_lint.py`, seeded
+  into projects as `docs/ux/lint.py`, run via `/ux-lint` or
+  `python3 docs/ux/lint.py`) — turns the prose rules into a check that
+  fails: missing Figma frames per screen state (when Figma enabled),
+  flows referencing non-existent `SCR-IDs`, unresolved scenario traces,
+  must/should stories without scenarios, `built` screens without coverage,
+  index↔entry desync, duplicate/gapped IDs, orphan screens, broken relative
+  links. Stdlib-only, tolerant parsing (strips HTML comments so template
+  examples never false-positive), exit codes 0/1/2, `--strict`. Wired into
+  the hard rule, `/ux` inspect, and every skill's "run the linter after
+  changes" pointer; recommended for CI/pre-commit.
+- **System map** (`references/system-map.md`) — the whole pipeline, files,
+  skills, and the four sync rules (chain-first, same-change, no-drift,
+  run-the-linter) on one page; every SKILL.md opens with a pointer to it so
+  an agent entering from any trigger sees the whole system. A project-facing
+  copy (`templates/README.md` → `docs/ux/README.md`) is seeded too.
+- Installers (`install.sh`, `bin/super-ux.js`), `/ux-rule`, and `/ux`
+  repair now seed `docs/ux/README.md` and refresh `docs/ux/lint.py`. The
+  plugin validator compiles the linter.
+
+## [0.14.0] - 2026-07-23
+
+### Added
+
+- **UI Screen Registry** (`docs/ux/screens.md`, ux-contract v4) — the
+  canonical design map: one entry per screen with a stable `SCR-NN` id,
+  every state (loading/empty/error/success) carrying its own Figma frame
+  link, plus wireframe, code coverage, scenarios touching it, related
+  UX/UI resources (components, tokens, assets, data deps), and a Status
+  (designed → built → drifted → retired). A Design system block records the
+  Figma library and where tokens/components/assets live in code. Flows now
+  reference screens by `SCR-ID` instead of duplicating specs, so a screen
+  used by many flows is described once.
+- **Same-change update rule extended to the UI**: any interface change must
+  update `screens.md` (and, when Figma is enabled, the Figma frame plus its
+  link) in the same change; code diverging from a screen's record or a
+  stale/broken Figma link is a `drifted` finding. Wired into the hard rule
+  (template, /ux-rule, super-ux.mdc, README), `ux-flows` Update, and
+  `/ux-update`.
+- **Audit drift + coverage** now check code vs the screen registry (states
+  rendered, elements present, coverage accurate → `drifted`), Figma-link
+  presence per state, and registry orphans (screens unused by flows, flows
+  referencing missing SCR-IDs).
+- `ux-flows` owns and maintains `screens.md`; templates, installers
+  (`install.sh`, `bin/super-ux.js`), `/ux` skeleton, and `/ux-rule` seed it.
+
+## [0.13.0] - 2026-07-23
+
+### Added
+
+- **Figma design integration** (`references/figma-integration.md`), an
+  opt-in surface enabled by default: the agent asks once at the start of
+  design whether to mock up in Figma; if yes and the Figma MCP isn't
+  connected it recommends connecting it (never blocks — degrades to
+  markdown + wireframes and syncs later); records the Figma file in
+  `foundation.md` → Design tooling before drawing; during `ux-flows` Design
+  mirrors every screen-state into a Figma frame applying the visual-craft
+  practices (BP-079..090) as hard constraints; **every screen row carries
+  its Figma frame deep-link** (flows.md Screens & states gains a Figma
+  column) — a screen without a frame link is an incomplete-design finding.
+- **Explicit build gate** in the hard rule (templates/claude-rule,
+  /ux-rule, super-ux.mdc, README, ux-flows DoD): do NOT write interface
+  code until the UX workflow is done — chain designed and approved, and
+  (Figma on) the UI mocked up with every screen linked. Stated plainly to
+  the user, who is not expected to know the internals.
+- Foundation gains a Design tooling section; `/ux` step 0 asks the Figma
+  question for design tasks; `/ux-flows` and the Cursor flow rule updated.
+
+## [0.12.1] - 2026-07-23
+
+### Fixed
+
+- Consistency audit across all documents: `templates/scenarios.md` and
+  `templates/audit-report.md` brought up to ux-contract v3 (Traces column,
+  action→response steps, Alt paths; Depth/passes header, Context line,
+  Practice compliance section); hard-rule text unified across
+  `templates/claude-rule.md` and `/ux-rule` (chain wording, all four
+  skills, `/ux` entry point; `/ux-rule` now replaces outdated rule blocks);
+  `/ux-update` routes feature ideas through the full chain and cascades to
+  flows; Cursor `ux-scenarios` rule Index gains Traces; README practice
+  count corrected to 90 and hard-rule section aligned; installers
+  (`install.sh`, `bin/super-ux.js`, `/ux` repair, `/ux-rule`) now seed all
+  three templates (scenarios, foundation, flows), never overwriting.
+
+## [0.12.0] - 2026-07-23
+
+### Added
+
+- **Visual craft in the catalog** (BP-079..BP-090): body-text baseline
+  (16px / 1.5 line height / 45–75 CPL, target ~66 — Baymard, USWDS, Dyson &
+  Haselgrove research chain), single type system (≤2 faces, 1.3–1.6×
+  heading scale), contrast floors with softened extremes (WCAG 4.5:1, no
+  harsh #000-on-#FFF), 60-30-10 palette with one scarce accent, semantic
+  colors as a contract (never repurposed, never color-only), dark mode as a
+  designed palette (gray surfaces, desaturated accents, tonal elevation),
+  4/8pt spacing grid with proximity-as-grouping, whitespace-as-hierarchy,
+  single-grid alignment, tabular figures for data, microcopy rules (verbs,
+  sentence case, stable action names), decoration subtraction. New tag
+  group "Visual craft".
+- Selection protocol: "any graphical UI" mandatory set (BP-079..090) +
+  artifact rows for screen build/polish, reading surfaces, data tables.
+
+## [0.11.0] - 2026-07-23
+
+### Added
+
+- **Practice Selection Protocol** (`references/practice-selection.md`) —
+  the deterministic bridge between the catalogs (BP-001..078, PRN-01..16)
+  and the design/audit functions: product profile (platform, money model,
+  distribution, acquisition, forms, analytics) → mandatory consideration
+  sets → per-artifact checklists (onboarding, paywall, upgrade-at-limit,
+  trial, winback, rating prompt, forms, navigation, permissions,
+  lifecycle, voice/chat, empty states, store listing, experiments) →
+  compliance table with verdicts applied/adapted/rejected(reason)/
+  deferred(trigger)/missing. No silent skips; no cargo-culting
+  (consideration is mandatory, adoption only when a traced job is served);
+  user-owned rejections recorded and not re-litigated.
+- **Design function**: `ux-flows` Design gains a mandatory Practice pass —
+  compliance table attached to every flow entry before approval.
+- **Audit depth levels**: `quick` (scenarios), `standard` (+ flow
+  conformance, default), `deep` (+ heuristic pass, practice pass via the
+  protocol, chain coverage) — five ordered passes; report format gains
+  Depth and a Practice compliance section.
+
+## [0.10.0] - 2026-07-23
+
+### Added
+
+- **Monetization economics in the catalog** (BP-067..BP-078, sourced from
+  RevenueCat State of Subscription Apps 2025, OpenView/ProductLed 2025
+  benchmarks, converged ASO 2025 guidance): model choice with data (hard
+  paywall ~5× freemium download-to-paid; hybrid beats subscription-only),
+  first-session paywall placement (>80% of trials start day 0), trial
+  design levers (opt-out ~31% vs opt-in ~9%; 17–32-day trials ~46% only
+  with engagement), the 14-day conversion window, activation before
+  monetization pressure, visible value-metric freemium boundaries,
+  upgrade-at-limit triggers, store listing as onboarding screen zero
+  (screenshots move conversion 20–35%), the 4.0+ rating loop,
+  ad→listing→onboarding coherence, web-to-app funnels.
+- **Monetization as a foundation layer**: `foundation.md` gains a
+  Monetization section (model + reason, value metric, free boundary, money
+  moments, acquisition coherence); money moments become first-class flows
+  (paywall, upgrade-at-limit, trial start/end, cancel/winback, rating
+  prompt); per-product scenario checklist extended accordingly;
+  `ux-foundation` interview asks how the product earns.
+
+## [0.9.0] - 2026-07-23
+
+### Added
+
+- **Catalog expansion from verified sources** (BP-049..BP-066, 18 entries):
+  mobile interfaces (thumb-zone placement, platform tap-target sizes with
+  the WCAG 2.2 24px floor, gesture affordances, visible navigation, current
+  platform design languages — Apple HIG/Liquid Glass 2025, Material 3
+  Expressive — motion-as-feedback); web apps & forms (Baymard-backed field
+  minimization, guest-first flows, address automation, INP ≤200ms feedback
+  budgets, WCAG 2.2 AA baseline); voice & conversational (tiered
+  confirmations, echo-what-was-heard error recovery, barge-in, deviation
+  tolerance, multimodal pairing, short latency-cued turns, honest AI
+  limits). Tag taxonomy extended: voice, ai-chat, web, android, forms,
+  checkout, navigation, accessibility, performance, feedback,
+  error-recovery.
+- **Plain-language routing in `/ux`**: the user never needs to know skills
+  or layers — step 0 asks one everyday-words question (or reads
+  `$ARGUMENTS`) and maps intent to the right workflow via a routing table;
+  README gains a "one command, plain words" section.
+
+## [0.8.0] - 2026-07-23
+
+### Added
+
+- **ux-flows skill** — the HOW layer (`docs/ux/flows.md`): task analysis →
+  mermaid user flows (screens, explicit branches, recoverable error edges,
+  all entry points) → screen/state tables → optional ASCII wireframes and
+  storyboards. Workflows: Design (forward), Reverse (backwards mode for
+  existing products, `inferred` tags with file:line evidence), Update,
+  Improve (heuristic evaluation → traced before/after redesign proposals).
+- **ux-design-principles.md** — the agent's thinking playbook: the 7-step
+  pipeline (research → define → structure → specify → visualize → build →
+  verify) with forward and backwards modes, task-analysis method, flow and
+  screen rules, heuristics PRN-01..10 (after Nielsen) and cognitive
+  principles PRN-11..16 with audit questions, the improvement procedure,
+  wireframe/storyboard conventions, anti-patterns.
+- **ux-contract v3** — scenarios become use cases: steps as `user action ->
+  system response`, new `Alt paths` field, `Traces` includes `FLW-NN`;
+  traceability now covers flows (every node and edge needs a scenario).
+- `ux-audit`: verifies code against flow diagrams (nodes reachable, edges
+  wired, states present); new `heuristics` scope (`[PRN-NN]` findings).
+- `/ux-flows` command; `/ux` menu grows to 11 actions including "Improve
+  existing UX"; `/ux-init` now chains foundation → flows → scenarios.
+- **UX plans** (`docs/ux/plans/YYYY-MM-DD-<scope>.md`) — the actionable
+  output of audits and Improve passes: target interface per affected screen
+  (elements, one primary action, states, behavior notes) + a
+  CREATE/MODIFY/DELETE change table where every row traces to
+  scenario/flow/finding/principle IDs, prioritized by Frequency × Severity
+  × Solvability, with a Definition of Done and an autonomous-execution
+  handoff (task-pipeline plugin if installed, else superpowers
+  writing-plans). Plans are written to be executable without the
+  originating conversation.
+
 ## [0.7.0] - 2026-07-20
 
 ### Added

package/README.md

@@ -33,13 +33,19 @@ flowchart LR
 | Piece | Purpose |
 |---|---|
 | skill `ux-foundation` | The WHY layer (`docs/ux/foundation.md`): personas, Jobs to Be Done with forces, customer journey maps, user stories with Given/When/Then acceptance criteria |
-| skill `ux-scenarios` | Maintain `docs/ux/scenarios.md`: scenarios derived from stories/journeys with `Traces:`, updated on every change, validated for conflicts, coverage, and traceability |
+| skill `ux-flows` | The HOW layer + UI map: `docs/ux/flows.md` (task analysis, mermaid user flows referencing screens) and `docs/ux/screens.md` — the design map: every screen and state with its **Figma frame link**, wireframe, code coverage, scenarios, and resources, kept in sync on every interface change (default-on Figma mockups apply the visual-craft practices); heuristic UX evaluation and traced redesign proposals |
+| skill `ux-scenarios` | Maintain `docs/ux/scenarios.md`: use-case scenarios (action → system response, alt paths) covering every flow node/edge, `Traces:` to stories and flows, validated for conflicts, coverage, and traceability |
 | skill `ux-audit` | Batched audit loop with full context: code vs every scenario + its story's acceptance criteria; verdicts PASS/PARTIAL/FAIL/BLOCKED with `file:line` evidence; `coverage` scope audits the chain itself |
 | `/ux` | **The one command**: sets up whatever is missing, then status across all layers + a menu of applicable actions with one recommended default. Idempotent |
-| `/ux-foundation` `/ux-init` `/ux-update` `/ux-audit` `/ux-rule` | Direct controls; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
+| `docs/ux/lint.py` + `/ux-lint` | Deterministic linter: missing Figma frames, unresolved SCR/story traces, orphans, built screens without coverage, index desync, ID gaps, broken links — run after changes and in CI so drift can't merge |
+| [system-map.md](plugins/super-ux/skills/references/system-map.md) | The whole system on one page — pipeline, files, skills, and the four sync rules; every skill points here |
+| `/ux-foundation` `/ux-flows` `/ux-init` `/ux-update` `/ux-audit` `/ux-rule` `/ux-lint` | Direct controls; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
+| [ux-design-principles.md](plugins/super-ux/skills/references/ux-design-principles.md) | How the agent thinks: the design pipeline (forward + backwards), task analysis, flow rules, heuristics PRN-01..16, improvement procedure, anti-patterns |
 | `cursor/rules/*.mdc` | The same methodology for Cursor (always-on hard rule + three agent-requested rules) |
 | `templates/` | Skeletons for the foundation, scenario base, audit report, and the CLAUDE.md rule snippet |
-| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of proven UX/growth practices (seeded with 48 subscription-app laws); agents filter by stage/domain tags and apply what serves a traced job |
+| [component-guidelines.md](plugins/super-ux/skills/references/component-guidelines.md) | When to use which control (radios/select/switch, sheet/alert, modal/disclosure, combobox, nav bar/rail, FAB, dates, toasts) + platform rules — from Apple HIG, Material 3, W3C ARIA APG, GOV.UK (BP-101..115) |
+| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 115 proven UX/growth practices — subscription-app laws, mobile/web/voice interface guidance (HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries, web2app), visual craft (typography, color, spacing, microcopy), Figma file structure (BP-091..100); selected deterministically via [practice-selection.md](plugins/super-ux/skills/references/practice-selection.md) |
+| [figma-integration.md](plugins/super-ux/skills/references/figma-integration.md) · [figma-structure.md](plugins/super-ux/skills/references/figma-structure.md) | Optional Figma surface (default-on): when/how to mock up, and how to structure the file so frames named `SCR-NN/<Screen>/<state>` map 1:1 to `screens.md` — deterministic lookup, checkable drift |
 
 The format all of them share is locked in
 [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md):
@@ -49,11 +55,21 @@ lifecycle, audit verdicts and severities.
 
 ## The hard rule
 
-- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
-- Any change touching user-facing behavior updates the scenario base **in the
-  same change**.
-- Any new feature or project **starts** with scenarios: draft, validate
-  against the existing base, approve — only then design and build UI.
+- `docs/ux/scenarios.md` is the source of truth for all user-facing
+  behavior; foundation (WHY) and flows (HOW) are the layers it traces to.
+- Any change touching user-facing behavior or interface updates **in the
+  same change**: scenarios, affected flows, the affected screens in
+  `docs/ux/screens.md` (the UI map — states, elements, coverage), and (Figma
+  on) the Figma frames plus their links. Code that diverges from a screen's
+  record, or a stale Figma link, is drift the audit flags.
+- Any new feature or project **starts** with the chain: which job, which
+  journey stage, which story — then flows and scenarios, validated and
+  approved.
+- **Do not write interface code until the UX workflow is done first** — the
+  foundation → flows → scenarios chain designed and approved, and (when
+  Figma is enabled, the default) the UI mocked up in Figma with every screen
+  linked to its frame. Building UI before this is the mistake super-ux
+  exists to prevent.
 
 ## Install
 
@@ -105,6 +121,15 @@ three rules into `.cursor/rules/` and seeds `docs/ux/scenarios.md`. An
 existing scenario base is never overwritten; re-run with `--force` to update
 rules after a new release.
 
+## For the user: one command, plain words
+
+You don't need to know the layers or skills. Run `/ux` and say what you
+want in your own words — "стартуем новый продукт", "добавить фичу", "UX
+неудобный, улучши", "проверь что всё работает", "что чинить в первую
+очередь". The agent asks at most one clarifying question, picks the right
+workflow itself, and only shows you human decisions (approve scenarios,
+pick a plan). Everything below this line is internals for the agent.
+
 ## Typical cycle
 
 1. `/ux` — first run sets everything up: foundation first (greenfield:
@@ -119,8 +144,10 @@ rules after a new release.
    batched verification of code vs scenarios (with acceptance criteria);
    `/ux-audit coverage` — chain gaps. Reports land in
    `docs/ux/audits/YYYY-MM-DD.md`.
-4. Findings become a prioritized fix plan (Frequency × Severity ×
-   Solvability) via your planning workflow; build; repeat.
+4. Findings become a concrete UX plan (`docs/ux/plans/…`): target interface
+   per screen + traced CREATE/MODIFY/DELETE change table, prioritized by
+   Frequency × Severity × Solvability — offered for autonomous execution
+   via task-pipeline (or your planning workflow); build; repeat.
 
 ## Development
 

package/bin/super-ux.js

@@ -74,14 +74,20 @@ function installCursor(target, force) {
     }
   }
 
-  const base = path.join(target, 'docs', 'ux', 'scenarios.md');
-  if (fs.existsSync(base)) {
-    console.log(`keep:    ${base} exists (never overwritten)`);
-  } else {
-    fs.mkdirSync(path.join(target, 'docs', 'ux', 'audits'), { recursive: true });
-    fs.copyFileSync(path.join(ROOT, 'templates', 'scenarios.md'), base);
-    console.log(`seed:    ${base}`);
+  fs.mkdirSync(path.join(target, 'docs', 'ux', 'audits'), { recursive: true });
+  for (const tpl of ['scenarios', 'foundation', 'flows', 'screens', 'README']) {
+    const dst = path.join(target, 'docs', 'ux', `${tpl}.md`);
+    if (fs.existsSync(dst)) {
+      console.log(`keep:    ${dst} exists (never overwritten)`);
+    } else {
+      fs.copyFileSync(path.join(ROOT, 'templates', `${tpl}.md`), dst);
+      console.log(`seed:    ${dst}`);
+    }
   }
+  // The linter is code, not a template — refresh it to the shipped version.
+  const lintDst = path.join(target, 'docs', 'ux', 'lint.py');
+  fs.copyFileSync(path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py'), lintDst);
+  console.log(`sync:    ${lintDst}`);
 
   console.log(`done: ${installed} installed, ${skipped} skipped`);
 }

package/cursor/rules/super-ux.mdc

@@ -13,8 +13,14 @@ alwaysApply: true
   coverage). New user-facing behavior with no scenario is a blocker, not a
   warning.
 - Any new feature or project STARTS with the chain: which job does it serve,
-  which journey stage, which story — then scenarios, validated against the
-  existing base (conflicts, overlaps, gaps), approved — only then design and
-  build UI. An idea serving no job is challenged, not silently accepted.
-- Workflows: `ux-foundation` rule (WHY layer), `ux-scenarios` rule
-  (scenario base), `ux-audit` rule (evidence-backed audits).
+  which journey stage, which story — then flows and scenarios, validated
+  against the existing base (conflicts, overlaps, gaps), approved. An idea
+  serving no job is challenged, not silently accepted.
+- Do NOT write interface code until the UX workflow is done first: the
+  foundation → flows → scenarios chain is designed and approved, and — when
+  Figma is enabled (default) — the UI is mocked up in Figma with every
+  screen linked to its frame. Building UI before this is the exact mistake
+  super-ux exists to prevent.
+- Workflows: `ux-foundation` rule (WHY), `ux-flows` rule (flows + Figma
+  mockups), `ux-scenarios` rule (scenario base), `ux-audit` rule
+  (evidence-backed audits).

package/cursor/rules/ux-audit.mdc

@@ -31,4 +31,9 @@ verdict BLOCKED with the exact reason. Never guess, never a courtesy PASS.
    verdicts with evidence, findings-register table.
 6. Update the base: `Last audit` = `YYYY-MM-DD VERDICT`; validated →
    implemented where PASSed. Do not edit scenario content during an audit.
-7. Offer (don't auto-run) to turn FAIL/PARTIAL findings into a work plan.
+7. With user's go-ahead produce `docs/ux/plans/YYYY-MM-DD-<scope>.md`:
+   target interface per affected screen (elements, states, behavior) +
+   CREATE/MODIFY/DELETE change table, every row traced to
+   scenario/flow/finding IDs, prioritized Frequency × Severity ×
+   Solvability. Then offer autonomous execution via the project's task
+   pipeline; the plan must be executable without the conversation.

package/cursor/rules/ux-flows.mdc

@@ -0,0 +1,56 @@
+---
+description: "Design or improve user flows (docs/ux/flows.md): apply for task analysis, flow diagrams, screen states, wireframes, heuristic UX evaluation, or any 'improve/fix the UX' request"
+alwaysApply: false
+---
+
+# ux-flows — Design HOW Users Move
+
+`docs/ux/flows.md` is the HOW layer between foundation (stories) and
+scenarios: task analysis + mermaid user flows referencing screens by
+`SCR-ID`. The canonical per-screen spec lives in `docs/ux/screens.md` — the
+UI map: every screen and state with its Figma frame, wireframe, code
+coverage, scenarios, and resources. IDs `FLW-NN`/`SCR-NN`, sequential, never
+reused. Any interface change updates `screens.md` (and the Figma frame when
+enabled) in the same change — a screen whose code diverges from its record
+is `drifted`.
+
+## Flow entry (ux-contract v4)
+
+Fields: `Traces` (story/job IDs), `Goal` (observable end state), `Entry
+points` (ALL of them), `Success exit`, `Task analysis` (numbered
+user-visible micro-steps), mermaid `flowchart` (screens as
+`Screen: <name>`, decisions as diamonds, `*_err` error nodes with labeled
+recovery edges), `Screens & states` table (each screen:
+loading/empty/error/success + key elements, one primary action).
+
+## Design rules
+
+- One flow = one user goal. Task analysis first: cut/merge/default-away
+  every step that doesn't serve the job; pull first value as early as
+  possible; happy path ≤5 steps or justified.
+- Every decision an explicit branch; every error edge lands on recovery —
+  dead ends are defects; all entry points enumerated.
+- Wireframes optional (`docs/ux/wireframes/FLW-NN.md`, ASCII hierarchy +
+  primary action, not pixels); storyboard only when usage context drives
+  design.
+- Figma mockups optional (default on): if the foundation's Design tooling
+  enables Figma and a Figma MCP is available, mirror each screen into a
+  frame applying visual-craft practices (BP-079..090), and link every
+  screen row to its frame; ask the user once at the start of design.
+- Backwards mode (existing product): reconstruct flows as they ARE from
+  code with file:line evidence, tag `inferred` until confirmed; gaps
+  between is/should become the improvement backlog.
+
+## Improving existing UX
+
+Walk flows against heuristics: system status visible; user's words not
+jargon; undo/cancel/back everywhere; consistency; error prevention over
+error messages; recognition over recall; shortcuts for frequent users;
+minimalist screens; recovery-oriented error text; help in context;
+progressive disclosure; smart defaults; limited choices; familiar
+patterns; prominent primary targets; polished peaks and endings.
+
+Violations: `[PRN-NN] node — issue — severity`. Redesign proposals MUST
+trace to a pain/job/story, cite the principle/practice, show flow
+before → after, and state the expected observable effect. Prioritize
+Frequency × Severity × Solvability. Cascade approved changes to scenarios.

package/cursor/rules/ux-foundation.mdc

@@ -10,7 +10,7 @@ alwaysApply: false
 stories (ST-NNN)**. IDs sequential, never reused; dropped entries kept, not
 deleted.
 
-## Formats (ux-contract v2)
+## Formats (ux-contract v4)
 
 - **Persona `P-NN`:** 1–3 sentences, grounded in data/observation,
   recognizable by a real user.

package/cursor/rules/ux-scenarios.mdc

@@ -11,8 +11,9 @@ every feature, button, state, error, result. Keep it true.
 ## File structure (scenario-format v1)
 
 Title, then header comment, then: **Index** table
-(`| ID | Title | Feature | Persona | Status | Last audit |`), **Personas**
-(1–3 sentences each), **Scenarios** grouped by feature.
+(`| ID | Title | Feature | Persona | Traces | Status | Last audit |`),
+**Personas** (pointer to foundation.md when it exists, else defined here),
+**Scenarios** grouped by feature.
 
 When `docs/ux/foundation.md` exists, scenarios derive from it: draft per
 user story / journey stage, fill `Traces:` (e.g. `ST-001 (JTBD-01,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.7.0",
+  "version": "0.17.1",
   "description": "Scenario-driven UI development for AI agents (Claude Code + Cursor): scenario base, scenario-first hard rule, evidence-backed UX audits. This package is the installer CLI.",
   "bin": {
     "super-ux": "bin/super-ux.js"

package/templates/README.md

@@ -0,0 +1,35 @@
+# docs/ux — UX design system (super-ux)
+
+This folder is the single source of truth for the product's UX. Keep it in
+sync with the code on every interface change.
+
+## The pipeline
+
+```
+Personas · JTBD · Journeys · Stories  →  Flows  →  Screens  →  Scenarios  →  Audits  →  Plans
+         foundation.md                    flows.md  screens.md  scenarios.md   audits/    plans/
+```
+
+| File | Holds |
+|------|-------|
+| `foundation.md` | WHO & WHY: personas, jobs-to-be-done, journeys, user stories, monetization, Figma on/off |
+| `flows.md` | HOW: user-flow diagrams (screens, branches, error paths), referencing screens by `SCR-ID` |
+| `screens.md` | THE UI MAP: every screen and state with its Figma frame link, wireframe, code coverage, scenarios, resources |
+| `scenarios.md` | WHAT EXACTLY: use-case scenarios — the source of truth for behavior |
+| `audits/` | audit reports (code vs the chain) |
+| `plans/` | UX plans (target interface + what to create/modify/delete) |
+| `wireframes/` | optional low-fi wireframes / storyboards |
+| `lint.py` | the integrity/drift linter |
+
+## Rules
+
+1. **Design before you build.** A new feature starts here (job → flow →
+   screen → scenario), approved, before any UI code.
+2. **Update in the same change.** Any interface change updates
+   `scenarios.md`, affected flows, the affected screens in `screens.md`,
+   and (Figma on) the Figma frame plus its link — together, not later.
+3. **No drift.** Code that diverges from a screen's record, or a stale Figma
+   link, is a bug to fix.
+4. **Lint it.** Run `python3 docs/ux/lint.py` after changes and in CI.
+
+Maintained with the super-ux plugin. In Claude Code, run `/ux`.

package/templates/audit-report.md

@@ -1,8 +1,9 @@
 # UX Audit — YYYY-MM-DD
 
 - **Scope:** all
-- **Method:** static code trace
-- **Base version:** <git SHA of scenarios.md at audit time>
+- **Depth:** standard
+- **Method:** static code trace; passes: scenario, flow conformance
+- **Base version:** <git SHA of docs/ux at audit time>
 
 ## Summary
 
@@ -15,12 +16,20 @@
 ## Batch 1: <feature> (SCN-001..SCN-005)
 
 ### SCN-001 — PASS|PARTIAL|FAIL|BLOCKED
+- **Context:** <traced story acceptance criteria met? per criterion, when foundation exists>
 - **Evidence:** file:line, file:line
 - **Findings:**
   - [AUD-YYYY-MM-DD-01] (critical|major|minor) <finding> -> <suggested fix>
+
+Heuristic findings (deep): [PRN-NN] (severity) node — issue -> fix
 -->
 
 ## Findings register
 
 | # | Scenario | Severity | Finding | Suggested fix |
 |---|----------|----------|---------|---------------|
+
+## Practice compliance (deep audits)
+
+| Practice | Verdict | How / why not |
+|----------|---------|---------------|

package/templates/claude-rule.md

@@ -1,11 +1,26 @@
 ## UX scenarios — hard rule (super-ux)
 
-- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
-- Any change that touches user-facing behavior MUST update
-  `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
-  coverage).
-- Any new feature or project STARTS with scenarios: draft them, validate
-  against existing scenarios (conflicts, overlaps, gaps), get them approved —
-  only then design and build UI.
-- Use the `ux-scenarios` skill to maintain the base and `ux-audit` to verify
-  the codebase against it.
+- `docs/ux/scenarios.md` is the source of truth for all user-facing
+  behavior; `docs/ux/foundation.md` (personas, JTBD, journeys, stories) and
+  `docs/ux/flows.md` (user flows) are the WHY and HOW layers scenarios
+  trace to.
+- Any change that touches user-facing behavior or interface MUST update, in
+  the same change: `docs/ux/scenarios.md`; affected flows; the affected
+  screens in `docs/ux/screens.md` (the UI map — states, elements,
+  coverage); and, when Figma is enabled, the Figma frame(s) plus their
+  links in `screens.md`. A screen whose code diverges from its record, or a
+  stale Figma link, is drift — the exact thing this system prevents.
+- Any new feature or project STARTS with the chain: which job does it
+  serve, which journey stage, which story — then flows and scenarios,
+  validated against the existing base, approved.
+- **Do NOT write interface code until the UX workflow is done first:** the
+  foundation → flows → scenarios chain is designed and approved, and — when
+  Figma is enabled (default) — the UI is mocked up in Figma with every
+  screen linked to its frame. Building UI before this is the exact mistake
+  super-ux exists to prevent.
+- After any UX change and before calling the work done, run the linter
+  `python3 docs/ux/lint.py` — it must pass (errors are drift/broken
+  structure; wire it into CI/pre-commit).
+- Use `/ux` as the entry point; skills: `ux-foundation`, `ux-flows`
+  (flows + Figma mockups), `ux-scenarios` for maintenance, `ux-audit` for
+  evidence-backed verification. Full map: the plugin's system-map reference.

package/templates/flows.md

@@ -0,0 +1,30 @@
+# User Flows
+
+<!-- Managed with super-ux (ux-contract v4). The HOW layer: task analysis
+and user flows. Flows reference screens by SCR-ID (full specs live in
+screens.md). Scenarios in scenarios.md trace to FLW-IDs and must cover every
+node and edge. -->
+
+<!-- ### FLW-01: <user goal>
+- **Traces:** ST-001 (JTBD-01, JRN-01/#2)
+- **Goal:** <observable end state for the user>
+- **Entry points:** <all of them: screen, deep link, push, empty-state CTA>
+- **Success exit:** <where the user lands on success>
+- **Task analysis:**
+  1. <user-visible micro-step; cut everything that doesn't serve the job>
+- **Flow:**
+
+```mermaid
+flowchart TD
+  A[Screen: <name>] -->|<action>| B{<decision?>}
+  B -->|ok| C[Screen: <next>]
+  B -->|fail| B_err[<error + recovery>]
+  B_err --> A
+```
+
+- **Screens traversed:**
+  | Screen | States used here |
+  |--------|------------------|
+  | SCR-01 <name> | success |
+  | SCR-02 <name> | error, success |
+-->

package/templates/foundation.md

@@ -1,6 +1,6 @@
 # UX Foundation
 
-<!-- Managed with super-ux (ux-contract v2). The WHY layer: personas, jobs
+<!-- Managed with super-ux (ux-contract v4). The WHY layer: personas, jobs
 to be done, customer journeys, user stories. Update when the understanding
 of users changes; scenarios in scenarios.md trace to the IDs defined here. -->
 
@@ -27,6 +27,26 @@ data/observation, recognizable by a real user. -->
 |---|-------|------------|------------|---------------|------|-------------|
 -->
 
+## Monetization
+
+<!-- When the product earns money (choose with data, BP-067..070):
+- **Model:** hard paywall | freemium | hybrid | trial (type, length) — and why
+- **Value metric:** <what the paid tier meters>
+- **Free boundary:** <what stays free, where the visible limit sits>
+- **Money moments:** <paywall placement, upgrade triggers, rating prompts, winback>
+- **Acquisition coherence:** <the one story ad -> listing -> onboarding tells>
+-->
+
+## Design tooling
+
+<!-- Visual mockups in Figma are optional (default on). Ask the user at the
+start of design; record the choice here (see figma-integration). The Figma
+file and design-system details live in docs/ux/screens.md (the UI map);
+this section just records the on/off choice and the file location.
+- **Figma:** enabled | disabled
+- **Figma file:** <url — one project file, one page per feature/flow group>
+-->
+
 ## User stories
 
 <!-- ### ST-001: <short name>

package/templates/scenarios.md

@@ -1,35 +1,34 @@
 # UX Scenarios
 
-<!-- Managed with super-ux (scenario-format v1). Update in the same change as any user-facing behavior change. -->
+<!-- Managed with super-ux (ux-contract v4). Update in the same change as any user-facing behavior change. -->
 
 ## Index
 
-| ID | Title | Feature | Persona | Status | Last audit |
-|----|-------|---------|---------|--------|------------|
+| ID | Title | Feature | Persona | Traces | Status | Last audit |
+|----|-------|---------|---------|--------|--------|------------|
 
 ## Personas
 
-<!-- Every persona referenced below, 1-3 sentences each: who they are, what
-they know, what they want. Example:
-
-### new-user
-Opens the product for the first time. Knows nothing about it; wants to reach
-first value with zero reading.
--->
+<!-- If docs/ux/foundation.md exists, this section is just a pointer to it.
+Otherwise define personas here, 1-3 sentences each: who they are, what they
+know, what they want. -->
 
 ## Scenarios
 
 <!-- Group scenarios by feature under "## <feature>" headings. Entry shape
-(see scenario-format v1 for field rules):
+(see ux-contract v4 for field rules); steps are use-case style — one user
+action per step paired with the observable system response:
 
 ### SCN-001: <Title>
 - **Persona:** <persona-id>
 - **Feature:** <feature>
+- **Traces:** <ST-…, FLW-… (JTBD-…, JRN-…/#stage) — required when those layers exist>
 - **Entry point:** <where the user starts>
 - **Preconditions:** <state required, or "none">
 - **Steps:**
-  1. <one user action per step>
+  1. <user action> -> <observable system response>
 - **Expected result:** <what the user observes on success>
+- **Alt paths:** <meaningful non-error deviations and system responses, or omit>
 - **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>

package/templates/screens.md

@@ -0,0 +1,41 @@
+# UI Screen Registry
+
+<!-- Managed with super-ux (ux-contract v4). The design map: every screen and
+state with its Figma frame, wireframe, code coverage, and related UX/UI
+resources. Update in the same change as any interface change; when Figma is
+enabled, update the frame and re-verify its link in the same change. A screen
+whose code diverges from its record here is a "drifted" finding. -->
+
+## Index
+
+| ID | Screen | Used by | Figma | Status | Coverage |
+|----|--------|---------|-------|--------|----------|
+
+## Design system
+
+- **Figma library:** <url/name, or "none — platform defaults">
+- **Tokens in code:** <where color/type/spacing tokens live, e.g. src/theme/tokens.ts>
+- **Component source:** <shared UI components dir, e.g. src/components/>
+- **Assets:** <icons/illustrations location>
+
+## Screens
+
+<!-- One entry per screen (see ux-contract v4 for field rules):
+
+### SCR-01: <name>
+- **Used by:** <FLW-… and the step(s)>
+- **Purpose:** <the job step this screen serves>
+- **Elements:** <each element; mark the ONE primary action>
+- **States:**
+  | State | Trigger | Figma frame | Behavior |
+  |-------|---------|-------------|----------|
+  | success | default | <frame deep-link> | <what shows> |
+  | empty | <trigger> | <frame deep-link> | <prompt to act> |
+  | error | <trigger> | <frame deep-link> | <message + recovery> |
+  | loading | <trigger> | <frame deep-link> | <skeleton/progress> |
+- **Wireframe:** wireframes/SCR-01.md (optional)
+- **Coverage:** <file:line, or "none yet">
+- **Scenarios:** <SCN-… touching this screen>
+- **Resources:** <related components, shared assets, API/data deps, links>
+- **Status:** designed | built | drifted | retired
+-->