super-ux 0.18.0 → 0.23.2

package/CHANGELOG.md

@@ -1,5 +1,218 @@
 # Changelog
 
+## 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.
+
+- **FIX (distribution): shared contracts now ship with every skill.** The skills
+  CLI copies only a skill's OWN directory, so the sibling `skills/references/`
+  reached Claude Code plugins but arrived **dangling on Cursor / Codex / OpenCode /
+  OpenClaw / …** — `~/.agents/skills/ux-audit/` held nothing but `SKILL.md` while
+  its SKILL.md called `scenario-format.md` a contract to "never deviate" from.
+  Each skill now carries its own `references/` (the transitive closure of what it
+  links) and links them `references/…`. `skills/references/` stays the source of
+  truth; `test/sync_references.py` re-syncs; the validator fails on drift, on a
+  missing shipped contract, on any `../references/` link, and on dangling links
+  inside the copies.
+- Cursor always-on rule gains the `screens.md` and linter bullets it was missing
+  (it was two canon versions behind the Claude rule).
+- `ux-scenarios.mdc` contract stamp corrected `scenario-format v1` → `ux-contract v4`.
+- `system-map.md` lists `/ux-init`; README fixes "both skills" → "all four",
+  "three agent-requested rules" → "four", and the release note now names
+  `package.json` in the version-sync set (the validator has always enforced it).
+
 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).

package/README.md

@@ -4,74 +4,52 @@
 [![CI](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-Scenario-driven UI development for AI agents (Claude Code + Cursor).
-
-AI agents generate poor interfaces because they build UI without a model of
-user behavior: screens appear feature by feature, while error states, empty
-states, and cross-feature flows get invented ad hoc or skipped. **super-ux**
-fixes the process, not the symptom — a versioned base of UX scenarios becomes
-the source of truth for all user-facing behavior. Scenarios are written and
-validated *before* UI is built, updated in the same change as any behavior
-change, and used as the checklist for recurring, evidence-backed audits of
-the codebase.
+**Scenario-driven UI development for AI agents** — Claude Code, Cursor, and
+70+ other agents.
+
+Coding agents build bad interfaces for one reason: they write UI without a
+model of user behavior. Screens appear feature by feature; error states,
+empty states, and cross-feature flows get invented ad hoc or skipped, and
+three prompts later the agent quietly rewrites something you already
+approved. super-ux fixes the process, not the symptom: a versioned design
+chain in `docs/ux/` becomes the source of truth, written and approved
+*before* UI exists, updated in the same change as any behavior change, and
+used as the checklist for evidence-backed audits of the code.
 
 ```mermaid
 flowchart LR
-    W[Personas + JTBD\n+ journeys + stories] --> B[Derive scenarios\nwith Traces]
-    A[Feature idea] --> V{Which job? Which stage?\nValidate vs base}
-    W --> V
-    V -->|approved| D[Design & build UI]
-    D --> E[Update scenarios\nin the same change]
-    E --> F[/ux-audit: code vs scenarios\nwith story acceptance criteria/]
-    B --> F
-    F --> G[Report + findings]
-    G --> H[Prioritized fix plan\nFreq × Severity × Solvability] --> D
+    F["Foundation<br/>personas · JTBD<br/>journeys · stories"] --> L["Flows<br/>task analysis<br/>+ branches"]
+    L --> S["Screens<br/>states · elements<br/>Figma frames"]
+    S --> C["Scenarios<br/>action → response<br/>alt + error paths"]
+    C --> B["Build UI<br/>only now"]
+    B --> A["Audit<br/>code vs the chain<br/>file:line evidence"]
+    A --> P["Fix plan<br/>Freq × Severity<br/>× Solvability"]
+    P --> B
+    B -.->|same change| C
 ```
 
-## What's inside
-
-| 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-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 |
-| `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 |
-| [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):
-scenario entries with stable `SCN-NNN` IDs, personas, per-feature and
-per-product completeness checklists, the `draft → validated → implemented`
-lifecycle, audit verdicts and severities.
-
-## The hard rule
-
-- `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
+Every layer traces to the one above it. New product? Build it forward. Existing
+codebase? The same artifacts get filled in backwards from the code, tagged
+`inferred` until you confirm them — the gap between "is" and "should" becomes
+your improvement backlog.
+
+## What you get
+
+- **Context stops evaporating.** You describe who the product is for and what
+  job it does once; every later prompt inherits that instead of re-deriving it
+  from the diff.
+- **Scenarios become acceptance criteria.** "Make it nicer" can no longer mean
+  "silently change the error handling" — a file says what the error handling
+  does, and the audit checks the code against it.
+- **Drift gets caught, deterministically.** A linter fails on missing Figma
+  frames, broken traces, orphan screens, and index desync; audits report what
+  no longer matches with `file:line` evidence. That is the review pass you'd
+  otherwise never run.
+- **Designer artifacts without being a designer.** Personas, jobs to be done,
+  journeys, flows, screen states, wireframes, Figma frames — produced in your
+  repo, in the vocabulary a design review actually uses.
+
+## Quick start
 
 ### Claude Code
 
@@ -80,97 +58,184 @@ lifecycle, audit verdicts and severities.
 /plugin install super-ux@super-ux
 ```
 
-Then in your project: `/ux`. That's it — it installs the hard rule, seeds
-`docs/ux/`, builds the scenario base if empty, and on every later run just
-reports status and the next action.
+Then in your project, run `/ux` and answer in plain words. First run installs
+the hard rule, seeds `docs/ux/`, and builds the chain; every later run reports
+status and recommends one next action. You never pick a skill or a layer —
+routing is the agent's job.
 
-### Any agent via the skills CLI (70+ agents)
+### Cursor
 
 ```sh
-npx skills add ssheleg/super-ux            # both skills, current project
+npx super-ux --cursor /path/to/your/project
+```
+
+Copies the rules into `.cursor/rules/` (one always-on hard rule + four
+agent-requested rules), seeds `docs/ux/`, and installs the linter. An existing
+scenario base is never overwritten; re-run with `--force` after a release to
+refresh rules and linter only.
+
+### Any agent (70+, via the skills CLI)
+
+```sh
+npx skills add ssheleg/super-ux            # all four skills, current project
 npx skills add ssheleg/super-ux -g         # user-global
 npx skills add ssheleg/super-ux --skill ux-audit   # one skill
 ```
 
 [vercel-labs/skills](https://github.com/vercel-labs/skills) discovers the
 skills through this repo's marketplace manifest and installs them for Claude
-Code, Cursor, Codex, OpenCode and others. Note: this installs the two skills
-only — the `/ux` commands and the Cursor always-on hard rule come with the
-methods below.
+Code, Cursor, Codex, OpenCode and others. This channel ships the skills only —
+the `/ux` commands come with the plugin, the always-on hard rule with the
+Cursor install.
 
-### Interactive (pick agent + scope)
+### Interactive (pick channels and agents)
 
 ```sh
 npx super-ux
 ```
 
-Multi-select menu (space to toggle, `a` = everything at once, enter to
-install): skills for any of 70+ agents (delegates to the `skills` CLI picker
-— choose agents and global/project there), Cursor rules into a project, and
-the Claude Code plugin user-globally — any combination in one run.
+Multi-select menu (space toggles, `a` selects everything, enter installs):
+skills for any of 70+ agents, Cursor rules into a project, and the Claude Code
+plugin user-globally — any combination in one run. Also works straight from
+GitHub: `npx github:ssheleg/super-ux --cursor <dir>`, or clone and run
+`./install.sh --cursor <dir>`.
 
-### Cursor
+## The hard rule
+
+Installed into your project's `CLAUDE.md` (and as the always-on Cursor rule):
+
+- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
+  foundation (WHY), flows (HOW), and screens (the UI map) 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`, and — when Figma is on — the 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, screens, and scenarios, validated
+  against the existing base and approved.
+- **Do not write interface code until that workflow is done** — chain designed
+  and approved, and (Figma on, the default) the UI mocked up with every screen
+  linked to its frame. Building UI before this is the mistake super-ux exists
+  to prevent.
+- One **style pack** is the visual identity for the whole product, recorded in
+  `docs/ux/screens.md` → Design system. Inventing a palette, type pairing, or
+  motion per screen is drift too.
+- Run `python3 docs/ux/lint.py` after any UX change and in CI — it must pass.
+
+## Typical cycle
+
+1. **`/ux`** — first run sets everything up: foundation first (greenfield:
+   an interview about personas, jobs, journeys; existing code:
+   reverse-engineering them), then flows, screens, and scenarios derived from
+   the stories with full traceability.
+2. **Work normally.** Every user-facing change updates the chain in the same
+   change — the always-on rule catches it, `/ux-update` gives manual control.
+   New feature ideas get validated against the chain first: which job, which
+   journey stage, which story. An idea serving no job is challenged, not
+   silently built.
+3. **`/ux-audit`** — batched verification of code against every scenario plus
+   its story's acceptance criteria. `deep` adds heuristic, practice, and chain
+   coverage passes; `coverage` audits the chain itself. Reports land in
+   `docs/ux/audits/YYYY-MM-DD.md`.
+4. **Fix plan.** Findings become `docs/ux/plans/…`: the target interface per
+   screen plus a traced CREATE/MODIFY/DELETE table, prioritized by Frequency ×
+   Severity × Solvability — written to be executable without the conversation
+   that produced it. Build, then re-audit.
+
+## Companions (recommended, never required)
+
+super-ux owns structure and behavior, and deliberately stops at two edges.
+Each companion is offered once with its one-time install; the chain works
+fine without either.
+
+| When | Companion | What it adds |
+|---|---|---|
+| 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` |
+| 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>` |
+
+The boundary that keeps them from fighting: BP-079..090 are craft **floors**
+(contrast, line length, tap targets, spacing rhythm) and always win on safety;
+the style pack owns **identity** and wins on look. Both decisions land in the
+compliance table. Full protocol:
+[visual-identity.md](plugins/super-ux/skills/references/visual-identity.md).
+
+## What's inside
+
+Four skills, one entry point, and a set of contracts they all obey.
+
+| 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, the monetization model |
+| skill `ux-flows` | The HOW layer + the UI map: `docs/ux/flows.md` (task analysis, mermaid flows referencing screens by ID) and `docs/ux/screens.md` — every screen and state with its Figma frame, wireframe, code coverage, scenarios and resources. Also heuristic evaluation and traced redesign proposals |
+| skill `ux-scenarios` | `docs/ux/scenarios.md`: use-case scenarios (action → observable response, alt and error paths) covering every flow node and edge, `Traces:` to stories and flows, validated for conflicts, coverage and traceability |
+| skill `ux-audit` | Batched audit with full context: code vs every scenario plus its story's acceptance criteria; verdicts PASS / PARTIAL / FAIL / BLOCKED with `file:line` evidence; depths `quick` / `standard` / `deep`; a `coverage` scope that audits the chain itself |
+| `/ux` | **The one command**: sets up whatever is missing, reports status across every layer, then offers only the applicable actions with one marked recommended. Idempotent |
+| `/ux-init` `/ux-foundation` `/ux-flows` `/ux-update` `/ux-audit` `/ux-rule` `/ux-lint` | Direct controls for when you know exactly what you want; `/ux-rule` installs the hard rule into `CLAUDE.md` |
+| `docs/ux/lint.py` + `/ux-lint` | The deterministic half: missing Figma frames, unresolved SCR/story traces, orphans, built screens without coverage, index desync, ID gaps, broken links. Stdlib-only, exit 1 on problems — wire it into CI so drift can't merge |
+| `cursor/rules/*.mdc` | The same methodology for Cursor: one always-on hard rule + four agent-requested rules |
+| `templates/` | Seeds for `docs/ux/`: foundation, flows, screens, scenario base, the folder README, the audit-report skeleton, and the CLAUDE.md rule snippet |
+
+The contracts every skill reads:
+
+| Reference | Holds |
+|---|---|
+| [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 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 |
+| [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 |
+| [figma-integration.md](plugins/super-ux/skills/references/figma-integration.md) · [figma-structure.md](plugins/super-ux/skills/references/figma-structure.md) | The optional Figma surface (on by default): when and 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 |
+
+## Keeping installs current
+
+Global channels (run after a release, then restart the Claude Code session so
+the plugin reloads):
 
 ```sh
-npx super-ux --cursor /path/to/your/project
+claude plugin marketplace update super-ux && \
+claude plugin update super-ux@super-ux && \
+npx --yes skills update ux-audit ux-flows ux-foundation ux-scenarios --global --yes
 ```
 
-(also works: `npx github:ssheleg/super-ux --cursor <dir>` straight from the
-repo, or clone and run `./install.sh --cursor <dir>` — same behavior.) Copies the
-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.
+Cursor rules and the seeded `docs/ux/lint.py` are per-project (Cursor has no
+global rules directory) — refresh each project you use:
 
-## For the user: one command, plain words
+```sh
+npx super-ux@latest --cursor /path/to/your/project --force
+```
 
-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.
+`--force` replaces the rule files and the linter; your scenario base and the
+rest of `docs/ux/` are never touched. Check the published version with
+`npm view super-ux version`.
 
-## Typical cycle
+## Contributing
 
-1. `/ux` — first run sets everything up: foundation first (greenfield:
-   interview about personas, jobs, journeys; existing code:
-   reverse-engineer them), then scenarios derived from the stories with
-   full traceability.
-2. Work normally; every user-facing change updates the base in the same
-   change (the always-on rule catches it; `/ux-update` for manual control).
-   New feature ideas are validated against the chain first: which job,
-   which journey stage, which story.
-3. `/ux` any time — status across layers + action menu; `/ux-audit` —
-   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 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
-
-`python3 test/validate.py` checks repo consistency (manifests, versions,
-front-matter, templates, links); CI runs it on every push and PR. Versioning
-is semver; bump `marketplace.json` + `plugin.json` + `CHANGELOG.md` together
-— the validator enforces the sync.
-
-## По-русски (коротко)
-
-Проблема: агенты генерируют плохие интерфейсы, потому что строят UI без
-модели поведения пользователя. super-ux строит цепочку: **персоны → JTBD →
-карта пути → user stories → UX-сценарии → аудиты → планы фиксов**.
-Foundation (`docs/ux/foundation.md`) отвечает на «зачем», сценарии
-(`docs/ux/scenarios.md`) — источник правды поведения, трассируются к
-stories. Всё пишется и валидируется **до** интерфейса, обновляется тем же
-изменением, что и поведение. Аудиты (`/ux-audit`) проверяют код против
-сценариев вместе с acceptance criteria, вердикты PASS/PARTIAL/FAIL/BLOCKED
-с доказательствами `file:line`; `/ux-audit coverage` ищет дыры в самой
-цепочке. Установка: в
-Claude Code — `/plugin marketplace add ssheleg/super-ux`, в Cursor —
-`npx super-ux --cursor <проект>`. Дальше одна команда — `/ux`: сама ставит
-правило и базу, а при повторных запусках показывает статус и следующий шаг.
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
+for the repo layout, the validator, and the release checklist. Everyone taking
+part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md); to report a
+vulnerability, see [SECURITY.md](SECURITY.md). In short:
+`python3 test/validate.py` must pass (CI runs it on every push and PR), and
+edits to `plugins/super-ux/skills/references/` need
+`python3 test/sync_references.py` to refresh the per-skill copies.
+
+## Author
+
+Built by ssheleg — [sshlg.me](https://sshlg.me)
+
+- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
+- Telegram — [@sshlg](https://t.me/sshlg)
+
+Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):
+`super-ux`, `task-pipeline`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
+One command installs all five for every agent you use:
+
+```bash
+npx sshlg-skills install
+```
 
 ## License
 

package/bin/super-ux.js

@@ -74,7 +74,9 @@ function installCursor(target, force) {
     }
   }
 
-  fs.mkdirSync(path.join(target, 'docs', 'ux', 'audits'), { recursive: true });
+  for (const dir of ['audits', 'plans']) {
+    fs.mkdirSync(path.join(target, 'docs', 'ux', dir), { recursive: true });
+  }
   for (const tpl of ['scenarios', 'foundation', 'flows', 'screens', 'README']) {
     const dst = path.join(target, 'docs', 'ux', `${tpl}.md`);
     if (fs.existsSync(dst)) {
@@ -85,9 +87,19 @@ function installCursor(target, force) {
     }
   }
   // The linter is code, not a template — refresh it to the shipped version.
+  // Shipped via package.json files[]; if that ever regresses, warn instead of
+  // dying on an ENOENT stack trace after the rules are already installed.
+  const lintSrc = path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py');
   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}`);
+  if (fs.existsSync(lintSrc)) {
+    fs.copyFileSync(lintSrc, lintDst);
+    console.log(`sync:    ${lintDst}`);
+  } else {
+    console.error(
+      `warning: linter not found in this package (${lintSrc}); docs/ux/lint.py was not installed.\n` +
+        `         Get it from https://github.com/${REPO}/blob/main/plugins/super-ux/scripts/ux_lint.py`
+    );
+  }
 
   console.log(`done: ${installed} installed, ${skipped} skipped`);
 }

package/cursor/rules/super-ux.mdc

@@ -8,6 +8,12 @@ alwaysApply: true
 - `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
   `docs/ux/foundation.md` (personas, JTBD, journeys, user stories) is the WHY
   layer scenarios trace to.
+- `docs/ux/screens.md` is the UI map: every screen + state with its wireframe
+  and (Figma on) its frame link. A screen that changes in code changes here in
+  the SAME change.
+- Run the linter after any UX change and before calling work done:
+  `python3 docs/ux/lint.py`. It must pass — drift must not merge; wire it
+  into CI/pre-commit.
 - Any change that touches user-facing behavior MUST update
   `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
   coverage). New user-facing behavior with no scenario is a blocker, not a
@@ -17,10 +23,15 @@ alwaysApply: true
   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.
+  foundation → flows → screens → 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.
+- Visual identity is one locked style pack, recorded once in `screens.md` →
+  Design system and used by every frame and every built screen — picked with
+  the **sheleg-design** companion skill (`npx sheleg-design-skill`) when the
+  project has no design system of its own. Recommended, never forced; a
+  palette invented per screen is visual drift.
 - Workflows: `ux-foundation` rule (WHY), `ux-flows` rule (flows + Figma
-  mockups), `ux-scenarios` rule (scenario base), `ux-audit` rule
+  mockups + style pack), `ux-scenarios` rule (scenario base), `ux-audit` rule
   (evidence-backed audits).

package/cursor/rules/ux-audit.mdc

@@ -15,8 +15,9 @@ verdict BLOCKED with the exact reason. Never guess, never a courtesy PASS.
 
 ## Loop
 
-1. Read the base; scope = all | feature:<name> | ID range; note the git SHA
-   of scenarios.md for the report header; skip retired scenarios.
+1. Read the base (and foundation/flows/screens when they exist); scope =
+   all | feature:<name> | ID range | coverage; note the git SHA of `docs/ux`
+   for the report header; skip retired scenarios.
 2. Batch by feature, ~5–8 scenarios per batch; list batches up front.
 3. Per scenario check against the code: entry point reachable; every step
    implemented; every listed UI element present and wired; every listed
@@ -26,6 +27,12 @@ verdict BLOCKED with the exact reason. Never guess, never a courtesy PASS.
    `[AUD-YYYY-MM-DD-NN] (critical|major|minor) description -> suggested fix`.
 4. Verdicts: PASS (complete), PARTIAL (flow exists, gaps), FAIL (missing or
    broken), BLOCKED (cannot verify — say why).
+   When `flows.md`/`screens.md` exist, also check conformance: every flow
+   node reachable and every edge (error edges included) wired; every
+   registered screen's states rendered and its `Coverage` accurate — code
+   that diverges from a screen's record is a `drifted` finding. Scope
+   `coverage` audits the chain itself (orphan stories/flows/screens/
+   scenarios, journey stages without scenarios, personas unused).
 5. Write the report batch by batch: header (scope, method, base SHA),
    Summary (totals, top issues, prioritized next actions), per-batch
    verdicts with evidence, findings-register table.

package/cursor/rules/ux-flows.mdc

@@ -20,8 +20,14 @@ 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).
+recovery edges), `Screens traversed` table (`| Screen | States used here |`
+— SCR-IDs only; the full per-screen spec lives once in `screens.md`).
+
+Each screen entry in `screens.md`: `Used by`, `Purpose`, `Elements` (mark
+the ONE primary action), `States` table (`| State | Trigger | Figma frame |
+Behavior |` — a row per loading/empty/error/success that applies),
+`Wireframe`, `Coverage` (file:line), `Scenarios`, `Resources`, `Status`
+(designed|built|drifted|retired).
 
 ## Design rules
 
@@ -33,9 +39,20 @@ loading/empty/error/success + key elements, one primary action).
 - Wireframes optional (`docs/ux/wireframes/FLW-NN.md`, ASCII hierarchy +
   primary action, not pixels); storyboard only when usage context drives
   design.
+- Visual identity BEFORE any frame: `screens.md` → Design system →
+  `Style pack`. Empty and no design system in the project → pick a pack with
+  the **sheleg-design** companion skill (`workbench` for product UI /
+  dashboards / tools, `instrument-console`, `editorial-luxury`, or a new
+  pack on its contract; cinematic scroll pages also take its motion
+  methodology) and record the pack + token file. Missing → offer the
+  one-time install once (`npx sheleg-design-skill`) and continue on platform
+  defaults; recommend, don't force. The pack owns palette/type/motion and
+  its bans; BP-079..090 stay the floors it must clear. Never invent a look
+  per screen.
 - 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
+  frame built on the pack's tokens (they become the Figma variable
+  collections) 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

package/cursor/rules/ux-foundation.mdc

@@ -42,6 +42,13 @@ deleted.
   INVEST, observable criteria), coverage (persona→job→journey→story chain
   complete; must/should stories have scenarios).
 
+Two more sections this file owns, filled when they apply: **Monetization**
+(model + value metric + free boundary + money moments + acquisition
+coherence — each money moment becomes a first-class flow) and **Design
+tooling** (the Figma on/off choice, default on, plus the project's Figma file
+URL — asked once per project). Everything else about the visual layer, the
+design system and the style pack, lives in `docs/ux/screens.md`.
+
 Evidence beats opinion: mark unvalidated guesses as assumptions
 (desirability/viability/feasibility/usability) and test risky ones before
 building on them.

package/cursor/rules/ux-scenarios.mdc

@@ -8,7 +8,7 @@ alwaysApply: false
 `docs/ux/scenarios.md` describes everything the user can do, see, and hit —
 every feature, button, state, error, result. Keep it true.
 
-## File structure (scenario-format v1)
+## File structure (ux-contract v4)
 
 Title, then header comment, then: **Index** table
 (`| ID | Title | Feature | Persona | Traces | Status | Last audit |`),
@@ -21,8 +21,10 @@ JRN-01/#2)`), enforce traceability — every must/should story covered by ≥1
 scenario, every scenario serves ≥1 story or job.
 
 Scenario entry fields (exact names): `Persona`, `Feature`, `Traces`, `Entry point`,
-`Preconditions`, `Steps` (numbered, one user action each), `Expected result`
-(observable), `UI elements` (every button/field/link/dialog/toast involved —
+`Preconditions`, `Steps` (numbered, one user action each, paired with the
+observable system response), `Expected result` (observable), `Alt paths`
+(meaningful non-error deviations — skip/dismiss/alternate route — omit only
+when none exist), `UI elements` (every button/field/link/dialog/toast involved —
 this is what audits check), `States covered` (loading|empty|error|success),
 `Errors & recovery` (each failure: what the user sees, how they recover),
 `Status` (draft|validated|implemented|retired), `Coverage` (file:line or
@@ -35,7 +37,10 @@ never deleted. Lifecycle: draft → validated (human approval) → implemented
 Per-feature completeness: happy path, every error path, empty state, visible
 loading, destructive-action confirmation, returning-user variant.
 Per-product: first-run onboarding, every core flow, settings, multi-entity
-flows (e.g. second project), account/data lifecycle.
+flows (e.g. second project), account/data lifecycle, and — when the product
+earns money — the monetization flows: paywall (first-session placement),
+trial start/end, upgrade-at-limit, cancel + winback, rating prompt after
+success moments.
 
 ## Workflows
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "super-ux",
-  "version": "0.18.0",
-  "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.",
+  "version": "0.23.2",
+  "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"
   },
@@ -9,12 +9,16 @@
     "bin",
     "cursor",
     "templates",
+    "plugins/super-ux/scripts/ux_lint.py",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "repository": "github:ssheleg/super-ux",
   "homepage": "https://github.com/ssheleg/super-ux",
+  "bugs": {
+    "url": "https://github.com/ssheleg/super-ux/issues"
+  },
   "license": "MIT",
   "author": "ssheleg",
   "engines": {

package/plugins/super-ux/scripts/ux_lint.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""super-ux linter — checks a target project's docs/ux/ for integrity and drift.
+
+Deterministic enforcement of the ux-contract: run it after any UX change and
+before calling the work done, and wire it into the project's CI/pre-commit.
+It turns the prose rules (same-change, no lost Figma, no orphans, no drift)
+into a check that fails.
+
+Usage:
+  python3 docs/ux/lint.py            # lint ./docs/ux
+  python3 docs/ux/lint.py <dir>      # lint <dir> (a docs/ux directory or its parent)
+  python3 docs/ux/lint.py --strict   # warnings also fail (exit 1)
+
+Exit codes: 0 clean (warnings allowed unless --strict), 1 problems found,
+2 no UX docs at all (run /ux first). Stdlib only; tolerant parsing — reports
+what it can and never crashes on malformed markdown.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ERRORS: list[str] = []
+WARNS: list[str] = []
+
+
+def err(msg: str) -> None:
+    ERRORS.append(msg)
+
+
+def warn(msg: str) -> None:
+    WARNS.append(msg)
+
+
+def read(path: Path) -> str:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    # Strip HTML comments so template examples (shipped commented-out) and
+    # notes are never parsed as real entries.
+    return re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+
+
+def find_ux_dir(arg: str | None) -> Path | None:
+    base = Path(arg) if arg else Path.cwd()
+    for cand in (base, base / "docs" / "ux", base.parent if base.name else base):
+        if (cand / "scenarios.md").exists() or (cand / "foundation.md").exists():
+            return cand
+    return None
+
+
+def ids(text: str, prefix: str) -> list[str]:
+    """All '### PREFIX-NN:' entry ids, in order."""
+    return re.findall(rf"^###\s+({prefix}-\d+):", text, re.MULTILINE)
+
+
+def index_ids(text: str, prefix: str) -> set[str]:
+    """Ids appearing in a leading '| PREFIX-NN |' index-table cell."""
+    return set(re.findall(rf"^\|\s*({prefix}-\d+)\s*\|", text, re.MULTILINE))
+
+
+def refs(text: str, prefix: str) -> set[str]:
+    """Every PREFIX-NN token mentioned anywhere."""
+    return set(re.findall(rf"\b({prefix}-\d+)\b", text))
+
+
+def check_unique_and_gaps(entry_ids: list[str], label: str) -> None:
+    seen: dict[str, int] = {}
+    for i in entry_ids:
+        seen[i] = seen.get(i, 0) + 1
+    for i, n in seen.items():
+        if n > 1:
+            err(f"{label}: duplicate id {i} ({n} entries)")
+    nums = sorted(int(i.split("-")[1]) for i in seen)
+    if nums:
+        missing = [n for n in range(1, max(nums) + 1) if n not in nums]
+        if missing:
+            warn(f"{label}: id gaps (retired entries should stay): {missing}")
+
+
+def figma_enabled(foundation: str) -> bool | None:
+    """True/False from foundation Design tooling; None if unstated (default-on)."""
+    m = re.search(r"\*\*Figma:\*\*\s*(enabled|disabled)", foundation, re.IGNORECASE)
+    if not m:
+        return None
+    return m.group(1).lower() == "enabled"
+
+
+def screen_blocks(text: str) -> dict[str, str]:
+    """Map SCR-id -> its section body (from its header to the next ### / ##)."""
+    out: dict[str, str] = {}
+    parts = re.split(r"^###\s+(SCR-\d+):", text, flags=re.MULTILINE)
+    # parts = [pre, id1, body1, id2, body2, ...]
+    for i in range(1, len(parts), 2):
+        sid = parts[i]
+        body = parts[i + 1] if i + 1 < len(parts) else ""
+        body = re.split(r"^##\s", body, maxsplit=1, flags=re.MULTILINE)[0]
+        out[sid] = body
+    return out
+
+
+def check_links(ux: Path) -> None:
+    link_re = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
+    for md in sorted(ux.rglob("*.md")):
+        text = read(md)
+        for target in link_re.findall(text):
+            if target.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            resolved = (md.parent / target.split("#", 1)[0]).resolve()
+            if not resolved.exists():
+                warn(f"{md.name}: broken link -> {target}")
+
+
+def main() -> int:
+    args = [a for a in sys.argv[1:] if not a.startswith("-")]
+    strict = "--strict" in sys.argv[1:]
+    ux = find_ux_dir(args[0] if args else None)
+    if ux is None:
+        print("no UX docs found (docs/ux/scenarios.md). Run /ux to set up.")
+        return 2
+
+    foundation = read(ux / "foundation.md")
+    flows = read(ux / "flows.md")
+    screens = read(ux / "screens.md")
+    scenarios = read(ux / "scenarios.md")
+
+    has_flows = bool(ids(flows, "FLW"))
+    has_screens = bool(ids(screens, "SCR"))
+    has_stories = bool(ids(foundation, "ST"))
+
+    # --- ID integrity ---
+    for text, pref, label in [
+        (scenarios, "SCN", "scenarios.md"),
+        (flows, "FLW", "flows.md"),
+        (screens, "SCR", "screens.md"),
+        (foundation, "ST", "foundation.md/stories"),
+        (foundation, "JTBD", "foundation.md/jobs"),
+    ]:
+        entry_ids = ids(text, pref)
+        if entry_ids:
+            check_unique_and_gaps(entry_ids, label)
+
+    # --- Index <-> entries sync (scenarios, screens) ---
+    for text, pref, name in [(scenarios, "SCN", "scenarios.md"), (screens, "SCR", "screens.md")]:
+        entries = set(ids(text, pref))
+        if not entries:
+            continue
+        idx = index_ids(text, pref)
+        for missing in sorted(entries - idx):
+            warn(f"{name}: {missing} has no index row")
+        for ghost in sorted(idx - entries):
+            err(f"{name}: index lists {ghost} but no entry exists")
+
+    # --- Flows reference existing screens ---
+    if has_flows and has_screens:
+        screen_ids = set(ids(screens, "SCR"))
+        used = refs(flows, "SCR")
+        for miss in sorted(used - screen_ids):
+            err(f"flows.md references {miss} but screens.md has no such screen")
+        for orphan in sorted(screen_ids - used):
+            warn(f"screens.md: {orphan} is used by no flow (orphan)")
+
+    # --- Scenario traces resolve ---
+    if ids(scenarios, "SCN"):
+        story_ids = set(ids(foundation, "ST"))
+        flow_ids = set(ids(flows, "FLW"))
+        traced_st = refs(scenarios, "ST")
+        traced_flw = refs(scenarios, "FLW")
+        if has_stories:
+            for miss in sorted(traced_st - story_ids):
+                warn(f"scenarios.md: traces to {miss} which is not in foundation.md")
+        if has_flows:
+            for miss in sorted(traced_flw - flow_ids):
+                warn(f"scenarios.md: traces to {miss} which is not in flows.md")
+
+    # --- must/should stories have a scenario ---
+    if has_stories and ids(scenarios, "SCN"):
+        traced = refs(scenarios, "ST")
+        for m in re.finditer(r"^###\s+(ST-\d+):", foundation, re.MULTILINE):
+            sid = m.group(1)
+            # Only this story's own body: stop at the next heading, so a
+            # neighbor's Priority line is never read as this story's.
+            tail = re.split(r"^#{2,3}\s", foundation[m.end():], maxsplit=1, flags=re.MULTILINE)[0]
+            if re.search(r"\*\*Priority:\*\*\s*(must|should)", tail, re.IGNORECASE):
+                if sid not in traced:
+                    warn(f"foundation.md: {sid} (must/should) has no scenario tracing to it")
+
+    # --- Screen-level: Figma frames, coverage, drift status ---
+    if has_screens:
+        fig = figma_enabled(foundation)
+        for sid, body in screen_blocks(screens).items():
+            status_m = re.search(r"\*\*Status:\*\*\s*(designed|built|drifted|retired)", body)
+            status = status_m.group(1) if status_m else None
+            if status == "retired":
+                continue
+            # every state row present in the States table
+            state_rows = re.findall(r"^\s*\|\s*(loading|empty|error|success)\s*\|(.*)\|\s*$",
+                                    body, re.MULTILINE | re.IGNORECASE)
+            if fig is not False:  # enabled or default-on
+                for state, rest in state_rows:
+                    cells = [c.strip() for c in rest.split("|")]
+                    frame = cells[1] if len(cells) >= 2 else ""
+                    if not frame or frame in ("-", "—", "<frame deep-link>", "<frame link>"):
+                        err(f"screens.md: {sid} state '{state}' has no Figma frame link")
+            cov_m = re.search(r"\*\*Coverage:\*\*\s*(.+)", body)
+            cov = cov_m.group(1).strip() if cov_m else ""
+            if status == "built" and (not cov or cov.lower().startswith("none")):
+                warn(f"screens.md: {sid} is 'built' but has no Coverage")
+
+    check_links(ux)
+
+    # --- Report ---
+    for e in ERRORS:
+        print(f"ERROR: {e}")
+    for w in WARNS:
+        print(f"warn:  {w}")
+    total = len(ERRORS) + len(WARNS)
+    if not total:
+        print(f"OK — docs/ux is consistent ({ux})")
+        return 0
+    print(f"\n{len(ERRORS)} error(s), {len(WARNS)} warning(s)")
+    if ERRORS or (strict and WARNS):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/README.md

@@ -12,7 +12,7 @@ Personas · JTBD · Journeys · Stories  →  Flows  →  Screens  →  Scenario
 
 | File | Holds |
 |------|-------|
-| `foundation.md` | WHO & WHY: personas, jobs-to-be-done, journeys, user stories, monetization, Figma on/off |
+| `foundation.md` | WHO & WHY: personas, jobs-to-be-done, journeys, user stories, monetization, Figma on/off + file URL |
 | `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 |
@@ -29,7 +29,9 @@ Personas · JTBD · Journeys · Stories  →  Flows  →  Screens  →  Scenario
    `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.
+   link, is a bug to fix. The same goes for the look: one style pack is
+   recorded in `screens.md` → Design system (pick it with the
+   **sheleg-design** skill) and every screen obeys it.
 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/claude-rule.md

@@ -14,10 +14,15 @@
   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.
+  foundation → flows → screens → 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.
+- Visual identity is ONE locked style pack, recorded in `docs/ux/screens.md`
+  → Design system and obeyed by every Figma frame and every built screen —
+  picked with the **sheleg-design** companion skill when the project has no
+  design system of its own (recommended, not required). Inventing a palette,
+  type pairing, or motion per screen is visual drift.
 - 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).

package/templates/flows.md

@@ -27,4 +27,6 @@ flowchart TD
   |--------|------------------|
   | SCR-01 <name> | success |
   | SCR-02 <name> | error, success |
+- **Wireframe:** wireframes/FLW-01.md (optional; per-screen wireframes live
+  under the screen's SCR-ID in screens.md)
 -->

package/templates/screens.md

@@ -13,6 +13,11 @@ whose code diverges from its record here is a "drifted" finding. -->
 
 ## Design system
 
+<!-- Style pack = the locked visual identity every frame and built screen obeys.
+Pick it with the sheleg-design companion skill (workbench for product UI /
+dashboards / tools, instrument-console, editorial-luxury, or a new pack on its
+contract) before drawing anything; record its token file below. -->
+- **Style pack:** <pack name, or "none — platform defaults">
 - **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/>